engsys 1.0.0

package/engsys.config.example.yaml

@@ -0,0 +1,46 @@
+# engsys project config — copy to your project root as engsys.config.yaml,
+# edit, then run:  /path/to/engsys/install install --into .
+#
+# This file is the single source of truth for what the installer materializes.
+# Block lists must be indented under their key (see hook_patterns below).
+
+project:
+  name: Acme Widgets
+  description: One-line description rendered into CLAUDE.md.
+
+# Every stack dimension accepts a single value OR a list — mixed stacks compose
+# (each selected pack contributes its skills, CLAUDE.md fragment, and permissions).
+stack:
+  cloud: aws            # aws | azure | gcp | cloudflare | none   — or a list: [azure, cloudflare]
+  iac: terraform        # terraform | bicep | cdk | none          — or a list
+  lang: [typescript]    # typescript | python | swift | kotlin | shell
+  platform: [web]       # web | ios | android                    — e.g. [web, ios, android]
+  db: none              # prisma | mongo | none                   — or a list: [prisma, mongo]
+  # domain: [mobile-growth]   # optional extra packs under stacks/domain/
+
+# Issue tracker (PRs / CI always stay on GitHub — this is a separate axis).
+issue_tracker: github   # github | linear | jira
+
+agents:
+  core: all             # 'all' or an explicit list, e.g. [melvin, isabelle, bert]
+  extra: [sandy, gary]  # opt-in personas from optional-agents/ (sandy, gary [mobile], jos, steve)
+
+commands: all           # 'all' or an explicit list
+
+lessons:
+  seed: true                      # seed the universal lessons-library into the project
+  into: docs/agent-lessons/library  # where seeded lessons land (project-local lessons stay at docs/agent-lessons/)
+
+naturalize:
+  model_strategy: "Opus for orchestration and judgement; Sonnet for execution."
+  hook_patterns:
+    - glob: "*/schema.prisma"
+      reminder: "Schema changed — regenerate the client and rebuild dependents before pushing."
+    - glob: "docs/vision-and-spec.md"
+      reminder: "Bump the version/date header; keep docs cross-refs in sync."
+  invariants: []        # project hard rules appended to CLAUDE.md project facts
+  # project_facts: |     # optional; otherwise the installer leaves a TODO marker
+  #   Multi-line project facts can go here.
+
+engsys:
+  version: main         # tag / branch / commit the project was installed from

