doctrina-cli 0.15.1 → 0.17.0

package/templates/README.md

@@ -29,10 +29,45 @@ replace. No conditionals, loops, or includes.
 CLI authors and template authors share this vocabulary. Adding a token
 requires extending the templates spec at `.doctrina/specs/templates/spec.md`.
 
+### Playbook tokens
+
+The playbooks under `playbooks/` carry the variable parts of the procedure
+the agent executes. Each is PRE-RENDERED by the CLI into a plain string, so
+the template stays a document rather than a language with conditionals and
+loops in it.
+
+| Token | Meaning | Default if not supplied |
+|-------|---------|-------------------------|
+| `{{TITLE}}` | "Work playbook" or "Backfill playbook" | required in `work` |
+| `{{PROMPT}}` | The prompt the change was opened from, verbatim | required |
+| `{{FROM_DIFF_NOTE}}` | The code-first note, on `--from-diff` | empty |
+| `{{THIN_WARNING}}` | The thin-prompt clarification block | empty |
+| `{{CAPABILITY_BLOCK}}` | The pinned capability, the ranked hints, or "no match" | required in `work` |
+| `{{DIFF_MATCHES}}` | Capabilities the working tree touched | empty |
+| `{{STEP3_INTRO}}` | The delta step's opening, pinned or not | required in `work` |
+| `{{FROM_DIFF_DELTA_NOTE}}` | The backfill caveat on writing the delta | empty |
+| `{{MISSING_SPECS_WARNING}}` | Warning that `.doctrina/specs/` is absent | empty |
+
+A line holding NOTHING but one token whose value is empty is removed rather
+than left blank, which is what lets the optional blocks above be plain tokens.
+
+Colour is marked inline and expanded before substitution, so a token's value
+can never inject it:
+
+| Markup | Renders as |
+|--------|-----------|
+| `[[c]]...[[/c]]` | cyan — a command to run |
+| `[[g]]...[[/g]]` | gray — commentary |
+| `[[b]]...[[/b]]` | bold — a heading |
+| `[[y]]...[[/y]]` | yellow — a warning |
+
 ## Inventory (v0)
 
 ```
 README.md                                  this file
+playbooks/work.md.template                 the work / backfill playbook
+playbooks/chore.md.template                the spec-less chore playbook
+playbooks/bootstrap.md.template            the intake -> specs playbook
 AGENTS.md.template                         root rules for the target repo
 doctrina/                                  the .doctrina/ skeleton
   product.md.template

package/templates/adapters/claude/.claude/commands/doctrina-work.md.template

@@ -9,9 +9,12 @@ Drive the Doctrina spec-driven workflow for **{{PROJECT_NAME}}**.
    (No prompt, but you already edited code? Use `doctrina work --from-diff`.)
 2. Execute the printed playbook in order: read the pack with
    `doctrina context <capability> --concat`, write the spec delta, fill
-   `tasks.md`, implement, then `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. Close it: `doctrina close <id>` (verify → coverage → archive → validate) and
-   resolve every `error:` before reporting the work done.
+   `tasks.md`, implement. `doctrina change check <id>` previews everything
+   the close would refuse.
+3. Close it: `doctrina close <id>` — one attested pass over every gate. The
+   sequence is declared in one place and printed by `doctrina close --help`;
+   read it there rather than from a copy. Resolve every `error:` before
+   reporting the work done.
 
 Reach for the CLI instead of hand-authoring artifacts. Ask the human only on
 genuine ambiguity.

package/templates/adapters/cursor/.cursor/commands/doctrina-work.md.template

@@ -5,8 +5,9 @@ Turn the request into a Doctrina change and drive it through the gates.
 1. Run `doctrina work "<the request>"` (or `doctrina work --from-diff` if you
    already edited code) and follow the printed playbook.
 2. `doctrina context <capability> --concat` → write the spec delta → fill
