create-agent-room 1.2.1

package/templates/.agent-room/skills/systematic-debugging.md

@@ -0,0 +1,85 @@
+---
+name: systematic-debugging
+description: "Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes."
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask the
+underlying issue.
+
+**Core principle:** always find the root cause before attempting a fix.
+Symptom fixes are failure.
+
+## The iron law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+**Especially when:** under time pressure, "just one quick fix" seems
+obvious, you've already tried multiple fixes, or you don't fully understand
+the issue yet. None of these are reasons to skip investigation — they're
+exactly when guessing gets expensive.
+
+## The four phases
+
+### Phase 1: Root cause investigation
+
+1. **Read error messages and stack traces completely** — line numbers,
+   file paths, error codes, not just the first line.
+2. **Reproduce consistently** — exact steps, every time. Not reproducible?
+   Gather more data, don't guess.
+3. **Check recent changes** — git diff, recent commits, new dependencies,
+   config or environment differences.
+4. **In multi-component systems, gather evidence at each boundary** before
+   proposing fixes: log what enters/exits each component, verify
+   config/env propagation, check state at each layer. Run once, see *where*
+   it breaks, then investigate that specific component.
+5. **Trace data backward** when the error is deep in a call stack: where
+   did the bad value originate? What called this with that bad value? Keep
+   tracing up to the source — fix at the source, not at the symptom.
+
+### Phase 2: Pattern analysis
+
+- Find working examples of similar code in the same codebase.
+- If implementing a known pattern, read the reference completely — not a
+  skim.
+- List every difference between the working and broken case, however small.
+- Understand the dependencies, config, and assumptions involved.
+
+### Phase 3: Hypothesis and testing
+
+- State one hypothesis clearly: "I think X is the root cause because Y."
+- Test it with the smallest possible change — one variable at a time.
+- Worked? Move to Phase 4. Didn't work? Form a *new* hypothesis — don't
+  stack another fix on top.
+- Genuinely don't know? Say so explicitly rather than guessing.
+
+### Phase 4: Implementation
+
+1. Create a failing test that reproduces the bug (see
+   `.agent-room/skills/test-driven-development.md`).
+2. Implement a single fix addressing the root cause — one change, no
+   bundled refactoring.
+3. Verify: test passes, no other tests broke, the original issue is
+   actually resolved.
+4. **If the fix doesn't work, stop and count attempts.** Fewer than 3:
+   return to Phase 1 with the new information. **3 or more failed fixes
+   means the architecture is probably wrong, not the fix** — stop and
+   question the pattern itself rather than attempting fix #4.
+
+## Red flags — stop and return to Phase 1
+
+"Quick fix for now, investigate later" · "just try changing X" · "skip the
+test, I'll verify manually" · "it's probably X" · proposing a fix before
+tracing data flow · "one more attempt" after 2+ failures · each fix
+revealing a new problem somewhere else.
+
+## When investigation truly finds no root cause
+
+Document what was investigated, implement appropriate handling (retry,
+timeout, clear error message), add logging for next time. This is rare —
+most "no root cause" conclusions are incomplete investigation.

package/templates/.agent-room/skills/test-driven-development.md

