Merge pull request #2490 from open-gsd/docs/2481-adr-1239-effort-axis

feat(#2481): add a negotiated effortSurface axis and wire invocation-time effort
2026-07-21 20:14:27 -04:00
parent 3878dbdf02 ecef1e1670
commit d39ca0c004
51 changed files with 863 additions and 100 deletions
--- a/tests/effort-surface-axis.test.cjs
+++ b/tests/effort-surface-axis.test.cjs
@@ -0,0 +1,408 @@
+// allow-test-rule: source-text-is-the-product (see #2481)
+// The final describe block asserts on gsd-core/workflows/review.md's text. A
+// workflow .md IS what the runtime loads — its literal command lines are the
+// deployed contract, and there is no runtime seam that executes review.md here.
+// Every other block in this file is behavioral (CLI + module surface).
+
+/**
+ * #2481 — ADR-1239 `effortSurface` axis + ADR-443 path (a).
+ *
+ * Before this change effort reached a runtime only through install-time channels
+ * (EFFORT_RENDERING's `frontmatter`/`api`), so a reviewer CLI spawned as a
+ * subprocess silently inherited whatever effort sat in the user's own global CLI
+ * config. These tests pin the invocation-time channel: the negotiated axis that
+ * decides WHETHER effort is deliverable, the renderer that knows the syntax, and
+ * the live orchestration path that carries it.
+ */
+
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const fc = require('fast-check');
+
+const { runGsdTools, createTempProject, cleanup } = require('./helpers.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const {
+  renderEffortArgv,
+  EFFORT_ARGV,
+} = require(path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'model-catalog.cjs'));
+const {
+  HOST_INTEGRATION_AXES,
+  negotiateHostCapabilities,
+  degradationFor,
+} = require(path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'host-integration.cjs'));
+const {
+  _HOST_INTEGRATION_VOCAB,
+  validateRuntimeBody,
+} = require(path.join(REPO_ROOT, 'gsd-core', 'bin', 'lib', 'capability-validator.cjs'));
+
+/**
+ * A real shipped descriptor with one hostIntegration axis stripped.
+ *
+ * Deriving the fixture from a descriptor this gate did not author satisfies the
+ * fixture-provenance rule (#2371) — a hand-built body would only ever encode the
+ * author's mental model of a valid descriptor, which is how the required-axis
+ * defect reached the runner in the first place.
+ */
+function shippedDescriptorWithout(axis) {
+  const cap = JSON.parse(
+    fs.readFileSync(path.join(REPO_ROOT, 'capabilities', 'vscode', 'capability.json'), 'utf8'),
+  );
+  delete cap.runtime.hostIntegration[axis];
+  return cap;
+}
+
+/** Write a project whose effort cascade resolves to a known universal value. */
+function projectWithEffort(effort) {
+  const dir = createTempProject();
+  fs.writeFileSync(
+    path.join(dir, '.planning', 'config.json'),
+    JSON.stringify({ effort: { default: effort } }, null, 2),
+  );
+  return dir;
+}
+
+describe('#2481 effortSurface — closed vocabulary', () => {
+  test('is exactly argv|none — no config-file member', () => {
+    // Gemini CLI was the only host with a config-file effort surface and was
+    // removed as a sunset runtime (8f2ebbe9b / #1928 / PR #1996). A member no
+    // supported host can claim would invite guessed descriptor values.
+    assert.deepEqual([...HOST_INTEGRATION_AXES.effortSurface], ['argv', 'none']);
+  });
+
+  test('engine vocabulary and validator mirror agree (parity guard)', () => {
+    assert.deepEqual(
+      [...HOST_INTEGRATION_AXES.effortSurface],
+      [..._HOST_INTEGRATION_VOCAB.effortSurface],
+    );
+  });
+
+  test('undocumented is NOT a vocabulary member — it is the corpus sentinel', () => {
+    assert.ok(!HOST_INTEGRATION_AXES.effortSurface.includes('undocumented'));
+  });
+});
+
+describe('#2481 effortSurface — negotiation fails closed', () => {
+  const cases = [
+    ['argv declared', 'argv', 'argv'],
+    ['undocumented sentinel', 'undocumented', 'none'],
+    ['retired value (config-file)', 'config-file', 'none'],
+    ['unknown/future value', 'quantum-telepathy', 'none'],
+    ['empty string', '', 'none'],
+    ['none declared', 'none', 'none'],
+  ];
+  for (const [label, declared, expected] of cases) {
+    test(`${label} -> ${expected}`, () => {
+      const r = negotiateHostCapabilities({ protocolVersion: 1, modelMode: 'active', effortSurface: declared });
+      assert.equal(r.effective.effortSurface, expected);
+    });
+  }
+
+  test('axis omitted entirely -> safe floor, and the omission is warned', () => {
+    const r = negotiateHostCapabilities({ protocolVersion: 1, modelMode: 'active' });
+    assert.equal(r.effective.effortSurface, 'none');
+    assert.ok(r.warnings.some((w) => String(w).includes('effortSurface')));
+  });
+
+  test('a descriptor that omits the axis entirely still validates clean', () => {
+    // The axis was added after descriptors existed. Requiring it would invalidate
+    // every pre-existing descriptor — including third-party ones — and break the
+    // "purely additive" property ADR-1239 promises for external descriptors.
+    // Regression guard: 48 suites failed across both node lanes when it was required.
+    const cap = shippedDescriptorWithout('effortSurface');
+    const errors = validateRuntimeBody(cap);
+    assert.deepEqual(
+      errors, [],
+      `a descriptor without effortSurface must validate clean, got: ${JSON.stringify(errors)}`,
+    );
+  });
+
+  test('optional does not mean unvalidated — a present bad value is still rejected', () => {
+    const cap = shippedDescriptorWithout('effortSurface');
+    cap.runtime.hostIntegration.effortSurface = 'config-file'; // retired value
+    const errors = validateRuntimeBody(cap);
+    assert.ok(
+      errors.some((e) => String(e).includes('effortSurface')),
+      `a present invalid value must error, got: ${JSON.stringify(errors)}`,
+    );
+  });
+
+  test('an undeclared axis is never invented from a profile baseline', () => {
+    // Regression guard for the failure this axis was designed against: a
+    // programmatic-cli host must not inherit `argv` merely by being programmatic.
+    const r = negotiateHostCapabilities({
+      protocolVersion: 1,
+      embeddingMode: 'imperative',
+      commandSurface: 'slash-file',
+      modelMode: 'active',
+    });
+    assert.equal(r.effective.effortSurface, 'none');
+  });
+});
+
+describe('#2481 effortSurface — is its own axis, not folded into the model point', () => {
+  test('the model interface point still grades on modelMode alone', () => {
+    // Deliberate: modelMode has graded interface point 3 since Phase A. Widening
+    // it to also mean "delivers effort" would silently redefine that contract for
+    // every existing consumer. Effort is read from effective.effortSurface.
+    assert.equal(degradationFor('model', { modelMode: 'active' }).level, 'full');
+    assert.equal(degradationFor('model', { modelMode: 'passive' }).level, 'degraded');
+  });
+
+  test('declaring an effort surface does not change the model point', () => {
+    for (const es of ['argv', 'none', 'undocumented', undefined]) {
+      assert.equal(degradationFor('model', { modelMode: 'active', effortSurface: es }).level, 'full');
+    }
+  });
+
+  test('degradationFor never throws on a malformed axes object', () => {
+    for (const axes of [{}, { modelMode: null }, { effortSurface: 42 }, { modelMode: 'active', effortSurface: [] }]) {
+      assert.ok(['full', 'degraded', 'absent'].includes(degradationFor('model', axes).level));
+    }
+  });
+});
+
+describe('#2481 renderEffortArgv — per-host syntax and clamping', () => {
+  test('claude renders --effort', () => {
+    assert.deepEqual(renderEffortArgv('claude', 'xhigh', 'argv').argv, ['--effort', 'xhigh']);
+  });
+
+  test('opencode renders --variant', () => {
+    assert.deepEqual(renderEffortArgv('opencode', 'high', 'argv').argv, ['--variant', 'high']);
+  });
+
+  test('codex renders the generic -c config override, not a dedicated flag', () => {
+    // codex-rs/exec/src/cli.rs: model_reasoning_effort is NOT a CLI flag
+    // (config.toml key only), so -c key=value is the only argv route.
+    assert.deepEqual(
+      renderEffortArgv('codex', 'high', 'argv').argv,
+      ['-c', 'model_reasoning_effort=high'],
+    );
+  });
+
+  test('clamps the provider-unique tail levels', () => {
+    // claude has no `minimal`; codex has no `max`.
+    assert.deepEqual(renderEffortArgv('claude', 'minimal', 'argv').argv, ['--effort', 'low']);
+    assert.deepEqual(renderEffortArgv('codex', 'max', 'argv').argv, ['-c', 'model_reasoning_effort=xhigh']);
+  });
+
+  test('emits nothing when the surface is not argv', () => {
+    for (const surface of ['none', 'undocumented', 'config-file', '', null, undefined]) {
+      assert.deepEqual(renderEffortArgv('claude', 'xhigh', surface).argv, []);
+    }
+  });
+
+  test('emits nothing for a host with no known syntax', () => {
+    for (const host of ['gemini', 'cursor', 'zcode', '']) {
+      assert.deepEqual(renderEffortArgv(host, 'high', 'argv').argv, []);
+    }
+  });
+
+  test('inherited Object members are not mistaken for host specs', () => {
+    // Regression guard: a bare EFFORT_ARGV[host] lookup resolves these to
+    // inherited members — truthy, but with no clamp/render — so a hostile host
+    // id from an untrusted descriptor threw instead of degrading.
+    for (const host of ['__proto__', 'constructor', 'toString', 'hasOwnProperty', 'valueOf']) {
+      assert.deepEqual(
+        renderEffortArgv(host, 'high', 'argv').argv, [],
+        `${host} must degrade to no argument, not throw`,
+      );
+    }
+  });
+
+  test('emits nothing for a missing or unrecognised effort level', () => {
+    for (const level of ['', 'bogus', 'HIGH', ' high', null, undefined, 42]) {
+      assert.deepEqual(renderEffortArgv('claude', level, 'argv').argv, []);
+    }
+  });
+
+  test('property: a rendered level is always inside that host\'s supported set', () => {
+    const hosts = Object.keys(EFFORT_ARGV);
+    const levels = ['minimal', 'low', 'medium', 'high', 'xhigh', 'max'];
+    fc.assert(
+      fc.property(fc.constantFrom(...hosts), fc.constantFrom(...levels), (host, level) => {
+        const r = renderEffortArgv(host, level, 'argv');
+        if (r.argv.length === 0) return true;
+        return EFFORT_ARGV[host].supported.has(r.value);
+      }),
+      { numRuns: 200, seed: 2481 },
+    );
+  });
+});
+
+describe('#2481 live path — resolve-execution carries invocation-time effort', () => {
+  test('--host renders the argument for an argv host', (t) => {
+    const dir = projectWithEffort('xhigh');
+    t.after(() => cleanup(dir));
+
+    const r = runGsdTools('query resolve-execution gsd-planner --host claude', dir);
+    assert.ok(r.success, `resolve-execution failed: ${r.error}`);
+    const out = JSON.parse(r.output);
+    assert.equal(out.effort, 'xhigh');
+    assert.equal(out.effort_surface, 'argv');
+    assert.deepEqual(out.effort_argv, ['--effort', 'xhigh']);
+    assert.equal(out.effort_argv_string, '--effort xhigh');
+  });
+
+  test('--host on a host without a documented surface renders nothing', (t) => {
+    const dir = projectWithEffort('xhigh');
+    t.after(() => cleanup(dir));
+
+    const out = JSON.parse(runGsdTools('query resolve-execution gsd-planner --host cursor', dir).output);
+    assert.equal(out.effort_surface, 'none');
+    assert.deepEqual(out.effort_argv, []);
+    assert.equal(out.effort_argv_string, '');
+  });
+
+  test('an unknown host degrades closed rather than erroring', (t) => {
+    const dir = projectWithEffort('high');
+    t.after(() => cleanup(dir));
+
+    const r = runGsdTools('query resolve-execution gsd-planner --host not-a-real-host', dir);
+    assert.ok(r.success, 'an unknown host must degrade, not fail');
+    const out = JSON.parse(r.output);
+    assert.equal(out.effort_surface, 'none');
+    assert.deepEqual(out.effort_argv, []);
+  });
+
+  test('omitting --host leaves the JSON contract untouched', (t) => {
+    const dir = projectWithEffort('high');
+    t.after(() => cleanup(dir));
+
+    const out = JSON.parse(runGsdTools('query resolve-execution gsd-planner', dir).output);
+    for (const k of ['host', 'effort_surface', 'effort_argv', 'effort_argv_string', 'effort_argv_value']) {
+      assert.ok(!(k in out), `--host absent must not add "${k}" to the contract`);
+    }
+  });
+
+  test('--host requires a value', (t) => {
+    const dir = projectWithEffort('high');
+    t.after(() => cleanup(dir));
+
+    const r = runGsdTools('query resolve-execution gsd-planner --host', dir);
+    assert.ok(!r.success, 'a valueless --host must be a usage error');
+  });
+
+  test('a shell-metacharacter host is not interpolated, just unmatched', (t) => {
+    const dir = projectWithEffort('high');
+    t.after(() => cleanup(dir));
+
+    const r = runGsdTools('query resolve-execution gsd-planner --host "claude; touch pwned"', dir);
+    assert.ok(r.success);
+    assert.deepEqual(JSON.parse(r.output).effort_argv, []);
+    assert.ok(!fs.existsSync(path.join(dir, 'pwned')), 'no shell interpolation of the host value');
+  });
+});
+
+describe('#2481 — the escalation surface renders argv (CLI-level, not a workflow claim)', () => {
+  // NAMING IS DELIBERATE. This exercises `resolve-execution --attempt` directly,
+  // which is the CLI surface ADR-443's blocker explicitly EXCLUDES when it asks
+  // for "a real caller outside src/commands.cts's CLI surface and tests". It
+  // proves the escalation ladder still renders a host argument; it does NOT
+  // prove any workflow escalates. The live workflow caller for Decision item 6
+  // is #2296's gsd-core/references/execute-phase-quota-recovery.md, asserted
+  // separately below.
+  test('--attempt walks the effort ladder above the configured default', (t) => {
+    const dir = createTempProject();
+    t.after(() => cleanup(dir));
+    fs.writeFileSync(
+      path.join(dir, '.planning', 'config.json'),
+      JSON.stringify({
+        effort: { default: 'low' },
+        dynamic_routing: { enabled: true, escalate_on_failure: true, max_escalations: 3 },
+      }, null, 2),
+    );
+
+    const at = (n) => JSON.parse(
+      runGsdTools(`query resolve-execution gsd-planner --host claude --attempt ${n}`, dir).output,
+    );
+
+    // attempt 0 is the un-escalated baseline; a later attempt must not be lower.
+    const base = at(0);
+    const later = at(2);
+    const RANK = { minimal: 0, low: 1, medium: 2, high: 3, xhigh: 4, max: 5 };
+    assert.equal(base.effort, 'low');
+    assert.ok(
+      RANK[later.effort] >= RANK[base.effort],
+      `escalation must not lower effort: attempt0=${base.effort} attempt2=${later.effort}`,
+    );
+    // Whatever the ladder resolved, it must still reach the host as an argument.
+    assert.equal(later.effort_surface, 'argv');
+    assert.deepEqual(later.effort_argv, ['--effort', later.effort]);
+  });
+
+  test('a negative --attempt is rejected', (t) => {
+    const dir = projectWithEffort('high');
+    t.after(() => cleanup(dir));
+    assert.ok(!runGsdTools('query resolve-execution gsd-planner --attempt -1', dir).success);
+  });
+});
+
+describe('#2481 — ADR-443 mechanism callers, as they actually exist', () => {
+  const quotaRecovery = fs.readFileSync(
+    path.join(REPO_ROOT, 'gsd-core', 'references', 'execute-phase-quota-recovery.md'),
+    'utf8',
+  );
+  const executePhase = fs.readFileSync(
+    path.join(REPO_ROOT, 'gsd-core', 'workflows', 'execute-phase.md'),
+    'utf8',
+  );
+
+  test('Decision item 6 (escalation) has its live caller — from #2296, not this change', () => {
+    assert.match(
+      quotaRecovery, /resolve-execution\s+gsd-executor\s+--attempt/,
+      'execute-phase-quota-recovery.md must invoke resolve-execution with --attempt (#2296)',
+    );
+    assert.ok(
+      executePhase.includes('references/execute-phase-quota-recovery.md'),
+      'that reference must be @-included into execute-phase.md, or it is not a live caller',
+    );
+  });
+
+  test('Decision item 1 (invocation override) still has NO live caller', () => {
+    // Guards the corrected ADR-443 claim. If someone later wires --effort into a
+    // workflow, this fails and the ADR status text must be revisited — that is
+    // the point: the ADR must not silently drift back to being wrong.
+    const dirs = ['gsd-core/workflows', 'gsd-core/references', 'agents', 'commands'];
+    const hits = [];
+    const walk = (d) => {
+      const abs = path.join(REPO_ROOT, d);
+      if (!fs.existsSync(abs)) return;
+      for (const e of fs.readdirSync(abs, { withFileTypes: true })) {
+        const full = path.join(abs, e.name);
+        if (e.isDirectory()) walk(path.relative(REPO_ROOT, full));
+        else if (e.name.endsWith('.md') && /resolve-execution[^\r\n]*--effort\s/.test(fs.readFileSync(full, 'utf8'))) {
+          hits.push(path.relative(REPO_ROOT, full));
+        }
+      }
+    };
+    dirs.forEach(walk);
+    assert.deepEqual(
+      hits, [],
+      `ADR-443 records Decision item 1 as having no live caller; found: ${JSON.stringify(hits)}. ` +
+      'Update the ADR-443 amendment before adding one.',
+    );
+  });
+});
+
+describe('#2481 review workflow resolves effort per reviewer', () => {
+  const reviewMd = fs.readFileSync(
+    path.join(REPO_ROOT, 'gsd-core', 'workflows', 'review.md'),
+    'utf8',
+  );
+
+  test('review.md invokes resolve-execution — the grep ADR-443 said returned zero hits', () => {
+    assert.ok(
+      reviewMd.includes('resolve-execution'),
+      'ADR-443 blocks on no shipped orchestration calling resolve-execution',
+    );
+  });
+
+  test('each argv reviewer receives its effort variable on the command line', () => {
+    for (const [cli, varName] of [['claude', 'CLAUDE_EFFORT_ARGS'], ['codex', 'CODEX_EFFORT_ARGS'], ['opencode', 'OPENCODE_EFFORT_ARGS']]) {
+      assert.ok(reviewMd.includes(`$${varName}`), `${cli} invocation must carry $${varName}`);
+    }
+  });
+});
--- a/tests/fixtures/golden-install-parity/antigravity.json
+++ b/tests/fixtures/golden-install-parity/antigravity.json
@@ -39,7 +39,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "ea841e2865248e74",
-  "gsd-core/bin/gsd-tools.cjs": "df767e8f2f10fd3b",
+  "gsd-core/bin/gsd-tools.cjs": "cd7a95ed8536c5bc",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -298,7 +298,7 @@
  "gsd-core/workflows/remove-phase.md": "23b9eb0858a2535e",
  "gsd-core/workflows/remove-workspace.md": "1058d1d3160eb120",
  "gsd-core/workflows/resume-project.md": "98e2cf8908e73a52",
