@am_shork/attest 1.0.0 → 1.1.0

package/README.md

@@ -159,7 +159,7 @@ Every diagnostic carries a `code`, and every code has a section in
 ```
 ERROR   registry-not-static (requirements/upload.reqs.ts:5)
     Value is not a literal.
-    → https://gitlab.com/Pseudorca/attest/-/blob/v1.0.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v1.1.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "open-unresolved", "orphan-from-failed-registry", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "requirement-open", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "open-unresolved", "orphan-from-failed-registry", "orphan-test", "possible-drift", "proposed-spec-name-taken", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "requirement-open", "spec-in-change-dir", "spec-load-failed", "stale-spec-doc", "stale-workflow-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -54,6 +54,7 @@ export const ISSUE_CODES = [
     'spec-in-change-dir',
     'spec-load-failed',
     'stale-spec-doc',
+    'stale-workflow-doc',
     'tests-red',
     'unbound-param',
     'uncovered-requirement',

package/dist/core/gate.d.ts

@@ -101,6 +101,27 @@ export declare function specLoadFailedIssues(run: RunResult, already?: ReadonlyS
  * Those files are left alone here, so one file carries one finding.
  */
 export declare function notRunIssues(plan: AttestPlan, run: RunResult, specific?: readonly Issue[]): Issue[];
+/**
+ * What `tests-red` adds when the clock, rather than an assertion, is what the
+ * run disagreed about. Empty when nothing reached the ceiling, so an ordinary
+ * red suite reads exactly as it always has.
+ *
+ * Here rather than at either call site because both commands that run a suite
+ * ask it, which is the same reason `notRunIssues` is here — and here rather
+ * than in `runner.ts` because that module names `vitest` and this one must not
+ * acquire it (`tests/import-boundary.spec.ts`).
+ *
+ * **Why a report says this at all.** The standing answer to a red `verify` is
+ * to run the suite yourself under your own reporter, and that answer is
+ * circular in exactly the case that needs it: when the direct run is green, the
+ * disagreement between the two runs *is* the failure, and reproducing it
+ * reproduces nothing. The child run is isolated, so it drops the config that
+ * would have raised the timeout — which makes "did anything run out the clock"
+ * the one question the direct run cannot answer and this one can. It is a count
+ * rather than a list because naming the scenarios is the pass-through decision,
+ * which is open and is not this.
+ */
+export declare function timeoutClause(run: RunResult): string;
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, which no run
  * the gate observed has seen fail (design §6, mechanism 2).

package/dist/core/gate.js

@@ -131,6 +131,32 @@ export function notRunIssues(plan, run, specific = []) {
         ...declaredNotRunIssues(plan, run).filter((i) => !i.file || !diagnosed.has(i.file)),
     ];
 }
+/**
+ * What `tests-red` adds when the clock, rather than an assertion, is what the
+ * run disagreed about. Empty when nothing reached the ceiling, so an ordinary
+ * red suite reads exactly as it always has.
+ *
+ * Here rather than at either call site because both commands that run a suite
+ * ask it, which is the same reason `notRunIssues` is here — and here rather
+ * than in `runner.ts` because that module names `vitest` and this one must not
+ * acquire it (`tests/import-boundary.spec.ts`).
+ *
+ * **Why a report says this at all.** The standing answer to a red `verify` is
+ * to run the suite yourself under your own reporter, and that answer is
+ * circular in exactly the case that needs it: when the direct run is green, the
+ * disagreement between the two runs *is* the failure, and reproducing it
+ * reproduces nothing. The child run is isolated, so it drops the config that
+ * would have raised the timeout — which makes "did anything run out the clock"
+ * the one question the direct run cannot answer and this one can. It is a count
+ * rather than a list because naming the scenarios is the pass-through decision,
+ * which is open and is not this.
+ */
+export function timeoutClause(run) {
+    if (run.timedOut === 0)
+        return '';
+    const subject = run.timedOut === 1 ? '1 scenario' : `${run.timedOut} scenarios`;
+    return ` ${subject} reached the ${run.testTimeout} ms timeout this run applied, rather than failing an assertion.`;
+}
 /**
  * Never-red: a scenario attesting a requirement this change ADDs, which no run
  * the gate observed has seen fail (design §6, mechanism 2).
@@ -227,7 +253,7 @@ export function evaluateGate({ registry, plan, run, addedIds, unmergedAddedIds,
         blocking.push({
             level: 'ERROR',
             code: 'tests-red',
-            message: 'Some tests are failing; the change cannot be archived.',
+            message: `Some tests are failing; the change cannot be archived.${timeoutClause(run)}`,
         });
     }
     // 3) and 4) in one push, because the order between them is not this

package/dist/core/pipeline.js

@@ -6,10 +6,10 @@ import { byCodeUnit } from './order.js';
 import { applyDelta, addedIds, claimedIds } from './apply.js';
 import { readDeltaSource } from './static-registry.js';
 import { statusRows, statusCounts } from './status.js';
-import { evaluateGate, notRunIssues } from './gate.js';
+import { evaluateGate, notRunIssues, timeoutClause } from './gate.js';
 import { renderMarkdown, staleIssue } from './render.js';
 import { mergeRedRecord, readRedRecord, redRecordPath, serialiseRedRecord, } from './red-record.js';
-import { DEFAULT_TARGET, resolveTargets } from './targets.js';
+import { DEFAULT_TARGET, TARGETS, resolveTargets, staleWorkflowIssue } from './targets.js';
 import { writeAtomic } from './write.js';
 import { applyMerge, mergedSpecPath } from './merge.js';
 import { compilerIssue } from './compiler.js';
@@ -126,9 +126,39 @@ export async function runCheck(root, options = {}) {
             ...(await unclaimedProposedSpecIssues(root, scan, options, loader)),
             ...(await changeDirSpecIssues(root)),
             ...proposedNameTakenIssues(root, scan),
+            ...(await staleWorkflowIssues(root)),
         ];
     });
 }
+/**
+ * Every installed workflow document that is no longer the one `init` writes
+ * (ATX-89). Reads files and executes nothing, so it sits inside ATX-16 exactly
+ * as the rest of `check` does.
+ *
+ * Reported by `check` alone among the four static commands: it is the one an
+ * adopter runs unconditionally and the one the workflow document itself tells
+ * the agent to run, while `status` takes a change name and is therefore silent
+ * during exactly the brownfield adoption whose document is stalest. That this
+ * reports on the installed build rather than on the project's intent is not a
+ * widening of the command — `compilerIssue()` is already its first statement.
+ *
+ * Every target, not only the default one: an adopter who ran
+ * `init --target cursor` committed that file and no other, and it goes stale on
+ * the same upgrade. Absent targets fall out in `staleWorkflowIssue`, so the loop
+ * needs no filter and a project that ran `init` for none of them gets nothing.
+ */
+async function staleWorkflowIssues(root) {
+    const issues = [];
+    for (const target of TARGETS) {
+        // `target.file` is POSIX-spelled and Node takes that separator everywhere,
+        // so this needs no normalisation on the way in (ATX-28).
+        const current = await readFile(join(root, target.file), 'utf8').catch(() => undefined);
+        const issue = staleWorkflowIssue(target, current);
+        if (issue)
+            issues.push(issue);
+    }
+    return issues;
+}
 /**
  * A proposed spec whose merged name is already taken (design §7).
  *
@@ -332,6 +362,11 @@ export async function runVerify(root, options = {}) {
             runtimeCoverage: new Map(),
             outcomes: new Map(),
             unloadedFiles: [],
+            // No run happened, so there is no timeout in force and nothing
+            // reached one. Zero rather than Vitest's default: this stub must not
+            // claim a number no run produced.
+            testTimeout: 0,
+            timedOut: 0,
         }
         : await runAndCollect({
             root,
@@ -340,7 +375,11 @@ export async function runVerify(root, options = {}) {
             vitestConfig: options.vitestConfig,
         });
     if (!run.passed) {
-        issues.push({ level: 'ERROR', code: 'tests-red', message: 'Some tests are failing.' });
+        issues.push({
+            level: 'ERROR',
+            code: 'tests-red',
+            message: `Some tests are failing.${timeoutClause(run)}`,
+        });
     }
     // The load failures first, then the absences they caused — by the same
     // function the gate calls, which is the point. `verify` used to ask only for

package/dist/core/runner.js

@@ -69,6 +69,12 @@ export async function runAndCollect(options = {}) {
     try {
         const runtimeCoverage = new Map();
         const outcomes = new Map();
+        // Off the *resolved* config, so it is the timeout that actually applied:
+        // Vitest's default when the run is isolated, and the supplied config's value
+        // when one was given. Reading it is what keeps the number out of a message
+        // template, where it would be a constant about somebody else's release.
+        const testTimeout = vitest.config.testTimeout;
+        let timedOut = 0;
         // Reconstruct coverage from the task tree (not an in-process singleton).
         //
         // `file` is threaded down from the file task rather than read off the suite,
@@ -76,6 +82,8 @@ export async function runAndCollect(options = {}) {
         // two spec files declaring the same scenario name under one `requirement()`
         // from collapsing into a single entry that either of them could satisfy.
         const walk = (task, file) => {
+            if (task.type === 'test' && ranOutTheClock(task, testTimeout))
+                timedOut += 1;
             if (task.type === 'suite') {
                 const id = requirementIdOf(task.name);
                 if (id !== undefined) {
@@ -128,7 +136,7 @@ export async function runAndCollect(options = {}) {
         // missing API as zero failures and turning a red suite green. This is the
         // one boolean in the engine that must never fail open.
         const passed = vitest.state.getCountOfFailedTests() === 0;
-        return { passed, runtimeCoverage, outcomes, unloadedFiles };
+        return { passed, runtimeCoverage, outcomes, unloadedFiles, testTimeout, timedOut };
     }
     finally {
         await vitest.close();
@@ -167,6 +175,31 @@ function* scenariosUnder(suite) {
 function failedToLoad(file) {
     return (file.result?.errors?.length ?? 0) > 0;
 }
+/**
+ * Did this scenario fail by reaching the timeout rather than by asserting?
+ *
+ * Duration against the timeout, never the error text. Vitest does say "Test
+ * timed out in 5000ms." and matching that would be simpler, but it is the same
+ * category error this project refuses in its own diagnostics — a message is
+ * prose, and a detector that reads one is a detector the next release of
+ * somebody else's tool can silence in a way no test here would notice.
+ *
+ * `>=` rather than a tolerance below it: a run that reached the ceiling is
+ * stopped *at* the ceiling and recorded a hair past it (measured at 5015 ms
+ * against 5000), so there is no gap to bridge, and a margin would start
+ * claiming timeouts for slow assertions that failed honestly.
+ *
+ * A missing `duration` is not a timeout. That is the reading that fails
+ * quietly rather than loudly: a task tree that stopped carrying durations would
+ * otherwise report every failure as a timeout, which is a wrong diagnosis
+ * printed with confidence — the failure mode `spec-load-failed` exists to undo.
+ */
+function ranOutTheClock(task, testTimeout) {
+    if (task.result?.state !== 'fail')
+        return false;
+    const duration = task.result.duration;
+    return duration !== undefined && duration >= testTimeout;
+}
 /** The outcome of a task that ran, or `undefined` when it did not run at all. */
 function executedOutcome(task) {
     const state = task.result?.state;

package/dist/core/skill.js

@@ -30,17 +30,23 @@
 // actually needs it, and one fewer command beats saving an upgrade a diff.
 // `attest init` is idempotent: re-run it after an upgrade.
 //
-// The remaining exposure is honest and small: an old file describes an old
-// workflow to an agent that trusts it. The backstop is that every mistake it
-// could cause is a diagnostic with a fix hint — a registry written the old way
-// is `registry-not-static`, and the agent corrects itself from the report.
-// It has happened twice, the second time on a diagnostic that was not added but
-// *redefined* — the code table and the prose below it disagreed, and an agent
-// branches on the table. So: read this file when a release adds a diagnostic
-// **or changes what one means**, and grep this string for the code rather than
-// trusting that the section you edited was its only mention. Nothing gates it —
-// `ATX-57` catches a code the engine cannot emit, never one it can, and its
-// rationale records that one-directionality as deliberate.
+// The remaining exposure was called honest and small: an old file describes an
+// old workflow to an agent that trusts it, and the backstop was that every
+// mistake it could cause is a diagnostic with a fix hint — a registry written
+// the old way is `registry-not-static`, and the agent corrects itself from the
+// report. **That backstop is withdrawn (design §9).** A stale document producing
+// bad input is caught; one producing unnecessary work is not, and nothing fires
+// at any severity for the second. So the decision above stands on the chore
+// argument alone, and must not be re-derived from the backstop — that is the
+// part a rewrite has to keep. The measurement that withdrew it, and the pricing
+// of the adopter-facing form it reopens, are in CHANGELOG.md.
+// The exposure has happened twice, the second time on a diagnostic that was
+// not added but *redefined* — the code table and the prose below it disagreed,
+// and an agent branches on the table. So: read this file when a release adds a
+// diagnostic **or changes what one means**, and grep this string for the code
+// rather than trusting that the section you edited was its only mention.
+// Nothing gates it — `ATX-57` catches a code the engine cannot emit, never one
+// it can, and its rationale records that one-directionality as deliberate.
 /**
  * The one sentence that decides whether the workflow is ever loaded.
  *
@@ -428,6 +434,21 @@ Two things make that safe, and one keeps it from being a verdict:
   under the gate — that gap is the first thing to suspect when it does. See
   \`tests-red\` in the troubleshooting document, and \`--vitest-config\` if your
   specs need that environment.
+- **Your config's \`testTimeout\` is dropped along with the rest of it**, so the
+  isolated run applies Vitest's own default of five seconds. A scenario that
+  starts a subprocess, a container or a build can fit inside that on one machine
+  and not on another, which reads as a gate that fails intermittently rather than
+  as a clock. Give any scenario that goes near it an explicit timeout — the third
+  argument to \`scenario\` — rather than relying on a number the gate does not
+  take from you:
+
+  \`\`\`ts
+  scenario('builds the container', async () => { /* … */ }, 30_000);
+  \`\`\`
+
+  When it is the cause, \`tests-red\` says so: it names the timeout that applied
+  and how many scenarios reached it, which is the one thing running the file
+  yourself cannot tell you, because your run had your timeout.
 
 ### Four things you must not do
 

package/dist/core/targets.d.ts

@@ -49,4 +49,33 @@ export declare function resolveTargets(names: readonly string[]): {
     targets: AgentTarget[];
     issues: Issue[];
 };
+/**
+ * The freshness verdict for one installed workflow document: `undefined` when
+ * the file on disk is the document `init` writes now, an INFO otherwise.
+ *
+ * **`current` being `undefined` is silence, not a second code**, and that is the
+ * whole of ATX-90. `render`'s `staleIssue` is the obvious model and reports a
+ * rendering that was never generated under `missing-spec-doc`; copying that here
+ * would fire on every project that has not installed the workflow — two of this
+ * repository's own three targets, and the majority of adopters, since `init`
+ * writes one target by default and nothing obliges a project to run it at all.
+ * An absent file is indistinguishable from a repository that never adopted the
+ * workflow half, which is the observation ATX-84 makes from the other side.
+ *
+ * **The comparison is the document and not the bytes (ATX-91).** `init` writes
+ * `\n` and Git hands the file back as `\r\n` wherever `core.autocrlf` is on, the
+ * installer default on Windows, so a byte comparison would call a fresh clone
+ * stale. Deliberately the opposite of ATX-84, which compares this repository's
+ * own copy byte-for-byte and may, because `.gitattributes` here is committed and
+ * pins `eol=lf` — that file is Attest's here and nobody's in an adopter's tree.
+ *
+ * INFO, and the level is the requirement rather than a presentation choice: the
+ * obligation to keep this document current is Attest's, and no adopter is under
+ * one to take the update. So the tool says what it knows and asks for nothing —
+ * `ok`, the exit code and every gate are untouched at this level.
+ *
+ * `file` is `target.file`, already spelled with `/` on every platform (ATX-28),
+ * so nothing here goes near `path.relative`.
+ */
+export declare function staleWorkflowIssue(target: AgentTarget, current: string | undefined): Issue | undefined;
 //# sourceMappingURL=targets.d.ts.map

package/dist/core/targets.js

@@ -138,4 +138,50 @@ export function resolveTargets(names) {
         issues,
     };
 }
+/**
+ * The freshness verdict for one installed workflow document: `undefined` when
+ * the file on disk is the document `init` writes now, an INFO otherwise.
+ *
+ * **`current` being `undefined` is silence, not a second code**, and that is the
+ * whole of ATX-90. `render`'s `staleIssue` is the obvious model and reports a
+ * rendering that was never generated under `missing-spec-doc`; copying that here
+ * would fire on every project that has not installed the workflow — two of this
+ * repository's own three targets, and the majority of adopters, since `init`
+ * writes one target by default and nothing obliges a project to run it at all.
+ * An absent file is indistinguishable from a repository that never adopted the
+ * workflow half, which is the observation ATX-84 makes from the other side.
+ *
+ * **The comparison is the document and not the bytes (ATX-91).** `init` writes
+ * `\n` and Git hands the file back as `\r\n` wherever `core.autocrlf` is on, the
+ * installer default on Windows, so a byte comparison would call a fresh clone
+ * stale. Deliberately the opposite of ATX-84, which compares this repository's
+ * own copy byte-for-byte and may, because `.gitattributes` here is committed and
+ * pins `eol=lf` — that file is Attest's here and nobody's in an adopter's tree.
+ *
+ * INFO, and the level is the requirement rather than a presentation choice: the
+ * obligation to keep this document current is Attest's, and no adopter is under
+ * one to take the update. So the tool says what it knows and asks for nothing —
+ * `ok`, the exit code and every gate are untouched at this level.
+ *
+ * `file` is `target.file`, already spelled with `/` on every platform (ATX-28),
+ * so nothing here goes near `path.relative`.
+ */
+export function staleWorkflowIssue(target, current) {
+    if (current === undefined)
+        return undefined;
+    const eol = (s) => s.replace(/\r\n/g, '\n');
+    if (eol(current) === eol(target.content()))
+        return undefined;
+    return {
+        level: 'INFO',
+        code: 'stale-workflow-doc',
+        file: target.file,
+        // The hint names what the command does to the file, not just the command.
+        // `init` writes with no merge and no backup, so an adopter who edited these
+        // instructions is being pointed at something destructive — defensible,
+        // since Attest owns the path (rule 1 above), and worth saying anyway.
+        message: `"${target.file}" is not the ${target.tool} workflow document this version of Attest writes. ` +
+            `Re-run \`attest init --target ${target.name}\` to update it, which rewrites the file in place.`,
+    };
+}
 //# sourceMappingURL=targets.js.map

