doctrina-cli 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doctrina-cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Doctrina CLI — spec-driven, AGENTS.md-native framework for multi-agent AI development.",
   "license": "MIT",
   "keywords": [

package/src/commands/skill.js

@@ -54,7 +54,10 @@ function skillNew(args, flags) {
   idx.addSkill(index, {
     id: name,
     path: `.doctrina/skills/${name}.md`,
-    description: "<edit me — one-sentence summary>",
+    // Seed the index from the scaffolded frontmatter so a fresh skill does
+    // not immediately trip validate's description-drift check. Matches how
+    // deriveIndex (index rebuild) reads the description.
+    description: parseFrontmatter(body, "description") ?? "<edit me — one-sentence summary>",
     last_updated: date,
   });
   idx.touch(index, date);

package/src/commands/validate.js

@@ -67,7 +67,7 @@ export async function run(_positional, _flags) {
       for (const s of index.artifacts.specs ?? []) {
         const full = path.join(projectRoot, s.path);
         if (!isFile(full)) continue;
-        const m = read(full).match(/^\*\*Version:\*\*\s+(\S+)/m);
+        const m = read(full).match(/^(?:-\s+)?\*\*Version:\*\*\s+(\S+)/m);
         if (m && s.version && m[1] !== s.version) {
           warnings.push(`${s.path} declares version ${m[1]} but index.json records ${s.version} (sync the index)`);
         }
@@ -80,9 +80,24 @@ export async function run(_positional, _flags) {
   if (isDir(adrDir)) {
     for (const f of walk(adrDir)) {
       if (!f.endsWith(".md")) continue;
+      const base = path.basename(f);
+      // ADR filenames must be NNNN-slug.md (four digits). The entire ADR
+      // toolchain — decision new/accept/supersede, index derivation, and
+      // the orphan check below — keys off this shape; a file like
+      // "ADR-001-foo.md" is silently invisible to all of them.
+      if (base !== "README.md" && !/^\d{4}-.+\.md$/.test(base)) {
+        errors.push(
+          `${relPath(projectRoot, f)} has a non-canonical ADR filename ` +
+            `(expected four digits + slug, e.g. "0001-jwt-algorithm.md"; ` +
+            `the decision and index commands silently ignore other shapes)`,
+        );
+      }
       const text = read(f);
       if (!/^-\s+\*\*Status:\*\*\s+\S+/m.test(text)) {
-        errors.push(`${relPath(projectRoot, f)} missing or malformed Status: header`);
+        errors.push(
+          `${relPath(projectRoot, f)} missing or malformed Status: header ` +
+            `(expected a Markdown list item exactly like "- **Status:** accepted")`,
+        );
       }
     }
   }
@@ -105,7 +120,10 @@ export async function run(_positional, _flags) {
       if (entry === "archive" || entry.startsWith(".")) continue;
       const proposal = path.join(changesDir, entry, "proposal.md");
       if (!isFile(proposal)) {
-        errors.push(`open change "${entry}" missing proposal.md`);
+        errors.push(
+          `open change "${entry}" missing proposal.md ` +
+            `(every dir under .doctrina/changes/ needs a proposal.md — that exact filename)`,
+        );
       }
     }
   }
@@ -164,7 +182,7 @@ export async function run(_positional, _flags) {
 
   // 10. Orphan detection — files on disk not referenced in index.json.
   if (index?.artifacts) {
-    const indexedSpecIds = new Set((index.artifacts.specs ?? []).map((s) => s.id));
+    const indexedSpecIds = new Set((index.artifacts.specs ?? []).map((s) => s.id ?? s.capability));
     if (isDir(specsDir)) {
       const { readdirSync } = await import("node:fs");
       for (const cap of readdirSync(specsDir)) {

package/src/lib/scan.js

@@ -5,15 +5,23 @@ import { today } from "./dates.js";
 import { parseFrontmatter } from "../commands/skill.js";
 import { parseOperation, parseCapabilityFromDelta } from "../commands/change.js";
 
-// Parse a spec-style header line: **Name:** value
+// Parse a metadata header line, tolerating BOTH conventions:
+//   **Name:** value        (spec style)
+//   - **Name:** value      (ADR / proposal / intake style)
+// The leading "- " is optional so a one-character convention slip (an
+// agent hand-authoring an ADR with the bare spec form, or vice versa)
+// still parses instead of silently falling back to a default value.
+const HEADER_PREFIX = "(?:-\\s+)?";
+
+// Parse a spec-style header line: **Name:** value (dash optional).
 export function specHeader(text, name) {
-  const m = text.match(new RegExp(`^\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
   return m ? m[1].trim() : null;
 }
 
-// Parse an ADR/proposal-style header line: - **Name:** value
+// Parse an ADR/proposal-style header line: - **Name:** value (dash optional).
 export function listHeader(text, name) {
-  const m = text.match(new RegExp(`^-\\s+\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
+  const m = text.match(new RegExp(`^${HEADER_PREFIX}\\*\\*${name}:\\*\\*\\s+(.+)$`, "m"));
   return m ? m[1].trim() : null;
 }
 

package/templates/AGENTS.md.template

@@ -56,6 +56,34 @@ native multi-agent development. The full framework artifacts live under
 - Archived changes in `.doctrina/changes/archive/` are out of the default
   read path; consult only when explicitly debugging history.
 
+## Artifact invariants (verbatim — `doctrina validate` enforces these)
+
+Scaffold artifacts with the CLI (`doctrina decision new`, `doctrina work`),
+which writes from the canonical templates. Do NOT hand-author these files
+from memory. If you must write one by hand, match these exactly:
+
+- **Metadata headers come in two forms — do not mix them up:**
+  - ADRs, change proposals, and the intake use **list items**:
+    `- **Status:** accepted`, `- **Date:** 2026-06-13`.
+  - Specs use **bare bold** (no leading `- `):
+    `**Status:** active`, `**Version:** 0.1.0`.
+  Match the template for the artifact you are writing.
+- **ADR filename** must be `NNNN-slug.md` — four digits, e.g.
+  `0001-jwt-algorithm.md`. `ADR-001-...md` or `1-...md` is invisible to
+  `doctrina decision accept`, the index, and the orphan check.
+- **Change folder** at `.doctrina/changes/<id>/` must contain a file named
+  exactly `proposal.md` (not `change.md`, not `README.md`). `tasks.md` and
+  `design.md` are optional siblings.
+- **Spec** lives at `.doctrina/specs/<capability>/spec.md` and its
+  `**Version:**` header must equal the `version` recorded for it in
+  `.doctrina/index.json`.
+- **Every artifact on disk** must be registered in `.doctrina/index.json`,
+  and every path in `index.json` must exist on disk. Update the index in
+  the same change that adds or moves a file.
+
+Always finish by running `doctrina validate` and resolving every `error:`
+before considering work done.
+
 ## How to read context efficiently
 
 1. Read this `AGENTS.md`.