package/install

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+'use strict';
+
+// engsys installer — deterministic plumbing for the Claude Code engineering system.
+// Usage:
+//   ./install install --into <path> [--config <file>] [--dry-run] [--force]
+//   ./install update  --into <path> [--config <file>] [--dry-run]
+//   ./install verify  --into <path>
+//
+// The engsys source root is the directory this script lives in.
+
+const path = require('path');
+const fs = require('fs');
+const { runInstall, runUninstall, runVerify, ENGSYS_VERSION } = require('./lib/commands');
+const { exists } = require('./lib/util');
+
+const engsysRoot = __dirname;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--force') args.force = true;
+    else if (a === '--into') args.into = argv[++i];
+    else if (a === '--config') args.config = argv[++i];
+    else if (a === '--help' || a === '-h') args.help = true;
+    else args._.push(a);
+  }
+  return args;
+}
+
+const USAGE = `engsys ${ENGSYS_VERSION}
+
+Bring the engineering system into a project, faithfully — adopting whatever is
+already there (existing CLAUDE.md, settings, agents, or Copilot/Cursor config).
+
+Commands:
+  init [--into <path>] [--force]
+      Scaffold engsys.config.yaml in <path> (default: current dir) from the
+      bundled example. Handy after \`npm install -g engsys\`, where you don't
+      have the repo's example file to copy. Edit it, then run \`install\`.
+  install --into <path> [--config <file>] [--dry-run] [--force]
+      First-time materialization. Adopts existing infra: backs up a foreign
+      CLAUDE.md (folding it into project facts), merges settings/.mcp.json,
+      preserves the project's own agents, and imports Copilot/Cursor config.
+      Re-running over an existing install behaves as update.
+  update  --into <path> [--config <file>] [--dry-run]
+      Re-render from current engsys + config. Preserves CLAUDE.md project facts
+      and hand-added permissions; prunes files orphaned by deselected packs.
+  verify  --into <path>
+      Check installed files against the lock (drift detection).
+  uninstall --into <path> [--dry-run]
+      Remove everything engsys added and restore the project's prior files (from
+      .claude/.engsys-backup/). The project's own agents/files are left intact.
+
+  --force   overwrite generated files (CLAUDE.md/settings/.mcp.json) instead of merging.
+
+Config: <into>/engsys.config.yaml (or .yml / .json). See engsys.config.example.yaml.`;
+
+function list(label, items, max = 8) {
+  if (!items || !items.length) return [];
+  const shown = items.slice(0, max).map((i) => `      ${i}`);
+  if (items.length > max) shown.push(`      … and ${items.length - max} more`);
+  return [`  ${label}:`, ...shown];
+}
+
+function report(result, cmd) {
+  const { into, plan } = result;
+  const lines = [];
+
+  if (result.adopting) lines.push('  note: existing engsys install detected → adopting as `update`.');
+  if (result.versionFrom && result.versionFrom !== result.versionTo) {
+    lines.push(`  engsys: ${result.versionFrom} → ${result.versionTo}`);
+  }
+
+  lines.push(...result.actions.map((a) => '  ' + a));
+  const c = result.changes;
+  lines.push(`  files: ${result.managedCount} managed (${c.added} new, ${c.updated} updated, ${c.removed} removed), ${result.generated.length} generated`);
+
+  // Adoption surfaces (scenario 1 & 3) + prune (scenario 2).
+  if (result.preexistingCount) {
+    const p = result.preexisting;
+    const bits = [];
+    if (p.agents.length) bits.push(`${p.agents.length} agent(s)`);
+    if (p.commands.length) bits.push(`${p.commands.length} command(s)`);
+    if (p.skills.length) bits.push(`${p.skills.length} skill(s)`);
+    lines.push(`  preserved (the project's own): ${bits.join(', ')} — left untouched.`);
+    for (const a of p.agents.slice(0, 8)) lines.push(`      ${a}`);
+  }
+  if (result.snapshotted && result.snapshotted.length) {
+    lines.push(`  rollback: ${result.snapshotted.length} pre-existing file(s) snapshotted → \`engsys uninstall\` restores your prior setup.`);
+  } else if (result.firstInstall) {
+    lines.push('  rollback: `engsys uninstall` removes engsys and restores your prior setup.');
+  }
+  lines.push(...list('pruned (orphaned)', result.pruned));
+  if (result.importedNow) {
+    lines.push(`  imported AI config: ${result.foreign.length} file(s) → docs/imported-ai-config/`);
+    lines.push(...result.foreign.slice(0, 8).map((f) => `      ${f.tool}: ${f.rel}`));
+  }
+
+  // Naturalization checklist (model-side; never plumbing).
+  lines.push('');
+  lines.push('Next — naturalization (model-side, never plumbing):');
+  lines.push('  - Fill the CLAUDE.md PROJECT-FACTS region (or run /naturalize): stack, services, invariants, key paths.');
+  if (result.foldedClaude) {
+    lines.push('  - Your prior CLAUDE.md was folded into PROJECT-FACTS (original preserved in .claude/.engsys-backup/) — trim it.');
+  }
+  if (result.importedNow) {
+    lines.push('  - Fold docs/imported-ai-config/ (Copilot/Cursor rules + agent defs) into CLAUDE.md / .claude/agents via /naturalize, then delete it.');
+  }
+  if (result.preexisting && result.preexisting.agents.length) {
+    lines.push("  - Reconcile the project's own agents with the engsys roster (keep, merge, or rename on conflict).");
+  }
+  const placeholderHints = [];
+  for (const f of plan.claudeFragments) {
+    if (/<naturalize:|<proj>|<rg>|<env>|<suffix>/.test(f.text)) placeholderHints.push(f.pack);
+  }
+  if (Object.keys(plan.mcpServers).some((k) => /<naturalize:/.test(JSON.stringify(plan.mcpServers[k])))) {
+    placeholderHints.push('.mcp.json (MCP server env)');
+  }
+  if (placeholderHints.length) lines.push(`  - Replace <naturalize: ...> placeholders in: ${placeholderHints.join(', ')}.`);
+  lines.push(`  - Review .claude/settings.json permissions${Object.keys(plan.mcpServers).length ? ' and .mcp.json' : ''} before first use.`);
+  lines.push(`  - \`engsys verify --into ${into}\` any time to confirm nothing drifted.`);
+
+  if (plan.warnings.length || result.warnings.length) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const w of [...plan.warnings, ...result.warnings]) lines.push(`  ! ${w}`);
+  }
+  return lines.join('\n');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+
+  if (args.help || !cmd) { console.log(USAGE); process.exit(args.help ? 0 : 1); }
+
+  if (cmd === 'init') {
+    const into = path.resolve(args.into || '.');
+    if (!exists(into)) { console.error(`error: target does not exist: ${into}`); process.exit(1); }
+    const dest    = path.join(into, 'engsys.config.yaml');
+    const example = path.join(engsysRoot, 'engsys.config.example.yaml');
+    if (!exists(example)) { console.error(`error: bundled example not found: ${example}`); process.exit(1); }
+    if (exists(dest) && !args.force) {
+      console.error(`error: ${path.relative(into, dest) || dest} already exists (use --force to overwrite).`);
+      process.exit(1);
+    }
+    if (args.dryRun) { console.log(`engsys init (dry run — nothing written) → ${dest}`); process.exit(0); }
+    fs.writeFileSync(dest, fs.readFileSync(example, 'utf8'));
+    console.log(`engsys init → wrote ${path.relative(process.cwd(), dest) || dest}`);
+    console.log('  Edit it (pick cloud / iac / lang / platform / db / agents), then:');
+    console.log(`    engsys install --into ${args.into || '.'}`);
+    process.exit(0);
+  }
+
+  if (cmd === 'install' || cmd === 'update') {
+    if (!args.into) { console.error('error: --into <path> is required'); process.exit(1); }
+    const into = path.resolve(args.into);
+    if (!exists(into)) { console.error(`error: target does not exist: ${into}`); process.exit(1); }
+    const result = runInstall({ engsysRoot, into, config: args.config, dryRun: args.dryRun, force: args.force, mode: cmd });
+    const tag = args.dryRun ? ' (dry run — nothing written)' : '';
+    console.log(`engsys ${result.mode}${tag} → ${into}`);
+    console.log(`config: ${path.relative(into, result.configPath) || result.configPath}`);
+    console.log(report(result, cmd));
+    process.exit(0);
+  }
+
+  if (cmd === 'uninstall') {
+    if (!args.into) { console.error('error: --into <path> is required'); process.exit(1); }
+    const into = path.resolve(args.into);
+    const r = runUninstall({ into, dryRun: args.dryRun });
+    const tag = args.dryRun ? ' (dry run — nothing written)' : '';
+    console.log(`engsys uninstall${tag} → ${into}`);
+    console.log(`  removed ${r.removed.length} engsys file(s), restored ${r.restored.length} original(s).`);
+    if (!r.hadManifest) console.log('  note: no rollback manifest found — removed engsys files but had no snapshot to restore.');
+    const n = r.preexisting.agents.length + r.preexisting.commands.length + r.preexisting.skills.length;
+    if (n) console.log(`  left the project's own ${n} agent/command/skill file(s) intact.`);
+    process.exit(0);
+  }
+
+  if (cmd === 'verify') {
+    if (!args.into) { console.error('error: --into <path> is required'); process.exit(1); }
+    const into = path.resolve(args.into);
+    const r = runVerify({ into });
+    if (r.ok) {
+      console.log(`verify: OK — ${Object.keys(r.lock.managed).length} managed files match (engsys ${r.lock.engsysVersion}).`);
+      process.exit(0);
+    }
+    console.log(`verify: DRIFT detected (engsys ${r.lock.engsysVersion}).`);
+    for (const m of r.missing) console.log(`  missing:  ${m}`);
+    for (const m of r.modified) console.log(`  modified: ${m}`);
+    process.exit(2);
+  }
+
+  console.error(`unknown command: ${cmd}\n`);
+  console.log(USAGE);
+  process.exit(1);
+}
+
+main();