-  "gsd-core/workflows/review.md": "6f6575621367b9ff",
+  "gsd-core/workflows/review.md": "cb4ed7b2b77bba35",
  "gsd-core/workflows/scan.md": "1feb5f040e426562",
  "gsd-core/workflows/secure-phase.md": "34c0aba32c922218",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/augment.json
+++ b/tests/fixtures/golden-install-parity/augment.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "df9a45f0b1880999",
  "gsd-core/workflows/remove-workspace.md": "f67860c795fb4bfe",
  "gsd-core/workflows/resume-project.md": "f28da1200e4545f4",
-  "gsd-core/workflows/review.md": "f1fbefbd64bd890e",
+  "gsd-core/workflows/review.md": "d4f26b05b3eff7f6",
  "gsd-core/workflows/scan.md": "e6424af05656725a",
  "gsd-core/workflows/secure-phase.md": "f8b9436c35372281",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/claude-local.json
+++ b/tests/fixtures/golden-install-parity/claude-local.json
@@ -109,7 +109,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -368,7 +368,7 @@
  "gsd-core/workflows/remove-phase.md": "8effc8742d58a11a",
  "gsd-core/workflows/remove-workspace.md": "64b73daff58b9aec",
  "gsd-core/workflows/resume-project.md": "af9761bcec0f6fe9",