@@ -0,0 +1,100 @@
+---
+name: test-driven-development
+description: "Use when implementing any feature or bugfix, before writing implementation code."
+---
+
+# Test-Driven Development (TDD)
+
+## Overview
+
+Write the test first. Watch it fail. Write minimal code to pass.
+
+**Core principle:** if you didn't watch the test fail, you don't know if it
+tests the right thing.
+
+## When to use
+
+**Always:** new features, bug fixes, refactoring, behavior changes.
+
+**Exceptions (ask the maintainer first):** throwaway prototypes, generated
+code, configuration files.
+
+Thinking "skip TDD just this once"? That's rationalization — stop.
+
+## The iron law
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+Wrote code before the test? Delete it. Don't keep it "as reference," don't
+adapt it while writing the test, don't look at it. Implement fresh from
+tests.
+
+## Red-Green-Refactor
+
+```
+RED: write one minimal failing test
+  -> verify it fails for the right reason (not a typo, not existing behavior)
+GREEN: write the minimal code to pass
+  -> verify it passes, and nothing else broke
+REFACTOR: clean up, keep tests green, no new behavior
+  -> next failing test
+```
+
+### RED — write a failing test
+
+One behavior, clear name, real code (mock only if unavoidable).
+
+Good: `test('retries failed operations 3 times', ...)` — tests real behavior.
+Bad: `test('retry works', ...)` with a mock asserting call count — tests the
+mock, not the code.
+
+### Verify RED — mandatory, never skip
+
+Run the test command. Confirm: it fails (not errors), the failure message
+is the expected one, and it fails because the feature is missing — not
+because of a typo. If it passes, you're testing existing behavior — fix the
+test.
+
+### GREEN — minimal code
+
+Write just enough to pass. Don't add options, config, or "while I'm here"
+improvements the test doesn't require (YAGNI).
+
+### Verify GREEN — mandatory
+
+Run the test command again. Confirm it passes and nothing else broke, with
+clean output (no stray errors/warnings).
+
+### REFACTOR
+
+Remove duplication, improve names, extract helpers — only after green, and
+only while staying green.
+
+## Why order matters
+
+- **Tests written after code pass immediately** — passing immediately proves
+  nothing about whether the test would have caught a real bug.
+- **Manual testing isn't a substitute** — no record, can't re-run, easy to
+  forget edge cases under pressure.
+- **"I already spent hours on this, deleting is wasteful"** is sunk-cost
+  reasoning — the time is gone either way; the choice is rewrite-with-tests
+  (high confidence) vs. keep-untested (technical debt from day one).
+
+## Verification checklist before calling work done
+
+- [ ] Every new function/method has a test
+- [ ] Watched each test fail before implementing
+- [ ] Each test failed for the expected reason
+- [ ] Wrote minimal code to pass each test
+- [ ] All tests pass, output is clean
+- [ ] Edge cases and error paths are covered
+
+Can't check every box? TDD was skipped somewhere — go back.
+
+## Debugging integration
+
+Found a bug? Write a failing test that reproduces it first, then follow the
+same red-green-refactor cycle. Never fix a bug without a regression test.
+See `.agent-room/skills/systematic-debugging.md` for root-causing it first.

package/templates/.agent-room/skills/verification-before-completion.md

@@ -0,0 +1,56 @@
+---
+name: verification-before-completion
+description: "Use before claiming work is complete, fixed, or passing - before committing or opening a PR. Evidence before assertions, always."
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not
+efficiency.
+
+**Core principle:** evidence before claims, always.
+
+## The iron law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this turn, you cannot claim
+it passes.
+
+## The gate
+
+```
+Before claiming any status or expressing satisfaction:
+1. IDENTIFY what command actually proves the claim
+2. RUN the full command, fresh
+3. READ the full output — exit code, failure count, warnings
+4. Does the output confirm the claim?
+     no  -> state the actual status, with evidence
+     yes -> state the claim, with evidence
+```
+
+## Common failures
+
+| Claim | Requires | Not sufficient |
+| --- | --- | --- |
+| Tests pass | test command output: 0 failures | "should pass", a previous run |
+| Lint clean | linter output: 0 errors | partial check |
+| Build succeeds | build command: exit 0 | linter passing |
+| Bug fixed | test of the original symptom passes | code changed, assumed fixed |
+| Regression test works | red-green cycle actually verified | passes once |
+| Agent/subtask completed | diff shows the actual changes | "agent reported success" |
+
+## Red flags — stop
+
+Using "should", "probably", "seems to" · expressing satisfaction before
+verifying ("done!", "perfect!") · about to commit/push/open a PR without
+running anything · trusting a sub-agent's self-report instead of checking
+the diff · "just this once."
+
+## The bottom line
+
+Run the command. Read the output. Then make the claim. No shortcuts.

package/templates/.agent-room/skills/writing-plans.md

