Project output avoids Home resolution

Traceability

• Spec ID: project-output-home-resolution
• Status: Implemented

Intent

Allow record-fix-output to record verified Project-scoped output even when the current process Home directory is unavailable or cannot be canonicalized. This keeps Project output validation independent of unrelated Global-scope state.

Acceptance Scenarios

• AC-1: A result whose actualOutput entries are all scope: "Project" is accepted when every referenced file exists within the canonical workspace, even if HOME and USERPROFILE point to a non-existent directory.
• AC-2: A scope: "Global" output resolves and canonicalizes the process Home on demand, accepts an existing ~/... file within that canonical Home, and fails without writing the report when Home is unavailable.
• AC-3: Project output continues to require an existing file and rejects a canonical target that escapes the workspace.

Non-goals

• Change output schemas, CLI arguments, or result consumption behavior.
• Relax existing-file, realpath, or scope-containment validation.
• Add test-only production API parameters or alter host environment state.

Plan and Tasks

1. Add a deterministic CLI regression test that invokes record-fix-output with only Project output in a child process whose HOME and USERPROFILE refer to a non-existent directory.
2. Confirm the regression fails against the current eager Home resolution.
3. Make Home canonicalization lazy in assertOutputTargets, retaining the existing workspace canonicalization and Global validation behavior.
4. Run focused, task-loop, documentation-link, packaging, and practical full test gates; record any environment limitation.

Test and Review Evidence

• AC-1: node --test test/task-loop-report.test.mjs exercises the isolated child-process regression and verifies a successful JSON CLI result.
• AC-2: node --test test/task-loop-report.test.mjs runs isolated Global success and unavailable-Home failure cases; the latter verifies the JSON error envelope and that findings bytes are unchanged.
• AC-3: existing record-fix-output cases retain automated Project existing-file rejection. Focused source review confirms the canonical realpath containment check and its validation order are unchanged.
• Documentation: regenerate docs/better-harness-doc-links.mmd and run node --test test/doc-link-graph.test.mjs after adding this spec.
• Packaging: run npm run pack:verify; run npm test when the local runtime can complete the full suite.
• Risk: os.homedir() stays intentionally reachable for Global output only; a regression could weaken containment only if lazy initialization is applied to the wrong scope, which focused scope tests mitigate.

Observed Evidence (2026-07-30)

• Pre-fix regression: temporarily restoring eager Home resolution made the new Project-only child-process test fail with exit code 1.
• Focused gate: node --test --test-name-pattern="record-fix-output" test/task-loop-report.test.mjs passed 10/10.
• Task-loop gate: node --test test/task-loop-report.test.mjs passed 76/76.
• Documentation gate: the routing graph had no semantic diff and node --test test/doc-link-graph.test.mjs passed 6/6.
• Full regression: npm test exited 0; the suite retained its existing Windows symlink-permission skip.
• Package gate: npm run pack:verify passed using an isolated temporary npm cache, which was removed afterward.
• Environment limitation: Node v22.17.0 and npm 10.9.2 are below the repository minimums of Node 22.20.0 and npm 10.9.3.