-  "gsd-core/workflows/review.md": "8c05b76fe9d00c30",
+  "gsd-core/workflows/review.md": "9eb81c7c61cfe50e",
  "gsd-core/workflows/scan.md": "9126e95bf9c50f7e",
  "gsd-core/workflows/secure-phase.md": "396e2f708abfa7a1",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/claude.json
+++ b/tests/fixtures/golden-install-parity/claude.json
@@ -38,7 +38,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -297,7 +297,7 @@
  "gsd-core/workflows/remove-phase.md": "ada8a0546c686483",
  "gsd-core/workflows/remove-workspace.md": "015cde237c75be39",
  "gsd-core/workflows/resume-project.md": "7f8dc986f0f35d96",
-  "gsd-core/workflows/review.md": "013126685d8a9d50",
+  "gsd-core/workflows/review.md": "bba666ebc5e13130",
  "gsd-core/workflows/scan.md": "1890c846b98690bb",
  "gsd-core/workflows/secure-phase.md": "3f8fabf375f7d880",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/cline.json
+++ b/tests/fixtures/golden-install-parity/cline.json
@@ -42,7 +42,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "476aa24e8c4f03cf",
-  "gsd-core/bin/gsd-tools.cjs": "f737db8e3aa1ce61",
+  "gsd-core/bin/gsd-tools.cjs": "83c5cb31a129a87d",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -301,7 +301,7 @@
  "gsd-core/workflows/remove-phase.md": "e336350f8113a328",
  "gsd-core/workflows/remove-workspace.md": "79d3669cc9eb0b10",
  "gsd-core/workflows/resume-project.md": "e23981178fa37b3d",