package/lessons-library/README.md

@@ -0,0 +1,80 @@
+# lessons-library
+
+Curated, **generalized** lessons that recur across projects — the durable memory
+of the engineering system.
+
+Two tiers, kept distinct:
+
+1. **Project-local** lessons live in each project's `docs/agent-lessons/`, written
+   during `/project-closeout` by mining that project's local-review findings.
+2. **Generalized** lessons live here. When a lesson family recurs across projects
+   (e.g. "new E2E spec ⇒ register it in the CI matrix", dependabot triage), it's
+   rewritten stack-agnostically and promoted here.
+
+## Promotion
+
+`/project-closeout` ends with: *if a mined lesson generalizes, open a PR against
+`engsys/lessons-library/`*. That's the feedback loop that keeps engsys the source
+of truth instead of a fork point.
+
+## Format
+
+One lesson per file. Keep them LLM-optimized and trigger-first:
+
+```markdown
+# <short title>
+
+**Trigger:** the symptom that should make you recall this.
+**Failure mode:** what goes wrong and why.
+**Correct behavior:** the checklist / the fix.
+**Check:** a quick diagnostic before/after.
+**Seen in:** keep it generalized — e.g. "recurring across projects."
+```
+
+> This library is published publicly (npm + GitHub). Generalize before promoting:
+> **never** include private project/repo/company names, secrets, internal hosts,
+> or proprietary specifics in a lesson. The pattern is what's portable, not the
+> particulars.
+
+## Seeding
+
+A future installer option may seed a project's `docs/agent-lessons/` with the
+lessons relevant to its chosen stack. For now, promotion is manual via PR.
+
+## Index
+
+### Verification & review
+- [verify-ground-truth-not-reports](verify-ground-truth-not-reports.md) — check real state, not the narration.
+- [independent-objective-review-gate](independent-objective-review-gate.md) — fresh reviewer re-runs the gate, binary verdict.
+- [tests-can-assert-the-bug](tests-can-assert-the-bug.md) — a green test that contradicts a root cause is a suspect.
+- [prove-causation-before-acting](prove-causation-before-acting.md) — observe at the deciding boundary before fixing.
+- [re-read-state-before-acting](re-read-state-before-acting.md) — re-read at the moment you act, not at session start.
+- [gate-changes-on-measurement-not-vibes](gate-changes-on-measurement-not-vibes.md) — eval/golden-set, not intuition.
+- [shift-correctness-left-and-distrust-false-greens](shift-correctness-left-and-distrust-false-greens.md) — pre-push checks; a gate that didn't run is a false green.
+
+### Concurrency & safety
+- [claim-then-act-for-irreversible-ops](claim-then-act-for-irreversible-ops.md) — stamp the claim atomically, then execute.
+- [async-callbacks-verify-liveness](async-callbacks-verify-liveness.md) — confirm the target is still current before mutating it.
+- [enforce-your-guarantee-at-your-boundary](enforce-your-guarantee-at-your-boundary.md) — redact/sanitize/audit/authorize where you emit.
+
+### Data & identity
+- [keep-an-immutable-source-of-truth](keep-an-immutable-source-of-truth.md) — raw immutable; downstream is a replayable transform.
+- [model-identity-with-stable-ids-and-provenance](model-identity-with-stable-ids-and-provenance.md) — join on stable ids; carry source+timestamp.
+- [read-layer-tolerates-unbackfilled-rows](read-layer-tolerates-unbackfilled-rows.md) — handle legacy rows during the backfill window.
+
+### Workflow & git
+- [change-isnt-done-until-every-surface-updated](change-isnt-done-until-every-surface-updated.md) — update every rippled surface in the same PR.
+- [operator-choices-are-first-class](operator-choices-are-first-class.md) — track operator choices; copy criteria verbatim.
+- [co-commit-entangled-work](co-commit-entangled-work.md) — co-commit file-sharing issues; skip already-merged commits on rebase.
+- [stray-control-bytes-hide-changes](stray-control-bytes-hide-changes.md) — control bytes turn files binary and silence review.
+- [long-agent-runs-checkpoint-not-poll](long-agent-runs-checkpoint-not-poll.md) — checkpoint into short runs; end agents at PR-open.
+
+### Ops & deploy
+- [deploy-by-digest-and-verify-the-running-revision](deploy-by-digest-and-verify-the-running-revision.md) — immutable digest; verify the active revision.
+- [iac-first-no-console-changes](iac-first-no-console-changes.md) — version-controlled IaC with state and drift detection.
+- [worktrees-need-bootstrap-from-origin-main](worktrees-need-bootstrap-from-origin-main.md) — branch off origin/main; bootstrap; absolute paths.
+- [shell-safety-pipefail-and-validate-before-teardown](shell-safety-pipefail-and-validate-before-teardown.md) — pipefail; validate the risky step before teardown.
+
+### Tooling
+- [prefer-tool-enforced-structured-output](prefer-tool-enforced-structured-output.md) — schema/tool-enforced output over prompt-policed format.
+- [dependabot-triage-playbook](dependabot-triage-playbook.md) — 6-phase order for clearing a Dependabot pile.

