* 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:
@@ -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)}`);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user