-   `tasks.md` → implement → `doctrina analyze <id>` → `doctrina change apply <id>`.
-3. `doctrina close <id>` (verify → coverage → archive → validate); resolve
-   every `error:` before reporting the work done.
+   `tasks.md` → implement → `doctrina change check <id>` (the close's preview).
+3. `doctrina close <id>` — one attested pass over every gate; the sequence is
+   declared in one place and printed by `doctrina close --help`, so read it
+   there and not from a copy. Resolve every `error:` before reporting done.
 
 Prefer the CLI over hand-authoring artifacts. Ask only on genuine ambiguity.

package/templates/change/proposal.md.template

@@ -3,8 +3,24 @@
 - **Status:** proposed
 - **Date:** {{DATE}}
 - **Owner:**
+- **Lane:**
 - **Affects specs:**
 
+<!--
+Optional, and usually absent. The closing docs gate reads COMMAND and FLAG
+names out of the prose below and asks for documentation when it finds any.
+It cannot tell a change from a mention: explaining an effect, or writing a
+Scope boundaries line about what this deliberately does NOT touch, names
+things just as loudly as changing them would.
+
+When that happens, say so on the record instead of forcing the close:
+
+- **Documented surface:** n/a — names two commands to explain an effect; alters neither
+
+`none` reads the same as `n/a`, and a BARE one silences nothing — the
+reason is the declaration.
+-->
+
 ## Why
 
 <!-- The user-visible or technical reason this change exists. -->

package/templates/change/tasks.md.template

@@ -2,16 +2,11 @@
 
 <!--
 Each task is a single checkable item. Keep tasks small (under a few hours
-of work). The change is done when every box is checked, including the
-three closing steps at the bottom.
+of work). The change is done when every box is checked and
+`doctrina close {{CHANGE_ID}}` succeeds — the close applies the deltas,
+archives the change and updates the index, so those are not boxes here.
 -->
 
 - [ ]
 - [ ]
 - [ ]
-
-## Closing steps
-
-- [ ] Apply the change: merge each delta into the corresponding spec.
-- [ ] Archive the change folder to `.doctrina/changes/archive/{{DATE}}-{{CHANGE_ID}}/`.
-- [ ] Update `.doctrina/index.json` with new or modified artifacts.

package/templates/contract.md.template

@@ -107,8 +107,8 @@ Example (Behave): features/**/*.feature with pattern @([a-z0-9_-]+)
 <!--
 Ceilings that are a CONTRACT, not a preference: token limits, payload
 caps, timeouts. Direction distinguishes what goes IN from what comes
-OUT, because they fail differently — and `doctrina analyze` refuses a
-change that "fixes" an overflow by raising an OUTPUT ceiling, which
+OUT, because they fail differently — and `doctrina change check` and the
+close refuse a change that "fixes" an overflow by raising an OUTPUT ceiling, which
 buys headroom by truncating what mattered rather than sending less.
 -->
 

package/templates/hooks/pre-commit.sample

@@ -13,12 +13,26 @@
 #      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`.
+# line below with a bare `$DOCTRINA validate`.
 
-doctrina validate --fix || exit 1
+# The CLI that installed this hook, pinned by path (the hook is local to
+# the clone). Set DOCTRINA in the environment to run another one.
+DOCTRINA="${DOCTRINA:-{{DOCTRINA_BIN}}}"
+
+$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
+
+# ...and then check that the index this commit carries describes THIS COMMIT.
+#
+# Everything above reads the working tree. index.json is derived from the
+# whole tree, so it cannot describe a subset of one: stage part of
+# .doctrina/ and the index that just got staged names artifacts the commit
+# does not contain. On your disk they are all still there, so `validate`,
+# `index rebuild --check` and the close all pass — and the checkout in CI
+# fails with "index.json references missing artifact".
+$DOCTRINA index rebuild --check --staged || exit 1

package/templates/playbooks/bootstrap.md.template

