@am_shork/attest 0.7.2 → 0.7.3

package/CHANGELOG.md

@@ -13,6 +13,288 @@ 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.7.3] - 2026-08-07
+
+### Fixed
+
+- **A loader that never opened left its scratch directory behind — one per
+  `attest` invocation, i.e. one per CI build.** `createLoader` creates the
+  directory and writes the stub, and the only `rm` of it lives inside the `close`
+  of the object it returns — so nothing between those two points can be cleaned
+  up by anyone, because until the caller holds that object no `close` exists to
+  call. It is the exact leak the comment on `close` records as already fixed,
+  surviving on the other side of the same function. The window is now closed by
+  the function that opened it.
+  *Stated over the window rather than over `createServer`, which is where it was
+  found.* `writeFileSync` is inside it too, and a full disk or a temp directory
+  that turns read-only between the two calls reaches it with no project
+  involved — so scoping the repair to the call it was noticed at would have left
+  half of it.
+  *The trigger this was filed on does not reproduce, and that is the useful
+  half.* The entry proposed a malformed `package.json` at the root, on the
+  reasoning that `configFile: false` still leaves Vite reading it for `type`.
+  Measured: it starts a server cleanly, as do eight other shapes — a
+  `package.json` holding an array, one that is a directory, an unknown `type`, a
+  `node_modules` occupied by a file, a `node_modules/.vite` occupied by a file, a
+  `.env` that is a directory, a deleted root, and a well-formed control. Nine
+  candidates, zero throws. **`configFile: false` is why**, and it is worth
+  recording as a property rather than an accident: the option set chosen to stop
+  the loader reading a project's Vite config, and to stop it opening a socket,
+  also leaves almost no project I/O that can fail hard. The throw surface was
+  closed as a side effect of decisions taken for other reasons.
+  *So the repair is justified by ownership rather than by a symptom*, which is a
+  weaker case than this file usually accepts and is why the alternative was to
+  reject the entry outright. What decides it is the asymmetry of cost: the fan-out
+  entry below stays open because bounding concurrency changes how every run
+  behaves, whereas a `try` around a window nothing currently reaches changes
+  nothing observable on any path that exists. A resource whose ownership transfer
+  is conditional on nothing throwing is a shape, and the shape is what recurs.
+  *A cleanup that fails must not replace the error that caused it*, so the `rm`
+  swallows its own failure and the original throw propagates unchanged. The
+  regression test asserts the identity of what comes out, not its wording.
+  **`close` had the same hazard and now makes the same choice, which is a change
+  to an existing path rather than a new one.** Its `rm` runs in a `finally`, so a
+  failed cleanup replaced whatever `close` was doing — and all five callers in
+  `pipeline.ts` call `close` from a `finally` of their own, where the damage is
+  larger than symmetry: a real error on the way out is lost, and a *successful*
+  command becomes a crash about a temp directory. What that reader is handed is a
+  misdiagnosis pointing at their own correct files, which this project already
+  treats as worse than the gap it fills — the argument `ATX-49` records against
+  reporting a load failure as a wall of skipped scenarios, in a much smaller
+  place. Given up with it: the one signal a failed cleanup could have raised,
+  which no caller could have acted on.
+  *The test goes red without the fix, which is the only reason it is worth
+  having.* Verified by reverting `src/` and re-running: `expected [
+  'attest-loader-z7jhoK' ] to deeply equal []`, the leaked directory named in the
+  failure. It injects the throw at the module boundary — no project input could
+  produce one — and mocks `tmpdir` to a directory of its own, because on the
+  throwing path there is no loader to ask for its `scratchDir` and counting
+  `attest-loader-*` in the shared temp directory is the flake the lifecycle test
+  beside it already documents.
+  *It is its own file*, which is a rule this repo already wrote down and which
+  the first draft broke: `tests/locate-fanout.spec.ts` is separate because
+  `vi.mock` is file-scoped and it mocks a Node builtin, and the four lifecycle
+  tests boot the *real* Vite loader — sharing a module registry with a
+  `createServer` that throws is exactly what that convention exists to prevent.
+  The first attempt scoped the mocks with `doMock` and `resetModules` inside the
+  shared file instead, which is machinery bought to work around a constraint the
+  repo had already decided how to solve. Following it deleted the machinery.
+  *No new requirement, and the precedent cuts the other way, so it is worth
+  saying why.* `ATX-36` is the sibling property — what a live loader leaves on the
+  user's machine, stated as a count, with a scenario in `self/` — and "leaves no
+  scratch directory" is the same shape. What decides against filing one here is
+  that the success-path half has never had a requirement either, so a new one
+  covering only the throwing path would state half a contract and cost a
+  permanent scenario for the half nothing reaches. If it is ever filed it should
+  be filed whole, and that is a larger change than this fix.
+
+- **The `cmd.exe` guard in `tests/consumer.spec.ts` checked one character of a
+  class, and the comment above it claimed the quoting was doing work it cannot
+  do here.** `shellArg` asserted the argument held no `"` and then quoted only
+  when it held whitespace, so an argument with neither went to the shell bare
+  with `&`, `|`, `^`, `<`, `>`, `(` unexamined. Measured against the twelve
+  shapes: the old assertion let **11 of 12** through.
+  *What decided it, and it is the thing the entry this replaces did not have.*
+  That entry framed the choice as "widen the class, or fix the prose", and
+  argued that widening while leaving the prose is the change that looks like a
+  fix and settles nothing. Both halves turn on a fact neither named: **every
+  command this suite spawns is a `.cmd`**, which is the whole reason
+  `NEEDS_SHELL` exists, and a batch file expands `%*` into its own line *before*
+  anything parses it — so a metacharacter survives double quotes and is acted on
+  at the far end. That is the argument-injection hole Node closed in 22.x,
+  arrived at the long way round. So the quoting is not a defence that the
+  assertion merely backstops; **the assertion is the only defence**, and a
+  defence that covers one character of its class is the defect rather than the
+  prose being generous. Both are fixed together: the class is named, and the
+  comment now says the quotes do whitespace and nothing else.
+  *`%` and `!` are in the class for a different reason* — expansion rather than
+  syntax, and `!` only under delayed expansion, which the spawned shell does not
+  enable but a batch file can enable for itself. Neither costs anything to
+  refuse.
+  *The cost, which is real and is the right cost.* Windows permits `&`, `(` and
+  `%` in a user name, and `os.tmpdir()` sits under it — so on such a machine this
+  suite now stops with *"argument would need escaping, not quoting"* instead of
+  running. That is correct rather than a false red: through a batch target those
+  arguments genuinely are not safe, and the invariant the assertion guards is
+  that every argument is a literal flag or a path from `mkdtemp`. Stopping is
+  right even where quoting would have survived it, because the value is then not
+  the kind of value the helper accepts.
+  *What is measured, and what is not.* `pnpm test:consumer` was run on Windows,
+  where `NEEDS_SHELL` is true and the changed path actually executes: 11 tests
+  passed, none skipped — the distinction that matters, since the failure this
+  file's own comment records reported ten tests as *skipped* at zero run. CI is
+  Linux, where `shellArg` returns before the assertion, so the pipeline says
+  nothing about this either way. Not measured end to end: an argument carrying a
+  metacharacter actually reaching the guard, because no call site can produce
+  one — the class is verified as a predicate over the twelve shapes above and
+  the sixteen arguments the suite really passes, not by driving the suite red.
+
+- **A statement or rationale can no longer become HTML, or open a section of
+  its own.** `sanitised` is the entry §9.1 names and it strips control
+  characters and nothing else, so `statement` and `rationale` reached the
+  Markdown by concatenation exactly as written. Measured: a `rationale`
+  containing a newline and `## ATX-999` rendered a whole section — heading,
+  statement, `**Why:**` — for a requirement no registry holds, sitting between
+  two real ones and worded identically, with the overview table above it listing
+  three ids and the body carrying four sections. `<script>` and `<img onerror>`
+  survived the same way into a file that is committed and served. `check` and
+  `cover` saw nothing, because the id is in no registry, and `render --check`
+  could not object, because that *was* what the registry rendered to.
+  *Which of the three is intended, which is the part the fix had to decide.*
+  Marking prose up stays — `plain` escapes a param value precisely because the
+  value is data and the sentence around it is not — and that decision had never
+  been separated from allowing raw HTML or a heading. It is now a **fifth
+  obligation in design §9.1** rather than a patch at an emitter: prose may be
+  marked up, it may not become a tag, and it may not open a section. Stated as a
+  count over the document — one heading per requirement id — because what a
+  reader trusts is that a section means a requirement (`ATX-67`).
+  *Escaped rather than refused, on an asymmetry.* A rule that misses something
+  ships the document it ships today; a rule that fires wrongly makes a
+  legitimate rationale a hard error in the one command whose value is that it
+  always produces the document — the `ATX-29` argument about `--check` seen from
+  the other side. So there is no new diagnostic and no exit code moves.
+  *And escaped for the position, which is what keeps it lossless.* A code span
+  is literal text in every renderer, so `&lt;` written inside one is **visible**
+  — Markdown does not decode entities there, and this repository documents
+  `attest status <change>` in a statement. The scan therefore tracks spans and
+  leaves their contents alone, conservatively: a backtick run opens a span only
+  if a run of exactly that length closes it, and an unmatched run is text with
+  the defence still applied after it.
+  *One rendering change beyond the fix, and it is a repair.* A param
+  substituted inside the author's own code span was emitted as `**value**`,
+  which in a code span is two asterisks around the value; knowing the position
+  is what removes them. `SPEC.md` in this repository moves by 12 lines, all of
+  that shape — `` `**changes/<name>/first-run.json**` `` becomes
+  `` `changes/<name>/first-run.json` `` — and no `&lt;` appears anywhere in it,
+  which is the measurement that the span exception works on real prose.
+  *The defence had the defect it was written next to, and `ATX-59` gained a
+  third shape because of it.* The first code-span scan searched forward from
+  each backtick run for a run of the same length, so a rationale whose runs are
+  all of *different* lengths paid a scan to the end of the string for every one
+  of them: 500 KB cost 1.6 s and 2 MB cost 15 s, from `attest render` with no
+  flag, on text the registry chooses — the same "a registry must not decide what
+  rendering costs" defect the padded statement and the backtick-run param
+  already stand for. The runs are now read once and indexed by length, each
+  length holding a forward-only cursor, which is linear: 40 ms at 2 MB. It is
+  filed under `ATX-59` rather than here because the obligation is that one, and
+  it is worth saying where the site came from — the *defence another requirement
+  added*, which is the direction the next one will arrive from too.
+  *This leaves `Planned`.* The forged section was reproduced first, then the
+  four scenarios were run against the pre-fix renderer: three went red, and the
+  fourth — the setext underline, which heads the line *above* it — went green,
+  because counting `##` lines cannot see a heading that has no `##` in it. That
+  scenario was rewritten to assert the neutralised underline instead. A scenario
+  that cannot fail is the defect `archive` exists to catch, and it was caught
+  here only by running it against the old code.
+
+- **`attest init` no longer follows a symbolic link out of the project, and
+  refuses the whole run when a destination leads there.** `runInit` did
+  `join(root, target.file)`, `mkdir -p` and then the write, and nothing asked
+  whether the path was still under `root` once the filesystem had had its say.
+  A `.claude/skills/attest` planted in a repository as a link to anywhere the
+  user can write was followed by both: measured on Windows with a junction, a
+  file at the far end holding `USER OWNED FILE - DO NOT OVERWRITE` came back
+  holding the skill, and the report printed the relative path, so nothing on
+  screen said where it had gone. Every destination is now resolved segment by
+  segment before the first byte of any of them is written, and one that escapes
+  is an `unsafe-target-path` ERROR that writes nothing at all (`ATX-66`).
+  *What the exposure was, stated precisely, because two nearby things are not
+  it.* `writeAtomic`'s exclusive creation is not the gap and was never scoped to
+  be one: it defends the *temporary* path against a planted link, and it does
+  that perfectly in whichever directory the destination turns out to be. And
+  `workflowBody()` is a pure function of nothing, so no byte of the checked
+  project reaches the file — there is nothing to exfiltrate. What was exposed is
+  the **path**, which is `targets.ts`'s first scoping rule ("Attest owns the
+  path") having been an assumption rather than a check.
+  *Why the check is a resolution rather than a comparison.* `join` normalises
+  `..`, so a lexical containment test was already satisfied — the escape is a
+  segment that *is* a link, which only `realpath` can see. Containment itself
+  goes through `isInside` in `src/core/paths.ts`, asked as a relative path
+  rather than a string prefix: `/repo-backup` starts with `/repo`, and on
+  Windows a path on another drive has no relative spelling at all, so
+  `path.relative` answers with an absolute one instead of a chain of `..`. Both
+  read as contained under `startsWith`.
+  *The limit, recorded rather than papered over.* A link planted between the
+  resolution and the write is not caught, and no check outside the filesystem
+  can catch it. The exposure this closes is one committed to a repository, which
+  is the one a fresh clone and every merge-request checkout hands you.
+  *Behaviour change:* an `init` that used to write through such a link now
+  fails with exit 1. The only input that reaches it is a path that was already
+  leaving the project. The JSON surface is unchanged beyond one more `code`
+  value, which is additive — no `SCHEMA_VERSION` bump.
+  *This leaves `Planned`*, where it was filed with the measurement above; the
+  first act of building it was re-running that measurement, and it reproduced.
+
+### Changed
+
+- **The guidance now draws the line between a literal that is drift and a literal
+  that is a pin — the shipped text forbade the only defence against a shortened
+  domain.** `[0.7.2]` fixed the repo half: every param a scenario iterates gained
+  a literal pinning its extent, after three of that release's four green
+  mutations turned out to be a domain silently losing cases rather than the
+  tautology the experiment was looking for. The user-facing half was held back,
+  and it was not merely absent. The `init` skill's "Four things you must not do"
+  says **"Do not hardcode a value that lives in `params`"**, and the pin every one
+  of those fixes adds is, read literally, exactly that. An adopter who writes a
+  roster param — which the design actively pushes them toward, since a quantifier
+  a scenario can iterate is the shape `QUANTIFIED` recommends — was being handed
+  an instruction that forbids the only thing standing between them and a run that
+  covers less every time someone edits the list.
+  *The distinction is real and one sentence long*, and it is now drawn in all four
+  places the claim is made: the rule is about the **expectation** the system is
+  measured against, and the pin asserts what the **intent** is. A list a scenario
+  loops over is not a value under test — it is the set of cases the run covers,
+  so dropping a member removes a case while every assertion inside still passes,
+  with the expectation as independent as it ever was. That is why the `[0.5.0]`
+  rule (*the expectation must not be a function of the param the code under test
+  consumed*) does not reach it, and why a literal is the **only** independent term
+  available: anything derived from the list shrinks with it, so a length assertion
+  written as a function of the list is true at every length.
+  *Where it landed, and why it is four documents rather than one line appended.*
+  README §"killer move", the `init` skill (a sibling bullet in the model section
+  and a carve-out inside rule 3 itself, where the contradiction was), the
+  `possible-drift` troubleshooting section with a worked ✓/✗ pair, and design §11
+  as a residual weakness beside the tautology bullet it shares a gap with — both
+  languages. `[0.5.0]` records the reason this shape of change is done in one
+  deliberate pass rather than incrementally: it is the central claim of the tool
+  being reworded, and the last time it was split the halves disagreed.
+  *No engine change, and none is proposed here.* Nothing in this is detectable —
+  which surface a statement claims is prose judgement, the same judgement §11
+  already records as the reason obligation counting can never be an engine rule.
+  The counter-pressure that exists is a hand-judged table, and §11 now says so,
+  including what it cannot reach: a domain whose size is carried by a scalar.
+  *This leaves `Planned`*, where it was filed with the measurement above; the
+  measurement was already taken, and what it needed was the pass.
+
+- **The release publishes through `pnpm` again, and the check that read the
+  attestation back is gone.** Two corrections to the provenance job shipped in
+  `[0.7.2]`, both from what the first real tag pipeline showed.
+  *`pnpm publish --provenance` works on the pinned 10.28.0; the claim that it
+  did not was read off `pnpm publish --help`, where the flag is absent.* The
+  parser knows it — `--provenanceX` is rejected with *"Did you mean
+  'provenance'?"*, and `--provenance --dry-run` runs clean. A help text is a
+  document, not the interface; checking a flag means asking the parser. So the
+  job is pnpm like every other job here, `--no-git-checks` comes back with it
+  (pnpm inspects the branch, CI builds tags in detached HEAD), and
+  `COREPACK_ENABLE_STRICT=0` goes away, since it existed only so a bare `npm`
+  could run under a `packageManager` that pins pnpm.
+  *The post-publish check failed the 0.7.2 release, and the publish it failed
+  was correctly signed.* Six attempts over a minute all got a 404 from the
+  registry's attestation endpoint; the same endpoint now serves
+  `slsa.dev/provenance/v0.2` for `0.7.2`. Lengthening the budget was the wrong
+  repair, and the entry it replaces already contains the reason without drawing
+  the conclusion: the check runs *after* an irreversible step, so its red cannot
+  be cleared — the republish that would rerun it fails `EPUBLISHCONFLICT` on a
+  version that now exists. Every failure it can reach is therefore either a
+  false one or an unfixable one, on a job nobody can make green again, which
+  makes it a machine for teaching that red is routine — the exact habit the
+  `audit` job's comment refuses. A gate has to sit where the answer can still
+  change what happens. Verification moves to where it can: `npm audit
+  signatures` in an installing project, or the package page's Provenance panel.
+  *What is unchanged:* the attestation itself, the three preconditions, and the
+  fact that npm rejects the publish rather than degrading to an unsigned one if
+  any is missing. `0.7.2` is signed, and shipped signed, despite the red job.
+
 ## [0.7.2] - 2026-08-07
 
 ### Added
