@am_shork/attest 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -13,6 +13,172 @@ 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.4.3] - 2026-08-01
+
+### Added
+
+- **The README's two getting-started samples are now the fixture the packaging
+  test installs and runs.** `tests/docs-consistency.spec.ts` opened by naming
+  this hole: every `*.md` outside the generated `SPEC.md` is hand-written prose
+  that no mechanism binds to the code, "the framework's own blind spot (design
+  §11)". Every check in that file until now gated a version string or a name;
+  this is the first that gates *meaning* — a registry or a spec on the page that
+  the engine would now reject was undetectable, which for a tool whose whole
+  claim is reporting drift between intent and what the tests execute is the
+  failure that costs the most.
+  The mechanism is a naming split rather than new machinery, and most of it was
+  already there and unnamed: `fixtures/consumer/` imports by bare specifier from
+  `@am_shork/attest` and `@am_shork/attest/define` because it is installed from a
+  real tarball outside the repo — which is exactly what a reader has to be able
+  to paste. So the two files lost their fixture-specific commentary, gained the
+  README's teaching comments, and the README now quotes them; the new assertion
+  is byte-equality between the fenced block and the file, newline-normalised so a
+  CRLF checkout cannot call a clean tree stale. The fixture is the original and
+  the page is the quote: breaking either side fails.
+  *What moved in the README:* the spec sample is now `session.spec.ts` beside
+  `session.ts` rather than `auth/session.spec.ts`, matching the layout the
+  packaging test actually runs, and it shows both of the requirement's scenarios
+  because the installed run asserts `scenarioCount: 2`.
+  *Limits, both deliberate:* the gate covers 2 of the 23 fenced `ts` blocks in
+  the README and `docs/en/**` — the rest are elided, ✓/✗-annotated, or
+  deliberately rejected by the engine, and none of those can equal a runnable
+  file. And the two claims are joined only on a release: this gate runs in
+  `pnpm test` and proves the page and the fixture agree, while the run that
+  proves the fixture still *works* is `pnpm test:consumer`, which needs a network
+  and a tarball. Both remaining halves are in `Planned`.
+
+- **The `docs/en` ↔ `docs/zh` mirror rule is now a gate rather than a paragraph
+  in `CLAUDE.md`.** Two assertions in `tests/docs-consistency.spec.ts`, both
+  scoped to what is comparable without comparing prose. The file set: a page
+  added on one side only is not a stale translation, it is a page that does not
+  exist, and nothing in the repository would have noticed. And the structure of
+  each pair — the heading tree as levels in document order, and the sequence of
+  fence info strings — which catches a section dropped or reordered in
+  translation, a code sample present in one language only, and a ```ts that
+  became ```bash.
+  *The parse is the part with a trap in it.* A `#` at the start of a line inside
+  a ```bash sample is a shell comment, and these pages are full of them, so the
+  reader tracks fences and skips their contents; a closing fence must repeat the
+  character that opened it, or a ``` quoted inside a ~~~ block ends the wrong
+  thing. An unterminated fence is reported rather than ignored, because it hides
+  every heading after it — two documents can agree by being truncated. All three
+  are asserted directly, on the standard this file already applies to its other
+  parses: a check whose parser can silently match nothing is not a check.
+  *One third of the queued entry turned out to be already covered and was not
+  written.* It asked for the `##` issue-code headings of `troubleshooting.md` to
+  be held equal between languages; the roster check that predates it already
+  asserts each language against `ISSUE_CODES` in both directions, so their
+  equality follows and a third assertion would catch nothing they let through.
+  *The limit, stated because it is not small:* a page whose structure held while
+  its meaning went stale passes everything here. Translation is not a diff. Same
+  shape as the limit the History gate carries — it can check that a row cites a
+  real version, not that the row is true.
+
+### Documentation
+
+- **The agent-facing documents gained a diagnosis discipline, a review pass, and
+  a design vocabulary**, adapted from an external skill collection rather than
+  copied from it — the parts that survived are the ones this repository's own
+  defect history had already paid for.
+  *New skill, `.claude/skills/diagnose/`.* Its one rule is that no hypothesis may
+  be formed before a command exists that has been run at least once and can go
+  **red** on the bug in hand. Every defect this repository has recorded failed
+  silently rather than loudly, so that bar is higher here than the phrase
+  suggests, and the skill's local content is the questions that tell a green run
+  apart from one that never happened: read the test count rather than the colour,
+  since a `beforeAll` throw reports a file as *skipped* (`[0.4.2]`); confirm the
+  file you care about actually ran, since a glob that matched nothing is a clean
+  run over code that never loaded; and name which half a command covers before
+  trusting it. The ways that goes wrong are the Gotchas in `CLAUDE.md`, pointed
+  at rather than restated — a second copy of them would only be a second copy to
+  drift. The remainder is the standard loop: minimise until every element is
+  load-bearing, three to five falsifiable hypotheses before testing any,
+  `[DEBUG-…]`-tagged probes, and "no correct seam is itself the finding".
+  *`pre-commit-check` gained §8, a reading pass on two axes*, kept unmerged and
+  unranked against each other because a change can pass either and fail the
+  other. The Spec axis is mostly machine-checked here and nowhere else — `check`,
+  `cover` and `verify` *are* drift detection — so it reads only for what those
+  cannot reach: whether an `ATX-n`'s text states the contract, whether `params`
+  pin the values the scenario should be pinned to, and whether a green scenario
+  attests its requirement or merely passes. The Standards axis carries a twelve-
+  smell baseline (Fowler, *Refactoring* ch.3) as labelled heuristics that any
+  documented rule here overrides, with two weighted for this repository:
+  duplicated path-shaped code means a second copy that did not go through
+  `src/core/paths.ts`, and speculative generality is the other face of §1's rule
+  that every requirement costs a scenario forever.
+  *`CLAUDE.md` gained a design vocabulary* — module, interface, depth, seam,
+  adapter, and the three tests that settle most arguments — which exists because
+  the two structures it names were already these things and had no word for it.
+  `src/core/paths.ts` is the repository's deepest module, and the deletion test
+  is not hypothetical for it: every silent path defect in the Gotchas is what
+  this codebase looked like when that knowledge lived at the call sites. The two
+  registry readers are two adapters at one real seam, which is what makes the
+  differential suite possible — and the entry marks where the analogy stops,
+  since which adapter runs is fixed by the command and never a fallback, that
+  being a security property rather than a design preference.
+  *And a section on where a decision goes*, which is this file. It is stated in
+  `CLAUDE.md` rather than only in `pre-commit-check` because the moment to write
+  one is when the decision happens; a design evaluated and dropped mid-session is
+  what is most likely to be lost, and by commit time the reasoning that killed it
+  is already gone.
+  *The candidate that did not survive is the reason the section exists.* The
+  proposal was a `docs/adr/` directory holding three decisions lifted out of the
+  Gotchas — why `fixtures/nested-spec/` may not be flattened, why `render
+  --check` compares the document rather than the bytes, why one `spawn` helper.
+  All three were already recorded here, in more detail than the proposal would
+  have carried, so the directory's whole effect would have been to split a store
+  this file keeps deliberately single. Recorded rather than filed as work, since
+  no such directory exists: had it been put under `docs/en/`, the mirror gate
+  added above would not have seen it at all — `pages()` is a non-recursive
+  `readdir` filtered to `*.md`, so a subdirectory is invisible to the file-set
+  check, the structure check, and the version-bearing sample scan alike. A
+  documentation subdirectory is therefore an unmirrored one, silently, which is
+  this repository's signature failure shape wearing documentation's clothes.
+
+### Fixed
+
+- **The packaging test installed into a directory Windows spells two ways, and
+  read the result as the package being broken.** `tests/consumer.spec.ts` staged
+  its throwaway project under `os.tmpdir()`, which on Windows reads `TEMP` — set
+  by the OS to the 8.3 short form, `C:\Users\JOHN_C~1\...`. Vite resolves the
+  peer `vitest` from the *long* form of the same directory, so the consumer's
+  spec file and the installed `@am_shork/attest` imported two module instances of
+  it; `describe` ran against an uninitialised runner and the spec died at import
+  with `Cannot read properties of undefined (reading 'config')`, before a
+  scenario executed. What that surfaced as is the part worth recording: `attest
+  verify` reported `tests-red` plus `declared-not-run` for every scenario —
+  a report indistinguishable from a genuinely broken package, produced by a
+  package that is fine. Staging through `realpath` fixes it.
+  This is `CLAUDE.md`'s first failure family one form further out — not a
+  separator inside a path, but two spellings of one directory — and it was
+  unreachable until `[0.4.2]` made this suite run on Windows at all. CI is Linux,
+  where `os.tmpdir()` has one spelling, so the pipeline was never going to say
+  otherwise.
+
+- **The AST parser's own source file was binary, so every change to it since the
+  initial commit was unreviewable.** `src/core/parser.ts` separated the two
+  halves of its param-ref dedupe key with a **raw NUL byte** rather than the
+  `\x00` escape. One character no editor renders reclassified the whole file:
+  `git diff` answered `Binary files a/… and b/… differ` for every change to it,
+  `git grep` and `grep` skipped it in silence, and `.gitattributes`' `eol=lf`
+  never applied, because `text=auto` tests for binary first.
+  *What it cost is the reviewing, not the running.* A string escape is resolved
+  by the compiler, so the key is the same three code units on every platform —
+  no behaviour changes, and no requirement, scenario or schema moves. What was
+  lost is that every text sweep over this repository silently excluded the one
+  module that turns spec source into the plan every command reads. A pre-commit
+  pass grepping `src/` for a rule — a `path.relative` outside `paths.ts`, a
+  stray `spawn` — was answering about 27 of 28 files and reporting no gap, which
+  is worse than not having run it.
+  *And it shipped.* `files` carries `dist`, and `tsc` copies a template
+  literal's contents verbatim, so `dist/core/parser.js` put the byte into every
+  installed copy.
+  Recorded at this length because the defect is not the byte but its invisibility:
+  this is `CLAUDE.md`'s silent-failure shape with no platform in it at all, and
+  the tools anyone would bring to look for it are the ones it disables. The last
+  thing it costs is its own diff — the old side of this commit is still the
+  binary blob, so this entry is the only readable account of the change.
+
 ## [0.4.2] - 2026-07-30
 
 ### Added