@@ -0,0 +1,47 @@
+[[b]]Bootstrap playbook[[/b]][[g]] — agent-executed (ADR 0005); the CLI does no interpretation.[[/g]]
+
+Execute in order, in a single linear pass:
+
+1. Read [[c]].doctrina/intake.md[[/c]] (raw intent) and [[c]].doctrina/product.md[[/c]].
+
+2. Fill every product.md section from the intake: Vision, Problem,
+   Target users, Scope (in/out), Non-goals, Success criteria, and the
+   Delivery order — name the ONE end-to-end walking skeleton to build
+   and verify before fanning out (depth before breadth).
+   One fact, one home — product.md holds vision, never requirements.
+
+3. Derive the capability list: kebab-case, one per area of behaviour
+   (e.g. auth, billing, reports). For each capability:
+       [[c]]doctrina spec new <capability>[[/c]]
+   then replace the template placeholders in
+   .doctrina/specs/<capability>/spec.md with EARS requirements derived
+   from the intake (Ubiquitous / Event-driven / State-driven /
+   Unwanted-behavior / Optional). Keep the two axes honest — leave
+   Implementation: planned for what is not built yet; keep aspiration
+   under ## Maturity → Future, not in EARS; write concrete Acceptance
+   criteria, each [unverified] until a cited test proves it.
+
+4. If the project spans services/front-ends, own the seams between
+   them (port map, env, API/WS/event shapes) as a contract:
+       [[c]]doctrina contract new <name>[[/c]] → fill it → [[c]]doctrina contract check[[/c]]
+
+5. Record any architectural decision the intake forces (cite Evidence):
+       [[c]]doctrina decision new "<title>"[[/c]] → edit → [[c]]doctrina decision accept <num>[[/c]]
+
+6. Quality gates — fix everything they report before moving on:
+       [[c]]doctrina clarify --all[[/c]]
+       [[c]]doctrina validate[[/c]]
+       [[c]]doctrina coverage[[/c]]   (and [[c]]doctrina verify --init[[/c]] to declare the build gate)
+   If something in the intake is genuinely ambiguous, ask the user
+   before assuming.
+
+7. Mark the intake consumed — through the CLI, not by hand:
+       [[c]]doctrina intake --converted[[/c]]
+[[g]]   `next` branches on that header and `validate` refuses any other[[/g]]
+[[g]]   value, because every word but the two declared ones used to read[[/g]]
+[[g]]   as pending in silence. It refuses while `validate` reports an[[/g]]
+[[g]]   error — the step-6 gates are what "done" means.[[/g]]
+
+8. [[c]]doctrina next[[/c]] — follow the recommendation. Implementation then
+   flows through [[c]]doctrina work "<brief prompt>"[[/c]], one change at a time.
+{{MISSING_SPECS_WARNING}}

package/templates/playbooks/chore.md.template

@@ -0,0 +1,24 @@
+[[b]]Chore playbook — change {{CHANGE_ID}}[[/b]][[g]] — agent-executed (ADR 0005); no spec deltas.[[/g]]
+
+Prompt: "{{PROMPT}}"
+
+Execute in order, in a single linear pass:
+
+1. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
+   with small, checkable steps; implement them, checking each box.
+[[g]]   (Do it before implementing — the close refuses leftover scaffold[[/g]]
+[[g]]   placeholders, and `change tick` will not tick an empty box.)[[/g]]
+2. Prove it (the close refuses unchecked boxes):
+       [[c]]doctrina verify[[/c]]     — the project's typecheck/test/build gate
+       [[c]]doctrina verify --clean[[/c]] — clean-checkout reproducibility lint
+   Then check the proposal's ## Verification boxes and every task.
+3. This is a chore: no spec changes. If you find yourself needing a
+   spec delta, it is not a chore — reopen with [[c]]doctrina work "<prompt>"[[/c]].
+4. Close in one attested pass — the same close as any change; a chore
+   simply has no delta to apply:
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]
+[[g]]   It stops at the first failure with the exact rerun command, and the[[/g]]
+[[g]]   sequence is printed by the close itself. A chore that alters a[[/g]]
+[[g]]   documented surface still owes the docs and a changelog entry — or[[/g]]
+[[g]]   `- **Documented surface:** n/a — <why>` in the proposal.[[/g]]
+[[g]]   If this fix taught a lesson worth not relearning, capture it: [[/g]][[c]]doctrina skill new <slug>[[/c]][[g]].[[/g]]