@@ -0,0 +1,87 @@
+---
+name: writing-plans
+description: "Use when you have an approved design or requirements for a multi-step task, before touching code."
+---
+
+# Writing Plans
+
+## Overview
+
+Turn an approved design into an implementation plan, written as if the
+executor (a fresh agent session, a teammate, or future-you) has zero context
+on this codebase. Document exactly which files to touch, the code, the
+tests, and how to verify each step. DRY. YAGNI. TDD. Frequent commits.
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-sized task granularity
+
+Each step is one action, roughly 2-5 minutes:
+- "Write the failing test" — step
+- "Run it, confirm it fails for the right reason" — step
+- "Write the minimal code to pass" — step
+- "Run it, confirm it passes" — step
+- "Commit" — step
+
+## Plan document header
+
+Every plan starts with:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Goal:** [one sentence describing what this builds]
+**Architecture:** [2-3 sentences about the approach]
+**Tech stack:** [key technologies/libraries]
+
+---
+```
+
+## Task structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.ext`
+- Modify: `exact/path/to/existing.ext:123-145`
+- Test: `tests/exact/path/to/test.ext`
+
+**Step 1: Write the failing test**
+[complete test code, not "add validation"]
+
+**Step 2: Run test to verify it fails**
+Run: `<exact command>`
+Expected: FAIL with "<exact message>"
+
+**Step 3: Write minimal implementation**
+[complete code]
+
+**Step 4: Run test to verify it passes**
+Run: `<exact command>`
+Expected: PASS
+
+**Step 5: Commit**
+```bash
+git add <files>
+git commit -m "<message>"
+```
+````
+
+## Remember
+
+- Exact file paths always.
+- Complete code in the plan, never "add validation" as a placeholder.
+- Exact commands with expected output, not "run the tests."
+- DRY, YAGNI, TDD, frequent commits.
+
+## Execution
+
+Once the plan is saved, either:
+1. **Work through it task-by-task in this session**, verifying each step
+   before moving to the next (see `.agent-room/skills/test-driven-development.md`
+   and `.agent-room/skills/verification-before-completion.md`), or
+2. **Hand the plan file to a fresh agent session** to execute, if you want a
+   clean context with no accumulated assumptions from the design discussion.
+
+Either way: one task at a time, verify before moving on, commit frequently.

package/templates/.agent-room/workflow-classifier.md

