@brainervirus/workit-core 7.3.0 → 7.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainervirus/workit-core",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "private": false,
   "description": "Workit shared core — task, policy, evidence, review, decision, worker, and writer state for agentic coding workflows",
   "keywords": [

package/skills/workit-retro/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: workit-retro
+description: Find repeated friction in recent sessions; propose cited fixes ranked by enforcer strength, never applied. Use for retro.
+disable-model-invocation: true
+---
+
+# Retro: turn repeated friction into enforcers
+
+User-invoked: offer it, never start it yourself. Run it after a session, PR,
+stack or fan-in, including ones that went well; a smooth session still shows
+where agents searched too long, worked around a tool or re-ran a check. Retro
+proposes and stops. Nothing changes until the user approves.
+
+1. **Scope.** Default: this repository's work since the last retro (its
+   `retro:` row in `workit ledger list --type decision`), else the last ~10
+   sessions. State the window in one line.
+2. **Read through workit, cheapest first.** Every finding cites these:
+   - `workit ledger list --last 200`: rulings (ambiguities the agent had to
+     settle), failed or self verdicts, handoffs, check runs, CI reruns.
+   - `workit pr status --pr <n>` for each recent PR: threads, failing checks.
+   - `git log --oneline -50`, plus reverts and fixups after review.
+   - `workit knowledge lint`: today's AGENTS.md and need-based files.
+   - Session transcripts **only if the user opts in**, and only this
+     workspace's (`references/sources.md`). Never read other projects.
+
+   Cite by location (ledger row, PR, commit, session file and line). Never
+   copy secrets, tokens or personal data from any source into the report.
+3. **Group into classes.** Navigation cost (many searches before the right
+   file, a stale doc followed), repeated mistakes, workarounds (a hand-run
+   command where a verb exists, a skipped step), unstable checks (the same
+   `workit check <name>` red then green with no change). A class needs **2 or
+   more cited occurrences**; a one-off is not a learning.
+4. **Name the strongest enforcer that works**, strongest first: architecture
+   or types (the mistake cannot be written) > lint rule > configured check
+   (`workit.checks.json`, `workit check <name>`) or CI job > test >
+   `CODING_STANDARDS.md` (judgment the reviewer reads) > AGENTS.md pointer
+   (navigation only). A mechanical rule gets a check, not prose: a check can
+   fail, a sentence cannot. From types to test, the proof is that the new
+   enforcer fails on the cited past mistake. A rule whose mistake can no
+   longer happen is deleted.
+5. **Upstream.** When a workit skill, verb or hook caused the friction,
+   propose an issue or PR on BrainerVirus/workit. Never fork a local copy.
+   The issue shows the workit behavior in a minimal synthetic reproduction:
+   no private repo name, path, code, ledger text, PR or thread quote, or
+   transcript. Show the exact draft body; file it only after the user approves.
+6. **Bloat guards.** AGENTS.md stays within 8 KB: each addition names what it
+   removes. Create `CODING_STANDARDS.md` or `GLOSSARY.md` only in the same
+   edit as its first real entry, never as a scaffold. Edit steering text by
+   `references/steering.md`; `workit knowledge lint` passes after the slice.
+7. **Report one ranked list, then stop:** Accepted (proposed), Backlog,
+   Dropped, each with its citations, enforcer and reason. Each approved item
+   becomes a normal slice (workit-implement, then workit-ship), a tracker
+   issue, or `.out-of-scope/<concept>.md` when rejected and likely to return.
+   Record the user's answer so the next retro starts there:
+   `workit ledger decision "retro: <accepted ids>" --why "<window>"`.
+
+## Example
+
+Bad: "Agents seem lost in the build. Added 'read the build docs carefully' to
+AGENTS.md." One vague occurrence, no citation, a no-op line, auto-applied.
+
+Good: "Navigation, 3 occurrences (rulings 12, 19; PR #88 thread): agents sought
+check names in package.json, missing `workit.checks.json`. Enforcer: AGENTS.md
+pointer, +74 bytes, minus the stale Commands paragraph (-210). Unstable check,
+2 occurrences (ledger rows 31, 44: `e2e` red then green on one SHA): a debug
+slice to fix the check. Approve?"
+
+## Check
+
+```sh
+workit knowledge lint   # exit 0 before and after each approved slice
+```

package/skills/workit-retro/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Codex: user-invoked only (the counterpart of disable-model-invocation).
+policy:
+  allow_implicit_invocation: false

