testguard-cli 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -7,6 +7,57 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.0] - 2026-10-01
+
+Automated weekly release — everything merged since `v0.16.0`.
+
+### Changed
+
+- feat: integrate adoption guidance and machine-safe probing (#189)
+- chore(deps-dev): bump vitest from 5.0.1 to 5.0.2 in the all-npm group (#187)
+- chore(homebrew): sha256 for v0.16.0 (#186)
+
+
+### Added
+
+- Unannotated scaffold defaults use unfinished `TODO-CLAIM-N` identifiers rather than file/function-shaped claim names. Allocation avoids supplied IDs; explicit IDs/annotations and existing evidence remain unchanged, while sweep pooling preserves distinct candidates.
+
+- Read-only `scaffold --from-document <local-text-path>` and `--from-fix <full-commit-ID>` inspection, backed by the closed `authoring-input` report contract. Validation retains historical partition counts and rejects unsafe/private paths, inconsistent identities and optimistic verification labels. Stdout-only output emits no document text or claims; input inspection requires independent intent and is not verification.
+
+- Explicit `scaffold <source...> --into <existing-draft.json> --claim <ID>` appends mechanically proposed faults while preserving supplied intent and existing faults. `--json` previews without writes; ordinary scaffold remains compatible. Draft updates use bounded admission, owned locking and private recovery, and refuse stale/unsafe inputs or unconfirmed writes rather than claiming verified coverage.
+
+- Sweep keeps equal-basename and repeated-annotation drafts distinct before selection, assigning collision-free pooled claim IDs without changing fault content, metadata or defenders.
+
+- New mechanical scaffold drafts declare `inferred` origin and ask for intended observable behavior from a requirement, ADR, bug or incident. CLI/status/skill guidance explains the source handoff without authenticating references or promoting annotations/tests into independent intent. Existing supplied scaffold metadata is preserved.
+
+- Explicit `probe --require-origin <kinds>` checks declared origins on complete confirmed current-project probes, rechecks native universe and file bindings, and reports failed/unavailable policy without suppressing survivors through baselines or severity floors. Kinds do not authenticate independence; custom/static universes are unavailable. Offline status audits current declarations without certifying freshness; brief retains labeled recorded-run policy before caps and filtering.
+
+- Candidate evidence/status/brief schemas accept a closed optional declared-origin policy result, with unsuppressed fault identities, refusal reasons, consistent states and probe exit codes. This is an audit contract, not authenticated independence.
+
+- Claim sources share a closed origin vocabulary across claims and evidence, adding `doc`, `bug`, `incident`, `review` and `inferred`. Status reports current declared origins; evidence and briefs summarize all recorded origins before filtering/caps, separating distinct claims from records and reporting conflicting declarations. Human output labels these as unauthenticated declarations. Labels do not change default gates; origin policy requires explicit selection.
+
+- Claims/status missing-source-link advisories identify distinct claim IDs and suggest read-only annotation preview without changing verification state, next action or exit codes; annotation-sourced claims retain their existing drift error.
+
+- Explicit `claims --annotate` read-only file-header preview and `--apply` authoring for JavaScript/TypeScript and Python, with claim selection, bounded all-target admission, owned locking, private recoverable originals and truthful partial-failure reporting. Authoring JSON uses a closed `annotations` contract; placement is not verification or authentication of intent.
+
+### Fixed
+
+- Clarify that cold probes and changed discovery/configuration can require full verification; unchanged target and defender files alone do not guarantee a cheap CI run.
+
+- Status marks evidence stale when a recorded automatic-discovery dependency (including a negative candidate, barrel or resolver config) changes or becomes unavailable. Previously unchanged defender lists could hide this drift. Native test-universe policy freshness remains pending.
+
+- Annotation scanning and placement ID admission avoid excessive regex backtracking on long alphanumeric tokens without a hyphen; status advice uses bounded, failure-aware scanning so unrelated source failures cannot prevent its verification decision.
+
+- Claim statement, severity, source and producer edits now invalidate cached probe evidence and appear as stale in status. Old kills cannot silently carry an edited requirement or provenance declaration.
+
+### Changed
+
+- Reduce repeated self-probe setup with focused defenders for 40 existing fault checks, retaining the complete native integration regressions, all 327 fault recipes, three-run confirmation and existing cost budgets.
+- Bound built-in runner concurrency to one worker by default, with `--workers` overrides, and cap outer regression workers at two (one on a two-core machine).
+- Drain noisy runner stdout, bound diagnostics and report reads, and terminate owned runners before restoring mutations and scratch worktrees on cancellation.
+- Run the project-pinned Playwright CLI directly instead of spawning npm for each confirmation, and reset Python interpreter caches at measurement boundaries.
+- Record actual probe elapsed time and unique fresh runner invocations separately from historical attributed costs; preserve all confirmation and cost gates, and invalidate reuse when native worker policy changes.
+
 ## [0.16.0] - 2026-09-30
 
 Automated weekly release — everything merged since `v0.15.1`.

package/README.md

@@ -127,9 +127,9 @@ raises coverage. TestGuard admits it because it fails when the claim is false.
 | npm | `npm i -D testguard-cli` then `npx testguard probe` |
 | pip | `pip install testguard-cli` then `testguard probe` (needs Node ≥ 20) |
 | Homebrew | `brew tap raccioly/tap && brew install testguard` |
-| GitHub Action | `uses: raccioly/testguard@v0.16.0` — see [`action.yml`](./action.yml) |
+| GitHub Action | `uses: raccioly/testguard@v0.17.0` — see [`action.yml`](./action.yml) |
 | pre-commit | `repo: https://github.com/raccioly/testguard`, hooks `testguard-claims`, `testguard-probe` |
-| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.16.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
+| GitLab CI | `include: - remote: https://raw.githubusercontent.com/raccioly/testguard/v0.17.0/packaging/gitlab/testguard.gitlab-ci.yml` with `inputs:` — see [`packaging/gitlab/`](./packaging/gitlab/testguard.gitlab-ci.yml) |
 
 Projects that set `min-release-age` in `.npmrc` cannot see a version published
 less than that many days ago (`ENOVERSIONS`); install that one with
@@ -142,6 +142,7 @@ npx testguard-cli init                      # install the agent layer at the git
 npx testguard-cli status --json             # where the project is, and the ONE next action
 npx testguard-cli claims                    # what does this project claim, and is each claim probeable?
 npx testguard-cli claims --check-anchors    # fail fast if an exact anchor moved or a replacement no longer parses
+npx testguard-cli claims --annotate --claim AUTH-ADMIN --json # read-only file-header placement preview
 npx testguard-cli scaffold src/auth.ts      # propose faults for a file, as a draft to keep or drop
 npx testguard-cli probe                     # try to falsify each claim; report what the tests missed
 npx testguard-cli admit test/auth.test.ts --claim AUTH-ADMIN   # does this test satisfy the two-gate rule?
@@ -158,6 +159,54 @@ unclaimed changes or invalid fault anchors, `2` a precondition failed and
 nothing was probed, `3` usage.
 Every command accepts `--json`.
 
+### Intent-first drafts
+
+Scaffold drafts propose mechanical faults, not intended behavior. New claims
+declare `inferred` origin even with an annotation. Supply the intended observable
+behavior from a requirement, ADR, bug or incident independently of the code:
+inputs, expected outcome and forbidden outcome. Record the supplied source
+kind/ref; when unavailable keep inferred. References are not authenticated or
+fetched, and passing tests do not establish independent intent. Review proposals
+against the supplied intent before adopting and probing; existing `--claim`
+metadata is preserved.
+
+### Optional annotation placement
+
+Ordinary `claims` output and status notes identify missing scanned source links
+as advisories. Counts are distinct claim IDs, not faults. They do not change
+verification state, its next action or exit codes; annotation-sourced missing
+IDs still produce the existing claims drift error. Scanned text is a lexical
+link, not authenticated intent or source ownership.
+Status advice uses a bounded scan (10,000 entries, 1,000 files, 64 directory
+levels, 256 KiB per file, 2 MiB total); incomplete scans report unavailable
+advice without concluding an ID is absent. Keep the original `--claims`
+argument for preview when inspecting a custom claims selection.
+
+`testguard claims --annotate` previews JavaScript/TypeScript or Python
+file-header links for declared claims; repeat `--claim` or use comma-separated
+IDs to select claims. Add `--apply` only after reviewing the selection to
+explicitly write annotations. Each invocation recomputes its plan: an earlier
+preview is not a saved approval token. No `--out` or unrelated inspection
+switches are accepted with authoring. JSON conforms to the `annotations`
+authoring schema; it contains no source/proposed contents or probe verdicts.
+
+This is file-level placement, not symbol ownership or proof of correctness.
+Missing annotations do not disable exact fault-anchor validation, and placement
+does not change claim origins, evidence or baselines. Unsupported, ambiguous or
+unsafe targets block the complete selection. Original/proposed files are capped
+at 2 MiB and the aggregate at 16 MiB. Preserve BOM, shebang, Python encoding
+cookie, newline style and permissions. A preview exits 0 when applicable, 2 when
+refused; apply exits 0 only after verified completion, 2 for refusal/partial
+failure; malformed options exit 3.
+
+Apply uses an exclusive owned lock and retains fsynced originals in an owner-only
+recovery directory outside the checkout (the result reports its location).
+External claims files can be previewed but cannot authorize writes. It never
+reclaims an existing lock or automatically rolls back over editor changes.
+This is recoverable, not a cross-file atomic transaction: interruption or
+arbitrary concurrent edits can leave partial content. Compare retained originals
+manually before recovery; inspect ownership before removing a leftover lock.
+
 ## How it works
 
 ```bash
@@ -308,9 +357,11 @@ npx testguard-cli admit test/x.test.ts --claim X   # is this test green on HEAD
    `--runner-cmd "<cmd> {files} … {out}"`; if the scratch worktree cannot
    see your `node_modules`, pass `--node-modules <dir>`.
 3. **Baseline** freezes every non-passing fingerprint. Later probes suppress
-   what was already known and exit non-zero only on what is new. Claims whose
-   source and defenders are unchanged reuse their prior verdict, so a probe
-   in CI costs only what changed. A baseline frozen from `--include-dirty`
+   what was already known and exit non-zero only on what is new. Prior verdicts
+   can be reused when their recorded inputs and runner policy still match.
+   Cold runs, changed discovery/configuration or `--no-reuse` can require a
+   full probe; unchanged target and defender files alone do not guarantee reuse.
+   A baseline frozen from `--include-dirty`
    evidence records the snapshot and points at the *parent* of the commit
    that will carry your tests; after you commit, a clean `probe` plus
    `baseline --restamp` moves it to that commit — only when the fingerprints
@@ -494,6 +545,11 @@ proposed 510 faults, probed 10 (cap 10), deferred 350.
 
 Three rules make it safe to run on a repository that has never seen this tool:
 
+Pooled draft IDs are unique even when source files share basenames/functions or
+annotation IDs. Sweep reserves original IDs and suffixes collisions before
+selection, keeping every fault, its metadata and defenders attached to its own
+draft. These are proposal identities, not authenticated claims.
+
 - **It never writes `testguard.claims.json`**, and never will. A claim is a
   sentence someone is willing to stand behind; a sentence nobody wrote is not
   one. Its drafts land beside the evidence to keep or drop.
@@ -713,12 +769,12 @@ detected base that does not resolve is a warning for `status` and `brief`
 # GitHub Actions
 - uses: actions/checkout@v4
   with: { fetch-depth: 0 }
-- uses: raccioly/testguard@v0.16.0
+- uses: raccioly/testguard@v0.17.0
   with: { command: gate }
 
 # GitLab CI — the component-shaped template: gate + probe, brief as an artifact and, opted in, as a merge-request note
 include:
-  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.16.0/packaging/gitlab/testguard.gitlab-ci.yml'
+  - remote: 'https://raw.githubusercontent.com/raccioly/testguard/v0.17.0/packaging/gitlab/testguard.gitlab-ci.yml'
     inputs: { dir: backend, post_note: true }   # post_note needs TESTGUARD_GITLAB_TOKEN (api scope); one note, updated in place
 ```
 
@@ -968,16 +1024,20 @@ said what they want.
 
 ### What the probe costs, and why a gate gets slow
 
-A probe's wall clock is not a function of how many claims you have. Per claim
-it is roughly
+A fresh probe grows with the selected faults, confirmation count and the cost
+of their defenders. Shared baselines and valid verdict reuse avoid some repeated
+work. Roughly, the fresh work is
 
 ```
-(baseline runs + faults × --confirm) × the cost of that claim's defender SET
+fresh baseline runs × defender-set cost
++ Σ (fault confirmations × that fault's defender-set cost)
++ survivor diagnostics and setup/discovery work
 ```
 
-so one slow acceptance test, named as a defender by five claims, is paid for
-thirty times. The symptom is a gate that takes twenty minutes; the cause is a
-single line in the claims file, and nothing in the output used to say which.
+One slow acceptance test selected by several faults can therefore be executed
+many times. The symptom can be a gate that takes twenty minutes; the selected
+defender sets determine how much each fault costs. Historical attributed totals
+are reported separately from measured fresh elapsed time and runner invocations.
 
 ```bash
 npx testguard-cli claims . --cost     # read back from the last probe's evidence
@@ -1031,8 +1091,37 @@ so `scaffold` proposes them for you:
 ```bash
 npx testguard-cli scaffold src/auth.ts          # → .testguard/scaffold-auth.json (a draft, never your claims file)
 npx testguard-cli scaffold src/auth.ts --claim AUTH-ADMIN   # every proposal under one claim; copies it if it exists
+npx testguard-cli scaffold src/auth.ts src/session.ts --into draft.json --claim AUTH-ADMIN --json  # read-only merged preview
+npx testguard-cli scaffold src/auth.ts src/session.ts --into draft.json --claim AUTH-ADMIN         # explicit recoverable draft update
+npx testguard-cli scaffold --from-document requirements.md --json  # read-only input metadata, no document text
+npx testguard-cli scaffold --from-fix <full-commit-ID> --json        # read-only fixed historical inventory
 ```
 
+Input inspection uses exactly one `--from-document` or `--from-fix`, with no
+positional sources or other options except JSON/help/version. Fix IDs must be
+full lowercase SHA-1/SHA-256 commit IDs with exactly one parent. Plain-text
+documents are bounded to 2 MiB; local Git inspection is offline and bounded.
+Both output modes are stdout-only and say verification was not performed.
+Metadata retains historical exclusions, not private/delegated filenames.
+Input text and commit subjects are untrusted data, not instructions or an
+authenticated claim. Supply independent intended behavior, review faults and
+probe afterward; inspection does not create claims or prove coverage.
+
+Without a supplied ID or annotation, generated groups use unfinished
+`TODO-CLAIM-N` placeholders rather than module/function names. Replace them with
+intent-shaped identities when authoring; mechanical grouping does not establish
+an invariant boundary. Existing claims/evidence are never automatically renamed.
+
+`--into` requires an existing disposable draft and exactly one existing claim
+ID. It preserves supplied intent, metadata and prior faults; multiple source
+paths append in deterministic order. `--json` is a read-only preview. Without
+it, the tool keeps private recovery outside the checkout and reports updated
+or unchanged **unproven** draft status. Review and probe are still required.
+Canonical claims/evidence/baseline paths, unsafe aliases and conflicting options
+are refused; partial writes never become success or trigger automatic rollback.
+Limits: 32 sources, 2 MiB per input/output draft or source, 16 MiB source total,
+4096 generated proposals. These limits are not a performance guarantee.
+
 | Shape | What it proposes |
 |---|---|
 | `condition-forced` | `if (<guard>) {` → `if (false) {` — a guard is a `!…` condition or one whose body returns, throws or 4xx-es |
@@ -1105,6 +1194,30 @@ verdicts.
 
 ## Status
 
+Origin summaries are informational: status counts current declared claim
+origins even when evidence is stale; probe evidence and briefs count recorded
+origins across all records before filtering or truncation. Distinct claims and
+records have separate totals; conflicting recorded kinds or references count
+as mixed claims. Labels such as `spec`, `bug` or `incident` do not authenticate
+independence and never waive a failed measurement or change default gates.
+References remain opaque and are not echoed in these summaries. Older strict
+readers reject these additive fields; use the matching candidate reader for
+unreleased formats. The candidate `probe --require-origin spec,adr,bug,incident`
+option selects declared kinds for a complete confirmed current-project probe.
+Repeat the option or use comma-separated kinds; partial, provisional, explicit
+historical and ignore-dirty combinations are refused. Failed policy exits 1
+even when baseline debt or a severity floor hides ordinary findings; unavailable
+current bindings exit 2. The command rechecks native runner/configuration
+membership, current claims, targets, defenders and discovery dependencies before
+publishing. Custom/static runner universes cannot certify this boundary. This is
+a declaration check, not authenticated independence or an atomic disk snapshot.
+Offline status recomputes a current-declaration audit using the recorded eligible
+selection, always marking native freshness unavailable without launching a
+runner. It does not implicitly activate a new gate or replace status's next
+action. Briefs preserve the recorded-run policy before caps and baseline
+filtering, explicitly not current freshness. A zero-item cap never turns
+survivors into an all-defended message.
+
 **v0.5.** Eleven commands (`status`, `init`, `claims`, `probe`, `admit`,
 `replay`, `baseline`, `brief`, `gate`, `scaffold`, `sweep`, `mcp`), vitest, jest,
 Playwright and Python (pytest / stdlib unittest) runners, hand-authored faults
@@ -1120,6 +1233,32 @@ the transfer of a calibration between repositories — `replay` measures it now;
 whether it carries to a repository with no history is unproven. Each is
 designed for; none is claimed.
 
+### Keeping developer machines responsive
+
+Built-in probe, sweep, replay and admission runners default to one worker. Use
+`--workers 2` for a larger Vitest/Jest/Playwright worker ceiling; `--serial` always
+uses one. Python remains serial. Faults and mixed-runner groups run sequentially.
+Custom `--runner-cmd` commands, browser subprocesses, native library threads and
+test-created processes are not an OS resource sandbox. The regression suite also
+caps outer workers at two, or one when fewer than three CPUs are available
+in an interactive run; dedicated CI uses at most two because its acceptance tests start nested runners.
+
+`--budget` bounds each runner invocation; `--command-budget` bounds a complete
+command cooperatively and refuses partial result publication. Cancellation kills
+owned runners before restoring mutations and removing scratch worktrees. Already
+reparented daemons remain outside the portable cleanup guarantee. No runner output
+limit can count as an assertion failure or detection.
+
+New probe evidence includes actual elapsed time, unique fresh runner time and
+setup/discovery/other overhead. `probe --cost` and `claims --cost` display this
+separately from historical attributed record costs. Existing cost ceilings are
+unchanged; old evidence does not supply a measured breakdown.
+
+Playwright confirmations run the same project-resolved CLI used for discovery,
+avoiding an npm subprocess per run. Python projects whose configuration requires
+pytest-xdist must support serial execution; an incompatible configuration remains
+unproven rather than bypassing the worker policy.
+
 ## Licence
 
 MIT.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testguard-cli",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Breaks your code on purpose and reports every promise your tests did not notice breaking. Mutation testing bound to the claims a project makes — vitest, jest, Playwright, pytest and unittest.",
   "type": "module",
   "license": "MIT",

package/spec/GATE-SEMANTICS.md

@@ -1,5 +1,108 @@
 # Gate semantics
 
+## Declared claim origins
+
+Status rechecks every recorded automatic-discovery dependency hash, including
+negative candidate tests, barrels and resolver configuration. Edited, deleted,
+unreadable or non-regular/escaping inputs make the evidence stale without
+rewriting its verdicts. Legacy omission remains readable but does not establish
+a complete origin-policy freshness binding. Rechecking recorded dependencies
+alone does not detect a newly added test/configuration: native test-universe
+recomputation remains required before origin-policy activation.
+
+Canonical and recorded claim sources share the closed kinds `spec`, `adr`,
+`annotation`, `comment`, `manual`, `doc`, `bug`, `incident`, `review`, `inferred`.
+These are declarations, not authentication of independence, chronology,
+production occurrence or correctness. The optional reference remains opaque
+metadata (at most 512 characters); verification does not fetch it. Producer
+provenance and measured test independence are separate signals.
+Adding kinds does not change verdicts, baseline/fingerprint identity or default
+gates. Existing ranking weights stay unchanged; new kinds use the existing 0.9
+fallback, not an invented strength hierarchy. Existing documents remain valid
+under the candidate reader; older closed-schema readers reject new kinds.
+Optional `origins` summaries on evidence, status and brief have closed kind
+buckets and safe nonnegative integer counts. Distinct claim buckets plus
+`mixed` equal the claim total; record buckets equal the record total. Status
+uses `basis: declared`, omits records, has zero mixed claims and binds its
+total to current `counts.claims`, even when evidence is stale. Evidence and
+brief use `basis: recorded` and require record counts. Evidence validation
+recomputes from every actual record regardless of verdict: each claim ID
+counts once, with conflicting source kind OR reference counted as one mixed
+claim. Object-key order is not a conflict; absent and empty references differ.
+Brief totals bind to the complete summary, not its capped/filtered items.
+Status and brief omit the source projections needed to independently validate
+their kind split; arithmetic validity is not source authentication. Legacy
+documents without summaries remain valid; old closed readers reject them.
+Status supplies current declared origins once validated claims are available,
+including empty, unprobed, invalid-anchor and stale-evidence states. Probe
+evidence and evidence-backed briefs supply recorded origins from all records,
+including killed and non-killed records, before caps or baseline/floor filtering.
+Human status/probe/brief text and Markdown label the basis and print "declared
+origins, not authenticated independence". Evidence-free briefs and projects
+without a claims file omit the summary rather than inventing declarations.
+Probe JSON retains status's current declared basis; saved evidence has its own
+recorded basis. These informational fields do not change states, next actions,
+exit codes, fingerprints or default gates. Opt-in origin policy remains pending.
+
+## Explicit annotation authoring
+
+Ordinary `claims` reports a separate `annotationAdvisory` with distinct sorted
+`missingIds` and informational `notes`; status uses its existing informational
+`notes`. Missing links reduce discoverability and annotation reconciliation,
+not exact-anchor validation. Advice supplies `testguard claims --annotate` for
+read-only preview; it never changes state, next verification action, verdicts,
+source kinds or exit codes. Annotation-sourced missing IDs still retain the
+existing claims drift error. Scanned occurrences are lexical links, not proof
+of intent, source ownership or authenticated provenance.
+Status advisory scanning is bounded to 10,000 directory entries, 1,000 files,
+64 directory levels, 256 KiB per file and 2 MiB total read bytes. Read failures,
+unsafe file identities or limits produce unavailable advice, never a claim
+that an ID is absent from an incomplete scan. Verification state/next still
+comes from its existing inputs. For custom claims, preserve the original
+`--claims` argument when following the preview suggestion.
+Scanner and placement ID prefixes use mandatory separators between repeated
+alphanumeric groups, avoiding overlapping quantifiers on tokens lacking a
+hyphen without changing the supported identifier vocabulary.
+
+`claims --annotate` previews file-header placement without writes. Add `--apply`
+to explicitly apply a newly computed plan; a previous invocation's preview is
+not a saved approval token. Repeated/comma-separated `--claim` selects IDs;
+unknown or empty IDs are usage errors, never an implicit all-claims selection.
+Authoring flags are valid only on `claims`; `--apply` requires `--annotate`.
+Authoring rejects unrelated inspection/output switches and writes results only
+to stdout. It never updates claims metadata, evidence or baselines.
+
+The closed `annotations` document describes authoring, not verification. It
+contains selected IDs, admitted target/action summaries, refusals and, for
+apply, touched/verified/unchanged files and explicit failure/recovery details.
+It excludes source/proposed contents, inode identities, hashes and absolute
+source/root paths. Preview exits 0 when applicable, 2 when refused. Apply exits
+0 only for a fully verified apply (including idempotent no-op), 2 for refusal or
+partial failure. Invalid invocation exits 3. No authoring result changes probe
+verdicts, rank, coverage, source-kind declarations or authentication of intent.
+Failure reasons are stage-specific public summaries: raw syscall details can
+contain absolute input paths and remain private, never passed through to JSON.
+
+Placement supports JavaScript/TypeScript and Python file-level line-comment
+headers, not symbol ownership. Exact anchors remain checked without annotations.
+Every selected target must pass conservative path, regular-file, UTF-8/newline,
+anchor and size admission: 2 MiB per original/proposed file and 16 MiB aggregate
+charged before reads plus proposal growth. Any refusal blocks all writes.
+Preserve BOM, shebang, Python encoding cookies, newline style, inode and mode.
+Only leading line-comment headers are placement witnesses, not string contents.
+
+Apply reloads actual claims under an exclusive owned lock, replays all targets,
+and fsyncs owner-only originals/manifest outside the canonical project before
+writing. Recheck claims and targets immediately before each non-truncating
+descriptor write; verify output, distinguish potentially touched from verified
+files, and retain private recovery on partial failure. Reject the actual claims
+file as a target, root/descendant symlinks and recovery inside the checkout.
+Resolve parent aliases to bind the actual root. Never reclaim another writer's
+lock or automatically roll back over an editor's changes. Stage and fsync the
+final recovery journal before final naming. This is recoverable, not atomic:
+arbitrary same-inode editors and process/power failure can race or interrupt
+writes; directory durability across power loss is not guaranteed.
+
 ## Fault-specific defender selection
 
 A fault's `defendedBy`, when present, overrides its claim's declaration.
@@ -108,6 +211,17 @@ Rules that follow from the table:
    the fault is probed again: the cost of re-measuring is a run, the cost of
    the other direction is a verdict nobody measured.
 
+   **Claim metadata is also an input to reuse.** The recorded claim id,
+   statement, severity, source (including its reference), and optional
+   producer must match the current claim. Object-key order is not a change;
+   field values and producer presence are. Metadata edits make `status`
+   stale and require a fresh probe, even when the fault and defender inputs
+   are identical. A reused record must never be silently relabelled as a
+   different requirement or origin. Legacy records remain readable; missing
+   metadata cannot establish equality with a current declaration. This
+   does not change verdicts or baseline fingerprints, and a source label
+   still does not authenticate independent intent.
+
 9. **The fault must be the code that ran.** A green baseline proves the
    harness is not reporting everything as broken. It proves nothing about the
    opposite direction: a fault the interpreter never executes leaves the
@@ -467,6 +581,69 @@ Security- and money-shaped path names are explicit tie-breaking signals, never
 semantic claims about a file. Churn, path risk and claim coverage remain raw
 facts: they are never collapsed into one health score.
 
+### Intent-first scaffold authoring
+
+Unannotated generated draft groups use unfinished `TODO-CLAIM-N` identifiers,
+not file/function-shaped names. Allocation is deterministic in scan order and
+reserves explicit annotations and supplied existing IDs before choosing ordinals.
+It never copies unrelated existing metadata into a generated placeholder. Explicit
+claim IDs/annotations retain their existing behavior; neither annotations nor
+placeholder IDs authenticate intent. Grouping remains mechanical candidate
+organization, not invariant ownership. Sweep's pooled allocator keeps repeated
+per-file placeholders distinct without changing fault content. Existing claims
+and recorded evidence are not renamed. The claims schema/validator is unchanged:
+these are valid draft IDs and still require supplied intent and review/probing.
+
+Explicit `scaffold <source...> --into <existing-draft.json> --claim <ID>` appends
+mechanically derived faults only to that existing selected claim. Preview JSON
+is a conforming claims document (the existing claims schema and validator), not
+verification evidence. `--json` creates no files, locks or recovery. Without it,
+only the explicitly selected disposable draft is updated; unchanged repeats
+preserve exact bytes/mtime. Supplied statements/origins/metadata and existing
+faults/sibling claims remain intact. Review and probe are still required.
+
+`--into` is scaffold-only, singular and requires one nonempty existing claim ID
+and at least one source. Repeated/comma selections, `--out`, `--claims` and any
+explicit unrelated option refuse with usage exit 3 before reading/writing.
+Help/version retain their normal early-exit behavior. Ordinary scaffold remains
+one-file; annotation `--apply` retains its separate claims-only meaning.
+
+Refuse canonical `testguard.claims.json` names and built-in evidence/baseline
+destinations, unsafe aliases/symlinks/hardlinks/nested projects and nonregular
+inputs. Admission limits are 32 sources, 2 MiB per source/draft, 16 MiB aggregate
+source bytes, 4096 generated proposals and 2 MiB serialized output. Caps refuse,
+never truncate proposals. These are not whole-command performance guarantees.
+
+Changed drafts require a cooperative owned exclusive lock, current input replay,
+external private original/started/result recovery journals, nofollow descriptor
+publication through `writeSpecDoc`, short-write handling, fsync and exact
+byte/schema/path/source verification. Refusal, stale inputs, partial writes,
+verification or cleanup/journal failure exit 2, report recovery when available,
+and never print updated success. No automatic rollback, stale-lock reclamation,
+atomic multi-file snapshot or power-loss transaction is promised. Exit 0 means
+authoring completed, not defended coverage. Private recovery is not evidence.
+
+Sweep pools per-file drafts before selection. Repeated claim IDs from equal
+basenames/functions or annotations do not merge unrelated claims: reserve all
+original IDs, then allocate unused numeric suffixes to collisions in full
+target-path/original-ID order, within the existing 128-character limit. Metadata,
+fault IDs, injection anchors and defenders are preserved. Drafts, selected probe
+claims and finding lookup share these identities. This affects fresh collision
+cases only; existing documents, verdicts, caps and exit rules remain compatible.
+
+Scaffold's mechanically generated new claims declare `source.kind: inferred`,
+including proposals grouped by an annotation. Their TODO asks for intended
+observable behavior from a requirement, ADR, bug or incident: inputs, expected
+outcome and forbidden outcome. Existing supplied claim metadata retains its
+statement and declared origin under the existing `--claim` rules. Derived fault
+provenance remains derived. No automatic source promotion or canonical write.
+
+Human CLI, status authoring actions and the installed skill hand off independent
+intent authoring. Record a supplied source kind/ref; when unavailable keep
+inferred. References and annotations do not authenticate intent and are never
+fetched. Passing tests do not establish independent intent. State, next action,
+verdict and exit-code semantics are unchanged; this is authoring guidance.
+
 When existing evidence is clean but more source modules are unclaimed than
 claimed, the next action is to scaffold the highest-churn unclaimed module.
 Earlier correctness states still win: invalid anchors, stale evidence and
@@ -580,6 +757,48 @@ evidence; they simply do not turn CI red.
 
 ## Exit codes
 
+### Explicit declared-origin policy result contract
+
+Optional `originPolicy` on evidence, status and brief (and status's probe `run`)
+records an explicitly selected eligible-kind set, not authenticated independence.
+Legacy absence is not a pass. `probe --require-origin <kinds>` selects a
+repeatable comma-separated nonempty set from the closed source vocabulary.
+It requires a complete current-project run with confirm >= 3 and refuses
+`--claim`, `--allow-empty`, explicit `--ref` and `--ignore-dirty` as usage errors
+before loading or writing. No policy is inferred when the option is absent.
+After measurement, the command reloads current claims and collects the current
+native runner universe under the same command budget, then binds targets,
+resolved defenders and current discovery dependencies. Missing bindings or
+discovery failure yields unavailable; custom/static runner universes cannot
+certify this boundary. Expired command budgets still write no partial result.
+This is point-in-time admission, not an atomic filesystem snapshot. Stored
+results are not freshness authority. Offline status reuses only the recorded
+eligible-kind selection, recomputes current declarations/complete identities,
+and marks freshness unavailable without executing native discovery. This is
+an audit projection, not implicit activation of a new gate: the existing
+status state, next action and exit remain unchanged. Briefs preserve the
+recorded policy before baseline filtering or item caps, labeled recorded-run
+only and not current freshness. No absent policy is synthesized. A zero-item
+cap cannot turn unproven faults into an all-defended message.
+
+The closed result carries `state` (`passed`, `failed`, `unavailable`), sorted
+unique `eligibleKinds`, current `claims`/`faults` denominators, sorted unique
+`ineligibleClaims`, unique `nonKilledFaults` (`claimId`, `faultId` only), and
+sorted unique `unavailableReasons`. References and paths are excluded.
+Refusal reasons require unavailable; otherwise any ineligible claim or
+non-killed fault requires failed. Only a nonempty failure-free universe can
+pass. Baseline debt and severity floors cannot suppress policy failures.
+
+Evidence validation binds actual non-killed identities, and, for an available
+policy, unique recorded denominators, recorded eligibility, unmixed origins and
+confirmed injection. Validation cannot authenticate current metadata or disk
+freshness: evaluation must separately bind the complete current fault universe
+and existing input freshness. Projected status/brief bind denominators, not
+hidden source declarations. Brief policy describes its recorded run only.
+Completed probe JSON with unavailable policy exits 2; failed policy or ordinary
+new findings exits 1; passed policy without ordinary findings exits 0.
+Partial/provisional invocations cannot carry an origin policy.
+
 | Code | Meaning |
 |---|---|
 | `0` | No new gating findings at or above the severity floor. |
@@ -598,3 +817,79 @@ output is the existing `no-claims` status document, without run metadata;
 it never reports a clean measurement. Missing or invalid claims still fail,
 and selected claims cannot be silently skipped. Run `gate` separately to
 enforce coverage of changed files during adoption. Integrations must opt in.
+
+## Read-only authoring input (candidate)
+
+`authoring-input` is metadata-only inspection, never claims or evidence. Its
+closed purpose/verification/next fields explicitly state that verification was
+not performed and independent intent remains to be supplied. Documents expose
+only bounded project-relative file/hash/byte metadata, not text or absolute
+roots. A digest or schema-valid report does not authenticate intent or freshness.
+
+Fix inputs retain exact same-width commit/parent/path identities, untrusted
+single-line subjects, selected root/nested scope and full partition accounting.
+Visible rows exclude private/delegated names; their count stays in the total.
+Deleted and unsupported rows cannot become supported source. Validators reject
+duplicate/unsafe/private paths, inconsistent status/mode/zero-ID relations,
+disposition/count mismatches, unsafe subjects and resource overruns. Empty
+documents/inventories are admitted input metadata, not successful verification.
+Readers cannot infer actual history completeness or current input admission
+from shape alone; the runtime must use admitted local inputs without promotion.
+
+`scaffold --from-document <local-text-path>` or `--from-fix <full-commit-ID>`
+selects exactly one read-only authoring input. Both token dispatch and direct
+handler entry reject repetition, mixed modes, positional sources and unrelated
+explicit options (only JSON/help/version may accompany selection). Normal
+help/version early exits remain unchanged. Usage refusal exits 3; input admission
+or validated planning failure exits 2 with no success stdout. Success exits 0
+for inspection only, never coverage. Both JSON and human modes are stdout-only.
+JSON uses the validated metadata-only report; human rendering omits text,
+subjects, absolute roots and historical filenames while retaining full fix
+partition counts. Both name verification as not performed and require supplied
+independent intent before reviewing/probing faults. One elapsed budget covers
+input reads and validated serialization; scope resolution never retries with
+fresh time. Existing ordinary scaffold/append/probe behavior is unchanged.
+
+## Resource controls and measurement
+
+Built-in runners default to one worker. `--workers N` raises the worker ceiling
+for Vitest, Jest and Playwright; `--serial` overrides it to one. Python remains
+serial and disables pytest-xdist without installing or enabling any plugin.
+Faults and mixed-runner partitions remain sequential. This is a worker ceiling,
+not OS CPU/memory containment; test-created threads, native libraries and custom
+`--runner-cmd` commands manage their own concurrency. Native discovery is bounded
+and uses one worker where applicable.
+
+Runner stdout is drained without retention; stderr retains only its last 65,536
+characters. Complete JSON reports are read under the existing 16 MiB discovery
+report admission limit. An oversized, unreadable or incomplete report is an error,
+never an assertion kill. No confirmation count or verdict rule changes.
+
+Cancellation terminates only registered children and their attributable process
+trees, waits up to one second for close, restores live mutations and removes the
+registered scratch worktrees. It exits 130 without publishing partial evidence.
+Reparented daemons remain outside the portable containment guarantee. Git
+subprocesses have a 30-second hard deadline; the whole-command budget remains
+cooperative around synchronous setup, and bounded OS cleanup can outlive it.
+
+Optional `run.measurements` records monotonic elapsed time, fresh runner execution
+time, invocation count and remaining setup/discovery/other overhead. Each real
+runner invocation is charged once, including negative controls and mixed-runner
+partitions; reused records and cached baselines create no invocation charge.
+`elapsedMs = runnerMs + overheadMs`. Optional `run.workers` records the built-in
+worker ceiling and must be one for serial execution; custom commands omit it.
+Native evidence reuse requires the same recorded worker ceiling and serial policy.
+Older native evidence with no worker ceiling is remeasured; native and opaque
+custom-command policies are not interchangeable.
+`status.cost.measurements` copies these measurements when available. Historical
+`totalMs` and cost gates retain their existing record attribution, including
+reused durations and repeated shared baseline durations. Older evidence has no
+measured breakdown; consumers must not infer it from record totals.
+
+The existing Python interpreter cache is reset at probe and replay entry and
+reused within that invocation. Uncached adapter resolution consumes the same
+live per-run deadline as test execution.
+
+The regression suite caps outer concurrency at two workers in CI. Interactive
+runs reserve one available CPU and use at most two workers; a two-core machine
+therefore uses one. Nested built-in runners retain their one-worker default.