@@ -3375,26 +3657,6 @@ symptom are worth batching**: individually none justifies a commit, together the
 cost about an hour, and they are the group no gate could have found, since having
 no symptom is the definition of what a gate cannot see.
 
-- **Telling adopters about the domain trap, which the shipped guidance
-  currently walks them into.** The repo half landed under `[Unreleased]`; the
-  user-facing half has not, and it is not merely absent. `skill.ts`'s "Four
-  things you must not do" says **"Do not hardcode a value that lives in
-  `params`"**, and the pin every fix in that entry adds is, read literally,
-  exactly that. An adopter who writes a roster param — which the design
-  actively pushes them toward, since a quantifier a scenario can iterate is the
-  shape `QUANTIFIED` recommends — gets an instruction that forbids the only
-  defence against shortening it. The distinction is real and one sentence long:
-  the rule is about the **expectation** the system is measured against, and the
-  pin asserts what the **intent** is. Nothing shipped draws it.
-  *Why it is filed rather than done in the same pass.* It reaches README §"killer
-  move", the `init` skill, `possible-drift`'s troubleshooting section and design
-  §11, in both languages — the same surface `[0.5.0]` rewrote, and that entry
-  records the lesson: rewording the central claim of the tool is not a line
-  appended, and it was held back once precisely so it could be done deliberately
-  and in one pass. The measurement it needs is already taken; what it needs next
-  is the pass. *Not* a `possible-drift` change: nothing here is detectable by
-  the engine, for the reason the entry below gives about prose judgement.
-
 - **Binding the `✗` samples to fixtures whose rejection is asserted.** A sample
   showing input the engine must *reject* can be bound the way a runnable one is,
   to a fixture whose rejection is the thing under test — which is what
