fix(web-api-discovery): move the placement guard to the steps that actually write committable output

[MarkMichaelis]

Closes #471

The problem

The placement guard warned on the one step that can no longer pollute a work tree, and
was absent from the four that can.

Invoke-HarCapture.ps1 warned whenever a capture started from the primary checkout on the
protected branch. That was true as written when #300 added it — the default output was
then the work tree root. Two later changes moved it:

• fix(web-api-discovery): scrub output lands untracked at the repo root, is unstamped, and leaves no link back to its raw #377 made the default output the run's own session directory under .har-captures/,
  gitignored by construction (capture-har.js: with no --output-path,
  outputPath === sessionDir).
• fix(web-api-discovery): recording from a worktree writes raw captures where worktree cleanup destroys them #367 anchored .har-captures/ to the main working tree, never a linked worktree,
  because git worktree remove had destroyed a 71 MB capture.

So a default capture from main writes nothing into the work tree — but the guard fired
anyway, because ShouldWarn asked only about location and never about whether the run
would write anything committable. Its sibling outputDestinationWarning had already got
this right: "the default, which is never classified because it cannot be the problem".

Meanwhile the coverage was exactly inverted:

Step	Writes committable output into the work tree?	Guard before	Guard after
Invoke-HarCapture (default)	No — gitignored session dir	Yes	No
Invoke-HarCapture (explicit -OutputPath)	Yes	Yes	Yes
extract-har-reference.js --out	Yes	No	Yes
generate-api-document.js	Yes	No	Yes
Invoke-SanitizeHar.ps1 -OutputHar	Yes	No	Yes
Invoke-HarCatalogue.ps1 -OutputPath	Yes	No	Yes

A warning that fires without harm is not free — it is how the warning gets trained out of
an operator's attention, which is what happened: the reported behaviour was answering y
and going on recording from main. RepoWorkflowGuard.ps1 predicted it in its own
docstring: "noise is how a warning gets trained out of an operator's attention."

What changed

1. The guard asks about the destination, not only the location.
placementForOutput() is the single entry point for both start and catalogue. It
exempts the captures root structurally and hands everything else to
classifyDestination() — the same classifier outputDestinationWarning uses, so there is
no second gitignore answer free to disagree.

The exemption is structural rather than a gitignore question for a reason worth stating:
the captures root is gitignored, but this tool is what makes it so, and that happens
after the guard — which must fire before anything is recorded. Asking git in the window
between the two answers "not ignored" for a directory about to be ignored, which is the
false warning this PR exists to remove.

The decision also gets a single owner. The PowerShell front door used to run the check and
hand the recorder HARCAPTURE_PLACEMENT_GUARD_RAN so the operator was told once; it cannot
answer "is this destination gitignored" because it never resolves the destination. The
recorder does, so the recorder decides, and the handshake goes with the duplicate check.

2. The four steps that write committable output are guarded, before they write.
#300's load-bearing invariant is preserved — the guard runs before any work begins, so
nothing that cost the operator effort exists when it fires.

3. The message hands over commands rather than describing the problem.
A pre-write guard cannot end in mv the way the capture epilogue does, so the actionable
fix is the pair — filled in, not templated:

This is the primary checkout on the protected branch (main).
About to write docs/har-reference/demo.har, which is not gitignored there,
so the output will show as untracked where commits are blocked.
To put it somewhere committable:
    git worktree add .worktrees/har-reference -b <type>/<issue#>-har-reference main
    node scripts/har/extract-har-reference.js --in in.har --out .worktrees/<name>/docs/har-reference/demo.har
Continuing anyway is safe -- nothing is discarded.

4. Interactive operators can accept the offer.
Accepting creates the worktree and retargets the output into it. Non-interactive callers
get the commands and proceed — ShouldContinue throws under -NonInteractive, and an
agent must never be prompted.

Not in scope

• No new command-line options. Everything here changes an existing default or message
  text, so the Adding Command-Line Options — Prompt First rule is not engaged.
• No auto-worktree at capture time. fix(web-api-discovery): recording from a worktree writes raw captures where worktree cleanup destroys them #367 requires the raw capture to outlive worktree
  deletion, and no issue number exists at capture time to name a branch with.
