doctrina-cli 0.14.0 → 0.15.0

package/templates/AGENTS.md.template

@@ -34,8 +34,7 @@ prompt and approves; do not make them run the CLI or hand-author artifacts.
 ## Doctrina command surface (generated — reach for these, don't hand-author)
 
 Every command, with the moment you reach for it. The CLI scaffolds from
-canonical templates and keeps `index.json` in sync — prefer it over
-hand-authoring. Flags and detail: `doctrina <command> --help`.
+canonical templates and syncs `index.json`. Flags: `doctrina <cmd> --help`.
 **Bootstrap**
 - `doctrina init` — scaffold AGENTS.md and .doctrina/. *When:* starting a project that has no AGENTS.md yet.
 - `doctrina intake` — store the intent and print the bootstrap playbook. *When:* you have a full project description and no specs yet.
@@ -51,7 +50,8 @@ hand-authoring. Flags and detail: `doctrina <command> --help`.
 - `doctrina handoff (before compaction/handover)` — a resume note: open work, task state, next command. *When:* BEFORE compaction or handing over to another session.
 - `doctrina constitution` — accepted ADRs and product non-goals. *When:* you need the standing rules before deciding something.
 **Change**
-- `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* any request arrives that changes behaviour.
+- `doctrina triage` — classify the lane (product/runtime/chore) and check the declared runtime surface. *When:* a request arrives — BEFORE scaffolding, especially if it smells like an incident.
+- `doctrina work "<prompt>" (--capability · --chore · --from-diff · --quiet)` — scaffold a change and print the playbook to execute. *When:* a request arrives that changes behaviour (triage says PRODUCT).
 - `doctrina spec new|list|set` — create, list, and edit capability specs. *When:* a capability needs creating or its headers advancing.
 - `doctrina change new|apply|archive|check|tick|diff|abandon` — new / apply / archive / check / tick / diff / abandon. *When:* driving a change through its lifecycle by hand.
 - `doctrina contract new|list|check` — own and verify the integration surface. *When:* the change touches ports, env vars, or public endpoints.

package/templates/contract.md.template

@@ -32,11 +32,82 @@ Variables the running system requires, named IDENTICALLY across code,
 `.env.example`, and infra (compose/helm). `doctrina contract check` warns
 when a variable here is missing from `.env.example` — the DATABASE_URL /
 KAFKA_BROKER drift class.
+
+Values declares an ENUM when the variable is one. Write the alternation
+with escaped pipes so the table survives: `none\|critical\|serious`.
+check then fails an .env.example value outside the set (RT04), and warns
+when the consumer never mentions any member — an enum nothing validates.
+Leave Values empty or `—` for free-form variables.
+-->
+
+| Variable     | Required | Values | Example                                   |
+|--------------|----------|--------|-------------------------------------------|
+| DATABASE_URL | yes      | —      | postgres://user:pass@localhost:5432/app   |
+
+## Wiring
+
+<!--
+Where each variable's value COMES FROM, and what reads it. This is the
+table that closes the gap between "I configured it" and "the process saw
+it": a variable can be set in the CI provider and still never reach the
+program, because no `env:` line ever exports it.
+
+  Origin    vars | secrets | literal | local
+            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.
+  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.
+
+`doctrina contract check` then verifies (RT01/RT02) that the workflow
+really exports it, from the origin and under the name declared, and
+(RT03) that the consumer does not give it a default only an ABSENT
+value would trigger.
+
+Delete the rows that do not apply. A contract with no Wiring rows is
+not "verified" — it is unchecked, and check says so.
+-->
+
+| Variable | Origin | Workflow | Job/Step | Consumer |
+|----------|--------|----------|----------|----------|
+| <NAME>   | vars   | <path>   | <job>    | <file>   |
+
+## Selectors
+
+<!--
+The test selectors (BDD tags, suite names, filter expressions) this
+project DISPATCHES on. A selector that matches nothing runs zero cases
+and still exits 0 — a green job that tested nothing.
+
+  Source   glob for the files the selectors live in.
+  Pattern  a regex whose FIRST GROUP captures the selector name.
+  Used by  the selectors a pipeline actually dispatches on.
+
+Doctrina knows no test runner: it extracts with the pattern you declare
+and checks each selector in "Used by" against what it found (RT05),
+naming a near-miss when only the separator differs.
+
+Example (Behave): features/**/*.feature with pattern @([a-z0-9_-]+)
+-->
+
+| Selector | Source | Pattern | Used by |
+|----------|--------|---------|---------|
+| <NAME>   | <glob> | <regex> | <tag>   |
+
+## Budgets
+
+<!--
+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
+buys headroom by truncating what mattered rather than sending less.
 -->
 
-| Variable     | Required | Example                                   |
-|--------------|----------|-------------------------------------------|
-| DATABASE_URL | yes      | postgres://user:pass@localhost:5432/app   |
+| Limit  | Direction    | Value   |
+|--------|--------------|---------|
+| <NAME> | input/output | <count> |
 
 ## Interfaces
 

package/templates/spec.md.template

@@ -71,6 +71,28 @@ Easy Approach to Requirements Syntax. Use one of the five forms per item:
 
 -
 
+### Pipeline
+
+<!--
+OPTIONAL, and only for capabilities with an ORDER. The five EARS forms
+state each requirement independently and truthfully, and say nothing about
+sequence: "when the run finishes, append a summary" and "when the analysis
+completes, publish the dashboard" both pass every gate, and neither says
+the dashboard needs the analysis to have run first. The result ships green
+and one run stale.
+
+Declare the order and the artifact each step hands on. `doctrina validate`
+then enforces the one invariant a numbered list cannot: a step may only
+require what an EARLIER step produced.
+
+  1. run-suite — produces `reports/results.json`
+  2. analyse — requires `reports/results.json`, produces `reports/analysis.md`
+  3. publish — requires `reports/analysis.md`
+
+Mark inputs that come from outside the pipeline `(external)`. Delete this
+section when the capability has no ordering.
+-->
+
 ## Acceptance criteria
 
 <!--