doctrina-cli 0.4.0 → 0.8.0

package/templates/AGENTS.md.template

@@ -11,20 +11,47 @@ This repository uses the Doctrina framework for spec-driven, AGENTS.md
 native multi-agent development. The full framework artifacts live under
 `.doctrina/`.
 
-## Working from intent
-
-- **Bootstrap.** If `.doctrina/intake.md` exists with `Status: pending`,
-  the specs have not been written yet. Before anything else, run
-  `doctrina intake` and execute the printed bootstrap playbook in one
-  linear pass: fill `product.md`, derive capabilities, author one EARS
-  spec each, run the quality gates (`doctrina clarify --all`,
-  `doctrina validate`), then flip the intake to `Status: converted`. Ask
-  the user only when the intake is genuinely ambiguous. After conversion
-  the specs are the only source of truth — never edit `intake.md` to
-  change requirements.
-- **Day-to-day.** Turn a brief request into a scaffolded change with
-  `doctrina work "<prompt>"`, then follow the printed work playbook
-  (spec delta → tasks → implement → analyze → apply → archive → validate).
+## Working from intent (you drive; the human stays passive)
+
+You — the AI agent — run the Doctrina commands. The human gives a brief
+prompt and approves; do not make them run the CLI or hand-author artifacts.
+
+- **Bootstrap.** If `.doctrina/intake.md` is `Status: pending`, the specs
+  are not written yet: run `doctrina intake` and execute the printed
+  playbook in one pass (fill `product.md`, derive capabilities, one EARS
+  spec each, `doctrina clarify --all` + `doctrina validate`, then flip the
+  intake to `Status: converted`). After conversion the specs are the only
+  source of truth — never edit `intake.md` to change requirements.
+- **Day-to-day.** Turn any request into a change with `doctrina work
+  "<prompt>"` and follow the printed playbook (spec delta → tasks →
+  implement → analyze → apply → archive → validate). Unsure what to do
+  next? Run `doctrina next`. Need to read? Run `doctrina context`. Ask the
+  human only on genuine ambiguity.
+
+## Doctrina command surface (reach for these — don't hand-author)
+
+The CLI scaffolds from canonical templates and keeps `index.json` in sync,
+so prefer it over writing artifacts by hand. Full list: `doctrina --help`.
+
+- **Read / orient (any task, first & last):** `doctrina status` (health) ·
+  `doctrina context [<cap>] --concat` (read pack) · `doctrina next` (what's
+  next) · `doctrina why <cap>` (provenance) · `doctrina spec list` ·
+  `doctrina decision list` · `doctrina search <query>`
+- **Start:** `doctrina work "<prompt>"` · `--from-diff` (backfill from
+  existing code) · `--chore` (no-spec infra/docs/build)
+- **Scaffold (manual creation stays available):** `doctrina spec new <cap>`
+  (`--bug`) · `doctrina decision new "<title>"` · `doctrina change new <id>`
+  · `doctrina contract new <id>` · `doctrina skill new <slug>`
+- **Advance / close:** `doctrina change apply|archive|diff <id>` · `doctrina
+  decision accept|land|supersede <n>` · `doctrina spec set <cap> [...]` ·
+  `doctrina close <id>` (whole close in one pass)
+- **Gates (ground truth, not guesses):** `doctrina validate` (`--fix`) ·
+  `doctrina verify` · `doctrina review` (conformance vs specs/ADRs) ·
+  `doctrina coverage --strict` · `doctrina trace --strict` · `doctrina
+  contract check` · `doctrina clarify --all` · `doctrina analyze <id>`
+
+Continuous: `doctrina watch` re-syncs and re-orients on every save.
+Capture lessons: `doctrina skill suggest` surfaces skills worth writing.
 
 ## Stack and tooling
 
@@ -86,14 +113,14 @@ before considering work done.
 
 ## How to read context efficiently
 
