@am_shork/attest 0.8.0 → 0.9.0

package/dist/core/pipeline.js

@@ -316,21 +316,13 @@ export async function runVerify(root, options = {}) {
         specFiles: scan.specFiles.length,
         attesting: attesting.length,
     };
-    // A run with nothing to attest used to print "✓ No issues." and exit 0,
-    // because "no failing tests" was read as passed. An empty registry is the
-    // only shape of that which no other check already catches: with at least one
-    // requirement, an absent scenario is `uncovered-requirement` and a declared
-    // scenario that never executed is `declared-not-run`, both ERRORs. So this is
-    // narrower than "zero scenarios ran" — and firing on that too would only
-    // double-report a run that is already red.
-    if (counts.requirements === 0) {
-        issues.push({
-            level: 'ERROR',
-            code: 'empty-spec',
-            message: `No requirements found under this root, so this run attested nothing. ` +
-                `Point attest at the directory holding your *.reqs.ts files, or add one.`,
-        });
-    }
+    // `empty-spec` belongs to `validateStructure` above, not here: the registry
+    // alone decides it, so it is owed by every command performing §5.3 rather than
+    // by the one that executes. The guard a reader is most likely to want here is
+    // "zero scenarios ran", and it is deliberately not that — with at least one
+    // requirement, an absent scenario is already `uncovered-requirement` and a
+    // declared scenario that never executed is already `declared-not-run`, both
+    // ERRORs, so the wider rule would only double-report a run that is red anyway.
     // Nothing declares intent, so there is nothing for Attest to run. Skipping
     // the child run keeps an incumbent suite untouched; the verdict comes from
     // empty-spec or uncovered-requirement, both already ERRORs above.
