changeledger 0.7.0 → 0.9.0

package/templates/contract/core.md

@@ -5,11 +5,16 @@ reflection. Work is planned and documented before code is written.
 
 ## Read complete context before acting
 
-Running `changeledger context` is discovery, not compliance by itself. Read the
-complete output through the `CHANGELEDGER CONTEXT END` line, then follow the
-current mode. If that line is missing, the output was truncated. Stop and re-run
-the command directly, without pipes or filters, 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
@@ -19,16 +24,16 @@ 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 reject with a reason and start another approved change unless 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 (a new spec is a two-step `--new`
-   then `--into`) or run `changeledger graduate <id> --skip [reason]`; archive
-   only after that decision.
+   change, then graduate persistent truth or run `changeledger graduate <id>
+   --skip [reason]`; archive only after that decision. The close overlay owns
+   the full graduation recipe.
 
 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,
@@ -43,40 +48,43 @@ 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
-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.
+Delegate only with a clear boundary and benefit. Each delegation prompt states at least
+ownership, expected output and integration criterion; the task context carries the full
+prompt contract. Get a complete role skeleton to fill in with `changeledger agent-prompt
+<role>` (investigation | implementation | review). 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
-draft → approved → in-progress
-in-progress → in-review → in-validation → done   [review required]
-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]
-(draft | approved | in-progress | blocked) → discarded
-```
-
 - `draft`: documentation awaiting human approval; no implementation.
 - `approved`: ready to start after the Git/worktree checks.
 - `in-progress`: implementation underway.
 - `in-review`: independent review required.
-- `in-validation`: stop and wait for human acceptance or rejection.
+- `in-validation`: stop for human acceptance or a reasoned 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
-`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.
+Who owns each transition and how it is performed:
+
+| Transition | Owner | Mechanism |
+|---|---|---|
+| draft → approved | human | viewer |
+| approved → in-progress; blocked → in-progress; in-progress → in-review | agent | `changeledger status` |
+| in-progress → in-validation (no review) | agent | `changeledger status` |
+| in-review → in-validation | orchestrator | `changeledger review <id> pass` |
+| in-review → in-progress | orchestrator | `changeledger review <id> fail --retry` |
+| in-review → blocked | orchestrator | `changeledger review <id> fail --block` |
+| in-validation → done | human | viewer |
+| in-validation → in-progress | agent or human | `changeledger validation <id> fail "<reason>"` or viewer |
+| done → in-progress (pending closure) | agent or human | `changeledger reopen <id> "<reason>"` or viewer |
+| draft/approved/in-progress/blocked → discarded | agent (authorized) | `changeledger discard <id> "<reason>"` |
+
+`changeledger status <id> <status>` performs the agent-owned moves and does not accept `approved`, `done`, `discarded` or reopening.
+The discard reason is required and 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
 

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,34 @@ 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.
+When implementation and every task are complete, move to `in-review` if the type
+requires independent review by running this ordered gate — do not reconstruct it from memory:
+1. Confirm every Plan task is complete and its verification passes.
+2. `changeledger status <id> in-review`.
+3. Load `changeledger context review` once; do not reload it to record the verdict unless context was lost (compaction, a new session).
+4. Delegate to a fresh, read-only reviewer with clean context; it reports but never records the verdict itself.
+5. Record the delegate's verdict yourself with `changeledger review <id> pass|fail` — never `log`+`status`.
+
+`in-validation`: human accepts; agent rejects with `changeledger validation <id> fail "<reason>"`.
 
 ## 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
+After a 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/review.md

@@ -2,17 +2,15 @@
 
 Review-required work must be checked by a fresh subagent with clean context and
 a model sized to the review difficulty. Independence is correctness, not an
-optimization; do not trust the implementer's summary.
+optimization.
 
-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.
+Get the bounded prompt with `changeledger agent-prompt review`; the delegate
+then loads `changeledger agent-context review <id>`. That self-contained capsule
+owns the inspection checklist, read-only boundary and evidence contract. Do not
+copy its checklist into this orchestrator context.
 
-Deep security, SAST and lint belong to dedicated tools. The reviewer may run
-them and record their evidence; ChangeLedger does not reimplement them.
-
-Record exactly one verdict:
+The orchestrator records exactly one verdict; the read-only reviewer reports its
+finding but never runs the verdict command:
 
 - `changeledger review <id> pass` — criteria and Plan pass; move to
   `in-validation`.
@@ -21,6 +19,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, agent/human may reopen `done` with 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.