doctrina-cli 0.15.0 → 0.16.0

package/templates/change/proposal.md.template

@@ -3,6 +3,7 @@
 - **Status:** proposed
 - **Date:** {{DATE}}
 - **Owner:**
+- **Lane:**
 - **Affects specs:**
 
 ## Why

package/templates/contract.md.template

@@ -56,6 +56,13 @@ program, because no `env:` line ever exports it.
             vars and secrets are CI-injected, and CI injects the EMPTY
             STRING for one that is unset — not "absent". That is why a
             `getenv(NAME, default)` default silently never applies.
+
+            Exporting under a name that is not the source's is routine
+            (npm reads its credential from NODE_AUTH_TOKEN whatever your
+            secret is called). Declare it as `<origin>:<source>` — e.g.
+            `secrets:NPM_TOKEN` — and RT02 stays silent while the two
+            agree, and speaks the moment either side moves. A bare origin
+            keeps warning on any rename, which is the right default.
   Workflow  repo-relative path to the workflow/pipeline file.
   Job/Step  the job (or step) whose env: block must export it.
   Consumer  the file that reads it.

package/templates/hooks/pre-commit.sample

@@ -13,9 +13,13 @@
 #      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.

package/templates/playbooks/bootstrap.md.template

@@ -0,0 +1,43 @@
+[[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: in .doctrina/intake.md flip
+   "- **Status:** pending" to "- **Status:** converted".
+
+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,19 @@
+[[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 — analyze/close refuse leftover scaffold[[/g]]
+[[g]]   placeholders, and `change tick` will not tick an empty box.)[[/g]]
+2. Prove it (archive 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. [[c]]doctrina change apply {{CHANGE_ID}}[[/c]]  (zero deltas → flips to applied).
+5. [[c]]doctrina change archive {{CHANGE_ID}}[[/c]], then [[c]]doctrina validate[[/c]].
+[[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,76 @@
+[[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 — analyze 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]]   (equivalent, step by step: [[/g]][[g]]analyze → change apply → verify → coverage → trace → change archive → validate)[[/g]]
+   Before it: check the proposal's ## Verification boxes and every task,
+   closing steps included, and bump Implementation to verified.
+
+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]]