doctrina-cli 0.8.0 → 0.9.0

package/package.json

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

package/src/commands/skill.js

@@ -1,11 +1,12 @@
 import path from "node:path";
 import process from "node:process";
 import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import { exists, isDir, isFile, mkdirp, read, relPath, walk, write } from "../lib/fs-ops.js";
 import { locateTemplatesDir, substitute } from "../lib/templates.js";
 import * as idx from "../lib/index-json.js";
 import { today } from "../lib/dates.js";
-import { flagBool } from "../lib/args.js";
+import { flagBool, flagString } from "../lib/args.js";
 import { c } from "../lib/colors.js";
 import { suggest } from "../lib/suggest.js";
 
@@ -30,57 +31,91 @@ export async function run(positional, flags) {
 // Surface (and optionally scaffold) skills worth capturing (review 2026-06-27
 // passive-user feature #6). A skill exists so a hard-won lesson is not relearned
 // by the next agent/session; the framework otherwise never pulls you toward
-// writing one. `skill suggest` scans the archived changes for fix-shaped work —
-// the textbook case for a skill — and lists candidates whose lesson is not yet
-// captured. With --write it scaffolds a stub per candidate, pre-seeded from the
-// change so the human/agent only fills the body. Deterministic pattern match on
-// the archived folder name — a hint, never a decision (ADR 0005).
+// writing one. `skill suggest` scans for fix-shaped work — the textbook case for
+// a skill — from two deterministic sources and lists candidates whose lesson is
+// not yet captured: archived change proposals, and the git commit history
+// (ADR 0013). The archive only fills if a team runs the `doctrina change`
+// lifecycle, so without the git source `suggest` is inert in most repos. With
+// --write it scaffolds a stub per candidate, pre-seeded from the source so the
+// human/agent only fills the body. Both sources are a pattern match — a hint,
+// never a decision (ADR 0005); skills are still authored, never generated.
 const FIX_SHAPED = /(?:^|-)(fix|bug|hotfix|patch|parse|parsing|tolerate|workaround|race|deadlock|flaky|retry|escape|sanitize|sanitise)(?:-|$)/;
 
+// The same idea applied to a commit subject. Narrower than FIX_SHAPED on
+// purpose: a deliberate folder slug tolerates more noise than a free-form
+// subject line. Matches conventional fix-type prefixes (fix:, fix(scope):,
+// bug:, hotfix:, patch:, and the free-form "Fix the…") plus the strongly
+// fix-flavoured debugging keywords — never feat:/refactor:/docs:/chore:.
+const FIX_SHAPED_SUBJECT =
+  /^(?:fix|bug|hotfix|patch)\b|\b(?:tolerate|workaround|deadlock|flaky|race condition|retry|sanitiz|sanitis)/i;
+
+// How far back the git source looks when --since is not given, and how many
+// candidates we print before collapsing the rest into a "+N more" line.
+const GIT_LOG_LIMIT = 200;
+const MAX_SHOWN = 20;
+
 function skillSuggest(args, flags) {
   const projectRoot = process.cwd();
   ensureDoctrinaProject(projectRoot);
   const doWrite = flagBool(flags, "write", false);
+  const since = flagString(flags, "since");
 
-  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
   const skillsDir = path.join(projectRoot, ".doctrina", "skills");
   const existing = new Set(
     isDir(skillsDir) ? walk(skillsDir).filter((f) => f.endsWith(".md")).map((f) => path.basename(f, ".md")) : [],
   );
 
+  // Two deterministic sources, deduped by slug. `seen` guards against a lesson
+  // appearing twice (e.g. a fix committed and later archived as a change).
   const candidates = [];
+  const seen = new Set();
+
+  // Source 1 — archived change proposals with a fix-shaped folder name.
+  const archiveDir = path.join(projectRoot, ".doctrina", "changes", "archive");
   if (isDir(archiveDir)) {
     for (const name of readdirSync(archiveDir).sort()) {
       if (!isDir(path.join(archiveDir, name))) continue;
       const id = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
       if (!FIX_SHAPED.test(id)) continue;
       const slug = skillSlug(id);
-      if (existing.has(slug)) continue; // lesson already captured
+      if (existing.has(slug) || seen.has(slug)) continue; // captured or already queued
       const proposal = path.join(archiveDir, name, "proposal.md");
       const why = isFile(proposal) ? firstWhyLine(read(proposal)) : "";
-      candidates.push({ id, slug, why, archive: name });
+      seen.add(slug);
+      candidates.push({ id, slug, why, source: "change", from: name });
     }
   }
 
+  // Source 2 — fix-shaped commits in the git history (ADR 0013). Archive wins a
+  // slug collision: a `## Why` paragraph is a richer seed than a subject line.
+  for (const cand of gitFixCommits(projectRoot, { since, limit: GIT_LOG_LIMIT })) {
+    if (existing.has(cand.slug) || seen.has(cand.slug)) continue;
+    seen.add(cand.slug);
+    candidates.push(cand);
+  }
+
   if (candidates.length === 0) {
-    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/"));
-    console.log(c.gray("(skills are written by humans; this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
+    console.log(c.gray("no uncaptured fix-shaped lessons found in .doctrina/changes/archive/ or the git history"));
+    console.log(c.gray("(scans archived changes and fix-shaped commits — pass --since <ref> to widen the git window;"));
+    console.log(c.gray(" skills are written by humans, so this only surfaces candidates — `doctrina skill new <slug>` to author one)"));
     return 0;
   }
 
   if (!doWrite) {
     console.log(c.bold("Skill candidates") + c.gray(" — fix-shaped lessons not yet captured:"));
     console.log("");
-    for (const cand of candidates) {
-      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray("from " + cand.archive)}`);
+    for (const cand of candidates.slice(0, MAX_SHOWN)) {
+      console.log(`  ${c.cyan(cand.slug.padEnd(28))} ${c.gray(provenance(cand))}`);
       if (cand.why) console.log(`    ${c.gray(cand.why.slice(0, 90))}`);
     }
+    const hidden = candidates.length - MAX_SHOWN;
+    if (hidden > 0) console.log(c.gray(`  … +${hidden} more`));
     console.log("");
     console.log(c.gray(`${candidates.length} candidate${candidates.length === 1 ? "" : "s"}. Scaffold them: `) + c.cyan("doctrina skill suggest --write"));
     return 0;
   }
 
-  // --write: scaffold a stub per candidate, pre-seeded from the change.
+  // --write: scaffold a stub per candidate, pre-seeded from its source.
   const templatesDir = locateTemplatesDir();
   const tplPath = path.join(templatesDir, "skill.md.template");
   const tpl = read(tplPath);
@@ -97,7 +132,7 @@ function skillSuggest(args, flags) {
     let body = substitute(tpl, { SKILL_NAME: cand.slug });
     if (cand.why) {
       // Drop the originating lesson into the body so authoring is "fill", not "start".
-      body += `\n<!-- Candidate from change "${cand.id}". The lesson to capture:\n${cand.why}\n-->\n`;
+      body += `\n<!-- ${seedLabel(cand)}. The lesson to capture:\n${cand.why}\n-->\n`;
     }
     write(target, body, { force: false });
     idx.addSkill(index, {
@@ -118,6 +153,63 @@ function skillSuggest(args, flags) {
   return 0;
 }
 
+// One-line origin shown next to a candidate slug.
+function provenance(cand) {
+  return cand.source === "commit" ? `from commit ${cand.ref}` : `from ${cand.from}`;
+}
+
+// The label seeded into a scaffolded skill body so the author knows where the
+// lesson came from.
+function seedLabel(cand) {
+  return cand.source === "commit"
+    ? `Candidate from commit ${cand.ref}`
+    : `Candidate from change "${cand.id}"`;
+}
+
+// Source 2 for `skill suggest`: fix-shaped commits in the git history (ADR
+// 0013). Deterministic — a regex on the subject, never a read of the diff
+// (ADR 0005 semantic-fidelity ceiling). Returns [] silently when this is not a
+// git repo, git is absent, or the --since ref is unknown, so the command
+// degrades to archive-only rather than erroring.
+function gitFixCommits(projectRoot, { since, limit }) {
+  // US (0x1f) between fields, RS (0x1e) between records — robust against any
+  // newline or punctuation inside a subject or body.
+  const format = "%H%x1f%s%x1f%b%x1e";
+  const args = ["log", "--no-merges", `--format=${format}`];
+  if (since) args.push(`${since}..HEAD`);
+  else args.push("-n", String(limit));
+
+  const r = spawnSync("git", args, { cwd: projectRoot, encoding: "utf8" });
+  if (r.error || r.status !== 0 || !r.stdout) return [];
+
+  const out = [];
+  const seen = new Set();
+  for (const record of r.stdout.split("\x1e")) {
+    const [sha, subject = "", body = ""] = record.replace(/^\r?\n/, "").split("\x1f");
+    if (!sha || !sha.trim()) continue;
+    if (!FIX_SHAPED_SUBJECT.test(subject)) continue;
+    const slug = commitSlug(subject);
+    if (!slug || seen.has(slug)) continue; // first commit wins a duplicate lesson
+    seen.add(slug);
+    const firstBodyLine = body.split(/\r?\n/).map((l) => l.trim()).find(Boolean) ?? "";
+    out.push({
+      id: slug,
+      slug,
+      source: "commit",
+      ref: sha.trim().slice(0, 9),
+      why: subject.trim() + (firstBodyLine ? ` — ${firstBodyLine}` : ""),
+    });
+  }
+  return out;
+}
+
+// Derive a skill slug from a commit subject: drop a conventional-commit
+// "type(scope): " prefix, then reuse skillSlug for the lowercase/hyphenate/cap.
+function commitSlug(subject) {
+  const stripped = subject.replace(/^[a-z]+(?:\([^)]*\))?!?\s*:\s*/i, "");
+  return skillSlug(stripped.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, ""));
+}
+
 function skillSlug(id) {
   // Reuse the change id as the skill slug, trimmed to a sane length.
   const slug = id.replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
@@ -282,10 +374,13 @@ Subcommands:
   sync          Copy each skill's frontmatter description into
                 .doctrina/index.json so the index never drifts
                 from the frontmatter (single source of truth).
-  suggest [--write]
-                Surface fix-shaped lessons in the change archive whose
-                skill is not yet captured. --write scaffolds a stub per
-                candidate (pre-seeded from the change) to fill in.
+  suggest [--write] [--since <ref>]
+                Surface fix-shaped lessons not yet captured as skills,
+                from two sources: archived change proposals and the git
+                commit history (ADR 0013). --write scaffolds a stub per
+                candidate (pre-seeded from its source) to fill in.
+                --since <ref> scans commits in <ref>..HEAD instead of the
+                last 200 (e.g. --since v0.7.0).
 
 Skills are written by humans, not generated. See docs/en/skills.md
 for the design rationale and the distinction from specs / AGENTS.md /