lesson-foundry

ADLC Phase: P7 (compounding closer)

Converts prosecution findings into permanent defenses. Every recurring finding is paid for exactly once.

C9 in the ADLC component inventory. Without this tool the lifecycle does not get cheaper — lessons are re-bought on every run.

What it does

1. Reads prosecution findings from a JSONL ledger (default: .adlc/findings.jsonl)
2. Skips entries with verdict === 'killed'; surfaces malformed lines
3. Clusters findings by semantic similarity (token-set Jaccard >= 0.5)
4. Routes each cluster of size >= --min to its cheapest permanent defense:
   • LINT — any member desc contains a quoted literal or recognizable marker (TODO, FIXME, eslint-disable, etc.) → emits a grep-gate JSON descriptor + a runnable check-<name>.mjs script
   • SKILL — category is convention, pattern, architecture, or style → emits a SKILL.md stub with frontmatter and evidence quotes
   • SPEC-GAP — otherwise → appends a question to interrogation-template.md for P1 to address
5. By default: dry-run (prints what would be written). Add --write to emit files.
6. With --gate: exits 2 if any cluster has no existing non-empty defense file in --out-dir, or if findings ledger contains unparseable/malformed lines exceeding --tolerate-malformed

Usage

lesson-foundry [options]

Options:
  --ledger <name>          Ledger name to read findings from (default: findings)
  --min <n>                Minimum cluster size to surface (default: 2)
  --out-dir <path>         Output directory for defense files (default: .adlc/lessons)
  --write                  Emit files (default: dry-run — prints what WOULD be written).
                           An existing non-empty artifact is kept; an empty one is regenerated
  --gate                   Exit 2 if any cluster >= --min has no non-empty defense file in --out-dir
  --allow-missing-ledger   Allow missing ledger file when --gate is set (bootstrap opt-in).
  --tolerate-malformed <n> Tolerate up to <n> unparseable/malformed ledger lines before failing --gate (default: 0)
  --llm                    Refine cluster wording via one mid-tier LLM call per cluster;
                           exits 1 (writing nothing) when no cluster could be refined
  --prompt-only            Print LLM prompts and exit 0 (works with zero API keys)
  --json                   Machine-readable output (stdout JSON, errors to stderr)

Exit codes

Emitted file shapes

LINT: <name>.lint.json

{
  "name": "cluster-name",
  "pattern": "ESCAPED_LITERAL_OR_MARKER",
  "paths": ["**"],
  "message": "lesson-foundry: recurring finding — <desc>"
}

LINT: check-<name>.mjs

A runnable Node.js script that greps the repo for the pattern and exits 2 on match, 0 when clean. Run it as a CI gate.

SKILL: <name>.SKILL.md

Markdown with YAML frontmatter (name, description, category, triggers) and a body containing the rule, evidence quotes, and provenance count. Ready to load into any skill-mining pipeline.

SPEC-GAP: interrogation-template.md

Appended-to file with checkbox questions for each spec-gap cluster. Answer these in the P1 spec to prevent recurring findings.

Examples

Dry-run to see what would be produced:

lesson-foundry --ledger findings --min 2

Write defense files:

lesson-foundry --ledger findings --min 2 --write --out-dir .adlc/lessons

Gate in CI (fail if any recurring lesson is unbanked):

lesson-foundry --ledger findings --min 2 --gate

Machine-readable output:

lesson-foundry --min 2 --gate --json

Refine wording via LLM:

lesson-foundry --min 2 --write --llm

Print LLM prompts without calling any API:

lesson-foundry --min 2 --prompt-only

Relationship to sibling tools

ADLC phase

P7 — the compounding closer. Runs after prosecution findings accumulate across multiple ADLC cycles. The effect is a ratchet: each lesson is paid for exactly once, and recurring findings are demoted from probabilistic detection (LLM review, ~dollars per catch) to deterministic detection (lint/grep, ~free forever).

Core gaps

None. All required functionality is available in @adlc/core.