@am_shork/attest 0.8.0 → 0.9.1

package/dist/core/merge.js

@@ -4,8 +4,11 @@
 // until now a human then transcribed it by hand with nothing checking the
 // transcription. This is that step, and the whole of why it is allowed to exist
 // where the `AGENTS.md` merge tool was not: the registry is a literal Attest
-// defines, so the result of an edit is checkable by re-reading it, and the edit
-// itself is a pure insertion (`splice.ts`).
+// defines, so the result of an edit is checkable by re-reading it — and this
+// re-reads it (`verifyWritten`), rather than resting on the sentence. The edits
+// are bounded to match: an ADDED requirement is a pure insertion, and a MODIFIED
+// one replaces the span of a single value inside an entry it never rewrites
+// (`splice.ts`).
 //
 // **It is re-runnable, not atomic.** No primitive spans one edit, N renames and
 // a directory move, and a scratch copy of the project root would have to be
@@ -30,10 +33,11 @@
 // at runtime on the happy path, and a later reordering would look harmless.
 import { mkdir, readFile, rename, stat } from 'node:fs/promises';
 import { join, dirname, basename } from 'node:path';
-import { repointImport, spliceRequirements, UnwritableValue } from './splice.js';
+import { repointImport, spliceModifications, spliceRequirements, UnwritableValue, } from './splice.js';
+import { readRegistrySource } from './static-registry.js';
 import { writeAtomic } from './write.js';
 import { idPrefix } from './locate.js';
-import { addedIds } from './apply.js';
+import { addedIds, modifiedIds, sameRequirement } from './apply.js';
 import { byCodeUnit } from './order.js';
 import { relativePath } from './paths.js';
 /** `x.proposed.spec.ts` -> `x.spec.ts`, in place. */