-1. Read this `AGENTS.md`.
-2. Read `.doctrina/product.md`.
-3. Read the relevant `.doctrina/specs/<capability>/spec.md`.
-4. Read any open `.doctrina/changes/<id>/`.
-5. Read `.doctrina/decisions/` filtered by `Status: accepted`.
-6. If the task matches a skill in `.doctrina/skills/`, load the
-   relevant skill on demand (read its `description:` / `when:`
-   frontmatter; load the full body only when the trigger fires).
+`doctrina context [<capability>] --concat` assembles the read pack in one
+call, in order: this `AGENTS.md` → `.doctrina/product.md` → the capability
+spec → open `.doctrina/changes/<id>/` → `.doctrina/decisions/` filtered to
+`Status: accepted`. Run it for ANY task, not only `doctrina work`; it skips
+`changes/archive/` (history — read only when debugging it).
+
+On demand only: if the task matches a skill in `.doctrina/skills/`, read its
+`description:` / `when:` frontmatter; load the full body when the trigger fires.
 
 Keep this file under 150 lines. Density beats prose. Use exact commands.
 

package/templates/change/spec-delta.md.template

@@ -8,8 +8,19 @@ For ADDED: include the full new spec body below. On apply, the body is
 written verbatim to the target path.
 
 For MODIFIED: include only the sections that change, with clear
-before/after markers. On apply, the maintainer merges the delta into the
-existing spec by hand or with the CLI.
+before/after markers. Bookkeeping edits (flip a criterion, bump the
+version, set a header) can be made mechanical by adding a fenced `ops`
+block — on apply the CLI executes it against the target spec, all ops or
+none (ADR 0007). Anything the ops verbs cannot express (rewriting prose)
+stays a by-hand merge; a MODIFIED delta with no `ops` block prints a
+manual-merge pointer.
+
+  ```ops
+  set-header Implementation: verified — durable adapter (`src/db.ts`)
+  bump-version minor
+  set-criterion 1: verified
+  append-criterion [unverified] new signal — verified by `test/x.test.ts`
+  ```
 
 For REMOVED: the body may be empty; on apply, the target spec file is
 deleted and the capability is recorded in the change archive only.

package/templates/hooks/pre-commit.sample

@@ -1,7 +1,24 @@
 #!/usr/bin/env sh
 # Doctrina pre-commit hook.
-# Installed by `doctrina hooks install`. Runs validate and blocks the
-# commit if it exits non-zero. Edit freely after install; the CLI will
-# not overwrite without --force.
+# Installed by `doctrina hooks install`. Edit freely after install; the CLI
+# will not overwrite without --force.
+#
+# Runs `doctrina validate --fix`:
+#   1. --fix regenerates index.json from the tree (repairs metadata drift and
+#      migrates the framework_version stamp) BEFORE checking, so the single
+#      most common gate failure — a hand-edited header that drifted the index —
+#      is healed at commit time instead of blocking the commit.
+#   2. validate still exits non-zero (and blocks the commit) on real errors a
+#      rebuild cannot heal: missing artifacts, duplicate ADR numbers, broken
+#      EARS, ledger/index disagreement, and so on.
+#
+# To gate without auto-repairing (CI-style, fail on any drift), replace the
+# line below with a bare `doctrina validate`.
 
-doctrina validate
+doctrina validate --fix || exit 1
+
+# Re-stage the index if --fix rewrote it, so the repaired index lands in this
+# commit rather than as a leftover unstaged change. Harmless when unchanged.
+if [ -f .doctrina/index.json ]; then
+  git add .doctrina/index.json
+fi

package/templates/spec.md.template

@@ -3,6 +3,7 @@
 **Capability:** {{CAPABILITY}}
 **Status:** draft
 **Implementation:** planned
+**Realizes:** <product.md success-criteria anchors this delivers, or "n/a — <why>">
 **Last updated:** {{DATE}}
 **Version:** 0.1.0
 
@@ -18,9 +19,12 @@ behind it, and `doctrina validate` warns. To record a deliberate gap and
 silence the warning, add a note after the value, e.g.
 "**Implementation:** planned — backend deferred to Q3, see ADR 0007".
 
-Optional: trace this capability to product intent by adding a header
-"**Realizes:** SC1, SC3" that names the product.md anchors it delivers
-(`doctrina trace`; ADR 0006).
+Realizes ties this capability to product intent (`doctrina trace`;
+ADR 0006). Tag product.md success-criteria bullets with an anchor —
+"- [SC1] ..." — and list the ones this spec delivers above. An "active"
+spec with no Realizes: header warns under `doctrina validate`; if the
+capability genuinely maps to no product anchor (internal tooling), keep
+the header and write "n/a — <why>" to record that on purpose.
 -->
 
 ## Purpose