@@ -1880,26 +2046,10 @@ 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 and last
-below came out of reading another repository against this one — `fast-check` and
-`msw` respectively. The middle one came out of building something queued here,
-which is the other way an entry arrives: a gate that finds a defect on its first
-run files the defect.
-
-- **A structural parity gate over `docs/en/**` and `docs/zh/**`.** The mirror
-  rule — one Chinese page per English page, matching down to the comments inside
-  the code samples, both carried by the same commit — is enforced today by a
-  paragraph in `CLAUDE.md` and by whoever remembers to read it. The home is
-  `tests/docs-consistency.spec.ts`, which already enumerates both directories
-  and already says in its own header why it checks only the two couplings tight
-  enough to assert cheaply; this is a third. What is comparable without
-  comparing prose: the heading tree (level, order, count), the count of fenced
-  code blocks, and — for `troubleshooting.md` — the set of `##` issue-code
-  headings, which is machine-derived on both sides and so must be equal
-  exactly. Translation is not a diff and nothing here should pretend otherwise,
-  which is also the limit: a page whose structure held while its meaning went
-  stale passes. Same shape as the limit the History gate already carries — it
-  can check that a row cites a real version, not that the row is true.
+losing the argument would cost more than losing the task. The last below came out
+of reading another repository against this one — `msw`. The first came out of
+building something queued here, which is the other way an entry arrives: a gate
+that finds a defect on its first run files the defect.
 
 - **A diagnosable refusal when the resolved compiler has no AST API.**
   Discovered by building the `typescript` matrix (see `[0.4.2]`), which is