-  "gsd-core/workflows/review.md": "075ea1aa6a2b8339",
+  "gsd-core/workflows/review.md": "b1c5ebc05398ca45",
  "gsd-core/workflows/scan.md": "aa2ddc734251c24c",
  "gsd-core/workflows/secure-phase.md": "f7c624c1ab3cde3f",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/codebuddy.json
+++ b/tests/fixtures/golden-install-parity/codebuddy.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "df9a45f0b1880999",
  "gsd-core/workflows/remove-workspace.md": "f67860c795fb4bfe",
  "gsd-core/workflows/resume-project.md": "f28da1200e4545f4",
-  "gsd-core/workflows/review.md": "f1fbefbd64bd890e",
+  "gsd-core/workflows/review.md": "d4f26b05b3eff7f6",
  "gsd-core/workflows/scan.md": "e6424af05656725a",
  "gsd-core/workflows/secure-phase.md": "f8b9436c35372281",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/codex.json
+++ b/tests/fixtures/golden-install-parity/codex.json
@@ -145,7 +145,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -404,7 +404,7 @@
  "gsd-core/workflows/remove-phase.md": "9ee0fddd11a0d9d4",
  "gsd-core/workflows/remove-workspace.md": "d0160c5d05bcb2bb",
  "gsd-core/workflows/resume-project.md": "9965f87eb278f7f8",