@@ -0,0 +1,127 @@
+# Workflow Classifier
+
+Not all work deserves the same process. Classify before loading process —
+over-process wastes time, under-process builds the wrong thing.
+
+## Quick classifier
+
+| Work Type | Use it for | PRD | Architecture | TDD | Time |
+| --- | --- | --- | --- | --- | --- |
+| Bug | Something broke | None | None | Fix + regression test | Hours |
+| Enhancement | Small change on existing rails | Light | Light | Yes | Days |
+| Feature | New bounded capability | Yes | Yes | Full | Weeks |
+| Product | New system or unclear scope | Deep | Extensive | Full + spikes | Months |
+
+## Decision tree
+
+```
+Did something break?
+  yes -> Bug Flow
+  no
+    Does similar code/pattern already exist in this repo?
+      yes -> Enhancement Flow
+      no
+        Is the scope clear and bounded?
+          yes -> Feature Flow
+          no  -> Product Flow
+```
+
+Stop as soon as one answer is clear. Ask in this order:
+1. Did something break?
+2. Am I extending an existing pattern?
+3. Can I define "done" right now?
+4. If not, am I still discovering the problem?
+
+## Worked examples
+
+### "Fix: login button returns 500 on Safari"
+- Did something break? Yes — it worked before, now it doesn't.
+- **Classification: Bug.**
+- Process: Reproduce on Safari, read the server logs, find the root cause
+  (not the symptom), write a regression test, smallest fix, note why it
+  slipped through in `anti-patterns.md`. Hours.
+
+### "Add dark mode to the settings page"
+- Did something break? No.
+- Does similar code exist? Yes — there's already a theme toggle in the
+  header component and CSS custom properties for colors in `theme.css`.
+- **Classification: Enhancement.**
+- Process: Light PRD (one paragraph: "extend the existing theme system to
+  settings page, using the same CSS custom properties"), find the closest
+  prior example (`Header.tsx` theme toggle), TDD the new toggle, 1-2 days.
+
+### "Support webhook notifications for order status changes"
+- Did something break? No.
+- Does similar code exist? No — there's no webhook infrastructure, no
+  event system, no retry queue.
+- Is the scope clear? Yes — we know exactly which events trigger webhooks,
+  the payload shape, and the delivery guarantees we need.
+- **Classification: Feature.**
+- Process: Full brainstorm (delivery guarantees? retry policy? signature
+  verification?), design doc, architecture review, TDD, 1-2 weeks.
+
+### "We need to support multi-tenant data isolation"
+- Did something break? No.
+- Does similar code exist? No — the app is single-tenant.
+- Is the scope clear? Partially — we know what isolation means, but the
+  migration strategy, tenant resolution mechanism, and query scoping
+  approach all need design. We're still discovering the problem.
+- **Classification: Product.**
+- Process: Define the problem before the feature list. Write key hypotheses
+  ("row-level security vs. schema-per-tenant"). Spike the risky assumptions.
+  Build the smallest useful proof of concept. Learn and iterate. Months.
+
+## Misclassification signals
+
+You classified wrong if any of these are true:
+
+| Signal | What it means |
+| --- | --- |
+| A "Bug" fix requires changing more than 3 files | It's probably an Enhancement or Feature — the root cause is structural, not a local defect. |
+| An "Enhancement" keeps revealing new unknowns | It's actually a Feature — you can't define "done" because the scope keeps growing. |
+| A "Feature" has been in progress for 2+ months | It's actually a Product — the scope was never bounded, and you're discovering requirements as you build. |
+| A "Product" has a perfectly clear scope and takes 2 weeks | It was a Feature all along — you over-classified and loaded unnecessary process. |
+| Time spent dramatically exceeds the budget below | The classification, not the estimate, is probably wrong. Re-classify rather than push through. |
+
+**The fix is always the same:** stop, re-classify, adjust the process.
+Don't push through with the wrong process — that's how Bug fixes become
+multi-week refactors and Features become death marches.
+
+## Bug Flow (hours)
+Reproduce -> Diagnose (root cause, not symptom) -> Write the regression test
+first -> Smallest fix that passes -> Run the relevant checks -> Note why it
+slipped through (append to `.agent-room/anti-patterns.md`).
+
+Do not load: PRD files, architecture exploration, spikes.
+
+## Enhancement Flow (days)
+Confirm it fits existing rails -> short PRD (a paragraph is fine) -> find the
+closest prior example in the codebase -> TDD -> quick review and ship.
+
+Rule of thumb: if you can describe it as "do X like we already do Y," it's an
+enhancement. If you can't find a Y, it's a feature.
+
+## Feature Flow (weeks)
+Write the first design from the user journey -> let architecture discoveries
+tighten/simplify the design (don't treat draft 1 as sacred) -> TDD against the
+final shape -> review -> observe after shipping.
+
+Use the `brainstorming` -> `writing-plans` -> TDD chain in `.agent-room/skills/`
+for this.
+
+## Product Flow (months)
+Define the problem before the feature list -> write the key hypotheses ->
+spike the risky assumptions -> build the smallest useful MVP -> learn from
+reality and loop (iterate or pivot).
+
+## Time budget as a signal
+
+| Work Type | Design | Build | Review | Total |
+| --- | --- | --- | --- | --- |
+| Bug | 0 | ~2h | 30m | hours |
+| Enhancement | 30m | ~4h | 1h | 1-2 days |
+| Feature | 4-8h | 16h+ | 4h | 1-2 weeks |
+| Product | 8h+ | 40h+ | 8h+ | 4+ weeks |
+
+If real work keeps blowing past the expected budget, the classification —
+not the estimate — is probably wrong. Re-classify rather than push through.

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,85 @@
+# Agent Instructions — {{PROJECT_NAME}}
+
+This file is the entry point for any AI coding agent (Claude Code, Codex,
+Cursor, etc.) working in this repository. Tool-specific files (`CLAUDE.md`,
+`.cursor/rules`, ...) are thin pointers back to this file plus their own
+loading mechanics — the actual content lives here and in `.agent-room/`.
+
+## The First 5 Minutes
+
+When you first enter this repository or start a new task, **stop and read**.
+Do not immediately start writing code.
+
+1.  **Check coordination state:** Are there other agents working? Check open
+    PRs, issue assignments, or the `.agent-room/sessions/` directory.
+    Read `.agent-room/coordination/handoff-protocol.md` if you are picking
+    up someone else's work.
+2.  **Classify the work:** Use `.agent-room/workflow-classifier.md`. Don't
+    apply Feature-weight process to a one-line bug fix, and don't skip design
+    for a "simple" feature.
+3.  **Check guardrails:** Review `.agent-room/guardrails.md`. Ensure your
+    planned work does not touch protected paths or require human approval
+    without asking first.
+4.  **Review past decisions:** Read `.agent-room/anti-patterns.md` and
+    `.agent-room/decisions.md` to understand *why* the codebase is structured
+    this way, and what mistakes to avoid.
+
+## Read these before doing anything non-trivial
+
+- [`.agent-room/principles.md`](.agent-room/principles.md) — how to get
+  reliable output from an LLM (context, iteration, checkpointing, tests as
+  spec, negative knowledge).
+- [`.agent-room/guardrails.md`](.agent-room/guardrails.md) — boundaries and
+  constraints. Check before touching protected paths or making large changes.
+- [`.agent-room/workflow-classifier.md`](.agent-room/workflow-classifier.md) —
+  how to size the process to the work (Bug / Enhancement / Feature / Product).
+- [`.agent-room/anti-patterns.md`](.agent-room/anti-patterns.md) — things that
+  have already gone wrong in this project. Check before repeating a mistake;
+  append after fixing one.
+- [`.agent-room/decisions.md`](.agent-room/decisions.md) — short log of
+  architecture/design decisions and why. Append when you make one that future
+  sessions would otherwise have to re-derive.
+- [`.agent-room/skills/`](.agent-room/skills/) — procedures to follow, not
+  just read: `brainstorming`, `writing-plans`, `test-driven-development`,
+  `systematic-debugging`, `verification-before-completion`,
+  `closing-the-loop`.
+- [`.agent-room/coordination/`](.agent-room/coordination/) — protocols for
+  multi-agent workflows: `handoff-protocol`, `scope-boundaries`,
+  `session-log-format`.
+
+## The default workflow
+
+1. **Classify the work** using `.agent-room/workflow-classifier.md`.
+2. **For anything beyond a trivial bug fix**, brainstorm before building: ask
+   clarifying questions, propose 2-3 approaches with trade-offs, get the
+   design approved, *then* write a short design note under `docs/plans/`.
+3. **Use TDD**: write the failing test first, watch it fail, write the
+   minimal code to pass, refactor, commit. No production code without a
+   failing test first.
+4. **Debug systematically**: find the root cause before proposing a fix.
+   Reproduce, check recent changes, gather evidence at component boundaries.
+   No fixes without root-cause investigation.
+5. **Verify before claiming done**: run the actual test/build/lint command in
+   this turn and read its output before saying "tests pass" or "fixed."
+   "Should work" is not evidence.
+6. **Serialize state**: Before ending your session, log your work in
+   `.agent-room/sessions/` according to `session-log-format.md`, and write
+   a handoff note if the task is incomplete.
+7. **Close the loop — before ending the turn, not after**: this is a gate,
+   not a suggestion. Follow `.agent-room/skills/closing-the-loop.md`. If the
+   turn fixed a bug, found a root cause, or made a non-obvious design call,
+   append it to `.agent-room/anti-patterns.md` or `.agent-room/decisions.md`
+   *before* claiming the task is done. If nothing qualifies, say so
+   explicitly rather than silently skipping the check.
+
+## Project-specific notes
+
+- **Language:** {{LANGUAGE}}
+- **Package Manager:** {{PACKAGE_MANAGER}}
+- **Default Branch:** {{DEFAULT_BRANCH}}
+
+Commands:
+- Run tests: `{{TEST_COMMAND}}`
+- Run linting: `{{LINT_COMMAND}}`
+
+<!-- Add stack, conventions, and anything else an agent needs that isn't derivable. -->

package/templates/adapters/CLAUDE.md.tmpl

@@ -0,0 +1,38 @@
+# CLAUDE.md — {{PROJECT_NAME}}
+
+This file is read automatically by Claude Code. The actual guidance lives in
+[`AGENTS.md`](AGENTS.md) and [`.agent-room/`](.agent-room/) — read those
+first, this file only adds Claude Code-specific mechanics.
+
+## Skills
+
+The skills in `.agent-room/skills/` are mirrored into `.claude/skills/` so
+Claude Code can discover and invoke them (`/brainstorming`,
+`/writing-plans`, `/test-driven-development`, `/systematic-debugging`,
+`/verification-before-completion`, `/closing-the-loop`).
+
+`.agent-room/skills/` is the source of truth. If you edit a skill, re-run
+`npx create-agent-room sync` to refresh the `.claude/skills/` copies — don't
+edit the `.claude/skills/` copies directly, they'll be overwritten.
+
+## Closing-the-loop hook
+
+A `Stop` hook is wired up in `.claude/settings.json`, running
+`.agent-room/hooks/close-the-loop-check.js` at the end of every turn. If the
+turn changed tracked files outside the agent-room scaffold but didn't touch
+`.agent-room/anti-patterns.md` or `.agent-room/decisions.md`, the hook
+blocks the turn from ending and explains why. This is mechanical
+enforcement of `.agent-room/skills/closing-the-loop.md` — it can't judge
+whether an entry is *good*, only that the check wasn't silently skipped.
+
+The exit hatch is a one-line waiver in `decisions.md`:
+`<!-- no-log: routine change, no decision or anti-pattern worth recording -->`
+
+The hook only looks at `git status --porcelain`, so unrelated pre-existing
+dirty files in the work tree will also trigger it — commit or stash them
+first if that gets noisy.
+
+## Git rules
+
+- Do not run `git push` unless explicitly asked.
+- Do not amend or rewrite history on shared branches without being asked.

package/templates/adapters/claude-hooks/close-the-loop-check.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Claude Code Stop hook: mechanically enforces .agent-room/skills/closing-the-loop.md.
+ *
+ * Runs at the end of every turn. If tracked, uncommitted changes touch files
+ * outside the agent-room scaffold but neither .agent-room/anti-patterns.md
+ * nor .agent-room/decisions.md was also touched, it blocks the turn from
+ * ending (exit code 2) and explains why via stderr, which Claude Code feeds
+ * back to the model as the reason it can't stop yet.
+ *
+ * Exit hatch: touch either log file - a real entry, or a one-line waiver
+ * comment - and the check passes. See closing-the-loop.md for the format.
+ *
+ * Limitations (by design, to stay simple):
+ * - Only looks at `git status --porcelain` since the last commit, not since
+ *   the start of this turn. Pre-existing unrelated dirty changes in the work
+ *   tree will also trigger this - commit or stash them first if that's noisy.
+ * - Treats any file rename touching scaffold paths as a non-scaffold change
+ *   (rare, harmless false positive).
+ */
+
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+function sh(cmd) {
+  try {
+    return execSync(cmd, { cwd: process.cwd(), stdio: ['ignore', 'pipe', 'ignore'] }).toString();
+  } catch (err) {
+    return '';
+  }
+}
+
+function isGitRepo() {
+  return sh('git rev-parse --is-inside-work-tree 2>/dev/null').trim() === 'true';
+}
+
+const SCAFFOLD_PREFIXES = [
+  '.agent-room/',
+  'docs/plans/',
+  '.claude/skills/',
+  '.claude/settings.json',
+  '.cursor/rules/',
+];
+const SCAFFOLD_FILES = ['AGENTS.md', 'CLAUDE.md'];
+
+function isScaffoldPath(p) {
+  if (SCAFFOLD_FILES.includes(p)) return true;
+  // Bidirectional: p itself under a scaffold prefix (normal case), OR p is an
+  // ancestor directory of a scaffold prefix (git collapses an untracked dir
+  // with no other tracked siblings into a single porcelain line, e.g. a
+  // brand-new ".claude/" with nothing else in it yet shows as "?? .claude/").
+  return SCAFFOLD_PREFIXES.some((prefix) => p.startsWith(prefix) || prefix.startsWith(p));
+}
+
+function isLogPath(p) {
+  return p === '.agent-room/anti-patterns.md' || p === '.agent-room/decisions.md';
+}
+
+function main() {
+  const cwd = process.cwd();
+
+  if (!fs.existsSync(path.join(cwd, '.agent-room'))) {
+    process.exit(0); // not a scaffolded project
+  }
+  if (!isGitRepo()) {
+    process.exit(0); // no git history to check against
+  }
+
+  const lines = sh('git status --porcelain').split('\n').filter(Boolean);
+  const changedPaths = lines.map((line) => line.slice(3).trim());
+
+  const sourceChanges = changedPaths.filter((p) => !isScaffoldPath(p));
+  const logTouched = changedPaths.some(isLogPath);
+
+  if (sourceChanges.length === 0 || logTouched) {
+    process.exit(0);
+  }
+
+  const sample = sourceChanges.slice(0, 5).join(', ') + (sourceChanges.length > 5 ? ', ...' : '');
+  process.stderr.write(
+    'Closing-the-loop check failed: this turn changed ' + sourceChanges.length +
+      ' file(s) outside the agent-room scaffold (' + sample + '), but neither ' +
+      '.agent-room/anti-patterns.md nor .agent-room/decisions.md was touched.\n\n' +
+      'Follow .agent-room/skills/closing-the-loop.md before finishing this turn:\n' +
+      '- If this fixed a bug or found a root cause, append an entry to anti-patterns.md.\n' +
+      '- If this made a non-obvious design/architecture call, append an entry to decisions.md.\n' +
+      '- If genuinely neither applies, add a one-line waiver to decisions.md instead:\n' +
+      '  <!-- no-log: routine change, no decision or anti-pattern worth recording -->\n'
+  );
+  process.exit(2);
+}
+
+main();