package/templates/playbooks/work.md.template

@@ -0,0 +1,83 @@
+[[b]]{{TITLE}} — change {{CHANGE_ID}}[[/b]][[g]] — agent-executed (ADR 0005).[[/g]]
+
+Prompt: "{{PROMPT}}"
+{{FROM_DIFF_NOTE}}
+{{THIN_WARNING}}
+{{CAPABILITY_BLOCK}}
+{{DIFF_MATCHES}}
+
+Execute in order, in a single linear pass:
+
+1. Read the context pack and confirm (or correct) the capability:
+       [[c]]doctrina context {{CAPABILITY}} --concat[[/c]]
+
+2. If the capability has no spec yet:
+       [[c]]doctrina spec new <capability>[[/c]]
+[[g]]   Trace it to product intent: tag the product.md success-criteria bullet[[/g]]
+[[g]]   it serves with an anchor ("- [SC1] ...") and set the spec's[[/g]]
+[[g]]   "**Realizes:** SC1" header (or "n/a — <why>"). `doctrina validate` warns[[/g]]
+[[g]]   on an active spec with no Realizes; `doctrina trace` reports the link.[[/g]]
+
+{{STEP3_INTRO}}
+[[g]]       # Spec Delta — capability: <capability>[[/g]]
+[[g]]       **Operation:** ADDED | MODIFIED | REMOVED[[/g]]
+[[g]]       **Target spec on apply:** `.doctrina/specs/<capability>/spec.md`[[/g]]
+[[g]]       ---[[/g]]
+[[g]]       <EARS body. Keep the two axes honest (Status vs Implementation),[[/g]]
+[[g]]        keep aspiration under ## Maturity → Future, and cite the proof per[[/g]]
+[[g]]        criterion: "1. [unverified] <signal> — verified by `path/to/test`">[[/g]]
+[[g]]   New capability? `spec new` then an ADDED delta with the FULL body — apply[[/g]]
+[[g]]   replaces the untouched scaffold. Bookkeeping edits? MODIFIED with an ops[[/g]]
+[[g]]   block, applied mechanically (all ops or none):[[/g]]
+[[g]]       ```ops[[/g]]
+[[g]]       set-header Implementation: verified — `src/x.js`[[/g]]
+[[g]]       bump-version minor[[/g]]
+[[g]]       set-criterion 1: verified[[/g]]
+[[g]]       append-criterion [unverified] new signal — verified by `test/y.test.js`[[/g]]
+[[g]]       append-requirement event: When <trigger>, the system shall <action>.[[/g]]
+[[g]]       replace-requirement ubiquitous 2: The system shall <action>.[[/g]]
+[[g]]       ```[[/g]]
+[[g]]   append-* ops number/position at APPLY time, so concurrent changes[[/g]]
+[[g]]   appending to the same spec never collide. Only free-prose rewrites[[/g]]
+[[g]]   (Purpose, Maturity, ...) stay a by-hand merge.[[/g]]
+{{FROM_DIFF_DELTA_NOTE}}
+
+4. Replace the placeholder tasks in .doctrina/changes/{{CHANGE_ID}}/tasks.md
+   with small, checkable implementation tasks (a few hours each, max),
+   and record the change's What/Scope in its proposal.md. Do this BEFORE
+   implementing — `change check` and close refuse a change whose scaffold
+   placeholders were never replaced, and `change tick` will not tick them.
+
+5. Implement task by task, checking each box as it lands. Advance the
+   spec's Implementation: planned → partial → implemented as code lands.
+   If the prompt is genuinely ambiguous, ask the user before assuming.
+
+6. ADR checkpoint — does this change decide something structural
+   (an architecture, a boundary, a trade-off a future session must
+   not relitigate)? If yes: [[c]]doctrina decision new "<title>"[[/c]] now,
+   before closing — the definition of done requires it recorded.
+[[g]]   (close re-checks this: it warns when the change touches capabilities[[/g]]
+[[g]]   cited by an accepted ADR — amend via decision supersede, not silence.)[[/g]]
+   Touching an integration surface (ports, env vars, public endpoints)?
+   Own it in a contract: [[c]]doctrina contract new <id>[[/c]] · [[c]]doctrina contract check[[/c]].
+
+7. Close in one attested pass (preferred — runs every gate and stops
+   at the first failure with the exact rerun command):
+       [[c]]doctrina close {{CHANGE_ID}}[[/c]]
+[[g]]   It self-reviews on the way through: the close runs `doctrina review`[[/g]]
+[[g]]   before the apply, where its findings can still change what gets[[/g]]
+[[g]]   written. Advisory — it reports and the close continues.[[/g]]
+[[g]]   The sequence is declared in one place and printed by the close itself,[[/g]]
+[[g]]   so read it there rather than from a copy that goes stale.[[/g]]
+   Before it: check the proposal's ## Verification boxes and every task,
+   and bump Implementation to verified.
+   Two gates ask for WRITING, and both refuse late if you leave them:
+   a change that alters a documented surface needs the documentation to
+   move with it, AND an entry in the project's changelog — one says how it
+   works, the other says that it changed. If the command and flag names in
+   your prose are only MENTIONED, declare it instead of forcing:
+   [[c]]- **Documented surface:** n/a — <why>[[/c]] in the proposal.
+
+8. [[c]]doctrina next[[/c]] for the follow-up.
+[[g]]   If this change taught a reusable lesson (a fix you'd hate to relearn,[[/g]]
+[[g]]   a recurring convention), capture it: [[/g]][[c]]doctrina skill new <slug>[[/c]][[g]].[[/g]]

