@am_shork/attest 0.7.4 → 0.9.0

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.
  *
@@ -102,6 +106,19 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   rule forbids, and the distinction is the whole of it — that rule is about the
   **expectation** the system is measured against; this pin asserts what the
   **intent** is.
+- **Prefer a quantifier a scenario can iterate.** A statement that says *every*,
+  *all* or *any* has a finite set of scenarios under it and nothing holding the
+  two together — the id is covered, \`check\` is green, and whether those
+  scenarios span what the sentence claims is the part no gate looks at. What
+  decides the risk is *what* the quantifier ranges over. Over the inputs one
+  place processes, representative inputs settle it. Over a list the code itself
+  enumerates, a scenario looping that same list covers a new member by
+  construction — **this is the shape to write**, and when that list lives in
+  \`params\` rather than in the code, the pin above is what keeps it honest, since
+  an author can shorten it. Over *places in the implementation*, each needing its
+  own hand-written scenario, a new place is a new obligation and nothing
+  enumerates them: that is the one that silently stops being true. When you cannot avoid it, name the places in the statement instead
+  of quantifying over them, so a reader can count what is missing.
 
 ## Rules the engine enforces
 
@@ -115,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
@@ -163,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
@@ -266,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.
@@ -304,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
@@ -352,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.
@@ -366,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
@@ -387,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