changeledger 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "changeledger",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Turn conversations into buildable changes.",
   "type": "module",
   "bin": {

package/src/commands/context.mjs

@@ -7,9 +7,9 @@ import { resolveChange } from '../repo.mjs';
 
 const MODES = ['implement', 'review', 'spec', 'release'];
 const MODE_CONTEXT = {
-  implement: ['implement', 'readiness'],
-  review: ['review'],
-  spec: ['spec', 'readiness'],
+  implement: ['implement', 'delegation', 'readiness', 'handoff'],
+  review: ['review', 'delegation', 'handoff'],
+  spec: ['spec', 'delegation', 'readiness'],
   release: ['release'],
 };
 const STATUS_CONTEXT = {
@@ -17,7 +17,7 @@ const STATUS_CONTEXT = {
   approved: { mode: 'implement', fragments: MODE_CONTEXT.implement },
   'in-progress': { mode: 'implement', fragments: MODE_CONTEXT.implement },
   'in-review': { mode: 'review', fragments: MODE_CONTEXT.review },
-  blocked: { mode: 'blocked', fragments: ['blocked'] },
+  blocked: { mode: 'blocked', fragments: ['blocked', 'handoff'] },
   'in-validation': { mode: 'validation', fragments: ['validation'] },
   done: { mode: 'close', fragments: ['close'] },
   discarded: { mode: 'discarded', fragments: ['discarded'] },

package/templates/contract/blocked.md

@@ -1,6 +1,12 @@
 # Blocked — Resolve Before Implementing
 
-Do not resume implementation merely because context was requested. Inspect the
-blocked task and Log. If the impediment is resolved within authorized scope,
-record the decision, restore the task and move `blocked → in-progress`. If it
-requires scope or product judgment, ask the human. Never bypass the block.
+Do not resume implementation merely because context was requested. A change can
+be blocked by a `[!]` blocked task, an external impediment or a review escalation.
+Inspect the relevant task when one exists and read the Log for the recorded
+reason.
+
+If the impediment is resolved within authorized scope, record the decision,
+restore or update the task when applicable and move `blocked → in-progress`. If
+resolution requires scope or product judgment, ask the human. After moving to
+`in-progress`, run `changeledger context <id>` before modifying implementation.
+Never bypass the block.

package/templates/contract/close.md

@@ -1,18 +1,42 @@
 # Closing Accepted Work
 
-The human accepted this change. Graduate persistent truth before archiving:
+The human accepted this change. Resolve persistent truth before archiving.
+Changes describe a journey; `.changeledger/specs/*.md` describe the current
+capability, architecture or domain truth that code reflects.
 
-- `changeledger graduate <id> <spec-slug>` creates a new spec.
+Specs have no lifecycle or `status`. They use minimal frontmatter and free
+Markdown:
+
+```yaml
+---
+title: Short title
+updated: 2026-06-30T10:00:00Z
+tags: []
+---
+```
+
+Choose one graduation outcome:
+
+- `changeledger graduate <id> <spec-slug>` creates a new spec seeded from the
+  change's Specification and Proposal; refine its wording manually.
 - `changeledger graduate <id> <spec-slug> --into` links an existing spec and
   refreshes `updated` without overwriting the spec body (the agent edits the body manually).
 - `changeledger graduate <id> --skip [reason]` records that no persistent truth
   changed.
-- `changeledger graduate --pending` lists unresolved graduation decisions.
-- `changeledger archive <id>` hides the completed record from the default board.
+- `changeledger graduate --pending` lists accepted changes whose decision is
+  unresolved.
+
+Graduation and skip both set `reviewed: true` on the change: it means the
+persistent-truth question was settled, not necessarily that a spec was created.
+The graduation link remains derivable from the Log marker `graduado a spec`,
+which carries the spec link, rather than from the boolean flag.
+
+Operational inspection and visibility:
 
-Specs have no lifecycle: minimal frontmatter (`title`, `updated`, `tags`) plus
-free Markdown describing current capabilities, architecture or domain truth.
-The change is the journey; the spec is the destination.
+- `changeledger list [--status S] [--type T] [--json]`
+- `changeledger show <id> [--json]`
+- `changeledger archive <id>` / `changeledger unarchive <id>`
 
-After closure, share a brief retrospective. New work needs a new authorized
+Use Mermaid where it communicates persistent relationships better than prose.
+After closure, share a brief retrospective. New work needs a newly authorized
 change; `done` never reopens.

package/templates/contract/core.md

@@ -36,6 +36,18 @@ done directly. If unsure, document it in ChangeLedger.
 
 Humans consume changes in `changeledger view`; write for the rendered view.
 
+## Files and delegation
+
+Files are the source of truth and may be edited directly. CLI helpers are
+optional and preferred for error-prone operations such as timestamps, lifecycle
+transitions and task markers.
+
+Delegate only with a clear boundary and benefit. Each delegation prompt states
+ownership, expected output and integration criterion; coding agents must know
+they share the codebase and must not revert others' work. Do not over-shard or
+overlap write surfaces without an explicit integration plan. Size the model to
+the task's difficulty and risk.
+
 ## Lifecycle
 
 ```text
@@ -58,9 +70,11 @@ in-validation → in-progress                       [human rejection]
 - `discarded`: terminal tombstone; never reopen it.
 
 `changeledger status <id> <status>` enforces agent-owned transitions and does not accept `done` or `discarded`.
-Humans approve and validate in the viewer; use
-`changeledger discard <id> "<reason>"` for a discarded change. `done` and `discarded`
-never reopen.
+The viewer owns `draft → approved` and `in-validation → done|in-progress`; the
+agent performs the other non-terminal moves. Use
+`changeledger discard <id> "<reason>"`: the discard reason is required and
+logged, and dependencies remain resolvable. `done` and `discarded` never reopen;
+later reconsideration needs a newly authorized change.
 
 ## Context modes
 

package/templates/contract/delegation.md

@@ -0,0 +1,56 @@
+# Economical Delegation
+
+ChangeLedger is agnostic to how work is executed. Delegate when it reduces main
+context pressure, lowers cost with a sufficient model, parallelizes genuinely
+independent work or supplies independent verification. Do not delegate when the
+coordination costs more than the expected improvement in quality, speed or
+context control.
+
+## Delegate a real boundary
+
+A good delegation unit is a question, module, package, test area, migration
+slice or independent verification. The boundary must state what the delegate
+owns, what it returns and how the result integrates.
+
+- Request and Investigation may split independent codebase questions across
+  explorers.
+- Proposal and Specification may use stronger reasoning when ambiguity,
+  architecture, safety or product judgment is high.
+- Implementation may split only when write sets are disjoint and integration is
+  obvious.
+- Verification may be delegated when it catches risk without merely repeating
+  the implementer's work.
+- Configured review is special: a fresh clean-context subagent is a correctness
+  requirement, not an optimization.
+
+## Do not over-shard
+
+Do not create one subagent per file, line or tiny mechanical edit. For the same
+small change across many files, prefer one scoped delegate, a batch edit or a
+script verified by the main agent. Do not run parallel agents over the same
+files or conceptual surface unless overlap and integration are explicit.
+
+If you cannot state why the task is independent, what output you expect and how
+you will integrate it, keep the work in the main thread or regroup it.
+
+## Size the model to the work
+
+Use the strongest available models for ambiguous scope, architecture,
+security-sensitive reasoning and difficult reviews. Use sufficient cheaper
+models for inventories, localized exploration, mechanical edits and narrow
+checks. Escalate when uncertainty or risk rises; de-escalate when the work is
+well specified and mostly execution.
+
+## Delegation prompt contract
+
+Every prompt states:
+
+- why the work is delegated;
+- the owned files, area or investigation question;
+- the expected output;
+- the difficulty or risk that informed model choice;
+- the integration criterion.
+
+Tell coding delegates they share the codebase: stay inside assigned ownership,
+do not revert others' edits and report overlapping changes instead of silently
+resolving them.

package/templates/contract/handoff.md

@@ -0,0 +1,22 @@
+# Handoff Triage
+
+## Triage friction at handoff; retrospect after completion
+
+Before handing completed or blocked work to the human, classify friction and
+unfinished observations instead of silently mixing them into the active change:
+
+- If necessary to fulfill the purpose of an active change, update its
+  Specification, Plan and Log; this is not a new concern.
+- If it is an operational step such as verify, commit, graduate, archive or
+  close, execute or record it in the current flow.
+- If independent, too large or materially broader, keep it outside the active
+  change; propose its type, title, and reason to the human.
+  Create the draft only after explicit authorization; batch related proposals
+  when practical.
+- If too vague for backlog, mention it in the handoff without
+  creating a file.
+
+Do not mix independent concerns into active work or block otherwise-ready human
+validation. When a change reaches `done`, also share a brief retrospective about
+what went well and what caused friction. `discarded` records a decision, not a
+completed implementation cycle.

package/templates/contract/implement.md

@@ -1,52 +1,68 @@
 # Implementing an Approved Change
 
-1. Keep one concern per change. Work necessary for the authorized objective may
-   update Specification, Plan and Log. If related work materially expands observable scope, obtain explicit human
-   authorization before adding it; propose independent work separately.
-2. Never implement approved changes on `main`, `master`, or `dev`. Inspect the
-   worktree first. If unrelated changes exist, do not include them silently.
-3. Commit the approved change documentation before touching implementation code.
-   Implement one change at a time.
-4. Commit a completed unit before continuing when another task or shared edit makes attribution
-   ambiguous. Commit messages reference the id. If shared files make a combined commit
-   unavoidable, record it explicitly and name every change sharing the surface.
-5. Keep the change current with `changeledger task`, `changeledger log`,
-   `changeledger owner` and `changeledger status`.
-6. Follow the Specification exactly. Write a failing test from each criterion,
-   make it pass, then refactor. Do not silently drift the document.
-7. Leave no TODO/FIXME, dead code or unrelated residue without explicit agreement.
-8. When implementation and tasks are complete, move to `in-review` if the type
-   requires independent review; otherwise move to `in-validation` and stop.
+## Scope and truth
 
-## Correction isolation
+Keep one concern per change. Work necessary for the authorized objective belongs
+in its Specification, Plan and Log. If related work materially expands observable scope, obtain explicit human
+authorization before adding it; propose independent work separately.
 
-After review `fail --retry`, keep the candidate correction uncommitted while a
-fresh clean-context reviewer checks it. If it fails again, iterate on that diff.
-After `pass`, commit the confirmed correction and ledger truth before asking for
-human validation.
+Follow the Specification exactly. If code and document diverge, update code;
+never quietly drift the approved contract. Keep status, tasks, owner and Log
+current throughout execution.
+
+## Git protects traceability
 
-After human rejection (`in-validation → in-progress`), keep the correction
-uncommitted until the human confirms it. Do not start another task or change
-while a correction waits; the worktree is the isolation boundary.
+Never implement approved changes on `main`, `master`, or `dev`; create or switch
+to a work branch or ask the human before continuing. Inspect the worktree first. If
+unrelated changes exist, do not include them silently; ask the human whether to
+stash, commit, ignore or include them before changing the worktree.
 
-## Triage friction at handoff; retrospect after completion
+Commit the approved change documentation before touching implementation code.
+Implement one change at a time. Commit a completed unit before continuing when
+another task, change or edit of the same surface could make attribution
+ambiguous; do not wait until the end to reconstruct mixed diffs.
 
-Before handing the human completed or blocked work, classify discovered
-friction:
+Commit messages use the canonical shape:
 
-- If necessary to fulfill the purpose of an active change, update that change.
-- If it is an operational step such as verify, commit, graduate or archive,
-  execute or record it in the current flow.
-- If independent or materially larger, propose its type, title, and reason to
-  the human. Create the draft only after explicit authorization.
-- If too vague for backlog, mention it without creating a file.
+```text
+feat(scope): description [#20260629-234939]
+```
 
-When a change reaches `done`, also share a brief retrospective with the human.
+Use the actual change id and the appropriate conventional type. If shared files make a combined commit
+unavoidable, record it in Log or the handoff and name every change sharing the
+surface.
 
-## Useful commands
+## Execute the Plan
+
+Write the failing test from each criterion, make it pass, then refactor. Tick
+tasks as they become true, not in a batch at the end. Leave no TODO/FIXME, dead
+code or unrelated residue without explicit agreement.
+
+Useful mutation commands:
 
 - `changeledger status <id> <status>`
 - `changeledger task <id> done|block <n> [reason]`
 - `changeledger log <id> "<message>"`
 - `changeledger owner <id> <name|->`
 - `changeledger check [id]`
+
+When implementation and every task are complete, move to `in-review` if the
+type requires independent review; otherwise move to `in-validation` and stop.
+
+## Correction isolation
+
+After review `fail --retry`, keep the candidate correction uncommitted while a
+fresh clean-context reviewer checks it. If it fails again, iterate on that same
+diff. Do not start another task or change while a correction waits: the
+worktree is its isolation boundary. After `pass`, commit the confirmed correction
+with its related ledger truth before asking for human validation.
+
+After human rejection (`in-validation → in-progress`), run
+`changeledger context <id>` before modifying implementation; keep the correction
+uncommitted until the human confirms it fixes the reported failure. Do not start
+another task or change while a correction waits; iterate on
+the same diff if it does not. After human acceptance, graduate or record a skip,
+then commit the correction with its ledger truth.
+
+These exceptions prevent false fix attempts from becoming permanent history;
+they do not relax intermediate commits for already verified units.

package/templates/contract/readiness.md

@@ -1,19 +1,42 @@
 # Definition of Ready
 
-With `tdd: true`, an approved change is ready only when:
+ChangeLedger supports a deliberate split: a strong model documents and a less
+capable but able model implements. The approved change must contain enough
+precision that implementation does not redefine what should be tested.
 
-1. Every behavioral requirement is a concrete `CRn` with actual inputs, exact
-   outputs/effects and literal errors. Edge cases get separate criteria.
-2. Every implementation task names target file(s)/area(s), verification, and the
-   criteria it satisfies. It is sized to one red-green cycle.
-3. TDD is explicit: write the failing test from the criterion, make it pass, then
-   refactor. The implementer chooses how, not what, to test.
+The `tdd` flag in `.changeledger/config.yml` defaults to `true`; set `tdd` to
+`false` only for exploratory repos where behavior is intentionally still being
+discovered.
 
-Repos may configure `readiness.target_patterns` and
-`readiness.verification_patterns`. For manual checks, prefer a structural rule
-such as `verification_patterns: ["verify:"]`, then write evidence like
-`verify: manual Android device check` instead of listing every possible manual phrase.
+With `tdd: true`, a change is ready only when:
+
+1. **Specification is test-grade.** Every behavioral requirement is a `CRn`
+   with actual inputs rather than “a valid input”, exact outputs/effects and
+   literal error messages. Give every edge case its own criterion. Nothing that
+   must hold may live only in prose.
+2. **Plan is the implementation contract.** Every implementation task cites at
+   least one CR, names target file(s)/area(s) and contains concrete verification
+   in its description before the final `(CRn)` block. Size it to one red-green
+   cycle.
+3. **TDD is explicit.** Write the failing test from the criterion, make it pass,
+   then refactor. The implementer chooses how to test, not what behavior to
+   prove.
+
+Verification may be a colocated test, conventional test directory, concrete
+command or manual `verify:` clause. Examples:
+
+```markdown
+- [ ] Update `src/parser.mjs`; verify: `node --test test/parser.test.mjs` (CR1)
+- [ ] Update Android rendering; verify: manual Android device check (CR2)
+```
+
+Repos tune recognition with `readiness.target_patterns` and
+`readiness.verification_patterns`. For device/manual checks, prefer the stable
+structural convention `verification_patterns: ["verify:"]`; put the actual
+evidence in the task instead of listing every possible manual phrase in config.
 
 `changeledger check` reports missing Given/When/Then, uncovered or unknown CRs,
-tasks without traceability, and CR-bearing tasks without a configured target and
-verification (`draft` warnings; approved/in-progress errors).
+tasks without traceability and CR-bearing tasks without configured target and
+verification. Gaps are warnings in `draft` and errors in `approved` or
+`in-progress`. Truly operational `(support)` tasks are exempt; observable
+implementation is not.

package/templates/contract/release.md

@@ -7,6 +7,10 @@
 - `changeledger release record <version>` records exactly that plan in
   `.changeledger/releases/<version>.yml`.
 
+`changeledger release plan --json` is the handoff contract for the operating
+agent: consume that exact machine-readable membership and version when applying
+stack-specific release steps.
+
 Defaults live under `release.impacts` in `.changeledger/config.yml`; a change may
 override its type with `release_impact` (`none|patch|minor|major`).
 

package/templates/contract/review.md

@@ -1,19 +1,30 @@
 # Independent Review
 
 Review-required work must be checked by a fresh subagent with clean context and
-a model sized to the difficulty. Independence is correctness, not an
-optimization. The reviewer verifies every criterion, every Plan task, tests,
-the actual diff and absence of residue; it does not trust the implementer's
-summary.
+a model sized to the review difficulty. Independence is correctness, not an
+optimization; do not trust the implementer's summary.
 
-Delegate for a clear reason and boundary. Do not over-shard by file or tiny edit,
-and do not overlap write surfaces without an explicit integration plan.
+Inspect the selected change, every `CRn`, every Plan task, tests, the actual diff
+and absence of TODO/FIXME, dead code or unrelated residue. Confirm tasks are
+true rather than merely checked off and that implementation did not drift from
+the approved document.
 
-- Pass: `changeledger review <id> pass` → `in-validation`.
-- Fixable defect: `changeledger review <id> fail --retry "<reason>"` →
-  `in-progress`.
-- Scope/decision escalation: `changeledger review <id> fail --block "<reason>"`
-  → `blocked` for the human.
+Deep security, SAST and lint belong to dedicated tools. The reviewer may run
+them and record their evidence; ChangeLedger does not reimplement them.
 
-After a retry, the correction stays uncommitted until another clean reviewer
-passes it. Then commit correction + ledger before asking for human validation.
+Record exactly one verdict:
+
+- `changeledger review <id> pass` — criteria and Plan pass; move to
+  `in-validation`.
+- `changeledger review <id> fail --retry "<reason>"` — fixable defect inside the
+  authorized contract; return to `in-progress`.
+- `changeledger review <id> fail --block "<reason>"` — correction requires scope
+  or product judgment; move to `blocked` for the human.
+
+After `fail --retry`, the correction remains uncommitted until another fresh
+reviewer passes it. After the transition, run `changeledger context <id>` before
+modifying implementation. After pass, commit correction + ledger before asking
+for human validation.
+
+Types without `review_required` move directly from `in-progress` to
+`in-validation`; do not invent a review gate for them.

package/templates/contract/spec.md

@@ -1,6 +1,6 @@
 # Authoring a Change
 
-## Repository layout
+## Repository layout and creation
 
 ```text
 .changeledger/
@@ -11,42 +11,65 @@ AGENTS.md
 CLAUDE.md  # optional
 ```
 
-The project-owned `AGENTS.md` contains the ChangeLedger bootstrap. Run
-`changeledger context` before acting; no per-machine contract link is required.
+The project-owned `AGENTS.md` contains the bootstrap. Run `changeledger context`
+before acting. Create a change with:
+
+```text
+changeledger new <type> <slug> "<title>"
+```
+
+The CLI generates the UTC id, filename and active stages. The slug is structural
+and must be English; title and narrative follow the configured language. Files
+remain the source of truth and may be edited directly, but prefer the CLI for
+timestamps, enums and markers that are easy to mistype.
+
+One concern per change. If a request mixes unrelated concerns, propose separate
+changes and create them only after explicit human authorization. Work necessary
+for an already authorized objective stays in that change's Specification, Plan
+and Log. If related work materially expands observable scope, obtain explicit
+human authorization; independent work belongs in a separate change.
 
 ## Change document
 
-A change is one Markdown file with YAML frontmatter and fixed English stage
-headings. Required frontmatter:
+A change is one Markdown file: YAML frontmatter plus fixed English stage
+headings. Required and optional frontmatter:
 
 ```yaml
 ---
 id: "20260613-134548"
 title: Short, clear title
-type: feature
-status: draft
-created: 2026-06-13T13:45:48Z
-depends_on: []
-owner: ana             # optional
-release_impact: minor  # optional: none | patch | minor | major
+type: feature                  # feature | bug | audit | refactor | chore
+status: draft                  # lifecycle value
+created: 2026-06-13T13:45:48Z # full ISO 8601 UTC
+depends_on: []                 # change ids or external project:id refs
+owner: ana                     # optional
+release_impact: minor          # optional: none | patch | minor | major
 ---
 ```
 
-`owner` is assigned on `approved → in-progress` when absent, preferring the
-GitHub login and falling back to `git config user.name`.
+`owner` means responsibility for the change. On `approved → in-progress`, it is
+assigned when absent from the GitHub login (`gh api user --jq .login`), falling
+back to `git config user.name`. Override or clear it with
+`changeledger owner <id> <name|->`; absence means unassigned.
 
-Stages use this order:
+Keep each fact in one stage and link to it from the others. Do not let summaries
+or plans become competing versions of the same truth.
+
+## Stages
+
+Use fixed English `##` headings in this order and only when activated for the
+type in `config.yml`:
 
 | Key | Heading | Purpose |
 |---|---|---|
 | request | `## Request` | Ask, context and why |
-| investigation | `## Investigation` | Current state, evidence, constraints, risks |
-| proposal | `## Proposal` | Chosen solution and discarded alternatives |
-| specification | `## Specification` | Testable acceptance criteria |
-| plan | `## Plan` | Actionable checklist |
-| log | `## Log` | Chronological execution decisions |
+| investigation | `## Investigation` | Evidence, constraints and risks; root cause for bugs, core analysis for audits |
+| proposal | `## Proposal` | Chosen solution, discarded alternatives and scenarios |
+| specification | `## Specification` | Testable requirements and acceptance criteria |
+| plan | `## Plan` | Actionable task checklist |
+| log | `## Log` | Chronological decisions and execution changes |
 
-Use only the stages activated for the type in `config.yml`. Defaults are:
+Default activation matrix:
 
 | Type | request | investigation | proposal | specification | plan | log |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|
@@ -56,39 +79,83 @@ Use only the stages activated for the type in `config.yml`. Defaults are:
 | refactor | ✓ | — | ✓ | — | ✓ | ✓ |
 | chore | ✓ | — | — | — | ✓ | — |
 
+The configured matrix is authoritative. For bugs, Investigation contains the
+root cause; for audits, it is the core analysis. Proposal includes the chosen
+solution, discarded alternatives and scenarios.
+
+When a relationship, flow or architecture is clearer visually, use a Mermaid
+block and keep its text as the source; the viewer renders it.
+
 ## Acceptance criteria
 
-Each criterion is a separate `### CRn — name` block:
+Every behavioral requirement is a separate structured scenario:
 
 ```markdown
 ### CR1 — Short name
 - **Given** concrete precondition
 - **When** concrete action
 - **Then** exact result
-- **And** optional additional result
+- **And** optional additional step
 ```
 
-The heading, ids and Given/When/Then/And keywords are fixed English. Localized
-headings, inline criteria and `#### CR1` are not machine-readable.
+Use one `### CRn` block per scenario. Heading, ids and
+Given/When/Then/And keywords stay English; scenario content follows the repo
+language. Localized headings, translated keywords, inline criteria and
+`#### CR1` are not machine-readable.
+
+## Plan task grammar
 
-## Plan tasks
+Markers encode state and the final parenthesized block encodes traceability:
 
 ```markdown
-- [ ] Update `src/foo.mjs`; verify: `node --test test/foo.test.mjs` (CR1)
-- [x] Update `src/foo.mjs`; verify: `node --test test/foo.test.mjs` (CR1) — 2026-06-13T14:20:00Z
-- [!] Update `src/foo.mjs`; verify: `node --test test/foo.test.mjs` (CR1) — reason
-- [ ] Operational step with no observable behavior (support)
+- [ ] Update `src/app/foo.ts`; verify: `pnpm test` (CR1)
+- [x] Update `src/app/foo.ts`; verify: `pnpm test` (CR1) — 2026-06-13T14:20:00Z
+- [!] Update `src/app/foo.ts`; verify: `pnpm test` (CR1) — blocked reason
+- [ ] Run the complete test suite after implementation (support)
 ```
 
-The final `(CRn)` block provides traceability. Put target and verification text
-before it; the trailing em-dash suffix is reserved for done timestamps or block
-reasons. `(support)` is only for truly operational work.
+For a CR-bearing task, target and verification belong in the description before
+the final `(CRn)` block. Only that final block supplies traceability; mentions of
+`CR1` earlier in the sentence are prose. A task may cover several criteria with
+`(CR1, CR2)`.
+
+The trailing `— ...` suffix is resolution metadata only: an ISO UTC timestamp
+for `[x]` or a required reason for `[!]`. Pending tasks have no suffix. This form
+is invalid:
+
+```markdown
+- [ ] Update `src/app/foo.ts` (CR1) — verify: `pnpm test`
+```
+
+The parser removes `— verify: ...` before readiness checks, so the task retains
+CR traceability but appears to have no verification. Write verification before
+the criteria block as shown in the valid examples.
+
+`(support)` is reserved for operational work that does not directly implement
+observable behaviour: running a test suite, reading before refactoring,
+evaluating blast radius or scaffolding. Support tasks do not require a CR and do
+not run target/verification readiness checks. `(support)` must be the final
+parenthesized marker and is not a substitute for a missing criterion on
+observable behaviour.
 
 ## IDs and language
 
-The id is the UTC creation instant in `YYYYMMDD-HHMMSS` form. Filename is
-`{id}-{english-slug}.md`; the slug is always English and kebab ASCII.
+The id is the UTC creation instant in `YYYYMMDD-HHMMSS`, derived from `created`:
+`2026-06-13T15:04:02Z` becomes `20260613-150402`. The filename is
+`{id}-{english-slug}.md`. Timestamp ids sort chronologically and avoid central
+coordination; abbreviated viewer ids are display-only.
+
+Always English: frontmatter keys, enum values, stage headings, CR ids and step
+keywords, task markers, filenames/directories and CLI. Configured language:
+title, stage prose, scenario content and task descriptions.
+
+## Authoring helpers
+
+- `changeledger new <type> <slug> "<title>"` — scaffold a change with an English slug.
+- `changeledger check [id]` — validate one change or the repository.
+- `changeledger list [--status S] [--type T] [--json]` — inspect/filter changes.
+- `changeledger show <id> [--json]` — inspect one resolved change.
+- `changeledger owner <id> <name|->` — set or clear responsibility.
 
-Frontmatter keys/enums, stage headings, criterion keywords, markers, filenames
-and CLI stay English. Titles, prose and task descriptions follow the configured
-language.
+Run `changeledger <command> --help` for exact options; the commands support the
+file contract rather than replacing it.

package/templates/contract/validation.md

@@ -4,6 +4,7 @@ Implementation and required review are complete. Do not modify the result or
 mark it done. Ask the human to test the whole change in the viewer.
 
 Acceptance reaches `done`. Rejection requires a reason and returns the same
-change to `in-progress`; update Specification/Plan as needed and repeat review
-when configured. The agent never accepts on the human's behalf. `done` and
-`discarded` never reopen.
+change to `in-progress`; run `changeledger context <id>` before modifying
+implementation, update Specification/Plan as needed and repeat review when
+configured. The agent never accepts on the human's behalf. `done` and `discarded`
+never reopen.