doctrina-cli 0.2.2 → 0.4.0

package/src/lib/scan.js

@@ -55,6 +55,7 @@ export function deriveIndex(projectRoot, current) {
       changes: [],
       changes_archive: [],
       skills: [],
+      contracts: [],
     },
   };
 
@@ -65,13 +66,28 @@ export function deriveIndex(projectRoot, current) {
     if (!isFile(p)) continue;
     const text = read(p);
     const prev = (cur.specs ?? []).find((s) => s.id === cap);
-    out.artifacts.specs.push({
+    const entry = {
       id: cap,
       path: `.doctrina/specs/${cap}/spec.md`,
       status: specHeader(text, "Status") ?? prev?.status ?? "active",
       version: specHeader(text, "Version") ?? prev?.version ?? "0.1.0",
       last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
-    });
+    };
+    // Implementation is the capability axis (planned -> partial ->
+    // implemented -> verified), independent of the document Status. Only
+    // record it when the spec declares it or the index already tracked it,
+    // so specs that never opted in (e.g. bug specs) stay off the axis.
+    // The stored value keeps any explanatory note after the state word.
+    const implRaw = specHeader(text, "Implementation");
+    const impl = implRaw ? implRaw.trim() : prev?.implementation;
+    if (impl) entry.implementation = impl;
+    // Realizes: the product intent anchors this capability delivers (ADR
+    // 0006). Stored as an id list so the provenance link is queryable, not
+    // just prose. Header wins over the previous index, like Implementation.
+    const realizesRaw = specHeader(text, "Realizes");
+    const realizes = realizesRaw ? (realizesRaw.match(/[A-Z]+\d+/g) ?? []) : prev?.realizes;
+    if (realizes && realizes.length) entry.realizes = realizes;
+    out.artifacts.specs.push(entry);
   }
 
   // Decisions — NNNN-slug.md files; Status/Date headers win.
@@ -94,6 +110,8 @@ export function deriveIndex(projectRoot, current) {
     if (supersedes && supersedes !== "—") entry.supersedes = supersedes;
     const supersededBy = listHeader(text, "Superseded by");
     if (supersededBy && supersededBy !== "—") entry.superseded_by = supersededBy;
+    const landed = listHeader(text, "Landed");
+    if (landed && landed !== "—") entry.landed = landed;
     out.artifacts.decisions.push(entry);
   }
 
@@ -143,6 +161,22 @@ export function deriveIndex(projectRoot, current) {
     });
   }
 