@@ -1928,40 +2078,36 @@ run files the defect.
   it yet — a separate decision, with the honest answer for now being that the
   supported range has a ceiling and says so.
 
-- **Fixtures that are also the code samples the documentation shows.**
-  `tests/docs-consistency.spec.ts` opens by naming this exact hole: every `*.md`
-  outside the generated `SPEC.md` is hand-written prose that no mechanism binds
-  to the code — "the framework's own blind spot (design §11)" — and it asserts
-  only the two couplings cheap enough to assert. This is a fourth, after the
-  `docs/en` ↔ `docs/zh` parity gate queued above, and it is the one that reaches
-  meaning rather than structure: a fenced block in `cli-reference.md` or
-  `troubleshooting.md` showing a registry the engine would now reject is
-  undetectable today. For a tool whose entire claim is reporting drift between
-  intent and what the tests execute, its own documentation drifting from what the
-  engine does is the failure that costs the most and is currently reported by
-  nobody.
-  **The shape that makes it cheap is a naming split, not a new mechanism.** `msw`
-  requires every integration test to be two files: a `*.mocks.ts` holding a usage
-  example with *nothing test-specific in it*, and a `*.test.ts` that loads the
-  example and asserts against it — so the example is simultaneously the fixture
-  and a snippet publishable to users unmodified. Here that means promoting a
-  subset of `fixtures/` to that status and having the English page quote the file
-  rather than restate it, with the assertion being byte-equality between the
-  fenced block and the fixture.
-  **Not every fixture is a candidate, and the exclusions are the existing ones.**
-  `fixtures/runner-red` and `fixtures/e2e-bad` are inputs to child runs that
-  assert failure, and `fixtures/nested-spec/` exists to put a separator in a path
-  — none is written to be read as an example, and dressing them up as one would
-  cost the thing they are for.
-  *The cost is the mirror rule, and it caps what can be claimed.* `docs/zh/**`
-  matches `docs/en/**` down to the comments inside its code samples, so
-  byte-equality can hold on one side only; the Chinese block stays translated
-  prose around the same code, which is the parity gate's problem and is why these
-  two entries should land together or in that order. A page whose sample is
-  byte-equal to a living fixture while the paragraph above it describes the old
-  behaviour still passes — the same limit already written down for the History
-  rows, and the same answer: this binds what is machine-derivable and leaves the
-  rest to a reader.
+- **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
+  are now byte-equal to `fixtures/consumer/`. That buys 2 of the 23 fenced `ts`
+  blocks in the README and `docs/en/**`, and the ceiling is structural rather
+  than lazy — the other 21 are elided (`{ /* … */ }`), annotated (`// ✓ the single
+  source`, `// ✗ a literal that can drift`), or deliberately rejected by the engine
+  (`params: { maxMb: MAX_MB }`), and none of those can equal a runnable file.
+  **What raises it is marking spans, not a second mechanism.** A
+  `// #region readme:registry` and its close inside the fixture, with the
+  assertion running block against dedented span, lets one file feed several
+  passages and makes a partial quote bindable by construction. Where that
+  actually reaches, counted rather than hoped: `troubleshooting.md`'s
+  single-source pair is two verbatim lines of `fixtures/consumer/session.spec.ts`
+  and its `AUTH-3` block is the registry entry at a different indent — so a
+  handful more, not the remainder. Anything carrying a `✓`/`✗` is authored
+  commentary and stays a fragment; that is what it is for.
+  *The ✗ blocks are a separate question, and worth not conflating.* A sample
+  showing input the engine must reject could be bound to a fixture whose
+  *rejection* is asserted — which is what `fixtures/eval-invalid-registry`
+  already is. Binding those is the more valuable half, because a counterexample
+  that stopped being a counterexample is the one kind of stale sample that
+  actively teaches the wrong thing. It is also the one that needs a fixture per
+  diagnostic, so it is not free the way the regions are.
+  *The mirror rule still caps what can be claimed on the Chinese side.*
+  `docs/zh/**` matches `docs/en/**` down to the comments inside its code samples,
+  so byte-equality holds on one side only and the zh blocks stay translated prose
+  around the same code — the parity gate in `[0.4.3]` is what covers them now,
+  and it covers structure, not meaning. Unchanged from the whole-file half: the residual
+  risk recorded with it in `[0.4.3]` — that the gate and the run proving the
+  fixture still works live in different suites — applies here identically.
 
 ## Under consideration
 