package/skills/workit-retro/references/sources.md

@@ -0,0 +1,35 @@
+# Session transcripts (opt-in, this workspace only)
+
+Transcripts are the most expensive source and can hold private material. Read
+them only after the user says yes to a question such as "Also read the last 10
+session transcripts for this workspace? (local files, read-only)". The default
+is no: the ledger, `pr status` and git are enough for most retros.
+
+## Where they live
+
+Typical locations; confirm each exists. Resolve the path from this workspace's
+absolute path, never with a wildcard across projects. If a host's layout
+differs from the one below, say so and skip it rather than search wider.
+
+| Host | Location |
+| --- | --- |
+| Claude Code | `~/.claude/projects/<folder>/*.jsonl`, one folder per path from `git worktree list`: the absolute path with every `/` and `.` replaced by `-`. Compute each folder name; never glob for it |
+| Codex | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`. To filter, parse only line 1 (`session_meta`) and read only its `cwd` field; skip files whose `cwd` is not this workspace without reading or reporting anything else from them |
+| Cursor | `~/.cursor/projects/<workspace slug>/agent-transcripts/` |
+| Pi | `~/.pi/agent/sessions/--<workspace path, / replaced by ->--/*.jsonl` |
+| OpenCode | this project's sessions from `opencode session list`, read with `opencode export <id>` |
+
+Linked worktrees of the same repository count as this workspace; other
+repositories never do.
+
+## How to read them
+
+- Newest first, at most the agreed number of sessions.
+- On a host with subagents, one read-only analyst per lens, each returning
+  only cited occurrences (session file plus line or message index):
+  - navigation: searches and reads before the right file was found, stale docs
+    followed;
+  - tool economy: hand-run commands where a `workit` verb exists, repeated
+    reads of the same file, long outputs nobody used;
+  - repeated work: the same fix or check redone, a step undone later;
+  - request conflicts: instructions the agent had to reconcile or ask about.

package/skills/workit-retro/references/steering.md

@@ -0,0 +1,39 @@
+# Editing steering text (AGENTS.md, CODING_STANDARDS.md, skills)
+
+Steering text is paid for on every session that reads it. Each line must
+change what an agent does; everything else is cost.
+
+## Write
+
+- **Point, do not copy.** Link the file or name the command; never paste its
+  content. A pointer says when to follow it: "Read before editing a hook:
+  `docs/agents/hosts.md`".
+- **Say what done looks like.** "Run `bun run check`; it must exit 0" beats
+  "make sure everything works".
+- **Concrete over adjectives.** A command, a path, a number. Prefer the action
+  to take over a list of things to avoid.
+- **One rule, one home.** A rule with an enforcer (type, lint, check, test)
+  appears in steering text at most as a pointer to that enforcer. The same
+  sentence in AGENTS.md and CODING_STANDARDS.md is a defect
+  (`duplicate-rule`).
+- **Judgment goes to CODING_STANDARDS.md**, which the reviewer reads; only
+  navigation goes to AGENTS.md.
+
+## Cut
+
+- **No-ops.** Delete lines that would not change any behavior if removed:
+  "be thorough", "write clean code", "keep it concise", "follow best
+  practices".
+- **Session residue.** No notes about one session, no implementation detail
+  the code already shows, no `path:line` references (they go stale).
+- **Dead rules.** A rule whose mistake can no longer happen (a type or check
+  now prevents it) is deleted, not kept "for context".
+
+## Budget
+
+- AGENTS.md stays within 8 KB (`workit knowledge lint`, rule
+  `agents-budget`). A proposal that adds text names what it removes, or shows
+  the byte count still holds.
+- A need-based file (`CODING_STANDARDS.md`, `GLOSSARY.md`) is created in the
+  same edit as its first real entry. Headers-only or "TBD" files fail the lint
+  (`scaffold-file`).

package/skills/workit-review/SKILL.md

@@ -18,8 +18,9 @@ independent; `type-check-only` never proves a behavior change.
 3. Judge two axes separately, never merged or re-ranked:
    - **Spec:** does the diff do what the acceptance says? Missing, creep or
      wrong; quote the line.
-   - **Standards:** repo rules first, then a smell baseline (unclear name, long
-     function, duplicated logic, leaky abstraction). Judgment only; lint owns nits.
+   - **Standards:** repo rules first (`CODING_STANDARDS.md` when present),
+     then a smell baseline (unclear name, long function, duplicated logic,
+     leaky abstraction). Judgment only; lint owns nits.
 4. **Tests:** `workit test-audit --diff`. Would each new test fail if the
    behavior broke? Triage with workit-test-audit.
 5. **Blast radius:** for each touched contract, caller, config or migration,

package/skills/workit-shape/references/knowledge.md

@@ -10,11 +10,14 @@ user asks for one, say which trigger fired, and let the user decline.
 | Plan | more than one slice with dependencies, or work that will be resumed by someone else | `docs/<topic>/plan.md`, next to the spec |
 | ADR | the choice is hard to reverse **and** surprising **and** a real trade-off (all three) | `docs/adr/NNNN-<slug>.md` |
 | Glossary entry | a project term was ambiguous and you resolved it | `GLOSSARY.md` (create lazily) |
+| Coding standard | a judgment-call rule a reviewer must check, recurring twice (workit-retro); a mechanical rule gets a check instead | `CODING_STANDARDS.md` (create lazily) |
 | Out of scope | a request was rejected and is likely to come back | `.out-of-scope/<concept>.md` |
 
 Never: a spec for a one-file mechanical fix, a plan that restates the spec,
 file paths or line numbers in a spec (they go stale), a glossary entry for a
 general programming term.
+Create a lazy file only in the same edit as its first real entry, never as a
+headers-only or TBD scaffold (`workit knowledge lint` flags one).
 
 ## Spec (scaled to the work)
 

package/skills/workit-ship/SKILL.md

@@ -53,7 +53,8 @@ the base keeps moving, or after 3 failed fix attempts on the same check.
 6. **Verified.** After the last push a non-author records a verdict
    (workit-review); `pr status` showing self-reviewed is not verified. Land only when granted: `workit stack land` (the
    contiguous verified run from the root) or `workit pr merge`.
-7. **Observe it landed:** `workit verify-delivery pr` or `merge`.
+7. **Observe it landed:** `workit verify-delivery pr` or `merge`. At any endpoint
+   (stack land, fan-in too), after a failed verdict or a check red 3+ times: offer `/wk-retro`.
 
 ## Example
 

package/src/core/methods.ts

@@ -89,7 +89,7 @@ export function selectMethods(policy: Policy, capabilities: Capability[]): Selec
 export const invariantBootstrap = (): string =>
   `
 Workit is optional coordination and proof tooling around the host: you decide
-what and whether, the \`workit\` CLI does how and records what it observed.
+what and whether, the CLI does how and records what it observed.
 Native host allow/ask/deny, sandbox and org rules stay authoritative. Never
 switch paths to evade a denial, never claim enforcement a host cannot provide,
 and never fabricate an approval or verdict. A question answer is not
@@ -110,8 +110,8 @@ Autonomy contract:
   never edit workspaces.json or route around a grant_required.
 - Ask only for a product or preference choice, or for authority you lack, with
   your recommended answer. Facts are yours: read, run or prototype.
-- Label claims measured (you ran it this session and saw the result),
-  inferred, or guess. Prose is a note: only a configured check the CLI ran
+- Label claims measured (you ran it this session and saw it), inferred, or
+  guess. Prose is a note: only a configured check the CLI ran
   (\`workit check <name>\`) satisfies a gate; an ad-hoc
   \`workit check -- <cmd>\` never does.
 - Author is not verifier: your own verdict is \`--self\` (after an observed
@@ -123,23 +123,21 @@ Autonomy contract:
   reconcile every requested item and observe it (\`workit verify-delivery\`).
 
 CLI first: if a step has one right answer, use the \`workit\` verb instead of
-hand-running git, gh or glab: check, git, pr, ci, stack, verify-delivery,
-ledger, handoff, test-audit (\`workit help <verb>\`; without \`workit\` on
-PATH, \`npx -y @brainervirus/workit-cli\`). \`busy\` is retryable
-(\`workit doctor --fix-lock\` clears a dead lock); \`blocked\` names its unblock.
+hand-running git, gh or glab (\`workit git|pr|ci|check\`; \`workit help\` lists
+the rest; without \`workit\` on PATH, \`npx -y @brainervirus/workit-cli\`).
+\`busy\` is retryable (\`workit doctor --fix-lock\` clears a dead lock).
 The task families (task, policy, evidence, finding, decision, worker, state)
 are optional continuity for tracked work; each branch has one implicit task
 that the first recording creates, and a solo edit needs no task. A decision
 records a user choice; it never authorizes an effect. Judge work once with
 \`workit policy assess --judge risk= behavior= product-choice= plan=\`; an
 open choice or missing plan blocks edits until recorded.
-Omit revisions; a revision_conflict means one you passed is stale, so re-read.
+Omit revisions; on a revision_conflict, re-read.
 Across repositories, bind each item to its checkout, branch and endpoint,
 resolve competing targets before a mutation, and reconcile an uncertain
 external effect before retrying it.
 
-Mid-task input: answer a quick question in place, fold an adjustment in, and
-never silently drop or resume an objective (workit-continue).
+Mid-task: never silently drop or resume an objective (workit-continue).
 
 Skills: load the skill, never act from memory of it (slash aliases /wk-<name>).
 - brainstorm, plan, spec, grill, should we: workit-shape
@@ -153,4 +151,5 @@ Skills: load the skill, never act from memory of it (slash aliases /wk-<name>).
 - deslop, slop, dead code: workit-deslop
 - fan out, parallelize, parallel agents, swarm: workit-fanout
 - verify the app, smoke test, prove it works: workit-verify-app
+- retro (user-invoked; offer it): workit-retro
 `.trim();

package/src/core/skill-manifests.ts

@@ -13,6 +13,7 @@ export const WORKIT_METHOD_SKILLS = [
   "workit-deslop",
   "workit-fanout",
   "workit-verify-app",
+  "workit-retro",
 ] as const;
 
 export type WorkitSkill = (typeof WORKIT_METHOD_SKILLS)[number];
@@ -31,6 +32,7 @@ export const WORKIT_SKILL_ALIASES = {
   "wk-deslop": "workit-deslop",
   "wk-fanout": "workit-fanout",
   "wk-verify-app": "workit-verify-app",
+  "wk-retro": "workit-retro",
 } as const satisfies Record<string, WorkitSkill>;
 
 /**
@@ -50,6 +52,7 @@ export const WORKIT_SKILL_TRIGGERS: Readonly<Record<WorkitSkill, readonly string
   "workit-deslop": ["deslop", "slop", "dead code"],
   "workit-fanout": ["fan out", "parallelize", "parallel agents", "swarm"],
   "workit-verify-app": ["verify the app", "smoke test", "prove it works"],
+  "workit-retro": ["retro"],
 };
 
 /** The `description:` frontmatter value of a SKILL.md (one line, unquoted). */