-  "gsd-core/workflows/review.md": "e4e61845190da702",
+  "gsd-core/workflows/review.md": "6c74f7151f41df8b",
  "gsd-core/workflows/scan.md": "9d331d74a5ad47e5",
  "gsd-core/workflows/secure-phase.md": "858ef74a9f247bd5",
  "gsd-core/workflows/session-report.md": "dd8fa011c9394075",
--- a/tests/fixtures/golden-install-parity/copilot.json
+++ b/tests/fixtures/golden-install-parity/copilot.json
@@ -40,7 +40,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "ea841e2865248e74",
-  "gsd-core/bin/gsd-tools.cjs": "df767e8f2f10fd3b",
+  "gsd-core/bin/gsd-tools.cjs": "cd7a95ed8536c5bc",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -299,7 +299,7 @@
  "gsd-core/workflows/remove-phase.md": "e262654e319d1bc4",
  "gsd-core/workflows/remove-workspace.md": "e7e5b5b1e0cc9d81",
  "gsd-core/workflows/resume-project.md": "40db7f350f5866d8",
-  "gsd-core/workflows/review.md": "a9f422db38ab8bb9",
+  "gsd-core/workflows/review.md": "31d6ec81b8c8dddc",
  "gsd-core/workflows/scan.md": "b8615653ffa85e12",
  "gsd-core/workflows/secure-phase.md": "3afa175ee48491af",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/cursor.json