@@ -813,14 +805,44 @@ export async function runStatus(root, changeName, options = {}) {
         return nothing([invalidChangeNameIssue(changeName)]);
     if (unusable)
         return nothing([unusable]);
-    const read = await readDelta(root, changeName, options);
-    if ('issue' in read)
-        return nothing([read.issue]);
-    const scan = await scanProject(root);
-    const { merged: plan } = await changeMergedPlan(root, read.delta, scan);
-    const firstRun = await readRedRecord(root, changeName);
-    const rows = statusRows(addedIds(read.delta), plan, firstRun);
-    return { change: changeName, rows, counts: statusCounts(rows), issues: [] };
+    // One loader for the whole command, or none at all. Both reads below take the
+    // reader `options` asks for, so the escape hatch moves them together: the
+    // default path evaluates nothing, which is what puts this command on ATX-16's
+    // roster, and `--eval` is one named decision rather than one per file.
+    return withLoader(options, async (loader) => {
+        const read = await readDelta(root, changeName, options, loader);
+        if ('issue' in read)
+            return nothing([read.issue]);
+        const scan = await scanProject(root);
+        const { registry: base, issues: registryIssues } = await readRegistry(root, options, scan.reqsFiles, loader);
+        // `hasError`, the gate's own predicate over the same list, because the
+        // registry is what the delta is applied *to*: without it there is no end
+        // state to describe, and a report computed against half a registry would
+        // answer about a change nobody proposed.
+        if (hasError(registryIssues))
+            return nothing(registryIssues);
+        // The gate's own call, made here for its diagnosis rather than its result:
+        // the rows below stay decided by the delta, the specs and the record alone
+        // (ATX-32), and what this adds is the refusal. A delta that cannot be
+        // applied describes an end state that does not exist, so there is no
+        // progress toward it to report — an `unproven` against it would be a
+        // true-looking sentence about a change that cannot exist.
+        const { issues: deltaIssues } = applyDelta(base, read.delta);
+        if (deltaIssues.length > 0)
+            return nothing(deltaIssues);
+        const { merged: plan, issues: unreadableSpecs } = await changeMergedPlan(root, read.delta, scan);
+        // The same refusal the gate makes, from the same list and on the same
+        // argument (ATX-65): every state this command reports is computed *from* the
+        // plan, so a spec the parser could not read does not shrink the report — it
+        // changes what the remaining rows say. A requirement whose only scenario is
+        // in that file reads as having none, which is the opposite of the truth and
+        // is advice to redo work already on disk.
+        if (unreadableSpecs.length > 0)
+            return nothing(unreadableSpecs);
+        const firstRun = await readRedRecord(root, changeName);
+        const rows = statusRows(addedIds(read.delta), plan, firstRun);
+        return { change: changeName, rows, counts: statusCounts(rows), issues: [] };
+    });
 }
 /** Archive gate for a change (design §8, §9: `attest archive <change>`). */
 export async function runArchive(root, changeName, options = {}) {

package/dist/core/skill.js

@@ -34,9 +34,13 @@
 // 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 once, so: read this file when a release adds a diagnostic.
-// Nothing gates that — `ATX-57` catches a code the engine cannot emit, never one
-// it can.
+// 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 one sentence that decides whether the workflow is ever loaded.
  *
@@ -128,11 +132,16 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   or it is an \`unbound-param\` ERROR. A \`{placeholder}\` written into a
   *rationale* is a \`rationale-placeholder\` WARNING — rationales are not
   interpolated, so it would reach the rendered document with its braces intact.
-- **A registry is a literal.** Every value is written in the file: no imported
-  constant (\`params: { maxMb: MAX_MB }\`), no computed value, no \`Date.now()\`.
-  \`check\`, \`cover\` and \`render\` read \`*.reqs.ts\` with the compiler API and
-  never execute it, so anything they cannot read is a \`registry-not-static\`
-  ERROR. An imported constant also breaks the single-source rule outright — the
+- **A registry is a literal, and so is a delta.** Every value is written in the
+  file: no imported constant (\`params: { maxMb: MAX_MB }\`), no computed value,
+  no \`Date.now()\`. \`check\`, \`cover\` and \`render\` read \`*.reqs.ts\` with the
+  compiler API and never execute it, so anything they cannot read is a
+  \`registry-not-static\` ERROR. **The same rule covers
+  \`requirements.delta.ts\`**, which \`check\` and \`status\` read the same way — a
+  \`const\` lifted out of a delta is that same error, and a delta is the more
+  exposed of the two, living in \`changes/\` — the part of the tree that is by
+  definition still under review.
+  An imported constant also breaks the single-source rule outright — the
   value's real owner is then somewhere else. Inline it, and have the application
   code read it from the registry.
 - **Write prose as one long single-line string.** A template literal with no
@@ -176,13 +185,31 @@ lib/game/specs/
 └── fog.proposed.spec.ts     # this change's, and ../fog already resolves
 \`\`\`
 
-That name is the whole mechanism. It keeps the file out of \`attest verify\` and
-out of a plain \`vitest run\` while the change is in flight — the scenarios are
-red by construction — and \`attest archive <name>\` pulls it in by the requirement
-ids it covers: a change claims the proposed specs that declare a scenario for an
-id it ADDs, renames to, or MODIFIEs. Nothing lists paths anywhere, so nothing can
-fall out of step. A proposed spec no change claims is a \`proposed-spec-unclaimed\`
-ERROR from \`attest check\`, because it would otherwise run nowhere at all.
+That name is the whole mechanism. It keeps the file out of \`attest verify\`
+while the change is in flight — the scenarios are red by construction — and
+\`attest archive <name>\` pulls it in by the requirement ids it covers: a change
+claims the proposed specs that declare a scenario for an id it ADDs, renames to,
+or MODIFIEs. Nothing lists paths anywhere, so nothing can fall out of step. A
+proposed spec no change claims is a \`proposed-spec-unclaimed\` ERROR from
+\`attest check\`, because it would otherwise run nowhere at all.
+
+**It does not hide the file from your own test command.** \`*.proposed.spec.ts\`
+still ends in \`.spec.ts\`, so an ordinary \`**/*.spec.ts\` include — Vitest's own
+default among them — picks it up, and during stage 1 those scenarios are
+*supposed* to fail. Only Attest's scope excludes them. If a red \`npm test\` while
+a change is in flight is a problem for you, exclude the pattern in your own
+config; that is a decision about your suite, and Attest does not make it for you:
+
+\`\`\`ts
+// vitest.config.ts — optional, and only if you want your own suite green
+import { configDefaults, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // Spread the defaults: a bare \`exclude\` REPLACES them, and Vitest's include
+  // reaches node_modules without them.
+  test: { exclude: [...configDefaults.exclude, '**/*.proposed.spec.ts'] },
+});
+\`\`\`
 
 Writing it at its merged location is what makes merging it a rename. Its relative
 imports resolve now exactly as they will afterwards, so \`../fog\` never becomes
@@ -279,11 +306,17 @@ To see where the change stands at any point, without paying for a run:
 attest status <name> --json      # per added requirement: no-scenario / unproven / proven
 \`\`\`
 
-It reads the delta, the specs and \`first-run.json\`, and reports what the gate
-will still want. A change in flight is \`ok: true\` with rows to work through —
-this command never fails on unmet obligations, so do not read a clean table as
-"done". The state it cannot see is whether the tests pass; \`attest archive\` is
-the only thing that answers that.
+It reads the delta, the specs and \`first-run.json\`, and reports **two** of the
+gate's obligations, for the ids this change ADDs only: does each have a scenario,
+and has each scenario been recorded failing. A change in flight is \`ok: true\`
+with rows to work through — this command never fails on unmet obligations, so do
+not read a clean table as "done".
+
+**Everything else the gate checks is invisible here**, and that is more than
+whether the tests pass. A scenario left \`skip\`ped is \`declared-not-run\` and
+blocks the gate with the suite fully green; so does a spec file that will not
+import, or a proposed spec no delta claims. A clean table plus green tests is
+still not a verdict — \`attest archive\` is the only thing that decides.
 
 Then present the proposal, the ids, and the red output, and **stop**. Wait for
 agreement before implementing.
@@ -317,9 +350,32 @@ once. Branch on \`issues[].code\`, never on \`message\`:
 | \`add-conflict\` | the delta adds an id that already exists with different content |
 | \`change-not-found\` | no \`requirements.delta.ts\` for that name |
 | \`proposed-spec-name-taken\` | a proposed spec's merged name is already held by another spec |
-| \`apply-unsupported-delta\` | \`--apply\` writes back ADDED only, and this delta carries more |
+| \`apply-unsupported-delta\` | \`--apply\` writes back ADDED and MODIFIED; this delta carries RENAMED or REMOVED, or a MODIFIED value whose source span holds a comment |
 | \`apply-no-prefix-owner\` | no registry file owns the prefix of an id this change adds |
 
+### Iterating: run the spec directly, decide with the gate
+
+The gate does everything above after every edit, which makes it the slowest
+possible inner loop. While you are still making a scenario pass, run that one
+file instead, and keep \`attest archive\` for when you think you are finished:
+
+\`\`\`
+vitest run path/to/fog.proposed.spec.ts
+\`\`\`
+
+Two things make that safe, and one keeps it from being a verdict:
+
+- **It writes nothing.** \`first-run.json\` is only ever written by the gate, so
+  no number of direct runs can touch the record or the never-red obligation.
+- **\`attest status <name>\` still answers the readable half** without a run,
+  exactly as in stage 1.
+- **A green file here does not predict the gate.** Your config supplies aliases,
+  transforms and a DOM; the gate's child run is isolated (\`config: false\`) and
+  supplies none of them unless told to. So a scenario can pass directly and fail
+  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.
+
 ### Four things you must not do
 
 Each turns the gate green without changing the system, which is the exact
@@ -365,7 +421,8 @@ attest archive <name> --apply
 \`\`\`
 
 That finishes the merge the verdict just approved: it splices the change's ADDED
-requirements into the registry file owning their id prefix, repoints each proposed
+requirements into the registry file owning their id prefix, writes each MODIFIED
+requirement's changed values over the values they replace, repoints each proposed
 spec's import of \`requirements.delta.ts\` at that registry, renames the specs in
 place, and moves \`changes/<name>/\` to \`archive/<date>-<name>/\`. It re-runs the
 gate first and writes nothing if that fails, and it prints every path it touched.
@@ -379,10 +436,14 @@ Two things it does not do, and both are still yours:
    registry is a \`stale-spec-doc\` ERROR.
 2. **Run the merged suite.** \`attest verify\`, on the result, reported.
 
-**It writes back ADDED only.** A delta also carrying RENAMED, REMOVED or MODIFIED
-is refused whole as \`apply-unsupported-delta\`, with nothing written — the gate
-still checked all four, so nothing about the change is unverified, but the rest is
-merged by hand.
+**It writes back ADDED and MODIFIED.** A delta also carrying RENAMED or REMOVED is
+refused whole as \`apply-unsupported-delta\`, with nothing written — the gate still
+checked all four, so nothing about the change is unverified, but the rest is merged
+by hand. The same code refuses one MODIFIED *value* when a comment sits inside the
+span it would write over: the edit replaces a value and never the entry holding it,
+so \`statement\` and \`rationale\` can never hit this, while a \`params\` value or an
+\`outOfScope\` list can. Move the comment beside the value it belongs to, and run
+the command again.
 
 Merging by hand, when it refuses: splice the delta's entries into the registry
 file that owns their prefix; then for each \`*.proposed.spec.ts\`, **repoint its
@@ -400,7 +461,7 @@ move, so nothing else about it does either. Then move the change folder.
 | \`attest cover\` | which requirements lack a scenario. |
 | \`attest render\` | the registry as Markdown for human readers; \`--check\` gates a committed copy. |
 | \`attest archive <change>\` | the completion gate for a proposed change; \`--apply\` also performs the merge it approves. |
-| \`attest status <change>\` | what that gate still wants, without running the suite. |
+| \`attest status <change>\` | per id the change ADDs, two of the gate's obligations — scenario written, seen red — read without running the suite. A strict subset of the gate, never a second one. |
 
 \`verify\` starts the child run **isolated** — it does not read \`vitest.config.ts\`,
 so a verdict never depends on ambient configuration. Specs needing transforms, a

package/dist/core/splice.d.ts

@@ -36,6 +36,64 @@ export declare function requirementSource(id: string, req: Requirement, indent:
  * the same delta must produce the same file twice.
  */
 export declare function spliceRequirements(file: string, source: string, additions: Registry): string | undefined;
+/**
+ * One requirement a change modifies: what the registry holds, and what the gate
+ * proved the end state to be.
+ *
+ * Both halves, rather than the delta's patch, for the reason `MergeInputs.applied`
+ * exists — the patch is the authoring shape and the end state is what was proved
+ * green. Which fields actually move is then a *derived* fact, computed here by
+ * comparing the two, so a delta that restates a value it does not change writes
+ * nothing.
+ */
+export interface Modification {
+    id: string;
+    /** The entry as the file holds it — the gate's `base`. */
+    before: Requirement;
+    /** The entry as the gate proved it — `applied`. */
+    after: Requirement;
+}
+/**
+ * Why one value could not be written over, if it could not.
+ *
+ * `field` is `statement`, `outOfScope`, `params.totpWindowSec` — the path of the
+ * value, spelled the way the author would say it — and absent only when the
+ * refusal is about the entry rather than a value in it. The caller turns these
+ * into diagnostics; nothing here writes prose, because a refusal from this
+ * module refuses a whole merge and only the caller knows what to say about that.
+ */
+export interface ModifyRefusal {
+    reqId: string;
+    field?: string;
+    reason: 'comment' | 'entry-not-found' | 'not-a-literal' | 'param-dropped';
+}
+export type ModifyResult = {
+    ok: true;
+    source: string;
+} | {
+    ok: false;
+    refusals: ModifyRefusal[];
+};
+/**
+ * `source` with each modified requirement's **changed values** written over.
+ *
+ * The other half of `--apply`'s write-back, and the one the design refused for
+ * five releases. What makes it allowable is stated at the top of this file and
+ * is a property of *granularity*: this never replaces an entry, only the span of
+ * a value inside one. A `statement` is a single string literal, so a comment
+ * cannot be inside what it overwrites; a `params` key or an `outOfScope` list
+ * can be, and that span is the only place this has to ask. Everything else in
+ * the file — the keys, the commas, the layout, every comment attached to a field
+ * that did not move — is bytes this does not address.
+ *
+ * A refusal is per value and the caller's response is whole-merge: the list is
+ * returned complete rather than at the first one, so an author fixing them by
+ * hand sees the whole of what stopped it.
+ *
+ * `undefined` under the same condition `spliceRequirements` returns it, through
+ * the same reader.
+ */
+export declare function spliceModifications(file: string, source: string, changes: readonly Modification[]): ModifyResult | undefined;
 /**
  * `source` with every import of `from` repointed at `to`.
  *
@@ -45,9 +103,10 @@ export declare function spliceRequirements(file: string, source: string, additio
  * discipline as the splice, for the same reason.
  *
  * The extension is taken from the specifier being replaced rather than chosen
- * here. Whether a project writes `./x.reqs.js` or `./x.reqs.ts` is a property of
- * its module resolution, uniform across the project, and already answered by the
- * specifier sitting in front of us.
+ * here. Whether a project writes `./x.reqs.js`, `./x.reqs.ts` or `./x.reqs` is a
+ * property of its module resolution, uniform across the project, and already
+ * answered by the specifier sitting in front of us — the third spelling
+ * included, where the answer is "none".
  */
 export declare function repointImport(file: string, source: string, from: string, to: string): string;
 //# sourceMappingURL=splice.d.ts.map