enhance(#2573): stamp STATE.md with its commit and surface a freshness hint (#2622)

* enhance(#2573): stamp STATE.md with its commit and surface a commit-age freshness hint

Adds a `state_head` stamp to STATE.md and derives a tri-state commit-age
freshness proxy (state_commits_behind / state_commit_stale) through
state.cjs's readStateHeadFreshness, surfaced on smart-entry signals and as
health W024. The proxy is advisory: classify() deliberately does NOT consume
it (ADR-1787 locks the classification/routing boundary — a signal, not a route).

Composes with #3099 and #1882 (both merged to next after this branch): the
commit-age proxy reads `state_head` while the LAST_ACTIVITY_UNPARSEABLE
diagnostic reads `last_activity` — two different fields, not "two staleness
signals on one field." A new regression test asserts a STATE.md carrying both
an unparseable last_activity AND a valid state_head resolves each independently
(diagnostic fires once; freshness reads state_head, commits_behind 0).

Rebased onto next (flattened): resolved the add/add conflicts in
src/smart-entry.cts (kept both the #2573 freshness import/derivation and the
#3099 diagnostic import/call) and tests/smart-entry.unit.test.cjs (kept both
describe blocks). Drift-ack for health.md's W024 row is unchanged (12348 B).
Tests: smart-entry 62, state/state-transition/health/verify 639, all pass.

* chore(#2573): allowlist health-validation test in the prompt-injection scan

The scanner's `exec('` code-execution pattern matches the benign
`re.exec('<phase-id>')` RegExp method calls in the phase-ID grammar tests
(pre-existing: 16 such calls on next, this PR adds none). The file entered the
diff-mode scan's changed-file set only because #2573's W024 state_head
assertions touch it. Allowlist it alongside the other test files that carry
pattern-matching content as data (same DEFECT.PROMPT-INJECTION-SCAN-COLLISION
class). Scanner self-test 38/0; diff scan 14 files, 0 findings.
This commit is contained in:
Rezolv
2026-08-11 17:10:23 -04:00
committed by GitHub
parent 9341d8b8d3
commit e87fb409ee
19 changed files with 1014 additions and 7 deletions

View File

@@ -1816,3 +1816,149 @@ describe('validate consistency — checklist-style roadmap phases must not emit
});
});
}
// ── W024 (#2573): STATE.md commit-age freshness advisory ─────────────────────
//
// Advisory ONLY. It appends to warnings[] and must never change `status` or any
// existing count — promoting it to a gate is a separate, disclosed change.
//
// Goodhart guard (why the threshold is coarse and the wording is a proxy):
// `state_head` restamps on EVERY state write, so a low commits-behind count
// means "something wrote STATE recently", not "STATE's content is accurate".
// The number is a freshness proxy; the message must never assert drift.
describe('W024 — STATE.md commit-age freshness advisory (#2573)', () => {
const { after } = require('node:test');
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { runGsdTools, cleanup } = require('./helpers.cjs');
const { runGit } = require('./helpers/process-seam.cjs');
const {
STATE_HEAD_ADVISORY_COMMITS,
} = require('../gsd-core/bin/lib/verify.cjs');
const dirs = [];
const track = (d) => { dirs.push(d); return d; };
after(() => { while (dirs.length) cleanup(dirs.pop()); });
function project({ commitsAhead, stateHead = 'BASE' }) {
const base = track(fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-2573-h-')));
const planningDir = path.join(base, '.planning');
fs.mkdirSync(path.join(planningDir, 'phases'), { recursive: true });
fs.writeFileSync(
path.join(planningDir, 'PROJECT.md'),
'# Project\n\n## What This Is\nTest.\n\n## Core Value\nTest.\n\n## Requirements\nTest.\n',
);
fs.writeFileSync(path.join(planningDir, 'config.json'), JSON.stringify({ model_profile: 'balanced' }));
fs.writeFileSync(
path.join(planningDir, 'ROADMAP.md'),
'# Roadmap\n\n## Milestone v1.0\n\n### Phase 1: One\n**Goal:** g\n',
);
runGit(['init', '-q'], { cwd: base });
runGit(['config', 'user.email', 't@t.com'], { cwd: base });
runGit(['config', 'user.name', 'T'], { cwd: base });
runGit(['config', 'commit.gpgsign', 'false'], { cwd: base });
runGit(['add', '-A'], { cwd: base });
runGit(['commit', '-q', '-m', 'seed'], { cwd: base });
const head = runGit(['rev-parse', 'HEAD'], { cwd: base }).stdout.trim();
fs.writeFileSync(
path.join(planningDir, 'STATE.md'),
[
'---',
'status: executing',
...(stateHead === null ? [] : [`state_head: ${stateHead === 'BASE' ? head : stateHead}`]),
'---',
'',
'# State',
'',
'**Current Phase:** 1',
'**Status:** In progress',
'',
].join('\n'),
);
for (let i = 0; i < commitsAhead; i++) {
fs.writeFileSync(path.join(base, `f${i}.txt`), `${i}\n`);
runGit(['add', '-A'], { cwd: base });
runGit(['commit', '-q', '-m', `c${i}`], { cwd: base });
}
return base;
}
function health(dir) {
const r = runGsdTools(['validate', 'health', '--json'], dir);
assert.strictEqual(r.success, true, `unexpected failure: ${r.error}`);
return JSON.parse(r.output);
}
const w024 = (d) => (d.warnings ?? []).filter((w) => w.code === 'W024');
test('exports a named threshold constant rather than a bare magic number', () => {
assert.strictEqual(typeof STATE_HEAD_ADVISORY_COMMITS, 'number');
assert.ok(STATE_HEAD_ADVISORY_COMMITS > 0);
});
test('does NOT fire when STATE.md was written at HEAD', () => {
const data = health(project({ commitsAhead: 0 }));
const w024 = (data.warnings ?? []).filter((w) => w.code === 'W024');
assert.strictEqual(w024.length, 0, `expected no W024, got ${JSON.stringify(w024)}`);
});
test('boundary: silent at threshold-1, fires at threshold+1', () => {
// The 0/1/20 cases alone leave the actual boundary untested — 1 is a
// trivial-fit, not an edge. These two pin the comparison operator.
const below = health(project({ commitsAhead: STATE_HEAD_ADVISORY_COMMITS - 1 }));
assert.strictEqual((below.warnings ?? []).filter((w) => w.code === 'W024').length, 0,
`must stay silent at ${STATE_HEAD_ADVISORY_COMMITS - 1} commits`);
const above = health(project({ commitsAhead: STATE_HEAD_ADVISORY_COMMITS + 1 }));
assert.strictEqual((above.warnings ?? []).filter((w) => w.code === 'W024').length, 1,
`must fire at ${STATE_HEAD_ADVISORY_COMMITS + 1} commits`);
});
test('does NOT fire below the threshold (a healthy project stays quiet)', () => {
// Hyrum guard: firing on every ordinary project would change health's
// observable "clean" state and make anything gating on clean-health noisy.
const data = health(project({ commitsAhead: 1 }));
const w024 = (data.warnings ?? []).filter((w) => w.code === 'W024');
assert.strictEqual(w024.length, 0, `expected no W024 at 1 commit, got ${JSON.stringify(w024)}`);
});
test('fires at/above the threshold, states the count, and stays a proxy (never asserts drift)', () => {
const data = health(project({ commitsAhead: STATE_HEAD_ADVISORY_COMMITS }));
const w024 = (data.warnings ?? []).filter((w) => w.code === 'W024');
assert.strictEqual(w024.length, 1, `expected exactly one W024, got ${JSON.stringify(data.warnings)}`);
const msg = String(w024[0].message);
assert.ok(msg.includes(String(STATE_HEAD_ADVISORY_COMMITS)),
`W024 must state the commit count, got: ${msg}`);
assert.ok(/approximate/i.test(msg),
`W024 must frame the signal as approximate (freshness proxy), got: ${msg}`);
assert.ok(!/\bdrift(ed)?\b|\bis wrong\b|\bstale content\b/i.test(msg),
`W024 must NOT assert drift — it is a proxy, not a measurement. Got: ${msg}`);
});
test('is advisory only — lands in warnings[], never errors[] or the repair set', () => {
// NOT "stale.status === fresh.status": these fixtures already carry W006
// ("Phase in ROADMAP but no directory"), so both sides are `degraded`
// regardless of W024 and that assertion can never fail. Health derives
// status from warnings by design (warnings -> degraded), so the real
// invariant is that W024 is a WARNING and never escalates.
const data = health(project({ commitsAhead: STATE_HEAD_ADVISORY_COMMITS }));
assert.strictEqual(w024(data).length, 1, 'precondition: W024 fired');
assert.ok(
!(data.errors ?? []).some((e) => e.code === 'W024'),
`W024 must never appear in errors[]: ${JSON.stringify(data.errors)}`,
);
assert.notStrictEqual(data.status, 'broken',
'an advisory must never break health');
assert.ok(!w024(data)[0].repairable,
'W024 is diagnostic, not auto-repairable — it must not enter the repair set');
});
test('absent state_head → no W024 (unknown is not a finding)', () => {
const data = health(project({ commitsAhead: 5, stateHead: null }));
const w024 = (data.warnings ?? []).filter((w) => w.code === 'W024');
assert.strictEqual(w024.length, 0, `unknown must stay silent, got ${JSON.stringify(w024)}`);
});
});