@@ -48,8 +52,8 @@ export function mergedSpecPath(proposed) {
  * acting on it, and a merge that did the half it understood would put the file
  * into a state no verdict describes.
  */
-async function refusals(input, stamp) {
-    const issues = [];
+async function refusals(input, stamp, planned) {
+    const issues = [...planned];
     const { delta, root, changeName } = input;
     const archive = archivePath(input, stamp);
     // 0) The destination already exists. Checked here, before anything is
@@ -67,28 +71,34 @@ async function refusals(input, stamp) {
         });
     }
     // 1) Operations this does not perform. The gate applies all four in memory to
-    // reach its verdict; only writing them back is limited to ADDED, because
-    // REMOVED cannot say which comments belonged to the entry it deletes and
-    // MODIFIED is a formatting-preserving edit inside an existing literal. Both
-    // are the "destructive on a file the user cannot regenerate" shape.
+    // reach its verdict; writing them back covers ADDED and MODIFIED, and stops
+    // there because REMOVED cannot say which comments belonged to the entry it
+    // deletes — the "destructive on a file the user cannot regenerate" shape.
+    // MODIFIED was refused by this same clause until it was written at the
+    // granularity of a *value* rather than an entry, which is where that sentence
+    // stops applying and REMOVED's does not: an entry being deleted has no smaller
+    // span to fall back to (`splice.ts`).
     const unsupported = [
         delta.renamed?.length ? 'renamed' : '',
         delta.removed?.length ? 'removed' : '',
-        Object.keys(delta.modified ?? {}).length ? 'modified' : '',
     ].filter(Boolean);
     if (unsupported.length > 0) {
         issues.push({
             level: 'ERROR',
             code: 'apply-unsupported-delta',
             file: relativePath(root, join(root, 'changes', changeName)),
-            message: `--apply writes back ADDED requirements only, and this change's delta also carries ${unsupported.join(', ')}. ` +
+            message: `--apply writes back ADDED and MODIFIED requirements, and this change's delta also carries ${unsupported.join(', ')}. ` +
                 `The gate above still checked all of it — merge the remaining operations into the registry by hand, then run this command again to confirm.`,
         });
     }
-    // 2) An added id whose prefix no registry file claims. Which file it belongs
+    // 2) An id whose prefix no registry file claims. Which file it belongs
     // in — or whether a file should be created for it — is not something the gate
-    // verified, and guessing would file a requirement somewhere nobody chose.
-    for (const id of unmergedAdded(input)) {
+    // verified, and guessing would file a requirement somewhere nobody chose. Over
+    // modified ids as well as added ones: an unowned prefix is why the merge cannot
+    // find the file, and reporting it as "no entry to modify" would send the reader
+    // to look inside a file this never opened.
+    const unowned = new Set([...unmergedAdded(input), ...modifiedIds(input.delta)]);
+    for (const id of [...unowned].sort(byCodeUnit)) {
         if (input.prefixOwners[idPrefix(id)] === undefined) {
             issues.push({
                 level: 'ERROR',
@@ -146,6 +156,182 @@ function registryTargets(input, reqIds) {
 function unmergedAdded(input) {
     return addedIds(input.delta).filter((id) => !Object.hasOwn(input.base, id));
 }
+/**
+ * The requirements this change modifies that the registry on disk does not
+ * already hold in its end state.
+ *
+ * The MODIFIED half of re-runnability, and deliberately the same shape as
+ * `unmergedAdded`: derived from the tree as it currently is rather than from a
+ * list of what a previous run meant to do. An entry already equal to `applied`
+ * is not edited, so a re-run after a crash writes what is left and nothing else
+ * — and a delta restating a value it does not change writes nothing at all.
+ */
+function unmergedModified(input) {
+    const out = [];
+    for (const id of modifiedIds(input.delta)) {
+        const before = input.base[id];
+        const after = input.applied[id];
+        // A modified id the base does not have is `modify-missing`, which the gate
+        // reports and this never reaches; skipped rather than diagnosed a second
+        // time, because two commands answering for one condition is how they come to
+        // disagree.
+        if (!before || !after || sameRequirement(before, after))
+            continue;
+        out.push({ id, before, after });
+    }
+    return out;
+}
+/**
+ * What every registry file should end up holding, or why it cannot — computed
+ * without writing anything.
+ *
+ * Split from the write for one reason: a refusal that fires after two files have
+ * landed makes "refused whole" a claim with an exception in it, which is the
+ * kind of claim nobody can rely on (the note on `refusals` step 0 says the same
+ * thing about the archive destination). Both edits to a file are composed here,
+ * modification before splice, and the splice re-reads the text the modification
+ * produced rather than an offset taken before it — an insertion point is a
+ * position in a file, and the modification has just moved bytes in front of it.
+ */
+async function planRegistries(input) {
+    const { root } = input;
+    const issues = [];
+    const added = new Map();
+    const modified = new Map();
+    for (const id of unmergedAdded(input)) {
+        const file = input.prefixOwners[idPrefix(id)];
+        if (!file)
+            continue; // Refused as `apply-no-prefix-owner`; not diagnosed twice.
+        const group = added.get(file) ?? {};
+        group[id] = input.applied[id];
+        added.set(file, group);
+    }
+    for (const change of unmergedModified(input)) {
+        const file = input.prefixOwners[idPrefix(change.id)];
+        if (!file)
+            continue;
+        modified.set(file, [...(modified.get(file) ?? []), change]);
+    }
+    const files = [];
+    for (const file of [...new Set([...added.keys(), ...modified.keys()])].sort(byCodeUnit)) {
+        const source = await readFile(file, 'utf8');
+        const mods = modified.get(file) ?? [];
+        const adds = added.get(file);
+        const ids = [...mods.map((m) => m.id), ...Object.keys(adds ?? {})].sort(byCodeUnit);
+        const changed = spliceModifications(file, source, mods);
+        if (!changed) {
+            issues.push(unreadable(root, file));
+            continue;
+        }
+        if (!changed.ok) {
+            issues.push(...changed.refusals.map((r) => modifyRefusal(root, file, r)));
+            continue;
+        }
+        let text = changed.source;
+        if (adds) {
+            try {
+                const spliced = spliceRequirements(file, text, adds);
+                if (spliced === undefined) {
+                    issues.push(unreadable(root, file));
+                    continue;
+                }
+                text = spliced;
+            }
+            catch (err) {
+                // The emitter refused a value it cannot write as source — today only a
+                // `__proto__` param key, which the schema rejects before `--apply` runs.
+                // Caught rather than left to the CLI's crash envelope because `--apply`
+                // is destructive and a bare stack is the shape a resume cannot read.
+                if (!(err instanceof UnwritableValue))
+                    throw err;
+                issues.push({
+                    level: 'ERROR',
+                    code: 'internal-error',
+                    file: relativePath(root, file),
+                    message: `${relativePath(root, file)} could not be written: ${err.message}.`,
+                });
+                continue;
+            }
+        }
+        files.push({ file, source, text, ids });
+    }
+    return { files, issues };
+}
+/**
+ * Whether the file just written reads back as the requirements it was written
+ * from — the check the whole argument for editing a hand-written registry rests
+ * on, performed rather than argued.
+ *
+ * "The result of an edit is checkable by re-reading it" is the clause that
+ * separates this from the merge tool the `AGENTS.md` proposal was rejected for,
+ * and until MODIFIED existed nothing did the re-reading: a pure insertion is
+ * right by construction, so the sentence was load-bearing without being
+ * exercised. A replacement is not, so the re-read is here for both — the added
+ * entries included, because a check that covered only the newer half would leave
+ * the older claim in exactly the state this is fixing.
+ *
+ * What it cannot see is the other half, and saying so is the point: a re-read
+ * compares *values*, and a comment or a blank line that went missing does not
+ * appear in a `Registry` at all. That is why the edit is bounded to the span of
+ * one value rather than trusted to this (`splice.ts`).
+ */
+async function verifyWritten(input, plan) {
+    const { root } = input;
+    const back = readRegistrySource(plan.file, await readFile(plan.file, 'utf8'));
+    const wrong = back.ok
+        ? plan.ids.filter((id) => {
+            const written = back.registry[id];
+            const proved = input.applied[id];
+            return !written || !proved || !sameRequirement(written, proved);
+        })
+        : plan.ids;
+    if (wrong.length === 0)
+        return undefined;
+    return {
+        level: 'ERROR',
+        code: 'internal-error',
+        file: relativePath(root, plan.file),
+        message: `${relativePath(root, plan.file)} was written, but reading it back does not give the requirements the gate proved (${wrong.join(', ')}). ` +
+            `Check that file against the change's delta before running anything else — the merge stopped here, so the steps after it have not run.`,
+    };
+}
+/** The registry the gate read a moment ago, unreadable to the merge. */
+function unreadable(root, file) {
+    // Unreachable through the command, so it is reported as the internal
+    // inconsistency it is rather than as a diagnosis about the user's registry.
+    return {
+        level: 'ERROR',
+        code: 'internal-error',
+        file: relativePath(root, file),
+        message: `${relativePath(root, file)} read as a registry for the gate but not for the merge.`,
+    };
+}
+/**
+ * One value the merge declined to write over, as a diagnostic.
+ *
+ * The code is the one an unsupported operation already carries: to a consumer
+ * branching on `code`, "this delta has a part `--apply` does not write" is the
+ * same fact whichever part it is, and the narrowing that made most MODIFIED
+ * deltas writable should not cost anyone a new string to handle. The `reqId` and
+ * the field are what changed, and both are in the message where the reader is.
+ */
+function modifyRefusal(root, file, refusal) {
+    const where = refusal.field ? `${refusal.reqId}.${refusal.field}` : refusal.reqId;
+    const why = {
+        comment: `a comment sits inside the value it would replace, and which side of that edit the comment belongs to is not something --apply can decide`,
+        'entry-not-found': `the registry file that owns its prefix holds no entry for it`,
+        'not-a-literal': `the value it would replace is not written as a literal`,
+        'param-dropped': `the proved end state does not carry that param, and a delta has no way to say one was removed`,
+    };
+    return {
+        level: 'ERROR',
+        code: 'apply-unsupported-delta',
+        reqId: refusal.reqId,
+        file: relativePath(root, file),
+        message: `--apply cannot write "${where}" into ${relativePath(root, file)}: ${why[refusal.reason]}. ` +
+            `Merge this requirement by hand, then run this command again to confirm — nothing has been written.`,
+    };
+}
 /**
  * Perform the merge, or refuse it whole.
  *
@@ -163,67 +349,27 @@ export async function applyMerge(input) {
     // another — rare, and silent when it happens, which is the combination this
     // repository treats as worth the line.
     const stamp = new Date().toISOString().slice(0, 10);
-    const refused = await refusals(input, stamp);
+    // Every registry edit is computed before any of them is written, which is what
+    // makes "refused whole" true of the write-back and not only of the delta's
+    // shape: a comment sitting where a modification would land, or a value the
+    // emitter cannot write, is now found with the tree still untouched. Before
+    // MODIFIED existed the text generation could only fail on a `__proto__` key
+    // and it failed one file at a time, so this was the same claim by luck.
+    const planned = await planRegistries(input);
+    const refused = await refusals(input, stamp, planned.issues);
     if (refused.length > 0)
         return { issues: refused, written: [] };
     const { root } = input;
     const written = [];
-    // --- 1) Splice, first. See the note at the top of this file.
-    const byFile = new Map();
-    for (const id of unmergedAdded(input)) {
-        const file = input.prefixOwners[idPrefix(id)];
-        const group = byFile.get(file) ?? {};
-        group[id] = input.applied[id];
-        byFile.set(file, group);
-    }
-    for (const file of [...byFile.keys()].sort(byCodeUnit)) {
-        const source = await readFile(file, 'utf8');
-        let spliced;
-        try {
-            spliced = spliceRequirements(file, source, byFile.get(file));
-        }
-        catch (err) {
-            // The emitter refused a value it cannot write as source — today only a
-            // `__proto__` param key, which the schema rejects before `--apply` runs.
-            // Caught rather than left to the CLI's crash envelope so the account of
-            // what this merge had already written survives: `--apply` is destructive
-            // and half a merge reported as a bare stack is the shape a resume cannot
-            // read. The write for *this* file has not happened — the throw is in the
-            // text generation, above `writeAtomic`.
-            if (!(err instanceof UnwritableValue))
-                throw err;
-            return {
-                issues: [
-                    {
-                        level: 'ERROR',
-                        code: 'internal-error',
-                        file: relativePath(root, file),
-                        message: `${relativePath(root, file)} could not be written: ${err.message}.`,
-                    },
-                ],
-                written,
-            };
-        }
-        if (spliced === undefined) {
-            // Unreachable through the command — the gate read this file as a literal
-            // moments ago — so it is reported as the internal inconsistency it is
-            // rather than as a diagnosis about the user's registry.
-            return {
-                issues: [
-                    {
-                        level: 'ERROR',
-                        code: 'internal-error',
-                        file: relativePath(root, file),
-                        message: `${relativePath(root, file)} read as a registry for the gate but not for the merge.`,
-                    },
-                ],
-                written,
-            };
-        }
-        if (spliced !== source) {
-            await writeAtomic(file, spliced);
-            written.push(relativePath(root, file));
-        }
+    // --- 1) Write the registries, first. See the note at the top of this file.
+    for (const plan of planned.files) {
+        if (plan.text === plan.source)
+            continue;
+        await writeAtomic(plan.file, plan.text);
+        written.push(relativePath(root, plan.file));
+        const mismatch = await verifyWritten(input, plan);
+        if (mismatch)
+            return { issues: [mismatch], written };
     }
     // --- 2) Repoint each claimed spec's delta import, then rename it in place.
     //

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