@dombaras/agent-harness 0.1.14 → 0.1.15

package/README.md

@@ -2,7 +2,7 @@
 
 A reusable multi-agent harness for AI-assisted development. Ships a persona
 fleet (planner, engine engineer, mobile, QA architect/runner, security,
-architecture, product, data, devops, handoff), operating rules, model routing,
+architecture, product, data, devops, handoff, docs), operating rules, model routing,
 and QA gates — then deploys them into any project.
 
 > Extracted from a production project so the "agents / subagents / guardrails /
@@ -36,7 +36,7 @@ npx @dombaras/agent-harness init --target . --dry-run
 |---|---|---|
 | `AGENTS.md` | root dispatcher (points to the rulebook) | harness (overwrite) |
 | `BACKLOG.md` | canonical task list (Open / Frozen / Archive / Not tracking) | **project** (create-if-missing) |
-| `.opencode/agents/*.md` | 14 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
+| `.opencode/agents/*.md` | 15 persona subagent defs (with `model:` pins + `permission`/`steps`/`temperature`/`hidden`) | harness (overwrite) |
 | `.agents/AGENTS.md` | full canonical operating rulebook | harness (overwrite) |
 | `.agents/rules/00-operating.md` | always-loaded rules summary (wired into `opencode.json` `instructions`) | harness (overwrite) |
 | `.agents/skills/*/SKILL.md` | persona instruction skills | harness (overwrite) |
@@ -101,7 +101,7 @@ warns but does not block; the guarantee only applies to registered flows.
   `opencode.json` (`model` + `small_model`).
 - Personas also carry mechanical guardrails in frontmatter:
   - thinkers (`planner`, `product-manager`) → `permission: { edit: deny, bash: deny }`