+++ b/tests/fixtures/golden-install-parity/cursor.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "2525f1ae8b086828",
-  "gsd-core/bin/gsd-tools.cjs": "1c1255108c81fde6",
+  "gsd-core/bin/gsd-tools.cjs": "c4737aad8ff34691",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "ada8a0546c686483",
  "gsd-core/workflows/remove-workspace.md": "0572a83d71650937",
  "gsd-core/workflows/resume-project.md": "7f8dc986f0f35d96",
-  "gsd-core/workflows/review.md": "ea18faf9ff633667",
+  "gsd-core/workflows/review.md": "28a82741e3e8616d",
  "gsd-core/workflows/scan.md": "1890c846b98690bb",
  "gsd-core/workflows/secure-phase.md": "383a94ac2b089cc0",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/hermes.json
+++ b/tests/fixtures/golden-install-parity/hermes.json
@@ -39,7 +39,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "3a3409215044af9f",
-  "gsd-core/bin/gsd-tools.cjs": "38cc609e9d4cbc3c",
+  "gsd-core/bin/gsd-tools.cjs": "91cffa694a6becd3",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -298,7 +298,7 @@
  "gsd-core/workflows/remove-phase.md": "fce799aae3ab2715",
  "gsd-core/workflows/remove-workspace.md": "42029a7559f1d8fb",
  "gsd-core/workflows/resume-project.md": "a0443839f1f83c2d",
