refactor(#3217): withhold a percentage when its scope is not complete (#3318)

* wip(#3217): rule-4 scope withholding — parked, two open findings

Implemented but NOT shippable. An isolated review found buildStateFrontmatter
still hardcodes SCOPE.COMPLETE, so state json reports percent 0 where roadmap
analyze, stats and query progress all correctly report null on the same disk
state - rule 4 reintroduced at a site this phase claims to close. Also: roadmap
analyze emits scope complete beside progress_percent null with nothing
explaining it.

Parked to build Phase 4 (#3186) first, which is unblocked. Findings recorded in
.gsd/phase/refactor-3217-completion-ratio-scoping/60-review.json.

* fix(#3217): withhold the sync percentage on a non-complete scope

The parked blocker is fixed - buildStateFrontmatter no longer hardcodes
SCOPE.COMPLETE, and the prose Progress fallback is gated too, which was a second
leak found while tracing the first. roadmap analyze exposes progress_scope so a
consumer can tell WHY a percentage is absent from the JSON alone.

Then a residual gap was reproduced rather than assumed. cmdStateSync carried the
same hardcode behind a written reason claiming it did not reproduce. It did: on a
TRUNCATED window and on UNSCOPED row 4, state sync wrote Progress 0 percent to 100
percent while state json, roadmap analyze, stats and query progress all withheld -
and it persisted a self-contradictory file, body claiming 100 percent while its own
frontmatter correctly omitted percent.

The excuse was also wrong. syncRoadmapRaw is already parsed in that function and is
exactly what produces a real scope, so there was a scope to pass. Threaded through
listMilestonePhaseDirs; a non-complete scope now skips the write with a reason in
changes. milestoneBounded stays as the orthogonal 1761 guard for row 5.

Second time this epic a does-not-reproduce claim was too generous. Recorded in
ADR Amendment 8 as a correction rather than a quiet rewrite.

Verified on the remote runner.

* test(#3217): give the withholding fixtures a resolvable scope

40 matrix failures, all fixture drift - no code regression. My own hypothesis
that this was over-withholding was wrong and is recorded as such: the worry case,
a plain ROADMAP with Phase entries and no version heading, resolves to complete
exactly as ADR 7.1 says it should.

The real causes were two fixture shapes. Most had no ROADMAP.md at all, which is
unreadable via a pre-existing graceful path, and asserted a numeric percent. The
five vscode, pi-extension, mcp-server and shell-projection failures were that
shape - bare temp dirs using progress json as a reachability proxy while
asserting typeof percent is number, which under rule 4 is now null.

The rest had a version token in a title or heading with no STATE.md milestone
pointer to resolve it, which is classification row 4, versioned but unresolved,
so withholding is correct per the contract.

Verified on the remote runner.

* test(#3217): make the LM-tools reachability tests dispatch against their fixture

The gsd_progress reachability test was never testing its fixture. invoke()
resolves cwd from vscode.workspace.workspaceFolders by design (the real
LanguageModelToolInvocationOptions has no cwd field, per the 2103 fix in
extension.js), the mock had no workspace at all, and the test passed a cwd option
nothing reads - so it dispatched against the repo working directory. Writing a
ROADMAP into the temp dir had no effect. Rule 4 only made it visible.

Fixed by mocking workspaceFolders. The two siblings in the same file carried the
identical dead cwd and were dispatching against the repo too; they were not
failing only because their assertions did not touch scope-dependent output. Both
now use their own fixture with assertions unchanged - the no-planning fallback
paths already satisfy them honestly.

Re-scanned the other five reachability files: no further instances. They thread
cwd into parameters that genuinely read it, not through an options shape that
ignores it.

Verified on the remote runner.

* chore(#3217): backfill changeset PR number

pr:0 placeholder replaced with the real number now that #3318 exists.

* ci(#3217): give the coverage merge enough heap for the merged shards

The coverage gate OOMed at exit 134. c8 report merges three shard artifacts,
roughly 358MB of V8 dumps in coverage/tmp, and died holding their per-file
position maps at the ~4GB default heap. Verified as this branch's delta rather
than pre-existing: the same job succeeded on next at 14:18, after phases 4 and 5
merged.

Both coverage-gate steps get the bump because both re-slice the same merged data.
8192 doubles what failed and leaves headroom on a 16GB ubuntu runner, matching
the idiom the shard step already uses at 6144.

This is a memory bound, not a change to what is measured. No threshold was
touched. The test file was checked for gratuitous subprocess spawning and is
already reasonable at 43 spawns, each a distinct fixture-by-surface pairing.

Verified on the remote runner.

---------

Co-authored-by: sim <sim@local>

tests/vscode-lm-tools.test.cjs

@@ -19,6 +19,8 @@
 
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
 
 const pkg = require('../vscode/package.json');
 const extension = require('../vscode/extension.js');
@@ -32,7 +34,15 @@ class FakeToolResult {
   constructor(parts) { this.parts = parts; }
 }
 
-function mockVscodeLm() {
+// `workspaceCwd`: createLanguageModelTool's invoke() resolves cwd via
+// resolveWorkspaceCwd(vscode) — vscode.workspace.workspaceFolders[0].uri.fsPath
+// — NOT via a `cwd` field on the invoke() options object (LanguageModelToolInvocationOptions
+// has no such field on the real API; see extension.js's #2103 FIX comment on
+// createLanguageModelTool). A test that wants a real dispatch to run against a
+// fixture directory must mock workspace.workspaceFolders here, not pass
+// `{ cwd }` in the options object handed to invoke() (that field is simply
+// never read).
+function mockVscodeLm(workspaceCwd) {
   const registered = [];
   return {
     lm: {
@@ -41,6 +51,9 @@ function mockVscodeLm() {
         return { dispose() {} };
       },
     },
+    workspace: workspaceCwd
+      ? { workspaceFolders: [{ uri: { fsPath: workspaceCwd } }] }
+      : undefined,
     LanguageModelTextPart: FakeTextPart,
     LanguageModelToolResult: FakeToolResult,
     registered,
@@ -89,11 +102,20 @@ test('REACHABILITY (desktop): registerLanguageModelTools registers every manifes
 test('REACHABILITY (desktop): gsd_progress tool.invoke() dispatches through the hub and returns REAL output', async () => {
   const dir = createTempDir();
   try {
-    const mock = mockVscodeLm();
+    // #3217 (ADR-3180 §7.6 rule 4): a free-form ROADMAP.md (no version
+    // token) is COMPLETE scope for windowing (§7.1) — without this, a
+    // bare temp dir has no ROADMAP.md at all (UNREADABLE) and `percent`
+    // is withheld (null), breaking this reachability proxy.
+    fs.mkdirSync(path.join(dir, '.planning'), { recursive: true });
+    fs.writeFileSync(path.join(dir, '.planning', 'ROADMAP.md'), '# Roadmap\n');
+    // The LM tool's invoke() resolves cwd via vscode.workspace.workspaceFolders
+    // (resolveWorkspaceCwd), not via an options.cwd field — pass the fixture
+    // dir through the mock's workspace so dispatch actually runs against it.
+    const mock = mockVscodeLm(dir);
     extension.registerLanguageModelTools(mock, { subscriptions: [] });
     const progressTool = mock.registered.find((r) => r.name === 'gsd_progress');
     assert.ok(progressTool, 'gsd_progress must be registered');
-    const result = await progressTool.impl.invoke({ input: {}, cwd: dir }, {});
+    const result = await progressTool.impl.invoke({ input: {} }, {});
     assert.ok(result instanceof FakeToolResult, 'invoke must return a LanguageModelToolResult');
     assert.ok(Array.isArray(result.parts) && result.parts.length === 1);
     assert.ok(result.parts[0] instanceof FakeTextPart, 'result part must be a LanguageModelTextPart');
@@ -107,11 +129,14 @@ test('REACHABILITY (desktop): gsd_progress tool.invoke() dispatches through the
 test('REACHABILITY (desktop): gsd_plan_phase tool.invoke() forwards the "phase" input through dispatch (real, not UnknownCommand)', async () => {
   const dir = createTempDir();
   try {
-    const mock = mockVscodeLm();
+    // The LM tool's invoke() resolves cwd via vscode.workspace.workspaceFolders
+    // (resolveWorkspaceCwd), not via an options.cwd field — pass the fixture
+    // dir through the mock's workspace so dispatch actually runs against it.
+    const mock = mockVscodeLm(dir);
     extension.registerLanguageModelTools(mock, { subscriptions: [] });
     const planPhaseTool = mock.registered.find((r) => r.name === 'gsd_plan_phase');
     assert.ok(planPhaseTool);
-    const result = await planPhaseTool.impl.invoke({ input: { phase: 'nonexistent-phase-8675309' }, cwd: dir }, {});
+    const result = await planPhaseTool.impl.invoke({ input: { phase: 'nonexistent-phase-8675309' } }, {});
     const parsed = JSON.parse(result.parts[0].text);
     // Real dispatch reaches gsd-tools.cjs and returns a structured "phase not
     // found" response (proves the engine was reached) — not the manifest's
@@ -126,10 +151,13 @@ test('REACHABILITY (desktop): gsd_plan_phase tool.invoke() forwards the "phase"
 test('gsd_workstreams tool.invoke() dispatches through the hub and returns REAL output', async () => {
   const dir = createTempDir();
   try {
-    const mock = mockVscodeLm();
+    // The LM tool's invoke() resolves cwd via vscode.workspace.workspaceFolders
+    // (resolveWorkspaceCwd), not via an options.cwd field — pass the fixture
+    // dir through the mock's workspace so dispatch actually runs against it.
+    const mock = mockVscodeLm(dir);
     extension.registerLanguageModelTools(mock, { subscriptions: [] });
     const wsTool = mock.registered.find((r) => r.name === 'gsd_workstreams');
-    const result = await wsTool.impl.invoke({ input: {}, cwd: dir }, {});
+    const result = await wsTool.impl.invoke({ input: {} }, {});
     const parsed = JSON.parse(result.parts[0].text);
     assert.ok('workstreams' in parsed || 'mode' in parsed, 'expected a real workstream list response shape');
   } finally {