package/dist/core/types.d.ts

@@ -79,6 +79,35 @@ export interface RunResult {
      * separately, which is what this is.
      */
     unloadedFiles: string[];
+    /**
+     * The per-test timeout that was actually in force for this run, in
+     * milliseconds, read off the resolved child config rather than assumed.
+     *
+     * Read rather than assumed because it is the one number here Attest does not
+     * choose: an isolated run (`config: false`) gets Vitest's own default, and a
+     * run given `--vitest-config` gets whatever that config sets. A constant
+     * repeated in a message would be right in one of those cases and quietly
+     * wrong in the other, and it would go stale on a Vitest release with nothing
+     * to notice.
+     */
+    testTimeout: number;
+    /**
+     * How many scenarios failed by reaching {@link RunResult.testTimeout} rather
+     * than by failing an assertion.
+     *
+     * A count, deliberately, and not the names: what a red report is missing is
+     * carried in the run's own output, and reproducing it here is a decision this
+     * project has not taken. What the count adds is the one thing that output
+     * cannot supply when the direct run is green — whether the clock, rather than
+     * the code, is what the isolated run disagreed about.
+     *
+     * Detected by duration against the timeout, never by the child's error text:
+     * a message is prose in somebody else's project too, and a detector reading
+     * one is a detector a Vitest release can silence. Measured: a scenario that
+     * runs out the clock ends `fail` at a duration just past the timeout, while
+     * an assertion failure ends `fail` in under a millisecond.
+     */
+    timedOut: number;
 }
 /** Severity levels for graded reporting (design §5.3). */
 export type Level = 'ERROR' | 'WARNING' | 'INFO';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
   "packageManager": "pnpm@10.28.0",