-  "gsd-core/workflows/review.md": "cde982eb704261ef",
+  "gsd-core/workflows/review.md": "9a7fd3c1c2bd617d",
  "gsd-core/workflows/scan.md": "6c340b901b5d5d18",
  "gsd-core/workflows/secure-phase.md": "07415614146d8601",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/kilo.json
+++ b/tests/fixtures/golden-install-parity/kilo.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "ada8a0546c686483",
  "gsd-core/workflows/remove-workspace.md": "f5dc82bb63e2efa4",
  "gsd-core/workflows/resume-project.md": "7f8dc986f0f35d96",
-  "gsd-core/workflows/review.md": "6033fab6d070c993",
+  "gsd-core/workflows/review.md": "9299d96d44252a8a",
  "gsd-core/workflows/scan.md": "1890c846b98690bb",
  "gsd-core/workflows/secure-phase.md": "7e1613050966ae28",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/kimi.json
+++ b/tests/fixtures/golden-install-parity/kimi.json
@@ -103,7 +103,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -362,7 +362,7 @@
  "gsd-core/workflows/remove-phase.md": "df9a45f0b1880999",
  "gsd-core/workflows/remove-workspace.md": "f67860c795fb4bfe",
  "gsd-core/workflows/resume-project.md": "f28da1200e4545f4",
-  "gsd-core/workflows/review.md": "f1fbefbd64bd890e",
+  "gsd-core/workflows/review.md": "d4f26b05b3eff7f6",
  "gsd-core/workflows/scan.md": "e6424af05656725a",
  "gsd-core/workflows/secure-phase.md": "f8b9436c35372281",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/opencode.json
+++ b/tests/fixtures/golden-install-parity/opencode.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "dea4661e8f89596f",
  "gsd-core/workflows/remove-workspace.md": "21a8581add5f31ae",
  "gsd-core/workflows/resume-project.md": "ad9f06a10bab8cc0",
-  "gsd-core/workflows/review.md": "fbe68c9f86385274",
+  "gsd-core/workflows/review.md": "a2c5d053c8ef6e27",
  "gsd-core/workflows/scan.md": "63cf8d9067610704",
  "gsd-core/workflows/secure-phase.md": "7ad9fd285facdef8",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/pi.json
+++ b/tests/fixtures/golden-install-parity/pi.json
@@ -6,7 +6,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -265,7 +265,7 @@
  "gsd-core/workflows/remove-phase.md": "df9a45f0b1880999",
  "gsd-core/workflows/remove-workspace.md": "f67860c795fb4bfe",
  "gsd-core/workflows/resume-project.md": "f28da1200e4545f4",
-  "gsd-core/workflows/review.md": "f1fbefbd64bd890e",
+  "gsd-core/workflows/review.md": "d4f26b05b3eff7f6",
  "gsd-core/workflows/scan.md": "e6424af05656725a",
  "gsd-core/workflows/secure-phase.md": "f8b9436c35372281",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/qwen.json
+++ b/tests/fixtures/golden-install-parity/qwen.json
@@ -39,7 +39,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "6e98d76e955e35a2",
-  "gsd-core/bin/gsd-tools.cjs": "982a6ff24abb8e59",
+  "gsd-core/bin/gsd-tools.cjs": "76bb73c8061771ac",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -298,7 +298,7 @@
  "gsd-core/workflows/remove-phase.md": "e8ae4fbbfac700f0",
  "gsd-core/workflows/remove-workspace.md": "ae520235f4d1f4a5",
  "gsd-core/workflows/resume-project.md": "7f20769f302e5427",
-  "gsd-core/workflows/review.md": "b3548b43dcf1fb4e",
+  "gsd-core/workflows/review.md": "5b59389282a276fc",
  "gsd-core/workflows/scan.md": "9ebe1d469171af0d",
  "gsd-core/workflows/secure-phase.md": "e5e8bf031e95cf1d",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/trae.json
+++ b/tests/fixtures/golden-install-parity/trae.json
@@ -39,7 +39,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "de4627dff103d527",
-  "gsd-core/bin/gsd-tools.cjs": "cafd8c05ee085279",
+  "gsd-core/bin/gsd-tools.cjs": "9767839b936030c7",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -298,7 +298,7 @@
  "gsd-core/workflows/remove-phase.md": "a46c2fe853bf4e86",
  "gsd-core/workflows/remove-workspace.md": "8ddc5f04f7c48d6c",
  "gsd-core/workflows/resume-project.md": "f242e4c8aba18ea2",
