changeledger 0.6.4 → 0.8.0

package/templates/contract/core.md

@@ -3,14 +3,18 @@
 Documents under `.changeledger/` are the source of truth. Code is their
 reflection. Work is planned and documented before code is written.
 
-## Non-negotiable fast path
+## Read complete context before acting
 
-Running `changeledger context` is discovery, not compliance by itself. Run it
-directly, without piping, filtering, summarizing, limiting or truncating output
-before reading it. Read the complete output and follow the current mode. If the
-output is truncated or incomplete, including through tools such as `head`,
-`tail`, `sed` or `grep`, stop and restore complete context before creating or
-modifying files.
+Running `changeledger context` is discovery, not compliance by itself. Capture the first invocation completely in one pass
+and read through the `CHANGELEDGER CONTEXT END` line, then follow the current mode. Never request a preview, summary
+or voluntary line, byte or token cap; if the tool exposes an output budget,
+reserve enough for the whole response. A missing END after this deliberate full
+capture is exceptional recovery: stop and re-run with a larger capture before
+planning or acting on the partial output.
+
+While the complete core remains available in the active conversation, a new
+human message alone does not trigger a reload. Load only the specialized mode or
+change-id context required by a real task or lifecycle transition.
 
 1. Work starts with conversation. Read-only investigation may clarify a request,
    but create no change or implementation artifact until there is enough clarity
@@ -20,15 +24,16 @@ modifying files.
    agent decides how to divide and execute work within that authorized scope.
 3. Capture every authorized change in `.changeledger/changes/`. The document
    wins when code and documentation disagree.
-4. Never implement a `draft`. After approval, work one change at a time on a
-   non-main branch and commit the approved change document before code.
+4. Never implement a `draft`. After approval, implement one change at a time on
+   a non-main branch and commit the approved change document before code.
 5. Keep lifecycle, tasks, ownership and Log current while working.
 6. For types that require review, use a fresh clean-context reviewer before
    human validation.
-7. Stop at `in-validation`. The agent never accepts on the human's behalf.
+7. `in-validation` stops only that change; the agent never accepts on the human's behalf, but may start another approved change unless it or its `depends_on` chain (direct or transitive) reaches an `in-validation` change.
 8. After human acceptance, reload `changeledger context <id>` for the `done`
-   change, then graduate persistent truth or run
-   `changeledger graduate <id> --skip [reason]`; archive only after that decision.
+   change, then graduate persistent truth (a new spec is a two-step `--new`
+   then `--into`) or run `changeledger graduate <id> --skip [reason]`; archive
+   only after that decision.
 
 If no approved or in-progress change applies, do not silently edit repository
 files. Create or update a change, or ask the human whether a purely operational,
@@ -44,7 +49,8 @@ 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
+at least ownership, expected output and integration criterion; the task context
+carries the full prompt contract. 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.
@@ -58,6 +64,7 @@ in-progress → in-validation → done               [no review required]
 in-review → in-progress                           [review retry]
 in-review → blocked → in-progress                 [review escalation]
 in-validation → in-progress                       [human rejection]