package/lessons-library/async-callbacks-verify-liveness.md

@@ -0,0 +1,15 @@
+# Async callbacks must verify liveness
+
+**Trigger:** A callback, webhook, or deferred task fires and mutates the state of a target that may have moved on.
+
+**Failure mode:** By the time the callback runs, the target may be stale, superseded, or gone. Writing its state blindly resurrects dead entities or clobbers newer data. In-flight writes that don't gate downstream actions cause ordering bugs.
+
+**Correct behavior:**
+- Verify the target is still alive/current before touching its state.
+- Gate downstream actions on the completion of in-flight writes.
+- Make read-modify-write a single atomic statement, not a check-then-write pair.
+- Treat a stale/missing target as a no-op, not an error to force through.
+
+**Check:** If the target was deleted/superseded mid-flight, does the callback safely skip instead of writing?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/change-isnt-done-until-every-surface-updated.md

@@ -0,0 +1,15 @@
+# A change isn't done until every surface is updated
+
+**Trigger:** You renamed something, changed a signature, or reworked a flow/copy.
+
+**Failure mode:** The change ripples further than the diff. Docs, config, fixtures, mock factories, marketing copy, notifications, and E2E specs that assert the old copy/flow still reference the old shape — so half the system is inconsistent and tests pass on stale assumptions.
+
+**Correct behavior:**
+- Enumerate every surface the change touches: code call-sites, docs, config, fixtures, mock factories, user-facing copy, notifications.
+- Update all call-sites AND their test assertions AND mock/factory definitions.
+- Update E2E specs that assert the changed copy or flow.
+- Land all of it in the SAME PR, not as follow-ups.
+
+**Check:** Grep for the old name/string across the whole repo — zero hits outside history?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/claim-then-act-for-irreversible-ops.md