package/src/commands/constitution.js

@@ -1,145 +0,0 @@
-// @ts-check
-import path from "node:path";
-import process from "node:process";
-import { readdirSync } from "node:fs";
-import { exists, isDir, isFile, read } from "../lib/fs-ops.js";
-import { listHeader } from "../lib/scan.js";
-import { c } from "../lib/colors.js";
-import { notADoctrinaProject } from "../lib/exit-codes.js";
-
-// The project's standing rules in one read — Spec Kit parity for its
-// `constitution.md`, but ASSEMBLED, not a new home for facts. Doctrina's
-// constitution is its accepted ADRs (the immutable decisions that govern how
-// the codebase evolves) plus the product's declared non-goals. Both already
-// own those facts elsewhere; this is a read-only digest that gathers them so a
-// human or agent (especially one migrating from Spec Kit, which expects a
-// single constitution) can see "the rules" without reading the whole tree.
-//
-// To change a principle, supersede its ADR; to change a non-goal, edit
-// product.md. The command never writes — it has nothing of its own to own.
-
-// Flags this command accepts. Declared HERE, with the command, so
-// adding a command never requires editing the entrypoint — the gap that
-// let six flags ship undeclared and silently swallow a positional (C3).
-export const flags = { boolean: ["json"], string: [] };
-
-export async function run(_positional, _flags) {
-  const projectRoot = process.cwd();
-  if (!exists(path.join(projectRoot, ".doctrina"))) {
-    throw notADoctrinaProject();
-  }
-
-  const project = projectName(projectRoot);
-  console.log(
-    c.bold("Doctrina constitution") +
-      c.gray(` — ${project}  (standing rules: accepted decisions + non-goals)`),
-  );
-
-  // Principles — the accepted ADRs, by number. Every accepted decision is a
-  // binding rule; superseded/withdrawn/proposed ADRs are not yet (or no longer)
-  // in force and stay out.
-  console.log("");
-  console.log(c.bold("  Principles") + c.gray("  (immutable — supersede an ADR to change one)"));
-  const adrs = acceptedDecisions(projectRoot);
-  if (adrs.length === 0) {
-    console.log(`    ${c.gray("no accepted ADRs yet — record decisions with `doctrina decision new`")}`);
-  } else {
-    for (const a of adrs) console.log(`    ${c.cyan("ADR " + a.id)}  ${a.title}`);
-  }
-
-  // Non-goals — the explicit "what this project will not be", from product.md.
-  console.log("");
-  console.log(c.bold("  Non-goals") + c.gray("  (.doctrina/product.md)"));
-  const nonGoals = productSection(projectRoot, "Non-goals");
-  if (nonGoals.length === 0) {
-    console.log(`    ${c.gray("none declared — add a `## Non-goals` section to product.md")}`);
-  } else {
-    for (const g of nonGoals) console.log(`    ${c.gray("•")} ${g}`);
-  }
-
-  console.log("");
-  console.log(
-    c.gray(
-      `  ${adrs.length} accepted decision${adrs.length === 1 ? "" : "s"} · ` +
-        `${nonGoals.length} non-goal${nonGoals.length === 1 ? "" : "s"} · read-only`,
-    ),
-  );
-  return 0;
-}
-
-function projectName(projectRoot) {
-  try {
-    return JSON.parse(read(path.join(projectRoot, ".doctrina", "index.json"))).project
-      ?? path.basename(projectRoot);
-  } catch {
-    return path.basename(projectRoot);
-  }
-}
-
-// Accepted ADRs (NNNN-slug.md with Status: accepted), oldest first, with the
-// title read from the `# ADR NNNN — <title>` heading. Exported for `prime`,
-// which digests the same standing rules into the session primer.
-export function acceptedDecisions(projectRoot) {
-  const dir = path.join(projectRoot, ".doctrina", "decisions");
-  const out = [];
-  if (!isDir(dir)) return out;
-  for (const f of readdirSync(dir).sort()) {
-    const m = f.match(/^(\d{4})-.*\.md$/);
-    if (!m) continue;
-    const text = read(path.join(dir, f));
-    if ((listHeader(text, "Status") ?? "").toLowerCase() !== "accepted") continue;
-    const titleMatch = text.match(/^#\s+ADR\s+\d{4}\s*[—-]\s*(.+)$/m);
-    out.push({ id: m[1], title: titleMatch ? titleMatch[1].trim() : f });
-  }
-  return out;
-}
-
-// Bullets under a named `## <section>` of product.md, each accumulated across
-// its continuation lines so a wrapped bullet reads as one rule. Exported for
-// `prime`.
-export function productSection(projectRoot, name) {
-  const p = path.join(projectRoot, ".doctrina", "product.md");
-  if (!isFile(p)) return [];
-  const lines = read(p).split(/\r?\n/);
-  let inSection = false;
-  const out = [];
-  let cur = null;
-  const flush = () => {
-    if (cur) out.push(cur.replace(/\s+/g, " ").trim());
-    cur = null;
-  };
-  for (const line of lines) {
-    if (/^##\s+/.test(line)) {
-      if (inSection) {
-        flush();
-        break;
-      }
-      if (new RegExp(`^##\\s+${name}\\b`, "i").test(line)) inSection = true;
-      continue;
-    }
-    if (!inSection) continue;
-    const m = line.match(/^\s*[-*]\s+(.+)$/);
-    if (m) {
-      flush();
-      cur = m[1];
-    } else if (cur && line.trim() !== "") {
-      cur += " " + line.trim();
-    } else if (line.trim() === "") {
-      flush();
-    }
-  }
-  flush();
-  return out;
-}
-
-export const help = `
-Usage: doctrina constitution
-
-Print the project's standing rules in one read: the accepted ADRs (the
-immutable decisions that govern how the codebase evolves) and the product's
-declared non-goals. Read-only — it assembles facts the ADRs and product.md
-already own; it never writes.
-
-This is the Spec Kit \`constitution.md\` analogue: a single place to see the
-non-negotiables. To change one, supersede the ADR or edit product.md.
-`;