+done → in-progress                                [human reopen before durable closure]
 (draft | approved | in-progress | blocked) → discarded
 ```
 
@@ -67,22 +74,26 @@ in-validation → in-progress                       [human rejection]
 - `in-review`: independent review required.
 - `in-validation`: stop and wait for human acceptance or rejection.
 - `blocked`: an impediment or decision needs resolution.
-- `done`: terminal; the human accepted the complete result.
+- `done`: the human accepted the complete result; provisional until durable closure.
 - `discarded`: terminal tombstone; never reopen it.
 
 `changeledger status <id> <status>` enforces agent-owned transitions and does not accept `done` or `discarded`.
-The viewer owns `draft → approved` and `in-validation → done|in-progress`; the
-agent performs the other non-terminal moves. Use
+The viewer owns `draft → approved` and `in-validation → done|in-progress`, plus
+eligible `done → in-progress` with a reason; the agent performs other 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.
+logged, and dependencies remain resolvable. `discarded` never reopens. A `done`
+change can reopen only to finish its original scope before graduation/skip,
+archive or release; after durable closure, later work needs a new change.
 
 ## Context modes
 
 Valid modes: implement, review, spec, release.
 
-Run these only after reading the complete base output. Each mode and change-id
-context extends the core context already read without repeating it.
+Escalate to a mode before acting. Before documenting, run
+`changeledger context spec`. Before executing, run `changeledger context
+implement` or `changeledger context <change-id>`. Run each only after reading
+the complete base output. Every mode and change-id context extends the core
+context already read; it never repeats it.
 
 - `changeledger context spec`: author or refine a change.
 - `changeledger context implement`: execute an approved change.
@@ -98,4 +109,5 @@ Prefer structured CLI queries before scanning files:
 - `changeledger graduate --pending`: find accepted changes whose graduation decision is unresolved.
 
 Run `changeledger help` or `changeledger <command> --help` for exact CLI syntax.
-Structure is always English; narrative content follows `.changeledger/config.yml`.
+Structure is always English. Each context delivers the effective policy that
+applies to its task, so you never read `.changeledger/config.yml` raw to operate.

package/templates/contract/delegation.md

@@ -21,7 +21,8 @@ owns, what it returns and how the result integrates.
 - 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.
+  requirement, not an optimization — and read-only: it reports, the
+  orchestrator alone records the verdict.
 
 ## Do not over-shard
 

package/templates/contract/implement.md

@@ -17,10 +17,17 @@ to a work branch or ask the human before continuing. Inspect the worktree first.
 unrelated changes exist, do not include them silently; ask the human whether to
 stash, commit, ignore or include them before changing the worktree.
 
-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.
+After `approved → in-progress`, create a baseline commit of the approved change
+document before code. Implement one change at a time, even while another
+already-delivered change waits in `in-validation`.
+
+Commit completed units with their tasks and Log when later work could obscure
+attribution. Do not create a dedicated commit for a lifecycle-only transition.
+Coalesce it with the nearest meaningful commit; for example, include
+`in-progress → in-review` with the final implementation unit. Do not wait until
+the end to reconstruct mixed diffs. If a handoff precedes the next
+meaningful commit, one consolidated checkpoint persists pending state; record
+why and never create one per transition.
 
 Commit messages use the canonical shape:
 
@@ -44,25 +51,32 @@ Useful mutation commands:
 - `changeledger task <id> done|block <n> [reason]`
 - `changeledger log <id> "<message>"`
 - `changeledger owner <id> <name|->`
+- `changeledger review <id> pass|fail`
 - `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.
+type requires independent review, loading `changeledger context review`
+once first — it stays valid for the rest of the cycle, do not reload it just
+to record the verdict unless context was lost (compaction, a new session) —
+and recording the delegate's verdict yourself with `review <id> pass|fail`
+(never `log`+`status`). Otherwise move to `in-validation` and stop — its
+closing has no CLI, only the human does it.
 
 ## 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.
+worktree is its isolation boundary. After `pass`, commit the confirmed correction,
+tests and ledger before human validation; this is meaningful correction evidence,
+not a status-only commit.
 
 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.
+the same diff if it does not. After human acceptance, graduate or record a skip
+and include correction plus ledger in the final closure commit.
 
 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

@@ -37,6 +37,9 @@ 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 configured target and
-verification. Gaps are warnings in `draft` and errors in `approved` or
-`in-progress`. Truly operational `(support)` tasks are exempt; observable
+verification. Every diagnostic is a warning in `draft`. In `approved` or
+`in-progress`, readiness defects (missing Given/When/Then, unknown criterion
+references, CR-bearing tasks without target and verification) are errors, while
+coverage gaps (uncovered criteria, non-support tasks without a CR) stay
+warnings. Truly operational `(support)` tasks are exempt; observable
 implementation is not.

package/templates/contract/review.md

@@ -21,6 +21,11 @@ Record exactly one verdict:
 - `changeledger review <id> fail --block "<reason>"` — correction requires scope
   or product judgment; move to `blocked` for the human.
 
+A review verdict alone needs no commit. A pass leaves `in-validation` for
+closure unless it confirms uncommitted correction; then correction, tests and
+ledger form a commit. Retry keeps the diff isolated. Handoff may use the
+implementation contract's checkpoint.
+
 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

package/templates/contract/validation.md

@@ -3,8 +3,22 @@
 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.
 
+This stop is scoped to this change: the agent may start the next approved
+change unless its `depends_on` chain, direct or transitive, reaches this or
+another `in-validation` change. If every remaining approved change is
+blocked, it stops entirely and does not invent work or touch delivered
+results.
+
 Acceptance reaches `done`. Rejection requires a reason and returns the same
 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.
+configured. The agent never accepts on the human's behalf. Before graduation,
+skip, archive or release, the human may reopen `done` with a reason only to
+complete the original authorized scope; broader behavior needs a new change.
+`discarded` never reopens.
+
+The validation transition alone does not require a dedicated commit. After
+acceptance, resolve graduation or skip first; the close overlay then requires one
+final closure commit containing the pending lifecycle Log and graduation truth.
+After rejection, follow correction isolation instead of committing an
+unconfirmed attempt.