@@ -3413,43 +3675,6 @@ no symptom is the definition of what a gate cannot see.
   `[0.4.3]` — that the gate and the run proving the fixture still works live in
   different suites — applies here identically.
 
-- **`render`'s document can carry raw HTML and a forged requirement section.**
-  `sanitised` is the entry §9.1 names and it strips control characters and
-  nothing else, so `statement` and `rationale` reach the Markdown by
-  concatenation exactly as written. Measured: a `rationale` containing newlines
-  and `## ATX-999` renders a whole section — heading, statement, `**Why:**` —
-  for a requirement no registry holds, sitting between two real ones and worded
-  identically; `<script>` and `<img onerror>` survive the same way. `check` and
-  `cover` see only the real id, and `render --check` cannot object, because that
-  *is* what the registry renders to now.
-  *Not an accepted risk, which is the part worth pinning.* §9.1 and the
-  reference both scope their guarantee to control characters, and the
-  reference's heading over that paragraph is "Safe to read, and safe to keep",
-  with "a site generator" named in the threat it describes. What *is* a decision
-  is that prose may be marked up — `plain()` escapes a param value precisely
-  because it is data while the statement around it is not — and that decision
-  has never been separated from allowing raw HTML or a heading. So the entry is
-  as much about stating which of the three is intended as about the escaping,
-  and if the answer is that Markdown stays and HTML and headings go, that is a
-  fourth obligation in §9.1 rather than a patch at an emitter.
-
-- **`attest init` follows a symlink out of the project root.** `runInit` does
-  `mkdir(dirname(dest), { recursive: true })` and then `writeAtomic`, and
-  neither asks whether `dest` is still under `root`. A `.claude/skills/attest`
-  planted in the repository as a link to anywhere the user can write is followed
-  by both: measured on Windows with a junction, a file at the target holding
-  `USER OWNED FILE - DO NOT OVERWRITE` came back holding the skill. The report
-  prints the relative path, so nothing on screen says where it went.
-  *`write.ts` is not the gap and neither is `targets.ts`'s content.* The `wx`
-  flag defends the *temporary* path against a planted link and does exactly
-  that; the destination's directory was never in its scope. And `workflowBody()`
-  is a pure function of nothing, so no byte of the checked project reaches the
-  file — the exposure is the path, not the content, which is `targets.ts`'s
-  first rule ("Attest owns the path") being an assumption rather than a check.
-  The check belongs beside `resolveTargets`, which is already all-or-nothing for
-  the same reason: a name known to be unwritable must not leave half a set
-  behind.
-
 ## Under consideration
 
 Candidates with **no decision yet**, between the two sections either side of it
