changeledger 0.4.0 → 0.5.0

package/templates/contract/core.md

@@ -0,0 +1,64 @@
+# ChangeLedger — Core Contract
+
+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
+
+1. Work starts with conversation. Read-only investigation may clarify a request,
+   but create no change or implementation artifact until there is enough clarity
+   to document faithfully **and** the human explicitly authorizes documentation. A direct request such
+   as “create the change” is authorization; never invent missing requirements.
+2. The human authorizes scope, approves drafts and accepts the final result. The
+   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.
+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.
+8. After human acceptance, graduate persistent truth or record an explicit skip,
+   then archive the done change.
+
+Humans consume changes in `changeledger view`; write for the rendered view.
+
+## 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.
+- `blocked`: an impediment or decision needs resolution.
+- `done`: terminal; the human accepted the complete result.
+- `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.
+
+## Context modes
+
+Valid modes: implement, review, spec, release.
+
+- `changeledger context spec`: author or refine a change.
+- `changeledger context implement`: execute an approved change.
+- `changeledger context review`: independently verify completed work.
+- `changeledger context release`: plan portable delivery metadata.
+- `changeledger context <change-id>`: infer the correct context from lifecycle.
+
+Run `changeledger help` or `changeledger <command> --help` for exact CLI syntax.
+Structure is always English; narrative content follows `.changeledger/config.yml`.

package/templates/contract/discarded.md

@@ -0,0 +1,5 @@
+# Discarded — Terminal
+
+This change records work explicitly decided against. Preserve its reason and
+dependencies; do not implement, graduate or reopen it. Any later reconsideration
+requires a new authorized change.

package/templates/contract/implement.md

@@ -0,0 +1,52 @@
+# 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.
+
+## 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 diff.
+After `pass`, commit the confirmed correction and ledger truth before asking for
+human validation.
+
+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.
+
+## Triage friction at handoff; retrospect after completion
+
+Before handing the human completed or blocked work, classify discovered
+friction:
+
+- 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.
+
+When a change reaches `done`, also share a brief retrospective with the human.
+
+## Useful commands
+
+- `changeledger status <id> <status>`
+- `changeledger task <id> done|block <n> [reason]`
+- `changeledger log <id> "<message>"`
+- `changeledger owner <id> <name|->`
+- `changeledger check [id]`

package/templates/contract/readiness.md

@@ -0,0 +1,19 @@
+# Definition of Ready
+
+With `tdd: true`, an approved change is ready only when:
+
+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.
+
+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.
+
+`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).

package/templates/contract/release.md

@@ -0,0 +1,15 @@
+# Portable Release Planning
+
+- `changeledger release init <version>` adopts release tracking at an existing
+  stable SemVer; the baseline contains changes already done.
+- `changeledger release plan [--json]` deterministically selects unreleased done
+  changes and calculates the next version without writing.
+- `changeledger release record <version>` records exactly that plan in
+  `.changeledger/releases/<version>.yml`.
+
+Defaults live under `release.impacts` in `.changeledger/config.yml`; a change may
+override its type with `release_impact` (`none|patch|minor|major`).
+
+ChangeLedger owns portable membership and SemVer. The operating agent owns
+stack-specific version files, project gates, commits, tags and publishing.
+Never infer that every ChangeLedger repository uses npm or GitHub.

package/templates/contract/review.md

@@ -0,0 +1,19 @@
+# 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.
+
+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.
+
+- 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.
+
+After a retry, the correction stays uncommitted until another clean reviewer
+passes it. Then commit correction + ledger before asking for human validation.

package/templates/contract/spec.md

@@ -0,0 +1,94 @@
+# Authoring a Change
+
+## Repository layout
+
+```text
+.changeledger/
+  config.yml
+  changes/<id>-<english-slug>.md
+  specs/
+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.
+
+## Change document
+
+A change is one Markdown file with YAML frontmatter and fixed English stage
+headings. Required 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
+---
+```
+
+`owner` is assigned on `approved → in-progress` when absent, preferring the
+GitHub login and falling back to `git config user.name`.
+
+Stages use this order:
+
+| 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 |
+
+Use only the stages activated for the type in `config.yml`. Defaults are:
+
+| Type | request | investigation | proposal | specification | plan | log |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|
+| feature | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| bug | ✓ | ✓ | — | ✓ | ✓ | ✓ |
+| audit | ✓ | ✓ | — | — | — | ✓ |
+| refactor | ✓ | — | ✓ | — | ✓ | ✓ |
+| chore | ✓ | — | — | — | ✓ | — |
+
+## Acceptance criteria
+
+Each criterion is a separate `### CRn — name` block:
+
+```markdown
+### CR1 — Short name
+- **Given** concrete precondition
+- **When** concrete action
+- **Then** exact result
+- **And** optional additional result
+```
+
+The heading, ids and Given/When/Then/And keywords are fixed English. Localized
+headings, inline criteria and `#### CR1` are not machine-readable.
+
+## Plan tasks
+
+```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)
+```
+
+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.
+
+## 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.
+
+Frontmatter keys/enums, stage headings, criterion keywords, markers, filenames
+and CLI stay English. Titles, prose and task descriptions follow the configured
+language.

package/templates/contract/validation.md

@@ -0,0 +1,9 @@
+# Human Validation — Stop
+
+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.