@@ -2271,7 +2417,8 @@ 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.
 
-[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.4.2...main
+[Unreleased]: https://gitlab.com/Pseudorca/attest/-/compare/v0.4.3...main
+[0.4.3]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.3
 [0.4.2]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.2
 [0.4.1]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.1
 [0.4.0]: https://gitlab.com/Pseudorca/attest/-/tags/v0.4.0

package/README.md

@@ -67,13 +67,13 @@ export default defineRequirements({
 });
 ```
 
-**2. Attest it with a scenario** (`auth/session.spec.ts`):
+**2. Attest it with scenarios** (`session.spec.ts`):
 
 ```ts
 import { expect } from 'vitest';
 import { requirement, scenario } from '@am_shork/attest';
-import reqs from '../requirements/auth.reqs.js';
-import { createSession, advance, isValid } from './session.js';
+import reqs from './requirements/auth.reqs.js';
+import { createSession, advance, touch, isValid } from './session.js';
 
 requirement('AUTH-3', () => {
   scenario('idle timeout invalidates the session', () => {
@@ -82,9 +82,22 @@ requirement('AUTH-3', () => {
     advance(s, t + 1, 'minutes');
     expect(isValid(s, t)).toBe(false);
   });
+
+  scenario('activity resets the idle timer', () => {
+    const t = reqs['AUTH-3'].params.idleTimeoutMin;
+    const s = createSession();
+    advance(s, t - 1, 'minutes');
+    touch(s);
+    advance(s, t - 1, 'minutes');
+    expect(isValid(s, t)).toBe(true);
+  });
 });
 ```
 
+Both files above are quoted from `fixtures/consumer/`, which the packaging test
+installs from a real tarball and runs — a test asserts the quotes are byte-equal
+to the files, so a sample the engine would now reject cannot survive here.
+
 **3. Run the engine:**
 
 ```bash
@@ -136,7 +149,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.4.2/docs/en/troubleshooting.md#registry-not-static
+    → https://gitlab.com/Pseudorca/attest/-/blob/v0.4.3/docs/en/troubleshooting.md#registry-not-static
 ```
 
 The anchor **is** the code, so the link cannot point somewhere the section

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@am_shork/attest",
-  "version": "0.4.2",
+  "version": "0.4.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",
   "engines": {