@@ -3463,7 +3688,7 @@ decision, because that is what a re-proposal a year from now would otherwise
 have to gather again.
 
 - **Trusted publishing, which would delete `NPM_TOKEN` rather than add to it.**
-  The provenance work in `[Unreleased]` signs the release but does not change
+  The provenance work in `[0.7.2]` signs the release but does not change
   what authorises it: a long-lived automation token, masked and protected, that
   publishes as us to anyone holding it. npm's trusted publishing exchanges the
   same OIDC identity the attestation already uses for a short-lived credential,
@@ -3837,41 +4062,6 @@ have to gather again.
   because a project whose requirement count only rises should have decided in
   advance what would make one leave.
 
-- **The `cmd.exe` quoting in `tests/consumer.spec.ts` guards one character of
-  several.** `shellArg` asserts the argument holds no `"` and then quotes only
-  when it holds whitespace, so an argument with none goes to the shell bare —
-  and `&`, `|`, `^`, `<`, `>`, `(` are metacharacters there that the assertion
-  does not name. The fix is one character class, which is why the entry is not
-  about the fix.
-  *What blocks the decision is that no input reaches it.* Both arguments are
-  either a literal flag or a path from `mkdtemp`, `NEEDS_SHELL` is win32 only
-  and CI is Linux, and the one path an attacker could plausibly influence — the
-  checkout directory on a fork MR pipeline — comes from a GitLab project path,
-  whose character set excludes every metacharacter above. So this is an
-  observation with no attack path, and the honest question is not whether to
-  widen the class but whether the comment above it should stop claiming more
-  than the assertion covers: it says "the assertion keeps that true" about
-  arguments generally, where what it checks is one character. Widening the class
-  and leaving the prose is the change that would look like a fix and settle
-  nothing.
-
-- **A loader that fails to start leaves its scratch directory behind.**
-  `createLoader` calls `mkdtempSync` and writes the stub *before* `createServer`,
-  and the only `rm` of that directory is inside the `close` of the object
-  `createServer` returns — so a throw from it leaks one `attest-loader-*` per
-  invocation, which on a CI runner is one per build. That is the exact failure
-  shape the comment on `close` records as already fixed, surviving on the other
-  path.
-  *What blocks it is that nothing has been made to throw there.* With
-  `configFile: false` Vite still reads the `package.json` at the root to decide
-  `type`, so a malformed one in the checked project is the obvious candidate and
-  it is the project's to write — but it was not tried, and an entry claiming a
-  trigger it has not seen is the thing this section exists to not accumulate.
-  The repair is three lines (a `try` around the two calls that `rm`s and
-  rethrows) and is not what the decision turns on; measuring whether the throw
-  is reachable at all is, because if it is not, this is a leak with no input
-  that produces it.
-
 ## Considered and rejected
 
 Decisions **not** to build something, kept where they can be found before the
@@ -4196,6 +4386,7 @@ requirement, and human review at propose is still the whole answer. What is
 rejected is grouping as a way to assist it, and this reopens only on a
 contradiction that grouping would have caught.
 