@@ -0,0 +1,16 @@
+# Claim, then act, for irreversible operations
+
+**Trigger:** A destructive or exactly-once operation (charge, send, delete, provision) that must never run twice.
+
+**Failure mode:** Validate-then-destroy leaves a window where two callers both pass validation and both execute. Assuming the provider is idempotent without confirming it means duplicates slip through.
+
+**Correct behavior:**
+- Atomically stamp the claim marker FIRST, in the same statement/transaction, before doing the irreversible act.
+- Only proceed if your stamp won the claim.
+- Execute the irreversible act after the claim is held.
+- Clear the marker on failure so legitimate retries can re-claim.
+- Never assume provider-side idempotency; confirm it or enforce your own key.
+
+**Check:** If two requests race, does exactly one win the claim and exactly one side-effect occur?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/co-commit-entangled-work.md

@@ -0,0 +1,15 @@
+# Co-commit entangled work
+
+**Trigger:** You're splitting work into one-commit-per-issue, but several issues touch the same files; or rebasing a stacked PR after an upstream squash-merge.
+
+**Failure mode:** Forcing artificial 1:1 commit-per-issue when issues share files produces commits that don't build in isolation. Rebasing over a squash-merge re-applies already-merged commits, creating conflicts and phantom changes.
+
+**Correct behavior:**
+- Co-commit issues that share files when splitting would break the build; cite ALL issue numbers in the subject.
+- Don't force artificial one-commit-per-issue at the cost of a buildable history.
+- When rebasing a stacked PR after an upstream squash-merge, skip already-applied commits.
+- Verify the final diff contains ONLY new work, nothing already merged.
+
+**Check:** Does each commit build, and is the final rebased diff free of already-merged changes?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/dependabot-triage-playbook.md