+  // Contracts — the integration/runtime surface (ports, env, interfaces)
+  // that no single capability owns. Headers inside each contract win.
+  const contractsDir = path.join(dot, "contracts");
+  for (const f of walk(contractsDir)) {
+    if (!f.endsWith(".md")) continue;
+    const id = path.basename(f, ".md");
+    const text = read(f);
+    const prev = (cur.contracts ?? []).find((s) => s.id === id);
+    out.artifacts.contracts.push({
+      id,
+      path: `.doctrina/contracts/${id}.md`,
+      status: specHeader(text, "Status") ?? prev?.status ?? "active",
+      last_updated: specHeader(text, "Last updated") ?? prev?.last_updated ?? date,
+    });
+  }
+
   // Skills — frontmatter description wins.
   const skillsDir = path.join(dot, "skills");
   for (const f of walk(skillsDir)) {
@@ -183,7 +217,7 @@ export function indexesMatch(a, b) {
     const clone = { ...x };
     delete clone.last_updated;
     const arts = { ...(clone.artifacts ?? {}) };
-    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills"]) {
+    for (const cat of ["specs", "decisions", "changes", "changes_archive", "skills", "contracts"]) {
       arts[cat] = arts[cat] ?? [];
     }
     clone.artifacts = arts;

package/src/lib/version.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync } from "node:fs";
+
+// Single source for "which CLI version is running." Read from the package
+// manifest so it tracks the published version with no extra wiring. Used to
+// stamp index.json (so an artifact tree records the framework that manages
+// it — `doctrina validate` warns and `index rebuild` migrates when the stamp
+// falls behind the running CLI) and to print `doctrina --version`.
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+export function cliVersion() {
+  // src/lib/version.js -> packages/doctrina-cli/package.json
+  const pkgPath = path.resolve(here, "..", "..", "package.json");
+  try {
+    return JSON.parse(readFileSync(pkgPath, "utf8")).version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}

package/templates/change/proposal.md.template

@@ -19,7 +19,16 @@
 
 ## Verification
 
-<!-- How you will know the change is correctly applied. -->
+<!--
+How you will know the change is correctly applied. Use checkboxes: every
+box here is a claim that must be PROVEN before the change is done.
+`doctrina change archive` refuses to archive while any box below is
+unchecked (pass --force to archive anyway and record the gap). Distinguish
+"task marked done" from "verification passed" — link the evidence.
+-->
+
+- [ ] Automated checks pass (`doctrina verify`, or the project's typecheck/test/build).
+- [ ] The affected spec's acceptance criteria are met and cite their evidence (`doctrina coverage`).
 
 ## Open questions
 

package/templates/contract.md.template

@@ -0,0 +1,58 @@
+# Contract — {{CONTRACT_NAME}}
+
+**Contract:** {{CONTRACT_NAME}}
+**Status:** active
+**Last updated:** {{DATE}}
+
+## Purpose
+
+<!--
+The integration/runtime surface this contract OWNS. No single capability
+spec owns the seams between services and front-ends — this artifact does.
+If a login response shape, a WebSocket path, or a Kafka topic falls in the
+gap between two specs, it belongs here.
+-->
+
+## Ports
+
+<!--
+The single source of truth for who listens where. `doctrina contract check`
+fails when two rows claim the same port (the "front points at the wrong
+port" class of bug). Front-ends and clients read their targets from here.
+-->
+
+| Service | Port | Protocol |
+|---------|------|----------|
+| gateway | 8080 | http     |
+
+## Environment
+
+<!--
+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.
+-->
+
+| Variable     | Required | Example                                   |
+|--------------|----------|-------------------------------------------|
+| DATABASE_URL | yes      | postgres://user:pass@localhost:5432/app   |
+
+## Interfaces
+
+<!--
+API / WebSocket / event-stream contracts: endpoints, message shapes, event
+schemas, and the exact response shape each consumer can rely on (e.g. login
+returns `{ token, user }`, not a bare `TokenPair`).
+-->
+
+-
+
+## References
+
+<!--
+The capability specs that must conform to this contract. List each as
+`specs/<capability>`; `doctrina contract check` verifies each spec exists.
+-->
+
+- `specs/<capability>`

package/templates/decision.md.template

@@ -5,6 +5,24 @@
 - **Deciders:**
 - **Supersedes:** —
 - **Superseded by:** —
+- **Evidence:** —
+- **Landed:** —
+
+<!--
+Evidence anchors the decision to reality. Once accepted, cite the file(s)
+that prove this decision is actually implemented, in backticks, e.g.
+"- **Evidence:** `proto/order.proto`, `services/gateway/grpc.ts`".
+`doctrina validate` warns when cited evidence is missing on disk (the
+decision drifted from the code) or when an accepted ADR cites none. For a
+process decision with no code artifact, write "n/a — <why>".
+
+Landed is the non-mutating "this decision is now implemented and verified
+here" stamp. Many ADRs are accepted at design time with "Evidence: n/a — no
+implementation yet"; once the capability ships, run
+"doctrina decision land NNNN `path/to/proof.ts` ..." to record the date and
+proof without editing the immutable body. A filled Landed satisfies the
+accepted-ADR evidence check.
+-->
 
 ## Context
 

package/templates/doctrina/index.json.template

@@ -1,7 +1,7 @@
 {
   "$schema_version": "0.1.0",
   "project": "{{PROJECT_NAME}}",
-  "framework_version": "0.0.0",
+  "framework_version": "{{FRAMEWORK_VERSION}}",
   "last_updated": "{{DATE}}",
   "artifacts": {
     "product": {

package/templates/doctrina/product.md.template

@@ -28,4 +28,21 @@ Out of scope (deferred or rejected):
 
 ## Success criteria
 
-<!-- How you will know this project is working. Prefer measurable signals. -->
+<!--
+How you will know this project is working. Prefer measurable signals.
+Tag a bullet with a short stable id — "- [SC1] ..." — to make it an intent
+anchor that capability specs cite via "**Realizes:** SC1" (`doctrina trace`;
+ADR 0006). Untagged bullets are fine; anchors are opt-in.
+-->
+
+## Delivery order (walking skeleton)
+
+<!--
+Depth before breadth. Name the ONE end-to-end path that must work and be
+verified before any capability fans out — the walking skeleton (e.g.
+auth -> ingest -> ws -> ui). A spec'd capability with no working slice
+through it is breadth bought on credit: build and `doctrina verify` the
+skeleton first, then spec the next capability.
+-->
+
+1.

package/templates/spec.md.template

@@ -1,10 +1,28 @@
 # Spec — {{CAPABILITY}}
 
 **Capability:** {{CAPABILITY}}
-**Status:** active
+**Status:** draft
+**Implementation:** planned
 **Last updated:** {{DATE}}
 **Version:** 0.1.0
 
+<!--
+Two independent axes — keep them honest:
+  Status         — the document:   draft -> active -> deprecated
+  Implementation — the capability: planned -> partial -> implemented -> verified
+Flip Status to "active" only once this spec reflects intended truth.
+Advance Implementation as code lands; "verified" means a test proves it
+(cite the test per acceptance criterion — see `doctrina coverage`).
+An "active" spec left at "planned" is an inventory claim with nothing
+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).
+-->
+
 ## Purpose
 
 <!-- One paragraph: what this capability does and why it exists. -->
@@ -43,9 +61,33 @@ Easy Approach to Requirements Syntax. Use one of the five forms per item:
 
 ## Acceptance criteria
 
-<!-- Concrete, observable signals that the capability is correctly implemented. -->
+<!--
+Concrete, observable signals that the capability is correctly implemented.
+Each criterion is also a claim that must be proven: mark it [verified] or
+[unverified] and cite the artifact/test in backticks. `doctrina coverage`
+reports which criteria have no linked evidence — an [unverified] criterion
+with no test is explicit debt, not a fact.
+-->
+
+1. [unverified] <observable signal> — verified by `path/to/test`.
 
-1.
+## Maturity
+
+<!--
+The line between an MVP and a product wishlist. List under MVP only what
+this capability COMMITS to now. Anything aspirational goes under Future and
+is explicitly NOT accepted scope — do not write Future items in EARS as if
+they were already built (no WebGPU/multi-cloud/"50k entities at 30fps"
+smuggled in as committed requirements).
+-->
+
+**MVP (committed):**
+
+-
+
+**Future (aspirational, not committed):**
+
+-
 
 ## Out of scope for this spec