@am_shork/attest 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -13,6 +13,193 @@ input, removes/renames a public API or `--json` field, or changes a default
 runtime behavior an existing invocation relies on — diagnostic message text is
 not API.
 
+## [0.6.0] - 2026-08-03
+
+### Added
+
+- **The workflow `attest init` writes now describes this release, and one line
+  of it was telling agents to undo correct work.** The skill is the document an
+  agent reads without a human in the loop, and it had drifted twice.
+  **The wrong line.** Its merge step said the specs are renamed in place with
+  *"no import changes; if you find yourself editing a specifier, the spec was not
+  written at its merged location and stage 1 was the place to fix that."* Sixty
+  lines above, the same document teaches a stage-1 scenario to read its proposed
+  params from the delta — `import reqs from '../../changes/<name>/requirements.delta.ts'`
+  — with the comment *"only this line changes at merge"*. So the file contradicted
+  itself, and an agent following it either left a merged spec importing a path
+  that step 3 had moved into `archive/`, or concluded a correctly-written spec was
+  wrong and moved it, producing the very rewrite the sentence claimed to prevent.
+  Exactly the defect `--apply` hit while being built, sitting in the document that
+  is trusted furthest.
+  The merge step is now `attest archive <name> --apply`, with the by-hand path
+  kept for the operations it refuses and stated correctly: one specifier changes,
+  and it changes because the delta moves, not because the spec was misplaced.
+  Two prevention lines added where they cost nothing — a spec under `changes/`
+  is `spec-in-change-dir`, and a proposed name whose merged form is taken is
+  `proposed-spec-name-taken`, which is an authoring-time choice and so belongs in
+  the authoring guide rather than only in a diagnostic. `compiler-unsupported` is
+  deliberately **not** added to the stage-2 table: that table answers "what does
+  this mean for my change in flight", and a toolchain failure is not something an
+  agent fixes by editing the change.
+  **The gate that was missing** is now `ATX-57`. Troubleshooting is asserted
+  against `ISSUE_CODES` in both languages and the CLI reference against this file,
+  while the skill's content was held by four `toContain` calls and otherwise by
+  eye — the wrong footing for the one document whose reader is not a person and
+  who branches on the codes in it. Every code-shaped token it names is checked
+  against the roster, one-directionally: the workflow has no business naming every
+  code, so the obligation is only that what it does name exists. `ATX-40` is the
+  same shape pointing the other way over the other document. Given a requirement
+  rather than left a plain test for the reason this project exists: a gate that is
+  not itself gated is a gate someone deletes, and without one over it, removing
+  the check is a green diff.
+  `attest init` is idempotent and takes no input, so re-running it after upgrading
+  is the whole update mechanism; nothing here changes that.
+
+- **A compiler with no AST API is now a diagnosis rather than a crash
+  (`compiler-unsupported`).** Discovered by building the `typescript` matrix in
+  `[0.4.2]`, which is what a matrix is for. `typescript@7` is the native port: its
+  package resolves, imports cleanly and still answers `version`, while the AST
+  moved behind `typescript/unstable/ast*` — so `createSourceFile` and every
+  `ts.isX` guard both registry readers and the spec parser call is `undefined`,
+  and the first one touched throws. Measured: `attest check` died with
+  `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
+  stack — no code, no fix hint, and nothing saying which compiler it wanted, on
+  the crash path `[0.4.2]` had just finished sanitising.
+  **The declared range excludes 7, and that is not the same as being safe from
+  it.** A caret is a request, not a constraint an adopter cannot override:
+  `pnpm.overrides` and Yarn `resolutions` both pin a transitive dependency across
+  a whole tree, and a repo standardising on one compiler is exactly the repo that
+  uses them — this one has an `overrides` block of its own. So the reachable case
+  is a deliberate, reasonable act answered with a stack trace.
+  Every AST-reading command now refuses before it opens a file, naming the version
+  it found and the supported range. The range lives in `ATX-56`'s `params` and its
+  scenario compares that against `package.json`: a diagnostic naming a range that
+  has drifted from the dependency it describes is worse than one naming none.
+  The refusal takes a compiler rather than reaching for the import, because the
+  condition exists only on a compiler this repository cannot install beside the
+  one it builds with — and a check nothing can make fail is the `never-red` shape
+  the gate exists to catch.
+  *What it does not do is make Attest work on TypeScript 7.* That is a migration
+  to `typescript/unstable/ast`, against an API whose own name says not to depend
+  on it yet. The honest answer for now is a supported ceiling that says so, and
+  `troubleshooting.md` carries the override-scoping escape for anyone pinning the
+  compiler tree-wide.
+  This is a behaviour change only in the sense that a crash became an exit code:
+  nothing that worked before reports it.
+
+- **`attest archive <change> --apply` finishes the merge its gate approved.**
+  The gate proved a delta green, covered and drift-free, and a human then
+  transcribed it by hand with nothing checking the transcription — the verdict did
+  not cover the step acting on it. Reported by `mine-capablanca`: eight changes,
+  eight hand-written Python scripts, one of which located the delta's block by
+  `split('added: {', 1)`, trimmed two spaces of indent per line and re-terminated
+  the registry on `assert t.endswith('});')`.
+  Three steps, and the gate runs first in the same invocation: splice each ADDED
+  requirement into the registry file owning its prefix, repoint and rename the
+  change's proposed specs, move `changes/<name>/` to `archive/<date>-<name>/`.
+  Every path touched is printed. A red gate writes nothing, and there is no flag
+  that skips it — a merge acting on an earlier run's verdict could file an
+  unfinished change as done, which is the one thing this tool must not ship.
+  **Why this is not the `AGENTS.md` merge tool, which stays rejected.** That was
+  refused because "each of its failure modes is destructive on a file the user
+  cannot regenerate". The registry is a literal Attest defines, statically
+  parseable, with two readers already asserted to agree on it — so the result of an
+  edit is checkable by re-reading it. That clause only holds if the edit is a
+  **pure insertion**, so nothing renders a registry back out of a `Registry`
+  object: doing so would be easier and would drop every comment and layout choice
+  in a hand-written file while passing a re-read with flying colours, because the
+  values all survived. `tests/splice.spec.ts` asserts the insertion is pure by
+  reconstructing the original from the result, rather than by looking for the
+  comments — the comments are a sample of the property, not the property.
+  **Re-runnable rather than atomic, which is what pinned the step order.** No
+  primitive spans one edit, N renames and a directory move, and a scratch copy of
+  the project root would have to be swapped back through the same non-atomic set
+  again. So every step is derived from the tree as it currently is, and a partial
+  application is finished by running the same command again. `ATX-53` states that
+  and deliberately **not** the order it is bought with: an order is not observable —
+  every ordering agrees on the happy path — so a requirement about it could not be
+  falsified, which is the `never-red` shape the gate exists to catch. Resumability
+  can be falsified, and it fails exactly when the order is wrong: move the folder
+  first and the recovery has no delta left to re-derive from; rename before
+  splicing and the intermediate tree has merged specs reading a registry without
+  their ids.
+  **ADDED only, and refused whole otherwise** (`apply-unsupported-delta`,
+  `apply-no-prefix-owner`). The gate still applies all four operations in memory,
+  so nothing becomes unverifiable — only the write-back stops, 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 shape the
+  rejection named. Whole rather than partial because an implementation that merged
+  the half it understood would hand back a change the author believes is done.
+  **The collision that would have destroyed work** ships with it as
+  `proposed-spec-name-taken`, reported by `check`. `isSpecFile` and
+  `isProposedSpecFile` are disjoint, so `session.spec.ts` and
+  `session.proposed.spec.ts` coexist with nothing objecting — and the rename would
+  overwrite the first. Not a corner: a proposed spec is written beside the code it
+  attests, so a change to an already-tested module reaches for exactly that name.
+  Held in `check` rather than only refused at merge time, so the fix is a rename
+  while renaming is still free.
+  **One clause of this entry's own argument was wrong, and building it is what
+  found out.** It recorded that `[0.5.0]` had removed the import-rewriting blocker
+  outright, because a proposed spec sits at its merged location and merging it is
+  "a rename in place". True of its *location* — but `[0.5.0]` also made a delta
+  read as the registry it proposes, so a stage-1 scenario imports the delta, and
+  step 3 moves the delta away. The first working version of this command moved all
+  three things correctly and left every merged spec importing a path that no longer
+  existed; `check` was silent, and only running the merged suite showed it. So one
+  specifier is repointed after all — located by AST, replaced as text, with the
+  expression around it untouched because `reqs['AUTH-7'].params.x` reads the same
+  on both sides. Far smaller than "rewriting arbitrary TypeScript", but not the
+  zero this file claimed. `ATX-52` therefore attests that the *merged project
+  verifies clean*, not that three files moved: the broken version would have passed
+  the second.
+  **It does not re-render a committed `SPEC.md`,** and cannot: nothing in a project
+  records where its rendering lives, so the entry listing that as a fourth step was
+  describing something with no input. `render --out` afterwards, which a pipeline
+  running `render --check` already asks for.
+  `ATX-52`–`ATX-55`, with eight scenarios. `--apply` is additive — no exit code
+  moves for anyone not passing it — but `proposed-spec-name-taken` is a new ERROR
+  on `check` and **will turn some CI red**: a layout that passed before now fails,
+  and everything it fails would have been destroyed by the first merge.
+
+- **`check` now names a spec left under `changes/`, where nothing walks it
+  (`spec-in-change-dir`).** `[0.5.0]` moved a change's specs to their merged
+  location and told anyone with an open change directory to move each file,
+  rename it `*.proposed.spec.ts` and fix its imports once. It did not account for
+  the state *before* that is carried out. `changes` is in the project walk's
+  skip list, and `[0.5.0]` removed `changeExcludeGlobs` — the mechanism by which
+  `attest archive <name>` used to include `changes/<name>/specs/` explicitly.
+  Both halves are right on their own; together they mean the old location is
+  walked by no command.
+  **Measured before it was fixed**, on a copy of `fixtures/e2e-archive` with its
+  proposed spec put back at `changes/add-totp/specs/totp.spec.ts` and its two
+  specifiers re-depthed: `attest check` exited **0** with `✓ No issues.`, and the
+  only command that spoke was the gate — `uncovered-requirement`, verbatim
+  *"Requirement "AUTH-7" has no scenario attesting it. Add a scenario, or mark it
+  deferred."* The author had written two, and both were correct. So the one
+  diagnostic available told them to write what they had written, or to defer a
+  requirement they had finished. That is the misdiagnosis shape `ATX-49` records,
+  arriving from the other direction — there the verdict pointed away from a load
+  failure, here away from a path — and in both cases it spends the reader's
+  attention on files that are fine.
+  In `check` rather than the gate: the gate at least fails, while `check` is both
+  the command a pipeline runs first and the one that said nothing at all. Both
+  spellings are reported, because a `*.proposed.spec.ts` under `changes/` is a
+  migration done halfway — the right marker at the wrong path — and no more
+  reachable than one never begun. An ERROR rather than a warning for `ATX-47`'s
+  reason: a spec that runs nowhere is a total failure, not a misplaced one.
+  *It is not transitional and does not expire.* After `[0.5.0]` a spec under
+  `changes/` is wrong permanently; catching an unfinished upgrade is what it is
+  worth first, not what it is for.
+  **This is a behaviour change and turns some CI red** — a layout that passed
+  `check` in `[0.5.0]` now fails it. That is the point, and everything it fails
+  was already running nowhere. `ATX-51`, with three scenarios: the pre-move
+  spelling, the half-migrated one, and a proposed spec at its merged location
+  that must *not* be reported, because a check firing on the documented workflow
+  would be §9's "usually wrong about staleness" failure again.
+  Found while asking whether a *different* proposed check — the merged-name
+  collision under `attest archive --apply`, still in `Planned` — would help
+  anyone upgrading. It would not; this does.
+
 ## [0.5.0] - 2026-08-03
 
 ### Changed
@@ -2249,44 +2436,26 @@ feedback reports are triaged into issues or `Unreleased` and deliberately not
 kept in this tree; that rule stands, and holds for anything with a reporter, a
 repro, or a state to track. What is kept here is the narrower thing this file
 already keeps one section of: a **decision with an argument attached**, where
-losing the argument would cost more than losing the task. The first below came out
-of building something queued here, which is one way an entry arrives: a gate that
-finds a defect on its first run files the defect. The second came out of reading
-another repository against this one — `msw`. The last came out of an adoption
-report (`mine-capablanca`, 0.4.2, 34 requirements / 56 scenarios / greenfield),
-which is the third way: not a defect, but a shape the tool made an adopter work
-around eight times without ever erroring. Two further entries from that report
-left this section by shipping in `[0.5.0]` — a change's specs moving to their
-merged location, and the delta reading as the registry of what it adds — and
-their arguments are recorded there, including the part of the first one that
-turned out to be wrong.
-
-- **A diagnosable refusal when the resolved compiler has no AST API.**
-  Discovered by building the `typescript` matrix (see `[0.4.2]`), which is
-  what a matrix is for. `typescript@7` is the native port: its npm package's main
-  export is `{ version, versionMajorMinor }`, and the AST moved behind
-  `typescript/unstable/ast*` — so `ts.createSourceFile` and every `ts.isX` guard
-  the two readers call is `undefined`. Measured: `attest check` on it dies with
-  `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
-  stack, on the crash path this release just finished sanitising. No issue code,
-  no fix hint, and nothing saying which compiler it wanted.
-  **The range excludes 7, and that is not the same as being safe from it.** A
-  caret is a request, not a constraint the adopter cannot override: `pnpm.overrides`
-  and Yarn `resolutions` both pin a transitive dependency across the whole tree,
-  and a repo standardising on one compiler is exactly the repo that uses them —
-  this one has an `overrides` block of its own. So the reachable case is a
-  deliberate, reasonable act by an adopter, answered with a stack trace.
-  What is planned is a check of the API surface where the readers are entered,
-  reported as an ERROR naming the resolved version and the supported range. Cheap,
-  and it converts the one dependency failure this tool cannot survive from a crash
-  into a diagnosis. *Deliberately not folded into the matrix commit*: a new ERROR
-  is a behaviour change, it needs an issue code, a troubleshooting section in both
-  languages and an `ATX-n` with a scenario, and none of that belongs in a commit
-  whose whole claim is that nothing about behaviour moved.
-  *What it cannot do:* make Attest work on TypeScript 7. That is a migration to
-  `typescript/unstable/ast`, against an API whose own name says not to depend on
-  it yet — a separate decision, with the honest answer for now being that the
-  supported range has a ceiling and says so.
+losing the argument would cost more than losing the task. The one below came out
+of reading another repository against this one — `msw`.
+
+Five entries have left by being built, and the last three left together in
+`[0.6.0]`. `compiler-unsupported` came from building something queued here,
+which is one way an entry arrives: a gate that finds a defect on its first run
+files the defect, and the `typescript` matrix `[0.4.2]` added is what found this
+one.
+`--apply` came from an adoption report (`mine-capablanca`, 0.4.2, 34 requirements
+/ 56 scenarios / greenfield) — a third way an entry arrives: not a defect, but a
+shape the tool made an adopter work around eight times without ever erroring. It
+took `spec-in-change-dir` out with it, by a fourth way worth naming: designing one
+of `--apply`'s checks surfaced a different one, against a migration this file had
+itself shipped. **What a release costs its adopters is not fully known on the day
+it is cut** — and building the entry is what finds out, which is also how
+`--apply` discovered that one clause of its own argument here was wrong. Both are
+recorded under `[0.6.0]`, and two earlier entries from the same report left
+by shipping in `[0.5.0]` — a change's specs moving to their merged location, and
+the delta reading as the registry of what it adds — their arguments recorded
+there, including the part of the first one that turned out to be wrong.
 
 - **Region-marked samples, so a partial quote can be bound too.** The whole-file
   half of this shipped in `[0.4.3]`: the README's two getting-started blocks