@@ -0,0 +1,17 @@
+# Dependabot triage playbook
+
+**Trigger:** A pile of Dependabot PRs and security alerts has accumulated and you need to clear it without breaking the build.
+
+**Failure mode:** Merging blindly in arbitrary order causes conflicts, chases ghost alerts already fixed, and lands risky majors next to coordinated changes — turning a routine chore into a multi-day breakage.
+
+**Correct behavior (6 phases, in order):**
+- Phase 0 — Kill noise: regenerate the lockfile to clear ghost/transitive alerts already resolved.
+- Phase 1 — Merge the patch group together.
+- Phase 2 — Address residual real CVEs.
+- Phase 3 — Take safe major bumps.
+- Phase 4 — Risky majors, one per PR.
+- Phase 5 — Docker base-image coordination, last.
+
+**Check:** After each phase, is the build green before starting the next?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/deploy-by-digest-and-verify-the-running-revision.md

@@ -0,0 +1,15 @@
+# Deploy by digest, verify the running revision
+
+**Trigger:** You deployed, and code that's clearly merged appears missing in production.
+
+**Failure mode:** Deploying by a mutable tag (e.g. `:latest`) means the running container may be stale or ambiguous. Without verifying the active revision, "merged but missing" gets misdiagnosed as a code bug when it's actually a deploy/rollout/cache/data-gating issue.
+
+**Correct behavior:**
+- Deploy by immutable digest, not a mutable tag.
+- Use a unique revision id per deploy.
+- After every deploy, verify the ACTIVE revision/digest is the one you intended.
+- For "merged but missing", suspect deploy/rollout/cache/data-gating BEFORE suspecting code.
+
+**Check:** Does the live revision's digest match the artifact you just built?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/enforce-your-guarantee-at-your-boundary.md

@@ -0,0 +1,16 @@
+# Enforce your guarantee at your own boundary
+
+**Trigger:** You depend on an upstream contract for safety (redaction, sanitization, auth, audit) at the point where you emit output or take action.
+
+**Failure mode:** Trusting that "someone upstream already handled it" leaves gaps: secrets leak because redaction happened earlier and not here; partial sanitization (named entities but not numeric) is bypassable; open redirects; missing audit rows on failure paths; hiding content behind permission checks that the client can ignore.
+
+**Correct behavior:**
+- Redact at YOUR boundary; don't trust an upstream's redaction contract.
+- Sanitize/decode to a fixed point, covering BOTH named and numeric entity forms.
+- Validate user-supplied redirect URLs against an allowlist before use.
+- Emit audit rows on EVERY path — success AND failure.
+- Gate controls/affordances by permission; never gate sensitive content by hiding the control alone.
+
+**Check:** If every upstream guarantee were removed, would your boundary still be safe on its own?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/gate-changes-on-measurement-not-vibes.md

@@ -0,0 +1,15 @@
+# Gate changes on measurement, not vibes
+
+**Trigger:** You're about to adopt a "best practice" or standard technique, or write a claim about a measurable property.
+
+**Failure mode:** Intuition and reputation mislead. A technique that's standard everywhere can measurably degrade YOUR corpus. Writing "this meets contrast requirements" or "this improves hit-rate" without computing the number ships a false claim.
+
+**Correct behavior:**
+- Gate changes on an eval / golden-set, not on intuition or "everyone does this."
+- If a standard technique degrades your actual metric, reject it (or keep it behind a flag).
+- Compute the real metric (e.g. contrast ratio, hit-rate, accuracy) before asserting it.
+- Keep the eval cheap enough to run on every relevant change.
+
+**Check:** Is there a number from your own corpus backing this change, measured before and after?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/iac-first-no-console-changes.md