-  "gsd-core/workflows/review.md": "35d023ff48e3827f",
+  "gsd-core/workflows/review.md": "2e10545b307c867c",
  "gsd-core/workflows/scan.md": "a3ce29ceb62b8192",
  "gsd-core/workflows/secure-phase.md": "85112be3547bced4",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/windsurf.json
+++ b/tests/fixtures/golden-install-parity/windsurf.json
@@ -39,7 +39,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "5636ca0b726871b2",
-  "gsd-core/bin/gsd-tools.cjs": "abce82dc226344f2",
+  "gsd-core/bin/gsd-tools.cjs": "b6944a9b7ab1ec52",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -298,7 +298,7 @@
  "gsd-core/workflows/remove-phase.md": "e7a6af429b36e77b",
  "gsd-core/workflows/remove-workspace.md": "30ca05fe4a3efc25",
  "gsd-core/workflows/resume-project.md": "82cfe1b8cb17c085",
-  "gsd-core/workflows/review.md": "805bea46bed56bd8",
+  "gsd-core/workflows/review.md": "ac0c02f11e2ae1dc",
  "gsd-core/workflows/scan.md": "389025e963d0e502",
  "gsd-core/workflows/secure-phase.md": "666828983e5dd51f",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/fixtures/golden-install-parity/zcode.json
+++ b/tests/fixtures/golden-install-parity/zcode.json
@@ -110,7 +110,7 @@
  "gsd-core/VERSION": "ef0deccd81a6723c",
  "gsd-core/bin/check-latest-version.cjs": "e4a224058c8f4d74",
  "gsd-core/bin/ensure-runtime-build.cjs": "51bc64467ab30f62",
-  "gsd-core/bin/gsd-tools.cjs": "d44831d1e2f9c1c1",
+  "gsd-core/bin/gsd-tools.cjs": "9ad2ecce8b087676",
  "gsd-core/bin/gsd_run": "62d9b647ede212e6",
  "gsd-core/bin/shared/config-defaults.manifest.json": "517e6a7c1e9f4f16",
  "gsd-core/bin/shared/config-schema.manifest.json": "2f60b9eaa6cf6bc1",
@@ -369,7 +369,7 @@
  "gsd-core/workflows/remove-phase.md": "df9a45f0b1880999",
  "gsd-core/workflows/remove-workspace.md": "f67860c795fb4bfe",
  "gsd-core/workflows/resume-project.md": "f28da1200e4545f4",
-  "gsd-core/workflows/review.md": "f1fbefbd64bd890e",
+  "gsd-core/workflows/review.md": "d4f26b05b3eff7f6",
  "gsd-core/workflows/scan.md": "e6424af05656725a",
  "gsd-core/workflows/secure-phase.md": "f8b9436c35372281",
  "gsd-core/workflows/session-report.md": "2e5b1205324ddefa",
--- a/tests/prompt-injection-scan.security.test.cjs
+++ b/tests/prompt-injection-scan.security.test.cjs
@@ -68,6 +68,12 @@ const ALLOWLIST = new Set([
 // belong in ALLOWLIST). Only add files that are large but otherwise clean.
 const SIZE_ONLY_WORKFLOWS = new Set([
  'gsd-core/workflows/docs-update.md',  // ~51K after fix-loop truncation guard (#571)
+  // ~50.7K after the per-reviewer effort wiring (#2481). This file sat at 49,971
+  // chars — 29 below the 50K prompt-stuffing threshold — so it was going to trip
+  // on whatever was added to it next. Size-only: the file is still fully injection
+  // scanned, exactly like docs-update.md. Splitting it per the progressive-
+  // disclosure pattern is the real fix and is worth its own change.
+  'gsd-core/workflows/review.md',
 ]);

 // ─── Scanner ────────────────────────────────────────────────────────────────
--- a/tests/workflow-size-baseline.json
+++ b/tests/workflow-size-baseline.json
@@ -64,7 +64,7 @@
  "remove-phase.md": 8513,
  "remove-workspace.md": 7916,
  "resume-project.md": 17270,
-  "review.md": 50497,
+  "review.md": 51210,
  "scan.md": 7728,
  "secure-phase.md": 13987,
  "session-report.md": 4044,