@@ -2435,80 +2604,6 @@ have to gather again.
   here rather than moving to `Considered and rejected`: documenting a trap is
   not the same as deciding not to detect it.
 
-- **`attest archive <change> --apply`, finishing the merge the gate approved.**
-  `mine-capablanca`'s single loudest item: eight changes, eight hand-written
-  Python scripts, and the report quotes one — it locates the delta's block by
-  `split('added: {', 1)`, trims two spaces of indent per line, and re-terminates
-  the registry on `assert t.endswith('});')`. After the gate goes green the
-  adopter hand-splices the delta into the registry, moves specs into the suite,
-  rewrites their imports, moves the folder to `archive/` and re-renders `SPEC.md`.
-  **The cost is the smaller half of the argument. The hole is that the gate's
-  verdict does not cover the step that acts on it** — `archive` proves the delta
-  is green, covered and drift-free, and then a human transcribes it by hand with
-  nothing checking the transcription. A delta can be spliced in wrong, partially,
-  or twice, and the next `check` sees only whatever ended up in the file.
-  **The objection that has to be answered is the `AGENTS.md` block under
-  `Considered and rejected`.**
-  The `AGENTS.md` block was rejected because "that is a merge tool, and each of
-  its failure modes is destructive on a file the user cannot regenerate". The
-  argument for why it does not transfer, which needs to be right before this
-  ships: there, Attest would edit prose whose grammar it does not own; here the
-  registry is a **literal** Attest defines, statically parseable, with a
-  differential suite already asserting two readers agree on it — so the result of
-  a splice is checkable by re-reading it, and the delta was validated by the gate
-  that just ran. Idempotence is verifiable rather than assumed. That reasoning
-  covers delta→registry, the folder move and the re-render. It used **not** to
-  cover import rewriting, which is editing arbitrary TypeScript and is squarely
-  the rejected shape.
-  *That blocker is gone, and it was removed rather than solved.* Proposed specs
-  now live at their merged location under `*.proposed.spec.ts` (`[0.5.0]`), so
-  the merge step for a spec is a rename in place — there are no specifiers to
-  rewrite, and `--apply` no longer inherits the one part of the job that could
-  not be made safe. What is left for it is the delta→registry splice, the rename,
-  the folder move to `archive/` and the re-render, all of which the paragraph
-  above argues are checkable by re-reading the result.
-  *What still blocks the decision:* two questions with no answer yet — what
-  `--apply` does when the working tree is dirty (`archive` already has a position
-  on this; whether a file-mutating flag takes the same one is not obvious), and
-  whether a partially applied merge is recoverable or whether the flag must be
-  all-or-nothing against a scratch copy.
-  *The frequency blocker has moved.* This entry used to close on "one report, one
-  repo: the cost evidence is strong and the frequency evidence is a single
-  adopter." It is now two. This project's own maintainer proposed the same command
-  independently, without the entry in front of them, having felt the same step by
-  hand — which is the second data point that clause was waiting for. Not
-  conclusive about frequency in the field, and it does not touch either question
-  above, but it removes the reason to keep waiting for someone else to ask.
-
-  *A narrower shape was proposed with it and is rejected — `attest merge <change>`,
-  moving the change folder to `archive/<date>-<name>/` and nothing else.* Three
-  reasons, and the third is the one that decides it.
-  **(1) It targets the cheap half.** The expensive step in the report is the
-  delta→registry splice — the quoted Python locates the block by
-  `split('added: {', 1)`, trims two spaces per line, and re-terminates on
-  `assert t.endswith('});')`. The folder move is `mv`. A new command that saves a
-  shell invocation and leaves the TypeScript-literal surgery is the wrong half to
-  automate. The date it would stamp is real ergonomics but small: `archive/` is
-  named in three places and all three are exclusions (`locate.ts`'s SKIP_DIRS,
-  and the two exclude globs), so nothing reads the directory and a mis-stamped
-  date has no mechanical consequence at all.
-  **(2) It would make two command names mislead instead of one.** `attest archive`
-  archives nothing today — it is purely the gate. Adding a second verb that does
-  the archiving leaves `archive` still lying and `merge` doing its job; `--apply`
-  goes the other way and makes the existing verb finally mean what it says.
-  **(3) A move that does not re-run the gate can file an unfinished change as
-  done.** That is the one thing this tool must not ship: the whole claim is that
-  "done" has a hard definition, and a command able to mark completion around that
-  definition removes it. The alternative is that `merge` re-runs the gate — at
-  which point it *is* `--apply` and should be spelled that way. There is no third
-  option, which is why this is a rejection of the shape rather than of the idea.
-  *Recorded here rather than under `Considered and rejected`,* because nothing
-  was decided against: the idea is this entry, and only the narrow spelling of it
-  died. Also worth stating because it needed no release to ride — a new command
-  changes no exit code, rejects no previously-valid input, and removes no API, so
-  it is additive under this file's own Versioning rule and was never blocked on a
-  version bump.
-
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -2829,7 +2924,8 @@ The permanent half goes to design §11 with the params rule, not here.
 adopter owes their users, whose rows a reviewer would want in the rendered spec.
 None has been seen; the one that raised it was tuning.
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.5.0...main
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.6.0...main
+[0.6.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.6.0
 [0.5.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.5.0
 [0.4.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.3
 [0.4.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.2

package/README.md

@@ -157,7 +157,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/v0.5.0/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.6.0/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/index.js

@@ -11,12 +11,17 @@ import { Command } from 'commander';
 import chalk from 'chalk';
 import { resolve } from 'node:path';
 import { writeAtomic } from '../core/write.js';
-import { runCheck, runVerify, runCover, runArchive, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
+import { runCheck, runVerify, runCover, runArchive, runArchiveApply, runInit, runRender, runRenderCheck, runStatus, DEFAULT_TARGET, TARGET_NAMES, } from '../core/pipeline.js';
 import { hasError } from '../core/types.js';
 import { formatCrash, formatIssues, formatScope, summarize, formatCoverage, formatStatus, } from './report.js';
 import { archiveReport, checkReport, coverReport, errorReport, initReport, renderJson, renderReport, statusReport, verifyReport, } from './json.js';
 import { packageVersion } from '../core/version.js';
 const VERSION = packageVersion();
+/** `runArchive` in the shape `--apply` returns, so the two share one call site. */
+const gateOnly = async (dir, change, options) => ({
+    issues: await runArchive(dir, change, options),
+    written: [],
+});
 const program = new Command();
 program
     .name('attest')
@@ -267,14 +272,27 @@ program
     .argument('[dir]', 'project root', undefined)
     .option(JSON_FLAG, JSON_HELP)
     .option(VITEST_CONFIG_FLAG, VITEST_CONFIG_HELP)
+    .option('--apply', 'if the gate passes, merge the change: splice its ADDED requirements into the registry, rename its proposed specs, and move the change folder to archive/')
     .description('Run the archive gate; merge only if it passes.')
     .action((change, dir, opts) => runAction('archive', opts, async () => {
-    const blocking = await runArchive(root(dir), change, { vitestConfig: vitestConfig(opts) });
+    const run = opts.apply ? runArchiveApply : gateOnly;
+    const { issues: blocking, written } = await run(root(dir), change, {
+        vitestConfig: vitestConfig(opts),
+    });
     return {
         report: archiveReport(VERSION, change, blocking),
         human: () => {
             if (blocking.length === 0) {
-                console.log(chalk.green(`✓ Gate passed: change "${change}" can be archived.`));
+                console.log(chalk.green(opts.apply
+                    ? `✓ Gate passed and merged: change "${change}".`
+                    : `✓ Gate passed: change "${change}" can be archived.`));
+                // Every path the merge touched, because this is the command that
+                // edits files the user cannot regenerate and they need to know which
+                // ones to read before committing. It is also what a working-tree
+                // check would only have approximated, and it works for someone not
+                // using version control at all.
+                for (const path of written)
+                    console.log(chalk.dim(`  ${path}`));
             }
             else {
                 console.log(chalk.red(`✗ Gate failed: change "${change}"`));

package/dist/core/compiler.d.ts

@@ -0,0 +1,40 @@
+import type { Issue } from './types.js';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export declare const SUPPORTED_TYPESCRIPT = "^5.5.0 || ^6.0.0";
+/**
+ * The part of the compiler surface every AST reader in this project touches.
+ *
+ * Deliberately the two members that are reached *first* rather than an
+ * exhaustive list: `createSourceFile` and `ScriptTarget` are what
+ * `parser.ts`, `static-registry.ts` and `splice.ts` all open with, so a compiler
+ * that has them has the shape this check is about, and one that lacks either
+ * cannot get far enough for a longer list to matter.
+ */
+interface CompilerSurface {
+    version?: unknown;
+    createSourceFile?: unknown;
+    ScriptTarget?: unknown;
+}
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export declare function compilerIssue(compiler?: CompilerSurface): Issue | undefined;
+export {};
+//# sourceMappingURL=compiler.d.ts.map

package/dist/core/compiler.js

@@ -0,0 +1,64 @@
+// Whether the resolved TypeScript can be read from at all (design §5.1).
+//
+// Both registry readers and the spec parser walk the AST with the compiler API,
+// which makes `typescript` the one dependency this tool cannot survive the
+// absence of — and "absent" is not the shape it arrives in. `typescript@7` is
+// the native port: its package resolves, imports cleanly, and answers `version`
+// and `versionMajorMinor`, while `createSourceFile` and every `ts.isX` guard
+// moved behind `typescript/unstable/ast*`. So the members are `undefined` rather
+// than missing, and the first thing to touch one throws.
+//
+// Measured: `attest check` on it died with
+// `TypeError: Cannot read properties of undefined (reading 'Latest')` and a raw
+// stack — no issue code, no fix hint, and nothing saying which compiler it
+// wanted, on the crash path `[0.4.2]` had just finished sanitising.
+//
+// **The declared range excludes 7, and that is not the same as being safe from
+// it.** A caret is a request, not a constraint the adopter cannot override:
+// `pnpm.overrides` and Yarn `resolutions` both pin a transitive dependency
+// across a whole tree, and a repo standardising on one compiler is exactly the
+// repo that uses them — this one has an `overrides` block of its own. So the
+// reachable case is a deliberate, reasonable act by an adopter, answered with a
+// stack trace.
+//
+// What this cannot do is make Attest work on TypeScript 7. That is a migration
+// to `typescript/unstable/ast`, against an API whose own name says not to depend
+// on it yet. The honest answer for now is that the supported range has a ceiling
+// and says so.
+import ts from 'typescript';
+/**
+ * The range the readers are written against.
+ *
+ * Stated here rather than read from the manifest at runtime, because the
+ * manifest is not on disk beside a bundled build and a diagnostic that cannot
+ * name the range is most of the diagnostic gone. `ATX-56` keeps the two honest:
+ * its `params` carry this string, and its scenario compares them with
+ * `package.json`, so the constant cannot drift from the dependency it describes.
+ */
+export const SUPPORTED_TYPESCRIPT = '^5.5.0 || ^6.0.0';
+/**
+ * An ERROR when the resolved compiler has no AST API, or `undefined` when it
+ * does.
+ *
+ * Takes the compiler rather than reaching for the import directly, so the
+ * refusal can be attested against a stand-in: the condition only exists on a
+ * compiler this repository cannot install alongside the one it builds with, and
+ * a check nothing can make fail is the shape `never-red` exists to catch.
+ *
+ * No `reqId` and no `file`: the finding is about the toolchain, and every
+ * requirement and every file in the project is equally unreadable because of it.
+ */
+export function compilerIssue(compiler = ts) {
+    if (typeof compiler.createSourceFile === 'function' && compiler.ScriptTarget !== undefined) {
+        return undefined;
+    }
+    const version = typeof compiler.version === 'string' ? compiler.version : 'unknown';
+    return {
+        level: 'ERROR',
+        code: 'compiler-unsupported',
+        message: `The resolved TypeScript (${version}) does not expose the AST API Attest reads registries and specs with. ` +
+            `Attest supports ${SUPPORTED_TYPESCRIPT}. ` +
+            `If a resolution or override pins the compiler for the whole tree, exclude Attest from it or move that pin back into the supported range.`,
+    };
+}
+//# sourceMappingURL=compiler.js.map

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", "change-not-found", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "orphan-test", "possible-drift", "proposed-spec-unclaimed", "rationale-placeholder", "registry-invalid", "registry-no-default", "registry-not-static", "rename-source-missing", "rename-target-exists", "rename-target-invalid", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
+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", "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", "spec-in-change-dir", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -22,7 +22,10 @@ export const ISSUE_CODES = [
     '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',
@@ -35,6 +38,7 @@ export const ISSUE_CODES = [
     'never-red',
     'orphan-test',
     'possible-drift',
+    'proposed-spec-name-taken',
     'proposed-spec-unclaimed',
     'rationale-placeholder',
     'registry-invalid',
@@ -43,6 +47,7 @@ export const ISSUE_CODES = [
     'rename-source-missing',
     'rename-target-exists',
     'rename-target-invalid',
+    'spec-in-change-dir',
     'stale-spec-doc',
     'tests-red',
     'unbound-param',

package/dist/core/locate.d.ts

@@ -98,11 +98,28 @@ export declare function staticReader(): RegistryReader;
  * prefix a duplicate-prefix ERROR.
  *
  * Pass `files` to reuse a {@link scanProject} result instead of re-walking.
+ *
+ * `prefixOwners` comes back with the registry because the rule deciding it —
+ * first claim wins, in sorted file order — must have exactly one spelling. It is
+ * what `duplicate-prefix` is computed from here, and what tells `--apply` which
+ * file an ADDED id belongs in (design §7); a second walk arriving at its own
+ * answer would be a second rule the moment either was edited.
  */
 export declare function loadRegistry(root: string, reader: RegistryReader, files?: string[]): Promise<{
     registry: Registry;
     issues: Issue[];
+    prefixOwners: Record<string, string>;
 }>;
+/**
+ * The part of an id that names the space it lives in — `AUTH` of `AUTH-3`.
+ *
+ * The prefix is the only unit above the requirement (design §11) and two things
+ * now depend on agreeing about it: `duplicate-prefix`, and which file `--apply`
+ * writes an ADDED requirement into. An id with no dash is its own prefix, which
+ * cannot arise from `RequirementIdSchema` and is handled anyway because this
+ * also runs over ids a delta proposed.
+ */
+export declare function idPrefix(id: string): string;
 /**
  * Parse the given spec files into one merged plan (paths shown relative to
  * `displayRoot`). Files are read concurrently; the merge follows the input
@@ -115,6 +132,26 @@ export declare function loadRegistry(root: string, reader: RegistryReader, files
 export declare function parseSpecs(files: string[], displayRoot: string): Promise<AttestPlan>;
 /** Parse every `*.spec.ts` under root into one merged plan (file paths shown relative to root). */
 export declare function parseAllSpecFiles(root: string): Promise<AttestPlan>;
+/**
+ * Spec-shaped files sitting under `root/changes` — the location a change's
+ * specs used to live at, and which nothing walks any more (design §7).
+ *
+ * Two correct decisions compose into a blind spot. `changes` is in `SKIP_DIRS`,
+ * so `scanProject` cannot reach these; and the explicit include `attest archive`
+ * once applied to `changes/<name>/specs/` went away with `changeExcludeGlobs`
+ * when specs moved to their merged location. A spec left here therefore executes
+ * in no suite and no gate, and the only command that says anything is the gate,
+ * blaming coverage for a file it cannot see.
+ *
+ * Walks through `findFiles` rather than a second walker: `SKIP_DIRS` is consulted
+ * for *sub*directories only, so starting the walk at `changes` itself both
+ * reaches these files and keeps skipping `node_modules` beneath them.
+ *
+ * Both spellings are wrong here and both are returned. A `*.spec.ts` is the
+ * pre-move layout; a `*.proposed.spec.ts` is the right marker at the wrong path,
+ * which is the half-done migration and no more visible than the other.
+ */
+export declare function findChangeDirSpecs(root: string): Promise<string[]>;
 /** List the names of proposed changes under `root/changes`. */
 export declare function listChangeNames(root: string): Promise<string[]>;
 //# sourceMappingURL=locate.d.ts.map