@@ -0,0 +1,15 @@
+# IaC-first, no console changes
+
+**Trigger:** You're about to create or change a cloud resource through a console click or a one-off imperative script.
+
+**Failure mode:** Console/bash-script changes have no state, no diff, no review, and drift silently from any written intent. The "source of truth" becomes tribal knowledge, and rebuilding the environment is impossible.
+
+**Correct behavior:**
+- Provision every cloud resource via version-controlled IaC (e.g. Terraform/CDK/Pulumi) with managed state.
+- Require plan/diff review before apply.
+- Run drift detection and reconcile drift back into code.
+- Treat an imperative console/script change as not a source of truth — never the system of record.
+
+**Check:** Can you rebuild this resource from code alone, and does a plan show zero drift?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/independent-objective-review-gate.md

@@ -0,0 +1,15 @@
+# Independent, objective review gate
+
+**Trigger:** A change is "ready"; the author (human or agent) is signing off on their own work.
+
+**Failure mode:** Authors rationalize past their own blind spots — the same assumptions that produced the bug excuse it in review. For visual/CSS changes, reading the stylesheet "looks right" while the rendered page is broken.
+
+**Correct behavior:**
+- Have a fresh reviewer with no stake re-review from scratch, not just skim the diff.
+- The reviewer re-runs the gate independently rather than trusting the author's run.
+- Return a binary verdict (pass/fail), not a vibe.
+- For visual changes, inspect the RENDERED result (headless browser, screenshot), never just the source.
+
+**Check:** Did someone who didn't write the change independently reproduce the passing state?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/keep-an-immutable-source-of-truth.md

@@ -0,0 +1,15 @@
+# Keep an immutable source of truth
+
+**Trigger:** You're processing source data into derived artifacts, especially in a pipeline you'll want to improve later.
+
+**Failure mode:** Mutating source data in place, or treating derived artifacts as the only copy, means an improvement to the pipeline can't be applied retroactively — you'd have to re-acquire the raw data, which may be gone. Mutating shared/immutable resources corrupts everyone downstream.
+
+**Correct behavior:**
+- Store raw source data immutably; never overwrite it.
+- Make every downstream artifact a REPLAYABLE transform of the raw source.
+- Design so reprocessing after an improvement is free (just re-run the transform).
+- Reference shared/immutable resources; never mutate them in place.
+
+**Check:** After improving the pipeline, can you regenerate all artifacts from raw without re-fetching anything?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/long-agent-runs-checkpoint-not-poll.md

@@ -0,0 +1,15 @@
+# Long agent runs: checkpoint, don't poll
+
+**Trigger:** A single agent run is expected to take a long time, or an agent is sitting in a polling loop waiting on a review bot.
+
+**Failure mode:** Long single runs die from stale socket reuse (not a clean hard timeout), losing all uncommitted work. Agents that poll review bots burn time and tokens waiting, and block the orchestrator.
+
+**Correct behavior:**
+- Checkpoint long work into short runs that commit/push after each unit, so progress survives a death.
+- Don't rely on a single marathon run to finish before something breaks.
+- Terminate implementation agents at PR-open instead of polling for review results.
+- Let the orchestrator handle review follow-up, freeing the implementation agent.
+
+**Check:** If the run died right now, is the completed work already committed and pushed?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/model-identity-with-stable-ids-and-provenance.md

@@ -0,0 +1,15 @@
+# Model identity with stable ids and provenance
+
+**Trigger:** You're joining records, deduping, or attributing data across sources or over time.
+
+**Failure mode:** Joining on mutable names/handles breaks when they change or collide, silently merging distinct entities. Dropping provenance means you can't tell where a datum came from or how fresh it is. Guessing an identity to avoid a null fabricates wrong links.
+
+**Correct behavior:**
+- Join on stable, unique ids — never on mutable names/handles.
+- Carry source + timestamp provenance on every datum, end-to-end, so the UI can render it.
+- Prefer null over a guessed identity.
+- Surface provenance to users so they can judge freshness and origin.
+
+**Check:** For any displayed datum, can you trace its source and timestamp without guessing?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/operator-choices-are-first-class.md