+[0.7.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.3
 [0.7.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.2
 [0.7.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.1
 [0.7.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.7.0

package/README.md

@@ -29,6 +29,15 @@ together and the test stays green through any edit. Pin the expectation to
 something that does not move with the param — a fixture, a literal in the test,
 or a second independently derived value.
 
+A composite param has a second failure of its own, and it runs the other way. When
+a test **loops over** a list it read from `params`, that list is the set of cases
+the run covers: drop a member and every assertion inside the loop still passes
+over what is left, so the suite quietly tests less with nothing to show for it.
+Pin the extent beside the loop — the members against a literal when their identity
+is the promise, the length when the size is. That literal is not the copy the
+single source exists to prevent: it is not what the system is measured against,
+it is what the intent claimed to cover.
+
 ## Prerequisites
 
 - Node ≥ 20.19
@@ -157,7 +166,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.7.2/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.7.3/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/dist/cli/json.d.ts

@@ -74,8 +74,9 @@ export declare function renderReport(version: string, issues: Issue[], outFile?:
 /**
  * `init`. Carries the paths written so a consumer learns where the instructions
  * went without hardcoding the convention. `issues` is empty on the success path
- * — `init` writes or throws — apart from an `unknown-target` ERROR, which is
- * refused before anything is written and so reports no files at all.
+ * — `init` writes or throws — apart from the two ERRORs it refuses on,
+ * `unknown-target` and `unsafe-target-path`. Both are decided before anything is
+ * written and so report no files at all.
  *
  * `outFile` survives beside `outFiles` for the one-file run, which is what the
  * default invocation still is: dropping it would break the consumer the field

package/dist/cli/json.js

@@ -92,8 +92,9 @@ export function renderReport(version, issues, outFile) {
 /**
  * `init`. Carries the paths written so a consumer learns where the instructions
  * went without hardcoding the convention. `issues` is empty on the success path
- * — `init` writes or throws — apart from an `unknown-target` ERROR, which is
- * refused before anything is written and so reports no files at all.
+ * — `init` writes or throws — apart from the two ERRORs it refuses on,
+ * `unknown-target` and `unsafe-target-path`. Both are decided before anything is
+ * written and so report no files at all.
  *
  * `outFile` survives beside `outFiles` for the one-file run, which is what the
  * default invocation still is: dropping it would break the consumer the field

package/dist/core/docs.d.ts

@@ -8,7 +8,7 @@
  * and the `##` headings of both language documents, so landing here cannot
  * produce a dead link.
  */
-export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "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", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file"];
+export declare const ISSUE_CODES: readonly ["add-conflict", "add-invalid", "added-id-unmerged", "apply-no-prefix-owner", "apply-unsupported-delta", "change-not-found", "compiler-unsupported", "declared-not-run", "duplicate-prefix", "duplicate-requirement", "empty-spec", "internal-error", "invalid-change-name", "missing-spec-doc", "modify-invalid", "modify-missing", "never-red", "non-scalar-interpolation", "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", "spec-load-failed", "stale-spec-doc", "tests-red", "unbound-param", "uncovered-requirement", "unknown-target", "unreadable-file", "unsafe-target-path"];
 export type IssueCode = (typeof ISSUE_CODES)[number];
 /**
  * The page explaining `code`, or `undefined` when nothing explains it.

package/dist/core/docs.js

@@ -56,6 +56,7 @@ export const ISSUE_CODES = [
     'uncovered-requirement',
     'unknown-target',
     'unreadable-file',
+    'unsafe-target-path',
 ];
 const DOCUMENTED = new Set(ISSUE_CODES);
 const REPO = 'https://gitlab.com/Pseudorca/attest/-/blob';

package/dist/core/loader.js

@@ -60,38 +60,59 @@ const VITEST_STUB = 'export const describe=()=>{};export const it=()=>{};export
     'export default {};';
 export async function createLoader() {
     const dir = mkdtempSync(join(tmpdir(), 'attest-loader-'));
-    const stub = join(dir, 'vitest-stub.mjs');
-    writeFileSync(stub, VITEST_STUB);
-    const server = await createServer({
-        configFile: false,
-        logLevel: 'error',
-        // Not just quiet — sanitised. See `sanitisedLogger`: what survives
-        // `logLevel: 'error'` is exactly the message that carries the checked
-        // project's own text.
-        customLogger: sanitisedLogger(),
-        appType: 'custom',
-        // `ws: false` is load-bearing, and `middlewareMode` is not enough on its
-        // own: it suppresses the HTTP server but Vite still starts the HMR
-        // WebSocket server, which binds `::` — every interface, not loopback — on
-        // port 24678. Every `attest` command that reads a registry by evaluating it
-        // therefore opened a network port for the length of the run, on a
-        // developer's machine and on every CI runner, for a channel that does
-        // nothing here: nothing subscribes to HMR, because nothing is watching.
-        //
-        // The visible symptom was the collision. Two attest processes at once —
-        // ordinary in a CI matrix, and what this repo's own concurrent specs do —
-        // and the second printed `WebSocket server error: Port is already in use`
-        // into the middle of a report, through a `logLevel: 'error'` that was
-        // supposed to have silenced the loader entirely.
-        //
-        // `hmr: false` does *not* close it (measured, Vite 5.4): the ws server is
-        // created before the hmr option is consulted. `ws: false` is the one that
-        // leaves no listening handle at all.
-        server: { middlewareMode: true, ws: false },
-        resolve: { alias: { vitest: stub } },
-        ssr: { noExternal: ['vitest'] },
-        optimizeDeps: { noDiscovery: true },
-    });
+    // Everything between creating the directory and returning its owner runs
+    // inside this `try`, because until the caller holds the object below, nothing
+    // else can call `close` — so a throw here is the one path where the directory
+    // outlives the only code that knows about it. That is the same leak the
+    // comment on `close` records as already fixed, surviving on the other side of
+    // the same function.
+    //
+    // Stated over the window rather than over `createServer`, which is where it
+    // was found: `writeFileSync` is inside it too, and a disk that is full or a
+    // temp directory that turns read-only between the two calls reaches it without
+    // any project being involved.
+    let server;
+    try {
+        const stub = join(dir, 'vitest-stub.mjs');
+        writeFileSync(stub, VITEST_STUB);
+        server = await createServer({
+            configFile: false,
+            logLevel: 'error',
+            // Not just quiet — sanitised. See `sanitisedLogger`: what survives
+            // `logLevel: 'error'` is exactly the message that carries the checked
+            // project's own text.
+            customLogger: sanitisedLogger(),
+            appType: 'custom',
+            // `ws: false` is load-bearing, and `middlewareMode` is not enough on its
+            // own: it suppresses the HTTP server but Vite still starts the HMR
+            // WebSocket server, which binds `::` — every interface, not loopback — on
+            // port 24678. Every `attest` command that reads a registry by evaluating
+            // it therefore opened a network port for the length of the run, on a
+            // developer's machine and on every CI runner, for a channel that does
+            // nothing here: nothing subscribes to HMR, because nothing is watching.
+            //
+            // The visible symptom was the collision. Two attest processes at once —
+            // ordinary in a CI matrix, and what this repo's own concurrent specs do —
+            // and the second printed `WebSocket server error: Port is already in use`
+            // into the middle of a report, through a `logLevel: 'error'` that was
+            // supposed to have silenced the loader entirely.
+            //
+            // `hmr: false` does *not* close it (measured, Vite 5.4): the ws server is
+            // created before the hmr option is consulted. `ws: false` is the one that
+            // leaves no listening handle at all.
+            server: { middlewareMode: true, ws: false },
+            resolve: { alias: { vitest: stub } },
+            ssr: { noExternal: ['vitest'] },
+            optimizeDeps: { noDiscovery: true },
+        });
+    }
+    catch (err) {
+        // The original error is what the caller has to see, so a cleanup that fails
+        // must not replace it. `force` already forgives a directory that is not
+        // there; this forgives one that will not go.
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+        throw err;
+    }
     let closed = false;
     return {
         scratchDir: dir,
@@ -111,7 +132,16 @@ export async function createLoader() {
                 await server.close();
             }
             finally {
-                await rm(dir, { recursive: true, force: true });
+                // Swallowed for the same reason as the `rm` on the failing path above,
+                // and it counts for more here: every caller closes from a `finally`, so
+                // a throw from this line replaces whatever the block was doing — the
+                // real error on the way out, or a *successful* return turned into a
+                // crash about a temp directory. What that reader would then be handed
+                // is a misdiagnosis pointing at their own correct files, which this
+                // repository already treats as worse than the gap it fills.
+                // Given up with it: the one signal a failed cleanup could have raised,
+                // which no caller could have acted on anyway.
+                await rm(dir, { recursive: true, force: true }).catch(() => { });
             }
         },
     };

package/dist/core/paths.d.ts

@@ -12,4 +12,20 @@
 export declare function toPosixPath(path: string, separator?: string): string;
 /** `path.relative`, in the one spelling the rest of the engine expects. */
 export declare function relativePath(from: string, to: string): string;
+/**
+ * Whether `path` is `root` or sits below it, both given as resolved paths.
+ *
+ * Asked through `relativePath` rather than by comparing prefixes, because the
+ * two ways this goes wrong are both invisible in a `startsWith`. A sibling
+ * directory shares the prefix — `/repo-backup` starts with `/repo` — and on
+ * Windows a path on another drive has *no* relative spelling at all, so
+ * `path.relative` answers with an absolute one rather than a chain of `..`.
+ * Testing the relative form catches both: an escape is either `..`-led or
+ * absolute, and nothing else is.
+ *
+ * The caller owes the resolution. Nothing here follows a symbolic link, so a
+ * path that is lexically inside can still be physically outside — that is the
+ * question `join` cannot answer and this function does not pretend to.
+ */
+export declare function isInside(root: string, path: string): boolean;
 //# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.js

@@ -14,7 +14,7 @@
 // Normalising here rather than at the glob has a second dividend: a report is
 // then byte-identical across platforms, so a `--json` consumer diffing two CI
 // runs is not reading the runner's operating system.
-import { relative, sep } from 'node:path';
+import { isAbsolute, relative, sep } from 'node:path';
 /**
  * A native path as a POSIX one.
  *
@@ -33,4 +33,23 @@ export function toPosixPath(path, separator = sep) {
 export function relativePath(from, to) {
     return toPosixPath(relative(from, to));
 }
+/**
+ * Whether `path` is `root` or sits below it, both given as resolved paths.
+ *
+ * Asked through `relativePath` rather than by comparing prefixes, because the
+ * two ways this goes wrong are both invisible in a `startsWith`. A sibling
+ * directory shares the prefix — `/repo-backup` starts with `/repo` — and on
+ * Windows a path on another drive has *no* relative spelling at all, so
+ * `path.relative` answers with an absolute one rather than a chain of `..`.
+ * Testing the relative form catches both: an escape is either `..`-led or
+ * absolute, and nothing else is.
+ *
+ * The caller owes the resolution. Nothing here follows a symbolic link, so a
+ * path that is lexically inside can still be physically outside — that is the
+ * question `join` cannot answer and this function does not pretend to.
+ */
+export function isInside(root, path) {
+    const rel = relativePath(root, path);
+    return rel !== '..' && !rel.startsWith('../') && !isAbsolute(rel);
+}
 //# sourceMappingURL=paths.js.map

package/dist/core/pipeline.js

@@ -13,9 +13,9 @@ import { DEFAULT_TARGET, resolveTargets } from './targets.js';
 import { writeAtomic } from './write.js';
 import { applyMerge, mergedSpecPath } from './merge.js';
 import { compilerIssue } from './compiler.js';
-import { mkdir, readFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { relativePath } from './paths.js';
+import { isInside, relativePath } from './paths.js';
 import { hasError } from './types.js';
 // The runner half of the engine, reached only when a command actually needs it.
 //
@@ -450,15 +450,78 @@ export async function runInit(root, names) {
     const { targets, issues } = resolveTargets(names.length > 0 ? names : [DEFAULT_TARGET]);
     if (issues.length > 0)
         return { files: [], issues };
-    const files = [];
+    // Every destination is resolved before any of them is written, for the reason
+    // `resolveTargets` refuses the whole set on one unknown name: a run that stops
+    // partway leaves a repository carrying instructions for some agents and a
+    // failing command that does not say which.
+    // A root that does not exist yet is `init <dir>` on a directory this run
+    // creates, and nothing can have been planted inside a directory that is not
+    // there — so it stands for itself and every segment below it resolves
+    // lexically, which is what the old implementation did for all of them.
+    const realRoot = await realpath(root).catch(() => root);
+    const writes = [];
+    const refusals = [];
     for (const target of targets) {
-        const dest = join(root, target.file);
+        const resolved = await resolveDest(realRoot, target.file);
+        if (resolved.ok) {
+            writes.push({ target, dest: resolved.dest });
+        }
+        else {
+            refusals.push({
+                level: 'ERROR',
+                code: 'unsafe-target-path',
+                file: target.file,
+                message: `Refusing to write ${target.file}: it resolves to ${resolved.escape}, outside the project. Remove the link at that path and re-run.`,
+            });
+        }
+    }
+    if (refusals.length > 0)
+        return { files: [], issues: refusals };
+    const files = [];
+    for (const { target, dest } of writes) {
         await mkdir(dirname(dest), { recursive: true });
         await writeAtomic(dest, target.content());
         files.push(target.file);
     }
     return { files, issues };
 }
+/**
+ * Where a target's file really goes, or the path outside the project that
+ * asking put it at (design §9: ownership of the path is checked, not assumed).
+ *
+ * `join(root, file)` answers where the path *reads* as going, and that is not
+ * the same question: a segment that is a link makes a path lexically inside the
+ * root and physically outside it, which `mkdir -p` and the write both follow.
+ * So the resolution is the check, and a lexical one would not be — `join`
+ * normalises `..`, so it is already satisfied here. `writeAtomic`'s `wx` is not
+ * the defence either and was never scoped to be: it guards the *temporary* path
+ * against a planted link, in whichever directory the destination turns out to
+ * be.
+ *
+ * So every segment is resolved, not just the leaf. A link anywhere along the
+ * way is the escape, and the leaf is checked too — `rename` replaces a symlink
+ * rather than following it, so a link there would not leak the content, but it
+ * would silently destroy a file the user made deliberately.
+ *
+ * A segment that does not exist cannot be a link, and neither can the ones
+ * below it, so `realpath` failing means the rest of the path is Attest's own
+ * `mkdir` to create. What this cannot close is a link planted between this
+ * resolution and the write; the exposure it does close is one committed to the
+ * repository, which is the one a checkout hands you.
+ */
+async function resolveDest(realRoot, file) {
+    let current = realRoot;
+    // `AgentTarget.file` is spelled with `/` on every platform (ATX-28), so the
+    // segments are the same list here as they are in the report.
+    for (const segment of file.split('/')) {
+        const next = join(current, segment);
+        const real = await realpath(next).catch(() => next);
+        if (!isInside(realRoot, real))
+            return { ok: false, escape: relativePath(realRoot, real) };
+        current = real;
+    }
+    return { ok: true, dest: current };
+}
 /**
  * A change name must name one directory inside `changes/`, and nothing else.
  *

package/dist/core/render.js

@@ -6,7 +6,7 @@
 // back, so the direction OpenSpec's pure-Markdown model went (Markdown as
 // truth, and the free-form drift that comes with it) stays closed.
 //
-// Four properties this file must keep:
+// Five properties this file must keep:
 //  - **Intent only.** The document says what the system promises, never what is
 //    proven or green: coverage and results are verdicts, and verdicts belong to
 //    `cover` / `verify`, which recompute them on demand. Putting them here also
@@ -25,6 +25,10 @@
 //    and it is a *file* — committed, served, and read again long after the run
 //    that wrote it. See `sanitised` for why the defence sits here rather than
 //    at the terminal write.
+//  - **Prose stays prose.** A string the registry owns may be marked up and may
+//    not become a tag or a heading: the document promises one section per
+//    requirement, and a rationale that opens its own breaks the only structural
+//    claim the document makes. See `prose` (design §9.1).
 import { byCodeUnit, sortDeep } from './order.js';
 import { control } from './terminal.js';
 /** Whether a value reads as words in a sentence — a scalar, or a list of them. */
@@ -199,7 +203,7 @@ function compareIds(a, b) {
 function overviewTable(registry, ids) {
     const rows = ids.map((id) => {
         const req = registry[id];
-        return `| [${id}](${anchor(id)}) | ${cell(interpolate(req.statement, req.params))} |`;
+        return `| [${id}](${anchor(id)}) | ${cell(statementText(req))} |`;
     });
     return ['| ID | Requirement |', '| --- | --- |', ...rows];
 }
@@ -207,9 +211,9 @@ function section(id, req) {
     const out = [
         `## ${id}`,
         '',
-        interpolate(req.statement, req.params),
+        statementText(req),
         '',
-        `**Why:** ${req.rationale}`,
+        `**Why:** ${prose(req.rationale)}`,
     ];
     const params = Object.entries(req.params);
     if (params.length > 0) {
@@ -225,33 +229,200 @@ function section(id, req) {
         }
     }
     if (req.outOfScope.length > 0) {
-        out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${s}`));
+        out.push('', '**Out of scope**', '', ...req.outOfScope.map((s) => `- ${prose(s)}`));
     }
     return out;
 }
+/** The statement as the document says it, with its params in place. */
+function statementText(req) {
+    return prose(req.statement, req.params);
+}
+/**
+ * Author prose as Markdown that cannot become HTML and cannot open a section,
+ * with `{param}` placeholders substituted as it goes (design §9.1).
+ *
+ * One pass rather than two because the two jobs need the same fact — which
+ * regime each character is in. Escaping first and substituting after would run
+ * the value through a scanner reading backticks as structure; substituting
+ * first and escaping after would let a value's own backtick open a code span
+ * that was never in the statement, and carry the rest of the sentence out of
+ * the defence. Knowing the position is also what lets a value be escaped
+ * *for* it, which is the difference between `emphasised` and `literal` below.
+ *
+ * Which of the three things a registry string could do here is intended, and
+ * why this escapes rather than refuses, is §9.1. What is local to this function
+ * is where it stops: **a code span is left exactly as written**, because a
+ * span's contents are literal text in every renderer and an entity written
+ * there would be visible rather than decoded. The match is therefore
+ * deliberately conservative — a backtick run opens a span only if a run of
+ * *exactly* that length closes it (CommonMark), and an unmatched run is text
+ * with the defence still applied after it. Being wrong the other way, reading
+ * text as a span the renderer will not, is the only direction that leaks.
+ */
+function prose(text, params = {}) {
+    const spans = spanReader(text);
+    const out = [];
+    let i = 0;
+    let atLineStart = true;
+    while (i < text.length) {
+        const ch = text[i];
+        if (ch === '`') {
+            const end = spans.spanEndAt(i);
+            out.push(substitute(text.slice(i, end), params, literal));
+            atLineStart = false;
+            i = end;
+            continue;
+        }
+        if (ch === '{') {
+            const placeholder = /^\{\w+\}/.exec(text.slice(i));
+            if (placeholder !== null) {
+                out.push(substitute(placeholder[0], params, emphasised));
+                atLineStart = false;
+                i += placeholder[0].length;
+                continue;
+            }
+        }
+        if (ch === '\n') {
+            out.push(ch);
+            atLineStart = true;
+            i += 1;
+            continue;
+        }
+        if (atLineStart) {
+            // Leading whitespace does not end the line's opening position: `   # x` is
+            // a heading, and four spaces make an indented code block where the escape
+            // is visible but harmless. Counting the indent to tell those apart would
+            // be a second Markdown reader for one cosmetic case.
+            if (ch === ' ' || ch === '\t') {
+                out.push(ch);
+                i += 1;
+                continue;
+            }
+            atLineStart = false;
+            // A heading opens a section; a line of `=` or `-` alone makes a heading
+            // out of the line *above* it, which is the same forgery approaching from
+            // behind. A backslash before either renders the character and nothing else.
+            if (ch === '#' || SETEXT.test(lineAt(text, i))) {
+                out.push('\\');
+                continue;
+            }
+        }
+        out.push(ch === '<' ? '&lt;' : ch);
+        i += 1;
+    }
+    return out.join('');
+}
+/** A line that would turn the one above it into a heading. */
+const SETEXT = /^(?:=+|-+)[ \t]*$/;
+function lineAt(text, from) {
+    const end = text.indexOf('\n', from);
+    return end === -1 ? text.slice(from) : text.slice(from, end);
+}
+/**
+ * Where each code span in `text` ends, answered in constant time per question.
+ *
+ * The obvious implementation searches forward from the opening run for a run of
+ * the same length, and it is the ATX-59 defect in a second costume: a run that
+ * closes nothing scans to the end of the string, so prose whose runs are all of
+ * *different* lengths pays that for every one of them. Measured, before this:
+ * 500 KB of such a rationale took 1.6 s and 2 MB took 15 s — from `attest
+ * render` with no flag, on text the registry chooses.
+ *
+ * So the runs are read once and indexed by length, and each length keeps a
+ * cursor into its own list. Openers are visited left to right, so a cursor only
+ * ever moves forward and the total work is bounded by the number of runs. A
+ * shorter or longer run is not a closer and is never a candidate here, which is
+ * the CommonMark rule and also what stops a scanner believing in a span the
+ * renderer does not.
+ */
+function spanReader(text) {
+    const runs = [];
+    for (let i = 0; i < text.length; i += 1) {
+        if (text[i] !== '`')
+            continue;
+        const start = i;
+        while (text[i] === '`')
+            i += 1;
+        runs.push({ at: start, length: i - start });
+        i -= 1;
+    }
+    const byLength = new Map();
+    runs.forEach((run, index) => {
+        const list = byLength.get(run.length);
+        if (list === undefined)
+            byLength.set(run.length, [index]);
+        else
+            list.push(index);
+    });
+    const cursors = new Map();
+    let nextRun = 0;
+    return {
+        /** The end of the span opening at `at`, or the end of that run if none. */
+        spanEndAt: (at) => {
+            while (runs[nextRun].at < at)
+                nextRun += 1;
+            const opener = runs[nextRun];
+            const candidates = byLength.get(opener.length);
+            let cursor = cursors.get(opener.length) ?? 0;
+            while (cursor < candidates.length && candidates[cursor] <= nextRun)
+                cursor += 1;
+            cursors.set(opener.length, cursor);
+            const closer = cursor < candidates.length ? runs[candidates[cursor]] : undefined;
+            return closer === undefined ? at + opener.length : closer.at + closer.length;
+        },
+    };
+}
 /**
- * Substitute `{param}` placeholders with the actual value, emphasised so a
- * reader can see which words in the sentence are pinned to a single source.
+ * Substitute `{param}` placeholders in one region with `render`, the spelling
+ * that region's position calls for.
+ *
  * An unbound placeholder is left verbatim — `check` already reports it as an
  * `unbound-param` error, and silently swallowing it here would hide that.
  */
-function interpolate(statement, params) {
+function substitute(region, params, render) {
     // `Object.hasOwn`, never `in`: `'toString' in {}` is true, and an `in` probe
     // would splice `function toString() { [native code] }` into a document that
     // reviewers and audit read as the system's promise.
-    return statement.replace(/\{(\w+)\}/g, (whole, name) => Object.hasOwn(params, name) ? `**${plain(params[name])}**` : whole);
+    return region.replace(/\{(\w+)\}/g, (whole, name) => Object.hasOwn(params, name) ? render(params[name]) : whole);
+}
+/**
+ * A param value in prose position: escaped, and emphasised so a reader can see
+ * which words in the sentence are pinned to a single source.
+ *
+ * Escaped unlike the statement around it, because those are prose an author may
+ * want to mark up and a value is data that must survive verbatim — an unescaped
+ * `*` would otherwise break out of the emphasis it is wrapped in. `<` and `#`
+ * are in the class for the same reason the rest of it is: they are structure
+ * *here*. A value is spliced into a sentence, so a tag in one is a tag in the
+ * document, and a value carrying a newline puts what follows at the start of a
+ * line, where `#` opens a section (design §9.1).
+ */
+function emphasised(value) {
+    const one = (v) => v.replace(/([*_`[\]\\#])/g, '\\$1').replaceAll('<', '&lt;');
+    return `**${listed(value, (v) => one(inlineText(v)))}**`;
 }
 /**
- * A param value as prose, for inline use inside a statement. Escaped, unlike
- * the statement and rationale around it: those are prose an author may want to
- * mark up, a param value is data and must survive verbatim — an unescaped `*`
- * would otherwise break out of the emphasis it is wrapped in.
+ * A param value inside the author's code span: the value, and nothing added.
+ *
+ * A code span's contents are literal in every renderer, so escaping there is
+ * not merely unnecessary, it is *visible* — Markdown does not decode `&lt;`
+ * inside one, and this repository's own `ATX-30` renders a path with `<name>`
+ * in it. Emphasis is dropped for the same reason: `**` in a code span is two
+ * asterisks, which is what the document said before this knew where it was.
+ *
+ * The exception is a value that would end the span early — a backtick, or the
+ * blank line a code span cannot contain. There the author has asked for two
+ * incompatible things, and the prose escape is the safe answer rather than the
+ * pretty one: what follows the broken span is author text this pass has already
+ * walked past.
  */
-function plain(value) {
-    const one = (v) => v.replace(/([*_`[\]\\])/g, '\\$1');
-    return Array.isArray(value)
-        ? value.map((v) => one(inlineText(v))).join(', ')
-        : one(inlineText(value));
+function literal(value) {
+    const text = listed(value, inlineText);
+    return text.includes('`') || /\n[ \t]*\n/.test(text) ? emphasised(value) : text;
+}
+/** A list param reads as its members; a scalar reads as itself. */
+function listed(value, one) {
+    return Array.isArray(value) ? value.map(one).join(', ') : one(value);
 }
 /**
  * One param value as a run of text.
@@ -273,9 +444,7 @@ function inlineText(value) {
 function formatValue(value) {
     if (!isFlat(value))
         return '_see below_';
-    return Array.isArray(value)
-        ? value.map((v) => code(inlineText(v))).join(', ')
-        : code(inlineText(value));
+    return listed(value, (v) => code(inlineText(v)));
 }
 /**
  * A structured param as a fenced JSON block.

package/dist/core/skill.js

@@ -93,6 +93,15 @@ promises is a two-stage workflow, and the stages are separate on purpose.
   through any edit. Pin the expectation to something that does not move with the
   param — a fixture, a literal in the test, or a second independently derived
   value.
+- **A param the scenario loops over is the *domain* of the run, and shortening it
+  is silent.** Drop a member and you drop a case; every assertion inside the loop
+  still passes over what is left, with the expectation as independent as it ever
+  was — so the rule above does not reach this. Pin the extent beside the loop:
+  the members against a literal when their identity is the promise, the count
+  when the size is. That literal is **not** the hardcoded value stage 2's third
+  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.
 
 ## Rules the engine enforces
 
@@ -313,6 +322,16 @@ failure this framework exists to make visible:
    is the drift the single source exists to prevent, and the param is typed at
    the value written in the registry, so a stale expectation stops compiling
    rather than silently passing.
+   *This forbids one literal and not the other, and the difference decides
+   whether a domain can be shortened.* Forbidden is a literal standing in for the
+   param **as the value the system is measured against** — that is the second
+   copy. Required, when a scenario **iterates** a list it read from \`params\`, is
+   a literal pinning that list or its length beside the loop: the list is then
+   the set of cases the run covers rather than a value under test, and dropping a
+   member removes a case while every assertion inside still passes. A literal is
+   the only independent term available when what is at risk is the **size** of
+   the set, so the two never collide — one asserts what the system does, the
+   other what the intent promised.
    *One thing to know before implementation code reads a param this change
    ADDs:* the suite imports your \`*.reqs.ts\` from disk, while the gate applies
    the delta in memory — so that read throws at import and the gate answers

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "TDD-native spec framework: tests are the source of truth for verification, ID-bound requirements the source of truth for intent.",
   "type": "module",
-  "packageManager": "pnpm@10.28.0",
   "engines": {
     "node": ">=20.19"
   },
@@ -37,24 +36,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
-    "build": "pnpm run clean && tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "typecheck:all": "tsc -p tsconfig.typecheck.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
-    "lint": "eslint .",
-    "prepack": "pnpm run build",
-    "prepublishOnly": "pnpm run test:consumer",
-    "attest": "node bin/attest.js",
-    "check:self": "node bin/attest.js check self",
-    "verify:self": "node bin/attest.js verify self",
-    "cover:self": "node bin/attest.js cover self",
-    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
-    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
-  },
   "keywords": [
     "tdd",
     "spec",
@@ -81,13 +62,20 @@
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ],
-    "overrides": {
-      "brace-expansion@<5.0.9": ">=5.0.9",
-      "js-yaml@<4.3.1": ">=4.3.1"
-    }
+  "scripts": {
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive: true, force: true})\"",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:all": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:consumer": "pnpm run build && vitest run --config vitest.consumer.config.ts",
+    "lint": "eslint .",
+    "attest": "node bin/attest.js",
+    "check:self": "node bin/attest.js check self",
+    "verify:self": "node bin/attest.js verify self",
+    "cover:self": "node bin/attest.js cover self",
+    "render:self": "node bin/attest.js render self --out self/requirements/SPEC.md",
+    "render:self:check": "node bin/attest.js render self --out self/requirements/SPEC.md --check"
   }
-}
+}