fix(#3639): dir-aware sentinel recognition for the disk-side guards (#3698)

* test(#3639): pin bracket sentinel recognition in disk-side guards

* fix(#3639): dir-aware sentinel recognition for the disk-side guards

* chore(#3639): add changeset

* fix(#3639): disclose the digit-continuation residual, join phases-clear, load-bearing over-suppression guard

* test(#3639): match the token form W007 reports

* chore(#3639): backfill changeset pr number

---------

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

tests/adr-612-bracket-grammar.test.cjs

@@ -260,6 +260,46 @@ describe('bracket grammar: sentinel guard', () => {
     assert.strictEqual(core.isSentinelPhaseId('feature-branch'), false);
   });
 
+  test('#3639: isSentinelPhaseDir reads the MILESTONE off a bracket dir name, convention-less', () => {
+    // The disk-side guards see raw DIRECTORY names and do not know the repo's
+    // convention. isSentinelPhaseDir recognizes the full bracket dir shape
+    // (code prefix, dot, MILESTONE digits, hyphen, PHASE digits) so sentinel
+    // milestone dirs are recognized without a convention argument.
+    assert.strictEqual(core.isSentinelPhaseDir('GSD.999-07-icebox'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('GSD.00-01-backlog'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('GSD.000-01-padded'), true);
+    // Ordinary bracket milestones: not sentinels.
+    assert.strictEqual(core.isSentinelPhaseDir('GSD.03-01-auth'), false);
+    assert.strictEqual(core.isSentinelPhaseDir('GSD.998-01-near-icebox'), false);
+    // Legacy sentinel dirs keep their recognition through the same helper.
+    assert.strictEqual(core.isSentinelPhaseDir('999-interim'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('0-drafts'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('M-999-07-icebox'), true);
+  });
+
+  test('#3639: isSentinelPhaseDir never re-reads #1324 letter-prefixed REAL dirs as bracket sentinels', () => {
+    // ADR-2121 indistinguishability: the bracket branch requires PHASE DIGITS
+    // after the milestone hyphen — `P0.0-foundation` (letters after the
+    // hyphen) never matches it, and the legacy branch already returns false
+    // for these (pinned in the suite above).
+    assert.strictEqual(core.isSentinelPhaseDir('P0.0-foundation'), false);
+    assert.strictEqual(core.isSentinelPhaseDir('P0.999-x'), false);
+    assert.strictEqual(core.isSentinelPhaseDir('P0.3-2'), false);
+  });
+
+  test('#3639 disclosed residual: #1324 digit-continuation dirs with a SENTINEL-valued first decimal read as bracket sentinels', () => {
+    // ADR-2121: `{code}.{0|999}-{digit}...` is string-indistinguishable from
+    // a bracket sentinel dir — no convention-free discriminator exists. The
+    // dir-aware recognizer takes the sentinel reading (conservative at the
+    // disk-guard sites: a suppressed warning, never deleted data), while the
+    // NON-sentinel first decimals stay ordinary. Pinned so a change to either
+    // reading is a deliberate act, not drift.
+    assert.strictEqual(core.isSentinelPhaseDir('P0.0-1-foundation'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('P0.999-2-x'), true);
+    assert.strictEqual(core.isSentinelPhaseDir('P0.3-2'), false);
+    assert.strictEqual(core.isSentinelPhaseDir('P0.1-2-x'), false);
+  });
+
   test('the bracket sentinel path is OFF by default: a convention-less #1324 dir is not a sentinel', () => {
     // `P0.0-foundation` is a real #1324 letter-prefixed phase, NOT milestone-0
     // sentinel. Auto-detecting the `P0`/`.0` prefix would be a false positive

tests/health-diagnostic-rules/roadmap-disk-consistency.test.cjs

@@ -224,6 +224,61 @@ describe('W007 — disk dir with no ROADMAP entry', () => {
     assert.deepEqual(ruleFor('W007').check(snapshot), []);
   });
 
+  test('#3639: does not fire for a BRACKET icebox directory (GSD.999-07-icebox) even with no roadmap entry', (t) => {
+    // Bracket sentinel-ness lives in the MILESTONE portion ({CODE}.999-{PP});
+    // the convention-less predicate read only the phase token and never saw it.
+    const cwd = createTempDir('gsd-3639-w007-bracket-ice-');
+    t.after(() => cleanup(cwd));
+    writeRoadmap(cwd, ['## GSD.03 Current 🚧', '', '### Phase 3.1: Foo'].join('\n'));
+    makePhaseDir(cwd, 'GSD.03-01-foo');
+    makePhaseDir(cwd, 'GSD.999-07-icebox');
+
+    const snapshot = buildPlanningSnapshot(cwd);
+    const diagnostics = ruleFor('W007').check(snapshot);
+    assert.deepEqual(
+      diagnostics.filter((d) => d.message.includes('999-07-icebox')),
+      [],
+      `a bracket icebox dir is never-on-roadmap by convention — no orphan warning. Got: ${JSON.stringify(diagnostics)}`,
+    );
+  });
+
+  test('#3639: does not fire for a BRACKET pre-milestone directory (GSD.00-01-backlog)', (t) => {
+    const cwd = createTempDir('gsd-3639-w007-bracket-pre-');
+    t.after(() => cleanup(cwd));
+    writeRoadmap(cwd, ['## GSD.03 Current 🚧', '', '### Phase 3.1: Foo'].join('\n'));
+    makePhaseDir(cwd, 'GSD.03-01-foo');
+    makePhaseDir(cwd, 'GSD.00-01-backlog');
+
+    const snapshot = buildPlanningSnapshot(cwd);
+    const diagnostics = ruleFor('W007').check(snapshot);
+    assert.deepEqual(
+      diagnostics.filter((d) => d.message.includes('00-01-backlog')),
+      [],
+      `a bracket pre-milestone dir is never-on-roadmap by convention. Got: ${JSON.stringify(diagnostics)}`,
+    );
+  });
+
+  test('#3639 over-suppression guard: an UNCLAIMED ordinary #1324 digit-continuation dir still fires W007', (t) => {
+    // The disclosed residual (#3639 review): #1324 dirs with a SENTINEL-valued
+    // first decimal (`P0.0-1-x`) are indistinguishable from bracket sentinels
+    // and read as sentinel (suppressed). This row pins that the family is not
+    // BLANKET-suppressed: a NON-sentinel first decimal (`P0.1-2-x`), unclaimed,
+    // must still fire — otherwise the recognizer would silently swallow every
+    // letter-prefixed real dir.
+    const cwd = createTempDir('gsd-3639-w007-over-sup-');
+    t.after(() => cleanup(cwd));
+    writeRoadmap(cwd, ['## v1.0 Current 🚧', '', '### Phase 1: Foo'].join('\n'));
+    makePhaseDir(cwd, '01-foo');
+    makePhaseDir(cwd, 'P0.1-2-x');
+
+    const snapshot = buildPlanningSnapshot(cwd);
+    const diagnostics = ruleFor('W007').check(snapshot);
+    assert.ok(
+      diagnostics.some((d) => d.message.includes('P0.1-2')),
+      `an unclaimed ordinary #1324 digit-continuation dir must still fire W007 (the message names the extracted token, not the full dir). Got: ${JSON.stringify(diagnostics)}`,
+    );
+  });
+
   test('boundary: zero declared phases and zero phase directories produces zero findings', (t) => {
     const cwd = createTempDir('gsd-3309-w007-4-');
     t.after(() => cleanup(cwd));