@@ -0,0 +1,15 @@
+# Operator choices are first-class
+
+**Trigger:** A planning/orchestration workflow where an operator picks options and acceptance criteria come from a spec.
+
+**Failure mode:** Operator-selected options get treated as silent assumptions and quietly dropped. Acceptance criteria get paraphrased and drift from the spec. Grouping/sequencing derived from prose in issue bodies disagrees with the tracked board.
+
+**Correct behavior:**
+- Turn every operator-selected option into a first-class, tracked item — never a silent assumption.
+- Copy acceptance criteria VERBATIM from the spec as checkboxes.
+- Use the board's structured Phase field as the authority for grouping, not prose in issue bodies.
+- Make each tracked choice auditable back to the operator decision that produced it.
+
+**Check:** Can every plan item be traced to either a spec criterion (verbatim) or a recorded operator choice?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/prefer-tool-enforced-structured-output.md

@@ -0,0 +1,15 @@
+# Prefer tool-enforced structured output
+
+**Trigger:** You're relying on prompt instructions to make a model produce a specific format, or letting a pipeline proceed on an unknown model/config.
+
+**Failure mode:** "Please respond as JSON" is policed by the model's goodwill — it drifts, adds prose, or breaks downstream parsing. Pipelines that silently accept unknown/unpriced models or configs fail unpredictably or rack up surprise cost.
+
+**Correct behavior:**
+- Use schema/tool-enforced structured output (e.g. tool-use / function calling / response schemas) instead of prompt-policed formatting.
+- Treat formatting instructions as fragile; enforced structure as reliable.
+- Guard pipelines to refuse to proceed on unknown/unpriced models or configs.
+- Fail loud on a config you can't validate, rather than guessing.
+
+**Check:** If the model ignored every formatting instruction, would the output still parse?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/prove-causation-before-acting.md

@@ -0,0 +1,15 @@
+# Prove causation before acting
+
+**Trigger:** You have a plausible explanation — backed by vendor docs or a web search — and you're about to fix based on it.
+
+**Failure mode:** A plausible hypothesis is not a diagnosis. Anchoring on an adjacent hop that tests green (the source emitted the right thing) while the real decision happens elsewhere (the destination rejected it) leads to fixing the wrong layer.
+
+**Correct behavior:**
+- Isolate one variable at a time and observe its effect directly.
+- Instrument at the DECIDING boundary — read the destination's actual admission/decision, not the source's intent.
+- Don't let "this adjacent step passes" stand in for "the failing step is understood."
+- Reproduce the failure under your hypothesis before committing to the fix.
+
+**Check:** Can you show the exact point where good input becomes the bad outcome, observed (not inferred)?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/re-read-state-before-acting.md

@@ -0,0 +1,14 @@
+# Re-read state at the moment you act
+
+**Trigger:** You're about to act on a spec, file, or assumption you read earlier in the session.
+
+**Failure mode:** Content reconciles and changes under you between read and act. Acting on a snapshot from session start — or asserting "X doesn't exist" against a stale working tree — produces decisions based on a world that no longer exists.
+
+**Correct behavior:**
+- Re-read specs/files at the moment of acting, not just at session start.
+- Verify "X doesn't exist / X still says Y" against origin/main (or current truth), not a possibly-stale local copy.
+- After any reconcile/merge/regen step, re-read before continuing.
+
+**Check:** Is the content you're acting on the current version, fetched just now?
+
+**Seen in:** recurring across multiple production projects.

package/lessons-library/read-layer-tolerates-unbackfilled-rows.md

@@ -0,0 +1,15 @@
+# Read layer must tolerate un-backfilled rows
+
+**Trigger:** A fix ships new code plus a backfill migration for existing rows.
+
+**Failure mode:** Code goes live before the backfill finishes. During that deploy window the read layer encounters legacy rows missing the new field/shape and crashes or misbehaves — an outage caused by the fix itself.
+
+**Correct behavior:**
+- Assume the read layer will see not-yet-backfilled legacy rows during the deploy window.
+- Default/coalesce missing values safely at read time.
+- Don't require the backfilled shape until the backfill is confirmed complete.
+- Sequence: ship tolerant read code, run backfill, only then tighten if needed.
+
+**Check:** Does the new read path work correctly against a row in the OLD shape?
+
+**Seen in:** recurring across multiple production projects.