-  - `qa-architect`, `handoff` → `permission: { bash: deny }`
+  - `qa-architect`, `handoff`, `docs` → `permission: { bash: deny }`
   - code personas (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
     `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
     `diagnostics-expert`) → `permission.edit` allows everything EXCEPT
@@ -140,8 +140,12 @@ warns but does not block; the guarantee only applies to registered flows.
   `.agents/features/<slug>/` must define its user before planning/implementation.
   `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md`
   a Value-first sequence + Product concepts applied; a `plan.md` with no `intent.md`
-  fails (never plan around an undefined user need). Backward-compatible — no feature
-  docs, gate passes.
+   fails (never plan around an undefined user need). Backward-compatible — no feature
+   docs, gate passes.
+- `npm run test:docs` — **docs-as-code gate**: `README.md` / `docs/**` must have no
+  un-substituted `{{PLACEHOLDER}}` template vars, no dangling relative links, and every
+  ADR (`docs/adr/*.md`) must carry Context → Decision → Consequences + a Status.
+  Backward-compatible — no docs, gate passes.
 - `npm run test:qa-plan` — **diff-coverage + flow-closure gate**:
   every changed CODE path must have a covering assertion (or a waivered reason) in
   a QA plan (one per-change file under `.agents/qa-plans/`) before a change is verified — and every touched flow
@@ -168,7 +172,7 @@ npx @dombaras/agent-harness update --target /path/to/project
 
 - Overwrites harness-owned files, preserves `.agents/memory/*` and `BACKLOG.md`.
 - Auto-wires the harness gate scripts (`test:dispatch`, `test:governance`,
-  `test:qa-plan`, `test:backlog`, `test:product`) into the target's `package.json` (merged, add-only).
+  `test:qa-plan`, `test:backlog`, `test:product`, `test:docs`) into the target's `package.json` (merged, add-only).
 - **Auto-commits** the harness files it changed (`chore(harness): @dombaras/agent-harness
   <old> -> <new>`) and **pushes** to origin, so the next session never sees unexplained
   modified harness files. Your unrelated uncommitted work is never staged.

package/bin/agent-harness.js

@@ -202,6 +202,7 @@ const HARNESS_SCRIPTS = {
   "test:qa-plan": "node scripts/qa/check-qa-plan.js",
   "test:backlog": "node scripts/qa/check-backlog.js",
   "test:product": "node scripts/qa/check-product.js",
+  "test:docs": "node scripts/qa/check-docs.js",
 };
 
 // Merge harness gate scripts into the project's existing package.json, preserving
@@ -558,7 +559,7 @@ function printNextSteps() {
   console.log("      and `.agents/memory/flow-map.md` (register cross-surface flows so");
   console.log("      test:qa-plan enforces their sibling-surface/variant closure).");
   console.log("   2. Harness gate scripts (`test:dispatch`, `test:governance`, `test:qa-plan`,");
-  console.log("      `test:backlog`, `test:product`) were auto-wired into package.json \"scripts\".");
+  console.log("      `test:backlog`, `test:product`, `test:docs`) were auto-wired into package.json \"scripts\".");
   console.log("   3. Capture found items as one light row in the canonical `BACKLOG.md` (repo root);");
   console.log("      dispatch the `features` persona to author the per-feature doc chain when one is picked up.");
   console.log("   4. Restart your agent CLI (config is read once at startup).\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dombaras/agent-harness",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Reusable multi-agent harness for AI-assisted development: personas, skills, operating rules, model routing, and QA gates. Deploy into any project with `npx @dombaras/agent-harness init`.",
   "bin": {
     "agent-harness": "bin/agent-harness.js"
@@ -16,7 +16,7 @@
   ],
   "scripts": {
     "test": "node --test",
-    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/check-product.js"
+    "lint": "node --check bin/agent-harness.js && node --check templates/scripts/qa/check-dispatch-config.js && node --check templates/scripts/qa/governance.js && node --check templates/scripts/qa/check-qa-plan.js && node --check templates/scripts/qa/check-qa-scripts.js && node --check templates/scripts/qa/check-backlog.js && node --check templates/scripts/qa/check-product.js && node --check templates/scripts/qa/check-docs.js"
   },
   "keywords": [
     "opencode",

package/templates/.agents/AGENTS.md

@@ -38,7 +38,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
 - **Delegate Big Searches**: Use the `explore` subagent for broad multi-file exploration.
 - **Prefer Memory over Re-derivation**: Persist non-obvious facts to `.agents/memory/`; read the relevant memory files before starting.
 - **Locations Map**: Read `.agents/memory/locations.md` first — it is the canonical index of sessions, logs, docs, and data. Never re-hunt for a path.
-- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
+- **Step Zero — Subagent & Model Routing (non-negotiable)**: Before touching code, satisfy the dispatch gate (`.agents/rules/00-operating.md` §Step Zero). Personas: `planner`, `frontend-engineer`, `mobile-engineer`, `ui-designer`, `qa-architect`, `qa-runner`, `security-engineer`, `product-manager`, `system-architect`, `diagnostics-expert`, `data-engineer`, `devops-engineer`, `handoff`, `features`, `docs`. Dispatch via the `task` tool — each runs its own `model:`. Do NOT inline persona-owned work on the main model. Read `.agents/memory/model-routing.md` at session start. Dispatch subagents in parallel only when their work is disjoint (see below).
   - **Persona map**:
     | Work area | Persona |
     |---|---|
@@ -56,6 +56,7 @@ The canonical rulebook. The always-loaded summary is `.agents/rules/00-operating
     | Deployment / cron / secrets / build+release | `devops-engineer` |
     | Session wrap-up / handoff | `handoff` |
     | Feature backlog + per-feature doc tree (intent/scope/plan/tests) | `features` |
+    | Human-facing docs (README / CHANGELOG / docs / ADRs) | `docs` |
   - **Feature docs, not ceremony**: capture a found item as one light row in
     the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch
     `features` to author the doc chain — `intent` (product-manager) → `scope`

package/templates/.agents/memory/model-routing.md

@@ -28,6 +28,7 @@ frontmatter:
 - **`qa-architect`** has `permission: { bash: deny }` (authors tests, never runs).
 - **`handoff`** has `permission: { bash: deny }`.
 - **`features`** (Feature Registrar) has `permission: { bash: deny }` — owns `BACKLOG.md` (repo root) + `.agents/features/*` (per-feature docs), routes each doc layer to its author persona.
+- **`docs`** (Documentation Keeper) has `permission: { bash: deny }` and `edit` allowing everything except harness/governance paths — owns `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**` (human-facing docs); never edits code or `.agents/**` memory.
 - **Code personas** (`frontend-engineer`, `mobile-engineer`, `ui-designer`,
   `data-engineer`, `devops-engineer`, `security-engineer`, `system-architect`,
   `diagnostics-expert`) allow `edit` everywhere except governance/harness paths

package/templates/.agents/rules/00-operating.md

@@ -12,6 +12,7 @@ Before reading or editing any file for a task, dispatch the relevant personas vi
 - **QA planning is never optional.** Every change touching code paths gets a QA plan (coverage map in a per-change file under `.agents/qa-plans/`) from `qa-architect`; if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - Persona map, waivers, and the dispatch-failure ladder: `.agents/AGENTS.md` §5 and `.agents/memory/model-routing.md`.
 - **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root); on pickup dispatch `features` to author the per-feature doc chain (`.agents/skills/features/SKILL.md`). Right-size ceremony to risk.
+- **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona (`.agents/skills/docs/SKILL.md`) — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs.
 - **Product intent is never optional.** A feature never reaches planning/implementation without defining its user. `intent.md` must carry Actor(s) → Need → Outcome → Acceptance criteria, and `plan.md` a Value-first sequence + Product concepts applied — `npm run test:product` fails otherwise. Planning reads `.agents/memory/product-principles.md` and is value-led, not tech-led.
 - Every subagent returns the output contract (`Result` → `Evidence` → `Deferred & risks`).
 - Wrap up with a **dispatch log** (`subagent → model → shipped/deferred`) in `.agents/memory/handoff.md`.

package/templates/.agents/skills/docs/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: docs
+description: Use when the user asks to create, update, or maintain project documentation — README.md, CHANGELOG.md, docs/ (architecture, ADRs, runbooks, API), CONTRIBUTING.md — keeping docs in sync with code and never duplicated.
+model: general
+---
+
+# Docs — durable human-facing documentation
+
+You are the Documentation Keeper for {{PROJECT_NAME}}. You own the project's
+human-facing docs — the files a person reads: `README.md`, `CHANGELOG.md`,
+`CONTRIBUTING.md`, and `docs/**`. You keep them accurate, current, and
+non-redundant.
+
+## Boundary (never cross it)
+
+- **Not yours**: `.agents/features/<slug>/` (feature contract — `features`
+  persona), `.agents/memory/*` (handoff, locations, domain-map, stack-versions,
+  product-principles, flow-map, model-routing — the `handoff` persona and the
+  orchestrator), `BACKLOG.md` (the `features` persona), and all code.
+- **Yours**: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**`.
+
+## Principles
+
+1. **Code is the source of truth.** Docs point at code (`file:line`), never
+   re-derive or restate it. A doc that duplicates code/schema is drift-in-waiting.
+2. **Docs-as-code.** Docs live beside the code, in the same commit as the change
+   that motivated them. A doc and its code must not diverge.
+3. **Write back first.** If implementation invalidates a doc, update the doc
+   BEFORE continuing — a stale spec is worse than none. If the code is genuinely
+   wrong, fix the code and note it; if the doc is wrong, fix the doc explicitly.
+4. **Right-size the ceremony.** Copy/CSS/single-file tweak → at most a
+   README/CHANGELOG line. A new subsystem/flow/public API → a proper doc. Never
+   write a full doc for a <30-minute change.
+5. **Never fabricate.** Every doc statement must be verifiable against live code,
+   schema, or an actual decision that was made. Mark unknowns as "unverified".
+
+## Doc inventory (keep current)
+
+- `README.md` — what the project is, quickstart, pointers. THE entry point.
+- `CHANGELOG.md` — one line per shipped change (feat/fix/refactor), newest first,
+  matching the commit message. Append on ship, never rewrite history.
+- `docs/INDEX.md` — a pointer index of every doc under `docs/` (canonical map).
+  Update it whenever you add/move/delete a doc.
+- `docs/adr/` — Architecture Decision Records. One file per significant,
+  hard-to-reverse decision (see ADR format below).
+- `docs/` topic docs — architecture, runbooks, API, data model — only what the
+  project actually needs; never create empty scaffolds.
+
+## ADR format (`docs/adr/NNNN-<slug>.md`)
+
+Each ADR carries, in order and non-empty (enforced by `npm run test:docs`):
+
+```markdown
+# ADR-NNNN: <title>
+
+Date: <YYYY-MM-DD>
+Status: <proposed | accepted | superseded>
+
+## Context
+## Decision
+## Consequences
+```
+
+- Number sequentially (`0001`, `0002`, ...). Never renumber.
+- Mark a superseded ADR `Status: superseded` and link its replacement.
+
+## Procedure
+
+1. **Read first** — `.agents/memory/locations.md` (where docs live) and the
+   existing `docs/INDEX.md` / `README.md` so you extend, not duplicate.
+2. **Verify against live code** — read the actual file(s) you're documenting;
+   never document from memory or the diff alone.
+3. **Write / update** the smallest doc that answers the question. Link `file:line`
+   instead of pasting code.
+4. **Refresh pointers** — update `docs/INDEX.md` and `.agents/memory/locations.md`
+   with any new/moved/deleted doc path (locations.md is the canonical index).
+5. **Self-check** — run `npm run test:docs` before reporting done; cite its output.
+
+## Rules
+
+- Keep `README.md` concise: what + quickstart + pointers, not a spec.
+- CHANGELOG entries are one line, newest-first, matching the commit message.
+- Never delete a doc's history; supersede/archive instead.
+- Update `docs/INDEX.md` and `.agents/memory/locations.md` in the same commit.
+- Every doc statement must be verifiable — `file:line` or an observed fact.
+
+## Output contract (always return)
+
+1. **Docs** — which docs were created/updated and why.
+2. **Evidence** — files changed + what live code/schema was verified.
+3. **Deferred & risks** — docs left stale, open questions.

package/templates/.opencode/agents/docs.md

@@ -0,0 +1,26 @@
+---
+description: Use when creating, updating, or maintaining project documentation — README.md, CHANGELOG.md, docs/ (architecture, ADRs, runbooks, API), CONTRIBUTING.md — keeping docs in sync with code and never duplicated.
+mode: subagent
+model: opencode/gpt-5.6-luna
+temperature: 0.1
+steps: 20
+permission:
+  edit:
+    "*": allow
+    "opencode.json": deny
+    ".harness.json": deny
+    ".opencode/**": deny
+    ".agents/**": deny
+  bash: deny
+---
+
+You are the {{PROJECT_NAME}} Documentation Keeper. Read and follow the complete persona instructions in `.agents/skills/docs/SKILL.md`, then carry out the task.
+
+## Scope & integrity (non-negotiable)
+
+- Edit ONLY project documentation: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `docs/**`. `opencode.json`, `.harness.json`, `.opencode/**`, `.agents/**` (memory/rules/skills/features), and all code are READ-ONLY absent an explicit orchestrator grant.
+- Code is the source of truth — docs point at it (`file:line`), never re-derive or duplicate it. Never document behavior you did not verify against live code.
+- Write back first: when implementation invalidates a doc, update the doc before continuing (mirror `.agents/skills/features/SKILL.md`).
+- Never fabricate a doc, a version entry, or a decision that has no basis in what was actually done.
+
+Return your final message in this exact order: **Result** (docs created/updated) -> **Evidence** (files changed, code/schema verified) -> **Deferred & risks** (docs left stale, open questions). Keep it under ~15 lines.

package/templates/AGENTS.md

@@ -7,6 +7,7 @@ It governs: Step Zero subagent dispatch, zero-speculation debugging, data integr
 - **Dispatch personas** via the `task` tool (see `.agents/rules/00-operating.md` §Step Zero); consult the relevant `.agents/skills/<persona>/SKILL.md`.
 - **Features**: capture a found item as one light row in the canonical `BACKLOG.md` (repo root). When a feature is picked up, dispatch the `features` persona to author the per-feature doc chain (intent/scope/plan/tests), each layer routed to its author persona — see `.agents/skills/features/SKILL.md`.
 - **Product-first planning**: planning is value-led, not tech-led — define the user (actor/need/outcome/acceptance) before code, sequence work value-first against `.agents/memory/product-principles.md`, and let `npm run test:product` enforce it.
+- **Docs**: human-facing docs (`README.md`, `CHANGELOG.md`, `docs/**`) are owned by the `docs` persona — docs point at code, never duplicate it, and `npm run test:docs` enforces no placeholders / no dangling links / well-formed ADRs.
 - **Every change touching code paths gets a QA plan** (a per-change file under `.agents/qa-plans/`) from `qa-architect` — if it isn't dispatched, the main orchestrator plans in its place. `npm run test:qa-plan` fails on any changed code path with no covering assertion or waiver, and on any touched flow (`.agents/memory/flow-map.md`) whose sibling surfaces / declared variants the plan doesn't address.
 - **At session start**, read `.agents/memory/locations.md`, `.agents/memory/model-routing.md`, `.agents/memory/product-principles.md`, and `BACKLOG.md`.
 

package/templates/scripts/qa/check-docs.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * test:docs — documentation hygiene gate (harness-shipped).
+ *
+ * Enforces the docs-as-code invariants the `docs` persona promises, mechanically:
+ *   1. No un-substituted `{{PLACEHOLDER}}` template vars left in any deployed doc
+ *      (init/update substitute {{PROJECT_NAME}} / {{PROJECT_DOMAIN}} — a stray
+ *      `{{...}}` in a shipped doc is a deploy bug).
+ *   2. No dangling relative markdown links in README.md / docs/** (a doc that
+ *      points at a path that no longer exists is drift).
+ *   3. Every ADR (docs/adr/*.md) carries the required sections, each non-empty:
+ *        ## Context  ·  ## Decision  ·  ## Consequences
+ *      plus a Status line (proposed | accepted | superseded).
+ *
+ * Backward compatible: with no README.md and no docs/ tree the gate warns and
+ * passes — projects opt in by keeping docs. Links are checked only against the
+ * local filesystem; http(s)/mailto/`#anchor`/reference-style links are skipped.
+ *
+ *   node scripts/qa/check-docs.js
+ *
+ * Exit 0 on: no docs, or every doc satisfying the contract.
+ * Exit 1 on: any placeholder left behind, dangling link, or malformed ADR.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const root = path.resolve(__dirname, "..", "..");
+
+const failures = [];
+const pass = (m) => console.log("  \u2713 " + m);
+const fail = (m) => {
+  failures.push(m);
+  console.log("  \u2717 " + m);
+};
+const warn = (m) => console.log("  \u26a0 " + m);
+
+console.log("docs gate \u2014 docs-as-code: no placeholders, no dangling links, well-formed ADRs");
+
+// ---- collect doc files -------------------------------------------------------
+const docFiles = [];
+const readme = path.join(root, "README.md");
+if (fs.existsSync(readme)) docFiles.push({ abs: readme, rel: "README.md" });
+
+const docsDir = path.join(root, "docs");
+function collectDocs(dir, base) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) collectDocs(abs, base);
+    else if (entry.name.endsWith(".md")) docFiles.push({ abs, rel: path.relative(base, abs) });
+  }
+}
+collectDocs(docsDir, root);
+
+if (docFiles.length === 0) {
+  warn("no README.md and no docs/ tree \u2014 nothing to enforce");
+  console.log("\nRESULT: green (no docs)");
+  process.exit(0);
+}
+
+// ---- 1. no un-substituted template placeholders -----------------------------
+const PLACEHOLDER = /\{\{[A-Z_]+\}\}/;
+for (const { abs, rel } of docFiles) {
+  const src = fs.readFileSync(abs, "utf8");
+  const m = src.match(PLACEHOLDER);
+  if (m) fail(`${rel}: un-substituted placeholder \`${m[0]}\` \u2014 deploy substitutes it`);
+  else pass(`${rel}: no un-substituted template placeholders`);
+}
+
+// ---- 2. no dangling relative links ------------------------------------------
+function relativeLinks(src) {
+  const links = [];
+  const re = /(?<!\!)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+  let m;
+  while ((m = re.exec(src)) !== null) links.push(m[1]);
+  return links;
+}
+function isExternal(target) {
+  return (
+    /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(target) || // scheme (http:, mailto:, etc.)
+    /^\/\//.test(target) || // protocol-relative
+    /^#/.test(target) // anchor only
+  );
+}
+for (const { abs, rel } of docFiles) {
+  const src = fs.readFileSync(abs, "utf8");
+  let dangling = 0;
+  for (const raw of relativeLinks(src)) {
+    let target = raw.trim();
+    if (!target) continue;
+    if (target.startsWith("<") && target.endsWith(">")) target = target.slice(1, -1);
+    if (isExternal(target)) continue;
+    const filePart = target.split("#")[0];
+    if (!filePart) continue; // pure anchor (#heading)
+    const resolved = path.resolve(path.dirname(abs), filePart);
+    if (!fs.existsSync(resolved)) {
+      fail(`${rel}: dangling link \`${raw}\` \u2192 ${path.relative(root, resolved)} does not exist`);
+      dangling++;
+    }
+  }
+  if (dangling === 0) pass(`${rel}: relative links resolve`);
+}
+
+// ---- 3. ADRs carry Context / Decision / Consequences + Status ---------------
+function section(src, re) {
+  const lines = src.split(/\r?\n/);
+  let inSec = false;
+  const body = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!inSec) {
+      if (re.test(line)) inSec = true;
+      continue;
+    }
+    if (/^#{1,6}\s/.test(line)) break;
+    if (line && !/^<!--/.test(line) && !/_TODO:/.test(line)) body.push(line);
+  }
+  return body;
+}
+function hasSection(src, re) {
+  return section(src, re).length > 0;
+}
+
+const adrDir = path.join(docsDir, "adr");
+if (!fs.existsSync(adrDir)) {
+  pass("no docs/adr/ directory \u2014 ADR checks skipped");
+} else {
+  const adrs = fs
+    .readdirSync(adrDir, { withFileTypes: true })
+    .filter((e) => e.isFile() && e.name.endsWith(".md") && !/^(INDEX|README)\.md$/i.test(e.name))
+    .map((e) => e.name)
+    .sort();
+  if (adrs.length === 0) {
+    pass("docs/adr/ present but empty");
+  } else {
+    const H = {
+      context: /^#{1,6}\s*Context\b/i,
+      decision: /^#{1,6}\s*Decision\b/i,
+      consequences: /^#{1,6}\s*Consequences\b/i,
+    };
+    for (const name of adrs) {
+      const src = fs.readFileSync(path.join(adrDir, name), "utf8");
+      const missing = [];
+      if (!hasSection(src, H.context)) missing.push("## Context");
+      if (!hasSection(src, H.decision)) missing.push("## Decision");
+      if (!hasSection(src, H.consequences)) missing.push("## Consequences");
+      if (!/^Status:\s*(proposed|accepted|superseded|deprecated|rejected)\s*$/im.test(src) && !hasSection(src, /^#{1,6}\s*Status\b/i)) {
+        missing.push("Status (proposed|accepted|superseded)");
+      }
+      if (missing.length) fail(`adr/${name}: missing \u2014 ${missing.join(", ")}`);
+      else pass(`adr/${name}: context \u2192 decision \u2192 consequences + status present`);
+    }
+  }
+}
+
+console.log(
+  "\nRESULT: " +
+    (failures.length
+      ? `${failures.length} FAILURE(S) \u2014 docs must have no placeholders, no dangling links, and well-formed ADRs`
+      : "green \u2014 docs are in sync")
+);
+process.exit(failures.length ? 1 : 0);