Merge pull request #1595 from davesienkowski/feat/1592-plan-drift-precheck

feat(#1592): add plan:pre codebase-drift pre-check before planner runs

tests/enh-1592-plan-drift-precheck.test.cjs

@@ -0,0 +1,177 @@
+'use strict';
+// allow-test-rule: source-text-is-the-product see #1592
+// The plan-phase.md host-dispatch assertions below read the workflow .md file — its text IS the
+// deployed contract the runtime loads (CONTRIBUTING.md exemption category). The registry assertions
+// are behavioral: they build the registry from the REAL capabilities/drift declaration via the
+// generator, so they fail if the plan:pre gate is ever removed or mutated.
+
+/**
+ * Enhancement (#1592): plan-time codebase-map freshness pre-check.
+ *
+ * The `drift` capability gains a non-blocking `plan:pre` codebase-drift gate so a stale codebase map is
+ * flagged BEFORE planning, instead of being discovered mid-execution by the existing
+ * `execute:wave:post` codebase-drift gate. Warn-only at `plan:pre` (no mapper-agent spawn): the
+ * capability's `drift_action: auto-remap` stays at `execute:wave:post`, so plan time never pays
+ * speculative mapper-agent cost.
+ *
+ * Per maintainer review on #1592 (mod 1a), the plan:pre gate is gated on a DEDICATED
+ * `workflow.plan_drift_precheck` toggle (default true) rather than reusing `workflow.schema_drift_gate`,
+ * so autonomous/CI runs can silence the plan-time advisory without disabling the execute-time gates.
+ * The gate declaration conforms to ADR-857 (`plan:pre` is an enumerated, additive-only loop point).
+ *
+ * Issue: #1592 (open-gsd/gsd-core).
+ */
+
+const { describe, test, after } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { loadAndValidate, buildRegistry } = require('../scripts/gen-capability-registry.cjs');
+const { cleanup } = require('./helpers.cjs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const DRIFT_CAP = JSON.parse(
+  fs.readFileSync(path.join(REPO_ROOT, 'capabilities', 'drift', 'capability.json'), 'utf8'),
+);
+const PLAN_PHASE = fs.readFileSync(
+  path.join(REPO_ROOT, 'gsd-core', 'workflows', 'plan-phase.md'),
+  'utf8',
+);
+
+// Track every temp dir created so the suite can remove them on teardown — leaked
+// mkdtemp dirs have been a flake source here before (per #1592 review).
+const tempCapDirs = [];
+
+function makeTempCapDir(capabilities) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'enh-1592-'));
+  tempCapDirs.push(tmpDir);
+  for (const [id, cap] of Object.entries(capabilities)) {
+    const subDir = path.join(tmpDir, id);
+    fs.mkdirSync(subDir, { recursive: true });
+    fs.writeFileSync(path.join(subDir, 'capability.json'), JSON.stringify(cap), 'utf8');
+  }
+  return tmpDir;
+}
+
+after(() => {
+  for (const dir of tempCapDirs) {
+    cleanup(dir);
+  }
+});
+
+function planPreDriftGate() {
+  const capDir = makeTempCapDir({ drift: DRIFT_CAP });
+  const { capMap, errors } = loadAndValidate(new Set(), capDir);
+  assert.deepEqual(errors, [], 'drift capability should validate cleanly: ' + JSON.stringify(errors));
+  const registry = buildRegistry(capMap);
+  const planPreGates = registry.byLoopPoint['plan:pre'].gates;
+  assert.ok(Array.isArray(planPreGates), 'plan:pre.gates should be an array');
+  return planPreGates.find(
+    (g) => g.capId === 'drift' && g.check && g.check.query === 'verify.codebase-drift',
+  );
+}
+
+describe('#1592 — drift plan:pre codebase-drift gate (registry, behavioral)', () => {
+  test('the real drift capability registers a non-blocking plan:pre codebase-drift gate', () => {
+    const driftGate = planPreDriftGate();
+    assert.ok(driftGate, 'plan:pre.gates must contain the drift codebase-drift gate');
+    assert.strictEqual(driftGate.blocking, false, 'plan-time drift gate must be NON-blocking');
+    assert.strictEqual(driftGate.onError, 'skip', 'must fail-soft (skip) — never halt planning');
+  });
+
+  test('the plan:pre gate is gated on the dedicated plan_drift_precheck toggle (mod 1a)', () => {
+    const driftGate = planPreDriftGate();
+    assert.strictEqual(
+      driftGate.when,
+      'workflow.plan_drift_precheck',
+      'plan:pre drift gate must use the dedicated toggle so CI/autonomous runs can silence it ' +
+        'without disabling the execute-time gates',
+    );
+  });
+
+  test('the execute:wave:post codebase-drift gate is preserved and keeps its OWN toggle (no regression)', () => {
+    const capDir = makeTempCapDir({ drift: DRIFT_CAP });
+    const { capMap } = loadAndValidate(new Set(), capDir);
+    const registry = buildRegistry(capMap);
+
+    const execGates = registry.byLoopPoint['execute:wave:post'].gates;
+    const stillThere = execGates.find(
+      (g) => g.capId === 'drift' && g.check && g.check.query === 'verify.codebase-drift',
+    );
+    assert.ok(stillThere, 'execute:wave:post codebase-drift gate must remain after adding the plan:pre gate');
+    assert.strictEqual(stillThere.blocking, false, 'execute codebase-drift gate stays non-blocking');
+    assert.strictEqual(
+      stillThere.when,
+      'workflow.schema_drift_gate',
+      'the execute-time gate keeps schema_drift_gate — the plan-time toggle is separable from it',
+    );
+  });
+
+  test('plan_drift_precheck is a separate toggle from schema_drift_gate (silencing is independent)', () => {
+    const planWhen = planPreDriftGate().when;
+    assert.notStrictEqual(
+      planWhen,
+      'workflow.schema_drift_gate',
+      'silencing the plan-time advisory must not require disabling the execute-time gates',
+    );
+  });
+
+  test('plan_drift_precheck is declared as a boolean defaulting to true', () => {
+    const cfg = DRIFT_CAP.config['workflow.plan_drift_precheck'];
+    assert.ok(cfg, 'workflow.plan_drift_precheck must be declared in the drift capability config');
+    assert.strictEqual(cfg.type, 'boolean', 'plan_drift_precheck must be a boolean');
+    assert.strictEqual(cfg.default, true, 'plan_drift_precheck must default to true (on by default)');
+  });
+
+  test('exactly one new config key is introduced (the dedicated plan_drift_precheck toggle)', () => {
+    const keys = Object.keys(DRIFT_CAP.config).sort();
+    assert.deepStrictEqual(
+      keys,
+      [
+        'workflow.drift_action',
+        'workflow.drift_threshold',
+        'workflow.plan_drift_precheck',
+        'workflow.schema_drift_gate',
+      ],
+      'the plan:pre gate adds exactly the dedicated plan_drift_precheck toggle — no other new keys',
+    );
+  });
+});
+
+describe('#1592 — plan-phase host dispatches the drift plan:pre gate before planning', () => {
+  const SECTION = PLAN_PHASE.slice(
+    PLAN_PHASE.indexOf('5.65. Codebase Map Freshness Pre-Check'),
+    PLAN_PHASE.indexOf('## 6. Check Existing Plans'),
+  );
+
+  test('§5.65 invokes the verify codebase-drift check', () => {
+    assert.match(PLAN_PHASE, /5\.65\. Codebase Map Freshness Pre-Check/, 'plan-phase must declare §5.65');
+    assert.match(PLAN_PHASE, /gsd_run verify codebase-drift/, '§5.65 must invoke `verify codebase-drift`');
+  });
+
+  test('the drift pre-check runs BEFORE the planner spawn (load-bearing ordering)', () => {
+    const preCheckIdx = PLAN_PHASE.indexOf('5.65. Codebase Map Freshness Pre-Check');
+    const plannerIdx = PLAN_PHASE.indexOf('## 8. Spawn gsd-planner Agent');
+    assert.ok(preCheckIdx > 0, '§5.65 must exist');
+    assert.ok(plannerIdx > 0, '§8 planner spawn must exist');
+    assert.ok(
+      preCheckIdx < plannerIdx,
+      'the drift map-freshness pre-check must run before the planner is spawned — the whole point of #1592',
+    );
+  });
+
+  test('§5.65 is documented as non-blocking and warn-only (no spawn)', () => {
+    assert.match(SECTION, /non-blocking/i, '§5.65 must state the gate is non-blocking');
+    assert.match(SECTION, /never blocks, never spawns/i, '§5.65 must state it never spawns the mapper at plan time');
+  });
+
+  test('§5.65 gates on the dedicated plan_drift_precheck toggle (mod 1a)', () => {
+    assert.match(
+      SECTION,
+      /workflow\.plan_drift_precheck/,
+      '§5.65 must dispatch on the dedicated plan_drift_precheck toggle, not schema_drift_gate',
+    );
+  });
+});

tests/plan-pre-hook-e2e.test.cjs

@@ -253,6 +253,7 @@ describe('plan:pre all-off — empty resolution', () => {
         research: false,
         pattern_mapper: false,
         schema_push_detection: false,
+        plan_drift_precheck: false,
       },
       intel: { enabled: false },
     });

tests/workflow-size-baseline.json

@@ -52,7 +52,7 @@
   "note.md": 6563,
   "pause-work.md": 14397,
   "plan-milestone-gaps.md": 11765,
-  "plan-phase.md": 93166,
+  "plan-phase.md": 93973,
   "plan-review-convergence.md": 23468,
   "plant-seed.md": 11741,
   "pr-branch.md": 15919,