• [NEEDS DISCUSSION - do not start] web-api-discovery: capture output placement is decided by git, and raw vs scrubbed follow opposite rules #361's broader placement redesign is not decided here. This resolves only its
  concern 4 — "a placement design that is correct by construction may make the guard
  unnecessary, or reduce it to a much narrower check" — which fix(web-api-discovery): scrub output lands untracked at the repo root, is unstamped, and leaves no link back to its raw #377 made true. [NEEDS DISCUSSION - do not start] web-api-discovery: capture output placement is decided by git, and raw vs scrubbed follow opposite rules #361 stays
  open for the rest.

Independent review

Reviewed by Claude Sonnet 5 (authoring model: Opus 5), two full passes plus a
confirmation pass.

Pass 1 raised five findings; four were accepted and fixed, one rejected with evidence:

• catalogue kept the pre-web-api-discovery: the placement guard warns on the one step that cannot pollute, and is absent from the four that can #471 location-only check. Accepted — it emitted the
  relocation notice for its own gitignored default, telling operators to mv a file that
  had never been misplaced. The exact bug this PR closes, surviving in the one command the
  first pass missed. Both commands now go through a single placementForOutput.
• PowerShell/Node divergence on a forged core.excludesFile. Accepted — the JS
  classifier strips the whole GIT_* namespace and pins HOME; the PowerShell probe did
  not, so an injected core.excludesFile could suppress the PowerShell warning and not the
  Node one. Both now probe the same stripped environment, with a forged-config case in the
  cross-runtime agreement table.
• Invoke-HarCatalogue classified the directory, not the file. Accepted.
• Top-level prefix comparison treated the checkout root as outside itself. Accepted.
• "A missing git leaves a stale $LASTEXITCODE." Rejected — measured:
  & nosuchcmd raises a terminating CommandNotFoundException, so the existing
  try/catch already returns unverifiable.

Pass 2 confirmed all five and found four Low/Nit items, since fixed: the re-entrancy guard
threw from inside the catch that means "git missing" (silencing the one failure it exists
to make loud); the catalogue fix had no regression test at the level it occurred; Pop
conflated "absent" with "present but empty"; and one comment overclaimed.

Pass 3 caught a regression introduced by the fix to the first of those, and it was right
to. Hoisting the environment push out of the try to make a re-entrant call throw where
the caller can see it also hoisted it out of the finally: a push failing after
publishing its saved copy would then leave HOME pointing at a directory that does not
exist and the slot permanently occupied, so every later probe in the process would report
a re-entry that never happened — worse than the mislabelled warning it replaced. The two
goals are separable because only one of the two steps mutates: the assertion is raised
before the try, the mutation stays inside it. Four tests now cover the paths nothing
exercised.

Pass 4 confirmed the fix and reported no Critical or Important issues.

Known gap, accepted: no test forces a failure inside the push itself, as opposed to
in the git call after it. The path is covered structurally and by trace; pinning it would
mean mocking Remove-Item, which buys less than it costs. Recorded rather than papered
over.

Verification

CI is billing-blocked, so everything was run locally.

Invoke-Pester capture-output-placement.Tests.ps1 HarCaptureOutputPlacement.Tests.ps1
Tests Passed: 67, Failed: 0

node --test  capture-har (71)          capture-recatalogue (14)
             capture-output-destination (29)  capture-durability (16)
             capture-quarantine (18)    capture-store
             repo-workflow-guard (20)   api-document   har-reference
9 suites, 9 pass, 0 fail

Both sets of new tests were confirmed Red against the pre-change code before the fix
landed — the start tests against capture-har.js at main, the catalogue tests
against the previous commit — so neither is vacuously green.

Functional check against a real throwaway checkout on main (not a fixture):

--- committable destination on main ---
extract-har-reference: This is the primary checkout on the protected branch (main).
  About to write docs/har-reference/demo.har, which is not gitignored there,
  ...
      git worktree add .worktrees/har-reference -b <type>/<issue#>-har-reference main
      node scripts/har/extract-har-reference.js --in in.har --out .worktrees/<name>/docs/har-reference/demo.har

--- gitignored destination on main ---   (no warning)
--- same run from a worktree ---         (no warning)

Accepting the offer was exercised directly:

Created .../work/.worktrees/har-reference on chore/har-reference.
Writing to .../work/.worktrees/har-reference/docs/har-reference/demo.har.

Environment restoration is pinned by test on both paths: a pre-existing GIT_CONFIG_COUNT
and HOME survive a successful probe and one where git cannot run at all, an
empty-string variable is restored rather than deleted, and a nested probe refuses without
disturbing the outer push.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Q4oCSX5MzcTAVKFWzFvZ9x