package/src/knowledge.ts

@@ -0,0 +1,368 @@
+// `workit knowledge lint`: deterministic checks over the repository's agent
+// knowledge files, so the guards against markdown rot are a check that can
+// fail rather than a sentence an agent may ignore. Four rules:
+//
+// - agents-budget: AGENTS.md (and a CLAUDE.md that is not the same file) stays
+//   at or under 8 KB; everything an agent pays for on every session.
+// - broken-link: a markdown link, or a backticked path whose first segment
+//   exists at the repository top, points at a local file that is missing.
+// - scaffold-file: a need-based file (CODING_STANDARDS.md, GLOSSARY.md) holds
+//   only headings, comments or placeholders. These files are created in the
+//   same edit as their first real entry, never as an empty scaffold.
+// - duplicate-rule: the same sentence (normalized: case, markup, wrapping)
+//   appears in a steering file and in CODING_STANDARDS.md. A rule lives once.
+//
+// Read-only; plain TS over node built-ins (git only to list tracked paths).
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+export const AGENTS_BYTE_BUDGET = 8 * 1024;
+
+/** Root files every session reads (navigation and rules). */
+const STEERING_FILES = ["AGENTS.md", "CLAUDE.md"];
+/** Root files that exist only once they hold a real entry. */
+const NEED_BASED_FILES = ["CODING_STANDARDS.md", "GLOSSARY.md"];
+const STANDARDS_FILE = "CODING_STANDARDS.md";
+/** A sentence shorter than this is a heading-like fragment, not a rule. */
+const MIN_RULE_WORDS = 6;
+
+type KnowledgeRule = "agents-budget" | "broken-link" | "scaffold-file" | "duplicate-rule";
+
+type KnowledgeFinding = {
+  rule: KnowledgeRule;
+  /** Repository-relative, forward slashes. */
+  file: string;
+  line: number | null;
+  message: string;
+};
+
+export type KnowledgeReport = {
+  root: string;
+  budget: number;
+  files: Array<{ file: string; bytes: number }>;
+  findings: KnowledgeFinding[];
+  /** Knowledge files that exist but could not be read (permissions, broken links). */
+  unreadable: string[];
+};
+
+type Doc = { file: string; text: string; lines: string[] };
+
+const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+const HEADING = /^\s{0,3}#{1,6}(\s|$)/;
+const TABLE_SEPARATOR = /^\s*\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)*\|?\s*$/;
+const LIST_ITEM = /^\s*(?:[-*+]|\d+[.)])\s+/;
+const PLACEHOLDER =
+  /^(?:(?:tbd|todo|tba|fixme)\b.*|n\/a|none|none yet|coming soon|placeholder|\.\.\.|…|-)?[.:]?$/i;
+
+const INDENTED_CODE = /^(?: {4}|\t)/;
+const blank = (line: string | undefined) => (line ?? "").trim() === "";
+
+/**
+ * Line indexes outside code (fenced blocks, closed only by a fence of the same
+ * character and at least the same length; 4-space indented blocks that do not
+ * continue a list), with HTML comments blanked.
+ */
+const proseLines = (lines: string[]): Array<{ index: number; text: string }> => {
+  const out: Array<{ index: number; text: string }> = [];
+  let fence: string | null = null;
+  let comment = false;
+  let indentedCode = false;
+  let inList = false;
+  lines.forEach((raw, index) => {
+    if (fence) {
+      const close = FENCE.exec(raw);
+      if (close && close[1][0] === fence[0] && close[1].length >= fence.length && !close[2].trim())
+        fence = null;
+      return;
+    }
+    if (!comment) {
+      const open = FENCE.exec(raw);
+      if (open && !(open[1][0] === "`" && open[2].includes("`"))) {
+        fence = open[1];
+        indentedCode = false;
+        return;
+      }
+      if (INDENTED_CODE.test(raw) && !blank(raw)) {
+        if (indentedCode || (!inList && blank(lines[index - 1]))) {
+          indentedCode = true;
+          return;
+        }
+      } else if (!blank(raw)) {
+        indentedCode = false;
+        inList = LIST_ITEM.test(raw) || (inList && /^\s/.test(raw));
+      }
+    }
+    let text = raw;
+    if (comment) {
+      const end = text.indexOf("-->");
+      if (end === -1) return;
+      comment = false;
+      text = text.slice(end + 3);
+    }
+    text = text.replace(/<!--[\s\S]*?-->/g, "");
+    const open = text.indexOf("<!--");
+    if (open !== -1) {
+      comment = true;
+      text = text.slice(0, open);
+    }
+    out.push({ index, text });
+  });
+  return out;
+};
+
+const withoutFrontMatter = (lines: string[]): string[] => {
+  if (lines[0]?.trim() !== "---") return lines;
+  const end = lines.indexOf("---", 1);
+  return end === -1 ? lines : [...lines.slice(0, end + 1).map(() => ""), ...lines.slice(end + 1)];
+};
+
+/** The file as a Doc; null when absent; "unreadable" when present but it cannot be read. */
+const read = (root: string, file: string): (Doc & { real: string }) | null | "unreadable" => {
+  const full = path.join(root, file);
+  try {
+    fs.lstatSync(full);
+  } catch {
+    return null;
+  }
+  try {
+    if (!fs.statSync(full).isFile()) return null;
+    const text = fs.readFileSync(full, "utf8");
+    return { file, text, lines: text.split(/\r?\n/), real: fs.realpathSync(full) };
+  } catch {
+    return "unreadable";
+  }
+};
+
+/**
+ * Top-level entries git tracks, so a pointer is judged the same locally and in
+ * CI; null outside a git repository (then the file system decides).
+ */
+const trackedTopLevel = (root: string): Set<string> | null => {
+  const run = spawnSync("git", ["ls-files", "-z", "--cached"], {
+    cwd: root,
+    encoding: "utf8",
+    maxBuffer: 256 * 1024 * 1024,
+    timeout: 20_000,
+    windowsHide: true,
+  });
+  if (run.status !== 0) return null;
+  return new Set(
+    run.stdout
+      .split("\0")
+      .filter(Boolean)
+      .map((file) => file.split("/")[0]),
+  );
+};
+
+const exists = (target: string): boolean => {
+  try {
+    fs.statSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+// --- broken-link -----------------------------------------------------------
+
+// Targets: `<anything>` or a run without spaces that may hold balanced parentheses.
+const LINK = /!?\[[^\]]*\]\(\s*(?:<([^>\n]+)>|((?:[^()\s<>]|\([^()\s]*\))+))(?:\s+["'(][^)]*)?\)/g;
+const REFERENCE_DEFINITION = /^\s{0,3}\[[^\]]+\]:\s*<?(\S+?)>?(?:\s|$)/;
+const CODE_SPAN = /`([^`\n]+)`/g;
+const PATH_LIKE = /^(?:\.{1,2}\/)?[\w@.-]+(?:\/[\w@.-]+)+\/?$/;
+
+const isExternal = (target: string) =>
+  /^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#") || target.startsWith("//");
+
+const localTarget = (target: string): string => {
+  const bare = target.replace(/[#?].*$/, "");
+  try {
+    return decodeURIComponent(bare);
+  } catch {
+    return bare;
+  }
+};
+
+const brokenLinks = (root: string, doc: Doc, tracked: Set<string> | null): KnowledgeFinding[] => {
+  const findings: KnowledgeFinding[] = [];
+  const base = path.dirname(path.join(root, doc.file));
+  const missing = (target: string, line: number, how: string) =>
+    findings.push({
+      rule: "broken-link",
+      file: doc.file,
+      line,
+      message: `${how} \`${target}\` points at a missing file`,
+    });
+  for (const { index, text } of proseLines(doc.lines)) {
+    // Links inside inline code are examples, not links.
+    const prose = text.replace(CODE_SPAN, (span) => " ".repeat(span.length));
+    const targets = [...prose.matchAll(LINK)].map((match) => match[1] ?? match[2]);
+    const definition = REFERENCE_DEFINITION.exec(prose)?.[1];
+    if (definition) targets.push(definition);
+    for (const target of targets) {
+      if (isExternal(target)) continue;
+      const local = localTarget(target);
+      if (!local) continue;
+      const resolved = local.startsWith("/") ? path.join(root, local) : path.resolve(base, local);
+      if (!exists(resolved)) missing(target, index + 1, "link");
+    }
+    // A backticked path counts as a pointer only when it is explicitly
+    // relative (./ or ../) or its first segment is a tracked top-level entry
+    // (dot-directories included), so commands, globs, placeholders, package
+    // names and local-only directories are never mistaken for one.
+    for (const [, span] of text.matchAll(CODE_SPAN)) {
+      const candidate = span.replace(/:\d+(?::\d+)?$/, "");
+      if (!PATH_LIKE.test(candidate)) continue;
+      const relative = /^\.\.?\//.test(candidate);
+      const first = candidate.split("/")[0];
+      if (!relative && !(tracked ? tracked.has(first) : exists(path.join(root, first)))) continue;
+      const resolved = relative ? path.resolve(base, candidate) : path.join(root, candidate);
+      if (!exists(resolved)) missing(span, index + 1, "pointer");
+    }
+  }
+  return findings;
+};
+
+// --- scaffold-file ---------------------------------------------------------
+
+const isPlaceholder = (text: string) =>
+  PLACEHOLDER.test(
+    text
+      .replace(LIST_ITEM, "")
+      .replace(/[*_`]/g, "")
+      .replace(/^\[\s?\]\s*/, "")
+      .trim(),
+  );
+
+/** True when the file has no line that is an entry: only headings, rules, comments, table headers or placeholders. */
+const scaffoldOnly = (doc: Doc): boolean => {
+  const lines = proseLines(withoutFrontMatter(doc.lines));
+  return lines.every(({ text }, position) => {
+    const trimmed = text.trim();
+    if (trimmed === "" || HEADING.test(text) || /^([-*_])(\s*\1){2,}$/.test(trimmed)) return true;
+    if (TABLE_SEPARATOR.test(text)) return true;
+    const next = lines[position + 1]?.text ?? "";
+    if (trimmed.startsWith("|") && TABLE_SEPARATOR.test(next)) return true;
+    if (trimmed.startsWith("|"))
+      return trimmed
+        .split("|")
+        .map((cell) => cell.trim())
+        .every((cell) => cell === "" || isPlaceholder(cell));
+    return isPlaceholder(trimmed);
+  });
+};
+
+// --- duplicate-rule --------------------------------------------------------
+
+/** Unwrapped list items and paragraphs, each with the line it starts on. */
+const ruleUnits = (doc: Doc): Array<{ line: number; text: string }> => {
+  const units: Array<{ line: number; text: string }> = [];
+  let current: { line: number; text: string } | null = null;
+  const flush = () => {
+    if (current) units.push(current);
+    current = null;
+  };
+  for (const { index, text } of proseLines(doc.lines)) {
+    const trimmed = text.trim();
+    if (trimmed === "" || HEADING.test(text) || trimmed.startsWith("|")) {
+      flush();
+      continue;
+    }
+    if (LIST_ITEM.test(text) || !current) {
+      flush();
+      current = { line: index + 1, text: trimmed.replace(LIST_ITEM, "") };
+    } else current.text += ` ${trimmed}`;
+  }
+  flush();
+  return units;
+};
+
+const normalize = (sentence: string): string =>
+  sentence
+    .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/[*_`]/g, "")
+    .toLowerCase()
+    .replace(/\s+/g, " ")
+    .replace(/[\s.,;:!?]+$/, "")
+    .trim();
+
+const sentences = (doc: Doc): Map<string, number> => {
+  const out = new Map<string, number>();
+  for (const unit of ruleUnits(doc))
+    for (const sentence of unit.text.split(/(?<=[.!?])\s+/)) {
+      const key = normalize(sentence);
+      if (key.split(" ").length >= MIN_RULE_WORDS && !out.has(key)) out.set(key, unit.line);
+    }
+  return out;
+};
+
+const duplicateRules = (steering: Doc[], standards: Doc): KnowledgeFinding[] => {
+  const findings: KnowledgeFinding[] = [];
+  const rules = sentences(standards);
+  for (const doc of steering)
+    for (const [key, line] of sentences(doc)) {
+      const standardsLine = rules.get(key);
+      if (standardsLine === undefined) continue;
+      findings.push({
+        rule: "duplicate-rule",
+        file: doc.file,
+        line,
+        message: `repeats ${standards.file}:${standardsLine} ("${key.slice(0, 60)}${key.length > 60 ? "…" : ""}"); keep the rule in one file`,
+      });
+    }
+  return findings;
+};
+
+// --- entry -----------------------------------------------------------------
+
+/** Lint the knowledge files at `root` (the repository top). */
+export function lintKnowledge(root: string): KnowledgeReport {
+  const seen = new Set<string>();
+  const unreadable: string[] = [];
+  const load = (file: string): Doc | null => {
+    const doc = read(root, file);
+    if (doc === "unreadable") unreadable.push(file);
+    if (doc === null || doc === "unreadable" || seen.has(doc.real)) return null;
+    seen.add(doc.real);
+    return doc;
+  };
+  const steering = STEERING_FILES.map(load).filter((doc): doc is Doc => doc !== null);
+  const needBased = NEED_BASED_FILES.map(load).filter((doc): doc is Doc => doc !== null);
+  const findings: KnowledgeFinding[] = [];
+
+  for (const doc of steering) {
+    const bytes = Buffer.byteLength(doc.text);
+    if (bytes > AGENTS_BYTE_BUDGET)
+      findings.push({
+        rule: "agents-budget",
+        file: doc.file,
+        line: null,
+        message: `${bytes} bytes, over the ${AGENTS_BYTE_BUDGET}-byte budget; move detail behind a pointer or into a check, and name what each addition removes`,
+      });
+  }
+  for (const doc of needBased)
+    if (scaffoldOnly(doc))
+      findings.push({
+        rule: "scaffold-file",
+        file: doc.file,
+        line: null,
+        message:
+          "holds no entry (headings, comments or placeholders only); delete it, or create it in the same edit as its first real entry",
+      });
+  const tracked = trackedTopLevel(root);
+  for (const doc of [...steering, ...needBased]) findings.push(...brokenLinks(root, doc, tracked));
+  const standards = needBased.find((doc) => doc.file === STANDARDS_FILE);
+  if (standards) findings.push(...duplicateRules(steering, standards));
+
+  return {
+    root,
+    budget: AGENTS_BYTE_BUDGET,
+    files: [...steering, ...needBased].map((doc) => ({
+      file: doc.file,
+      bytes: Buffer.byteLength(doc.text),
+    })),
+    findings,
+    unreadable,
+  };
+}