@warren-dean/code-kit 0.7.0 → 0.8.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "code-kit",
       "source": "./",
       "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
-      "version": "0.7.0",
+      "version": "0.8.0",
       "category": "development",
       "tags": ["guardrails", "architecture", "lanes", "layers", "spec-driven", "ci", "multi-agent"],
       "license": "MIT"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "code-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Keeps AI coding agents inside your project's rules, from idea to merged code: spec design, lanes, layer rules, protected paths with an approval log, spec-check and design gates, proof-before-finish checks, dispatch, review, build status and CI verification, configured per project from its docs",
   "author": {
     "name": "Warren Langeveldt"

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 What changed in each release of code-kit, newest first. Versions follow the plugin manifest and the npm package `@warren-dean/code-kit`. Each release is also on [GitHub Releases](https://github.com/warrendeanlangeveldt/code-kit/releases).
 
+## 0.8.0 (2026-10-11)
+
+You decide what's built and the rules; the lead delivers it. Only real decisions reach you, each with the story behind it, and the whole build reads as one story from your request to now.
+
+**Who decides what**
+
+- **No first merge.** Setting up commits the rules you approved straight onto `main`, so the lead can merge reviewed work from the start. Under autonomy, setup also drafts limits within which the lead merges and approves new packages itself; you adjust them before approving.
+- **Lane work is the lead's.** While the loop runs, a lane's finished work never waits for you: the lead reviews, sends back and merges it. With the loop off, Review and Merge are offered to you as before.
+- **Decisions come with their story.** Each one above the prompt says which story it's for ("for ST-4 Booking form (BOOK-1)"), and **d** opens it as a card in the new Decisions tab: what you asked for, the story and its requirements, what the agent was doing, what's already settled, why the lead couldn't settle it (the rule, and the limit it missed), and what each answer does. Usage and pauses are labelled "note", not "you".
+- **The Journal.** A Journal tab, and `code-kit journal`, tell the build by day: your request and the decisions in your brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session.
+
+**Seeing the build**
+
+- **The mission band.** Above the prompt, while the build moves: the milestone being built and how far along it is, what the lead is doing, the loop's next step, and each agent at work with its current tool.
+- **The Lanes pane** opens on the loop as a card (its mode, its steps, the next one), keeps each lane on fixed columns, shows a lane's stories as cards, and reads "orchestrating" while the lead works.
+- **The code map.** A story's files in a column per layer with the imports between them; a file fills with a lane's colour while that lane reads or edits it, and says whether its why is written. `code-kit map <story>`.
+- **The trail.** Each requirement drawn to its stories, code and tests, with a missing link in red. `code-kit trail`.
+- Tabs are now Lanes 1, Decisions 2, Journal 3, Code map 4, Trail 5, Queue 6, Usage 7.
+
+**Fixes**
+
+- Pausing the loop is recorded (`code-kit loop`), so Context Graph's background work pauses with it. A new session starts unpaused.
+- The stall check no longer nudges or restarts agents whose work is done, and until you choose how hands-off the loop is, a restart is offered, not taken.
+- With Context Graph, agents can add the guidance they find without your approval; only its settings stay yours.
+
 ## 0.7.0 (2026-10-10)
 
 The rest of the harness, in the mod (Claude Code 2.1.287 or later), and fixes from building a whole app with it.

package/README.md

@@ -17,6 +17,12 @@ It also carries the work from idea to merged code: spec an idea into requirement
   <img src="https://raw.githubusercontent.com/warrendeanlangeveldt/code-kit/main/assets/workflow.svg" alt="How code-kit works: the specs create the agents, skills and rules; the lead agent delegates stories to lane agents and takes decisions and approvals to you; lanes send scope and dependency requests back to the lead; hooks enforce ownership, layers, approvals and spec-check while each lane implements, tests and commits; the lead reviews against the requirements and CI runs verify." width="820">
 </p>
 
+<p align="center">
+  <a href="https://warrendeanlangeveldt.github.io"><img src="https://warrendeanlangeveldt.github.io/assets/media/harness.gif" alt="code-kit and Context Graph in a Claude Code session: the band above the prompt, the lanes, the code map lighting up as agents read and edit, and the module graph" width="900"></a>
+</p>
+
+**See it in action at [warrendeanlangeveldt.github.io](https://warrendeanlangeveldt.github.io)**, with a live replay of a real build.
+
 ## Quick start
 
 You need Claude Code, Node 22 or later, and git. Then, in Claude Code:
@@ -266,9 +272,9 @@ Editing an agent file can't loosen a rule. And the agent files are kit files (`.
 
 With Claude Code 2.1.287 or later, code-kit's mod shows the project in the session, in the terminal (VS Code's terminal included) and the Desktop app. Older versions skip it and keep enforcing everything through the hooks.
 
-- **The band** sits above the prompt whenever something waits for you, and is gone when nothing does. It shows:
+- **The band** sits above the prompt. While the build is moving (the lead mid-turn, an agent at work, the loop started) it opens with the mission: **goal**, the milestone being built and how many of its stories are done; **now**, what the lead is doing and the loop's state, with **Pause** or **Resume**; **next**, the step the loop takes next; and **agents**, a line per agent at work with its current tool and how long since. With Context Graph installed, a line says when a lane edited files without understanding them, and only then. Beneath, labelled **you**, what only you can decide, each with the story it's for ("for ST-4 Booking form (BOOK-1)"), and **d** ("Why, and what each choice does") opens it as a card in the Decisions tab; usage and the plan's pause are labelled **note**. While the loop runs, a lane's finished work is the lead's to review and merge, so it never waits here; with the loop off, Review and Merge are offered to you. With nothing happening and nothing waiting, the band is gone. It shows:
   - an agent's call held for you: installing a new package, writing or committing a protected file, or a lane changing the kit. Rather than stopping the agent, the call waits while the band asks ("web wants to install dayjs · 1:53"). **Approve** opens the confirmation and, once you confirm, the same call runs; **Refuse**, or no answer within `harness.hold.minutes` (2 unless set), refuses it as before. Under `autonomy: autonomous`, a call within `approvals.delegate` is approved as delegated without asking. Nothing is held under `claude -p` or the SDK, where nobody can answer;
-  - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed. A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged; at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges; the first merge, which brings code-kit's rules onto the base, is always yours. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
+  - the lead loop, under `harness.autonomy`. `/code-kit:init` asks you how hands-off you want it. Until you've chosen, the loop's first step waits in the band ("code-kit can keep the build moving between your prompts") with **Keep going**, **Ask each time** and **Off**, and your answer is recorded as your setting. Once the lead has finished a turn, the loop keeps the build moving: with the lead idle and nothing typed in the prompt, it asks `code-kit next` and prompts the lead to dispatch the ready stories, review a finished one, or build its own, never the same step twice while nothing has changed. A step the lead was prompted with twice in a row and that is still next goes to you instead, in the band: "Merge lead/st-1: still next after 2 prompts. Ask the lead again?" with **Go**. **Pause** and **Resume** stop and start it. Under `propose`, each step waits in the band for **Go**; under `off`, the loop does nothing. A lane agent with no tool call for `harness.stall.nudgeMinutes` (5) is messaged, unless its work is done (it handed back, or its branch is in review or the merge queue); at `stall.restartMinutes` (10) the lead is asked to stop it and dispatch its story again, at most `stall.maxRestarts` (2) times, and then the band flags the lane. When every story is done, the band says so and the loop stops. With `harness.agents.reviewer.on`, a finished branch is first reviewed in the background by code-kit's reviewer agent, which the lead starts: it runs `verify` and the review checklist, read-only, and grades each finding blocker, concern or nit. The lead's review prompt then carries the findings, and a blocker means the branch is sent back. The pane shows each review, running with its clock or what it found. If the reviewer hasn't reported within 15 minutes, or the plan's 5-hour use is past `harness.background.pauseAtPercent`, the lead reviews without it. A branch the lead's review passes joins the merge queue (`code-kit queue`). Branches merge one at a time, in the order they passed, each verified against the base as it is then: the lead merges where `approvals.delegate.merge` is on under `autonomous`, otherwise the band shows the head with **Merge** for you. Who may merge is read from the config committed on the base, so a branch can't grant itself merges. There's no first merge for you: setting up commits the rules you approved straight onto the base. A merged lane's worktree is removed when it holds nothing uncommitted. A head that conflicts or fails verify goes back to its lane. The pane lists the queue, and lanes whose branch waits in it read `queued`;
   - approvals agents have asked for: **Approve…** opens a confirmation with a reason prefilled from the request, which you keep or rewrite;
   - stories finished and waiting for review: **Review** asks the lead to run `/code-kit:review` on the branch, and **Merge** runs `verify`, checks included, then merges if it passes;
   - a finish check failing in this session: **Lanes** opens the pane;
@@ -277,7 +283,7 @@ With Claude Code 2.1.287 or later, code-kit's mod shows the project in the sessi
 
   Each button has a digit: type it in an empty prompt to press it.
 
-- **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **4**: **Lanes**, each lane with its agent, story, branch, state, and its current or last tool call with the time since, amber once quiet and red when stalled. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Queue**, the merge queue; **Usage**; and **Map**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, and the tests that name it. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
+- **`/lanes`** opens the Lanes pane. Its first line counts the stories by state (building, in review, queued, sent back, blocked, ready, merged), with the loop's state and the plan's 5-hour use; press a count to show only those lanes. Beneath it, whatever needs you (held calls, approvals, reviews, merges, stalled lanes, outliers) is pinned with its key. Tabs on **1** to **7**: **Lanes** opens on the loop as a card: its mode, the steps it took, the one running and the next. Then each lane on fixed columns: its name, state and story, its agent's current or last tool call with the time since beneath (amber once quiet, red when stalled), and its tokens; the lead reads orchestrating while its turn runs. A selected lane shows its stories as cards (state, requirements, what each waits on or its branch), then its agent and the paths it owns. **Decisions**, each decision that needs you as a card: what you asked for, the story and its requirements, what was happening, what's already settled, why the lead couldn't settle it, and each option with what it does; **Journal**, the build from your request to now in plain sentences, by day: the request and the decisions in the brief, the specification, each story handed out, sent back and merged, each approval and who gave it, each milestone finished, and the loop's steps this session, yours in yellow. Each lane has its own small pixel character, tinted in the lane's colour, whose pose shows its state: working (animated while its agent works), waiting on you, quiet, stalled, done or resting; the lead's wears a crown. Under each lane, its story's timeline on a shared time axis: building, then in review, with send-backs (↩), approvals (◆) and the merge (✓) marked where they fell; **Code map**, a story's files in a column per layer with the imports between them: a file fills with a lane's colour while that lane reads or edits it, and says whether its why (its Context Graph card) is written, out of date or not written yet; **j**/**k** select a file to see its card and what it imports and what imports it, and **o** opens it in Context Graph (box-drawing text in the terminal, an SVG on Desktop); **Trail**, every requirement in the specs as a cell by spec, its glyph and colour saying whether it's done and tested, done but untested, in progress, todo, without a story or removed, with a legend counting each. **h**/**l** and **j**/**k** move between cells and specs (or pick one from the list), showing the requirement's stories, their branches, the code they changed and the tests that name it; beneath the cells, the spec's trail drawn as a flow, each requirement to its stories, code and tests, with a missing link dashed in red; **Queue**, the merge queue; and **Usage**. **j** and **k** move between lanes, and the selected lane's acts are on **a** (approve), **r** (review), **s** (send back, with your reason), **m** (merge), **n** (nudge its agent) and **x** (stop it); **p** pauses or resumes the loop, and **f** filters the lanes by name, agent or story. **Enter** (or **o**) opens the selected lane's story: its requirements beside its spec-check report, the reviewer's findings by severity (each a way into the diff), `verify`'s problems, its usage and loop steps, and its diff against the base, file by file, with the acts its state allows. **b** or Escape goes back to the lanes. Inline (when the terminal can't dock it beside the transcript), it shows the counts, what needs you and a line per lane. It stays current within 2 seconds of a commit, a branch change, a plan edit or an agent starting or stopping. `/lanes` again, or Escape, closes it.
 - **Refusals** a code-kit hook gives an agent are drawn as cards: what was refused, the rule, what to do, and Approve… where your approval would allow it. The full text is a press away.
 - **`/harness`** opens the harness settings: how the lead loop acts, how long a call waiting on your approval is held, when a stalled lane is nudged and restarted, the reviewer agent and its model, and the use at which background agents pause. Changing one asks your reason, writes `.claude/code-kit.json` and logs a `kit` approval. Lanes, paths and rules still change through `/code-kit:init`.
 - **`/approvals`** lists the requests waiting and the approvals in force, with minutes left. **`/verify-branch`** runs `code-kit verify` on this branch. Neither calls the model.
@@ -341,8 +347,13 @@ code-kit settings set <key> <value> --reason "…"               # change one, a
 code-kit queue [--json]                                      # the merge queue: branches whose review passed, in order
 code-kit queue add|drop <branch>                              # the lead queues a branch its review passed, or takes it out
 code-kit queue merge --delegated|--person                     # merge the head, verified against the base as it is now; a conflict or failed verify sends it back to its lane
+code-kit loop [--json]                                        # whether the person paused the lead loop; other tools' background work pauses with it
+code-kit loop pause|resume                                    # the person's act, as Pause and Resume in the band
 code-kit story <id> [--json]                                  # one story's requirements, spec-check report, diff against the base and verify (without checks), for the drill-down
 code-kit timeline [--json]                                    # when each story's work happened: its branch made, last commit, merge, send-backs and approvals
+code-kit journal [--json]                                     # the build's lineage: the request, its decisions, the spec, each story handed out, sent back and merged, each approval and who gave it
+code-kit map <story> [--json]                                 # a story's code: its files by layer, the imports between them, and what adapters know of each
+code-kit trail [--json]                                       # each requirement to its stories, the code they changed and the tests that name it
 code-kit adapters [--json --session id]                       # the adapters in use; with --json, what they know of each lane's work in a session
 code-kit hold <id> [--minutes N]                              # used by the mod: a held call waits here for the band's answer (--answer approved|refused)
 code-kit approve <name>... --reason "…" [--lane name] [--delegated | --via pane|<tool>]  # record a person's approval from chat, or (--delegated) grant one within the delegated rules; a package name stands for its dep- approval

package/bin/code-kit.mjs

@@ -53,8 +53,11 @@ import { traceFile } from '../hooks/lib/trace.mjs';
 import { buildStatus, specCheckRows } from '../hooks/lib/plan.mjs';
 import { recordSentBack } from '../hooks/lib/reviews.mjs';
 import { storyTimes } from '../hooks/lib/timeline.mjs';
+import { storyMap, trail } from '../hooks/lib/storymap.mjs';
+import { journal } from '../hooks/lib/journal.mjs';
 import { dequeue, enqueue, lastMerged, readQueue, settle, waiting } from '../hooks/lib/queue.mjs';
 import { SETTINGS, parseSetting, settingOf, withSetting } from '../hooks/lib/harness.mjs';
+import { readLoop, writeLoop } from '../hooks/lib/loop-state.mjs';
 import {
   APPROVAL_MINUTES,
   approvalLifetime,
@@ -568,6 +571,69 @@ function queue() {
   left.forEach((e, i) => out(`  ${i + 1}. ${e.branch} (passed review ${e.passed})`));
 }
 
+/**
+ * MAP-1: a story's code: the files it changed by layer, with the imports between them, and what the
+ * active adapters know of each (its card, its rules). `map <id> --json` is what the pane draws.
+ */
+function mapCommand(id) {
+  const { config, raw } = load();
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan)
+    die('map needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
+  const from = base(config, false);
+  const { stories } = buildStatus('.', config, from, tracked());
+  const s = stories.find((x) => x.id === id.toUpperCase());
+  if (!s) die(`There is no story ${id} in ${plan}.`);
+  const map = storyMap(resolve('.'), s, config, from);
+  const facts = adapterFacts(raw, resolve('.'), { paths: map.files.map((f) => f.path) });
+  for (const f of map.files)
+    f.adapters = Object.fromEntries(
+      facts.filter((a) => a.files?.[f.path]).map((a) => [a.name, a.files[f.path]]),
+    );
+  map.open = facts.find((a) => a.open)?.open ?? null;
+  if (flag('--json')) return out(JSON.stringify(map, null, 2));
+  out(`${s.id} ${s.title} (${map.files.length} file(s)):`);
+  for (const layer of map.layers) {
+    out(`  ${layer}`);
+    for (const f of map.files.filter((x) => x.layer === layer))
+      out(`    ${f.path}${f.imports.length ? `  → ${f.imports.join(', ')}` : ''}`);
+  }
+}
+
+/** JOURNAL-1: the build's lineage, from the request to each merge, in plain sentences. */
+function journalCommand() {
+  const { config } = load();
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan)
+    die('journal needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
+  const from = base(config, false);
+  const events = journal(
+    resolve('.'),
+    buildStatus('.', config, from, tracked()),
+    from,
+    config.docs,
+  );
+  if (flag('--json')) return out(JSON.stringify({ base: from, events }, null, 2));
+  for (const e of events)
+    out(`${new Date(e.at).toISOString().slice(0, 16).replace('T', ' ')}  ${e.text}`);
+}
+
+/** TRAIL-1: each requirement to its stories, the code they changed and the tests that name it. */
+function trailCommand() {
+  const { config } = load();
+  const { specs, plan } = config.docs ?? {};
+  if (!specs || !plan)
+    die('trail needs docs.specs and docs.plan in the config. The spec-design skill writes both.');
+  const from = base(config, false);
+  const status = buildStatus('.', config, from, tracked());
+  const rows = trail(resolve('.'), status, from);
+  if (flag('--json')) return out(JSON.stringify({ base: from, requirements: rows }, null, 2));
+  for (const r of rows)
+    out(
+      `${pad(r.id, 10)} ${pad(r.stories.map((s) => s.id).join(', ') || '-', 14)} ${pad(`${r.files.length} file(s)`, 10)} ${r.tests.length ? r.tests.join(', ') : 'no test names it'}`,
+    );
+}
+
 /** When each story's work happened, for the mod's timelines (VIEW-2). */
 function timeline() {
   const { config } = load();
@@ -1069,8 +1135,31 @@ async function approve(given) {
   );
 }
 
+/**
+ * The lead loop's pause (LOOP-6): `loop` says whether the person paused it; `loop pause|resume`, the
+ * person's act from the code-kit band, records it, so other tools' background work pauses with it.
+ */
+function loopCommand() {
+  const root = resolve('.');
+  const [sub] = rest;
+  if (sub === 'pause' || sub === 'resume') {
+    writeLoop(root, sub === 'pause');
+    return out(sub === 'pause' ? 'The lead loop is paused.' : 'The lead loop is running.');
+  }
+  if (sub !== undefined) die('code-kit loop [--json] | loop pause | loop resume');
+  const state = readLoop(root);
+  out(
+    flag('--json')
+      ? JSON.stringify(state)
+      : state.paused
+        ? `The lead loop is paused (since ${state.at}).`
+        : 'The lead loop is running.',
+  );
+}
+
 const commands = {
   check,
+  loop: loopCommand,
   approve: () => (rest.length ? approve(rest) : usage()),
   merge: () => (rest.length === 1 ? merge(rest[0]) : usage()),
   requests,
@@ -1079,6 +1168,9 @@ const commands = {
   hold: () => (rest.length === 1 ? hold(rest[0]) : usage()),
   queue,
   story: () => (rest.length === 1 ? story(rest[0]) : usage()),
+  map: () => (rest.length === 1 ? mapCommand(rest[0]) : usage()),
+  trail: trailCommand,
+  journal: journalCommand,
   timeline,
   'sent-back': () => (rest.length === 1 ? sentBackCommand(rest[0]) : usage()),
   trace: () => (rest.length ? trace(rest) : usage()),
@@ -1103,6 +1195,8 @@ function usage() {
       '              | settings [--json] | settings set <key> <value> --reason "…" [--via pane]\n' +
       '              | hold <id> [--minutes N] | hold <id> --answer approved|refused\n' +
       '              | queue [--json] | queue add|drop <branch> | queue merge --delegated|--person\n' +
+      '              | loop [--json] | loop pause|resume\n' +
+      '              | map <story> [--json] | trail [--json] | journal [--json]\n' +
       '              | story <id> [--json] | timeline [--json]',
   );
 }

package/hooks/guard-bash.mjs

@@ -11,6 +11,7 @@ import { join, resolve } from 'node:path';
 import { addedPackages, dependencyApproval, isDependencyFile } from './lib/dependencies.mjs';
 import { CODE_KIT, GIT, codeOf, commandsOf, runs } from './lib/shell.mjs';
 import { block, start } from './lib/hook.mjs';
+import { CONFIG_FILE } from './lib/config.mjs';
 import { noteBefore } from './lane-audit.mjs';
 import {
   APPROVAL_LOG,
@@ -89,6 +90,14 @@ const branches = config.branches.protected
 // The branch is read before the command runs, so a command that switches to a protected branch and then
 // commits or merges in the same breath is judged by what it does, not by where it starts. Moving a
 // protected branch directly (branch -f, update-ref) is a commit on it by another name.
+/** Whether `file` is committed at HEAD in the repository at `root`. */
+function committedOnHead(root, file) {
+  return (
+    spawnSync('git', ['-C', root, 'cat-file', '-e', `HEAD:${file}`], { stdio: 'ignore' }).status ===
+    0
+  );
+}
+
 const writesHistory = runs(
   cmd,
   new RegExp(String.raw`^${GIT}(commit|merge|cherry-pick|rebase|revert|am)\b`),
@@ -151,6 +160,11 @@ if ((delegatedMerge && /\s--person\b/.test(cmd)) || (approves && /\s--via\b/.tes
   block(
     `Blocked: merging or approving as the person is the person's own act, from the code-kit pane or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
   );
+// Pausing and resuming the lead loop is the person's, from the band or their terminal.
+if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+loop\s+(pause|resume)\b`)))
+  block(
+    `Blocked: pausing or resuming the lead loop is the person's own act, from the code-kit band or their terminal. Ask them, and stop.\nCommand: ${cmd}`,
+  );
 // The harness settings are the person's to change, from the pane or their terminal.
 if (runs(cmd, new RegExp(String.raw`^${CODE_KIT}\s+settings\s+set\b`)))
   block(
@@ -233,9 +247,17 @@ try {
 } catch {
   // not a git repository yet
 }
-if (writesHistory && config.branches.protected.includes(branch)) {
+// SETUP-1: the one exception is setting up. Until the protected branch has the rules committed, the
+// lead commits the setup the person approved straight onto it, so no first merge needs anyone; from
+// that commit on, the branch is protected by the rules it now holds.
+const settingUp =
+  actor.kind === 'lead' &&
+  runs(cmd, new RegExp(String.raw`^${GIT}commit\b`)) &&
+  !runs(cmd, new RegExp(String.raw`^${GIT}(merge|cherry-pick|rebase|revert|am)\b`)) &&
+  !committedOnHead(root, CONFIG_FILE);
+if (writesHistory && config.branches.protected.includes(branch) && !settingUp) {
   block(
-    `Blocked: never commit or merge on ${branch}. Work on a branch; a person merges after review.`,
+    `Blocked: never commit or merge on ${branch}. Work on a branch; the lead merges it after review (or the person, where merges aren't delegated).`,
   );
 }
 

package/hooks/lib/adapters/context-graph.mjs

@@ -1,12 +1,12 @@
-// Context Graph (ctx) keeps a project's engineering context in `.ctx/`: ratified rules and concepts in
-// graph.ctx, settings in config.toml, the decisions agents record as they work in decisions.ctx, and
-// each file's card (its why) in cards.ctx. Every agent records decisions and cards for the files it
-// edits, so those two files are writable by any actor; the rules and settings
-// are the lead's, and changes to them go through the approval log. Ratifying a rule is a person's act,
-// signed with a commit trailer, so no Claude actor may write that trailer, unless the project lets the
-// lead act on what the person says in chat (`approvals.lead`). A delegated ratification, signed
-// `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's own act under the repository's [delegate]
-// rules: only the lead may write that trailer, and Context Graph's gate checks the kinds it covers.
+// Context Graph (ctx) keeps a project's engineering context in `.ctx/`: rules and concepts in graph.ctx
+// (proposals in proposals.ctx), settings in config.toml, the decisions agents record as they work in
+// decisions.ctx, and each file's card (its why) in cards.ctx. It runs in the background, so every agent
+// writes its cards, its decisions and the guidance it finds; the settings are the lead's, and a change
+// to them goes through the approval log. A rule that blocks edits, or a concept, needs a person's
+// signature, a commit trailer, and Context Graph's own gate checks it, so no Claude actor may write that
+// trailer, unless the project lets the lead act on what the person says in chat (`approvals.lead`). A
+// delegated ratification, signed `Ctx-Ratified-By: <ratifier> (delegated)`, is the lead's own act under
+// the repository's [delegate] rules: only the lead may write that trailer.
 // Ratifying with `--commit`, dropping a proposal and changing the harness settings are the person's acts
 // in ctx too, so no actor runs
 // them; only a command the line runs counts, so a heredoc or quoted text that mentions one isn't refused.
@@ -41,16 +41,12 @@ export default {
   detect: (root) => existsSync(join(root, '.ctx')),
   config: {
     lead: ['.ctx/**'],
-    anyActor: ['.ctx/decisions.ctx', '.ctx/cards.ctx'],
+    // Context Graph runs in the background: every agent writes its cards and decisions, and the guidance
+    // rules it finds (which inform and never block). A rule that blocks edits, or a concept, still needs
+    // a person's signed commit, and Context Graph's own gate checks that on every pull request.
+    anyActor: ['.ctx/decisions.ctx', '.ctx/cards.ctx', '.ctx/graph.ctx', '.ctx/proposals.ctx'],
     protected: [
-      {
-        glob: '.ctx/graph.ctx',
-        approval: 'ctx',
-        why: "Context Graph's rules and concepts",
-        // A person's ratification (`ctx ratify --commit`, `ctx drop --commit`) is signed, not logged.
-        signedBy: PERSON_SIGNED,
-      },
-      // Setting Context Graph up is ratified the same way: the person commits it from their terminal.
+      // Its settings are the person's: a change is logged, or signed when they commit it themselves.
       {
         glob: '.ctx/config.toml',
         approval: 'ctx',
@@ -100,7 +96,7 @@ export default {
       }
       return byType;
     },
-    /** Per file: the rules that apply to it, agreed and proposed. */
+    /** Per file: the rules that apply to it, agreed and proposed, and its card: current, stale or missing, with its text. */
     files: (root, paths) =>
       Object.fromEntries(
         paths.map((path) => {
@@ -108,6 +104,9 @@ export default {
           return [
             path,
             {
+              card: f?.card
+                ? { state: f.card.fresh === false ? 'stale' : 'current', text: f.card.text ?? '' }
+                : { state: 'missing', text: '' },
               rules: (f?.rules ?? []).map((r) => ({
                 id: r.id,
                 text: r.text,

package/hooks/lib/journal.mjs

@@ -0,0 +1,224 @@
+// The journal (docs/specs/15-decisions-and-journal.md, JOURNAL-1): the build's lineage in plain
+// sentences, oldest first: what the person asked for, the decisions that shaped it, the specification,
+// the rules being switched on, each story handed out, sent back and merged, each approval and who gave
+// it, and each milestone finished. Read from git and the project's own records, so it's the same for
+// every session and survives a restart.
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { APPROVAL_LOG } from './rules.mjs';
+import { sendBacks } from './reviews.mjs';
+import { storyTimes } from './timeline.mjs';
+
+const gitIn =
+  (root) =>
+  (...args) => {
+    try {
+      return execFileSync('git', ['-C', root, ...args], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+        maxBuffer: 32 * 1024 * 1024,
+      }).trim();
+    } catch {
+      return '';
+    }
+  };
+
+/** When a file was first committed, in ms, or null. */
+const addedAt = (git, file) => {
+  const t = git('log', '--diff-filter=A', '--format=%ct', '--', file)
+    .split('\n')
+    .filter(Boolean)
+    .at(-1);
+  return t ? Number(t) * 1000 : null;
+};
+
+/** The brief's title and its problem, in a sentence or two: what the person asked for. */
+export function briefRequest(text) {
+  const title = text.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? null;
+  const section = (name) => {
+    const m = text.match(
+      new RegExp(`^##\\s+${name}\\s*\\n([\\s\\S]*?)(?=^##\\s|$(?![\\s\\S]))`, 'm'),
+    );
+    return m ? m[1].trim() : '';
+  };
+  const firstParagraph = (s) =>
+    s
+      .split(/\n\s*\n/)[0]
+      .replace(/\s+/g, ' ')
+      .trim();
+  const problem = firstParagraph(section('Problem')) || firstParagraph(section('Outcome'));
+  return { title, problem: problem || null };
+}
+
+/** The brief's decision log: [{ date, decision, why }], from its `## Decision log` table. */
+export function briefDecisions(text) {
+  const m = text.match(/^##\s+Decision log\s*\n([\s\S]*?)(?=^##\s|$(?![\s\S]))/m);
+  if (!m) return [];
+  return m[1]
+    .split('\n')
+    .filter((l) => /^\|/.test(l) && !/^\|\s*-/.test(l) && !/^\|\s*Date\s*\|/i.test(l))
+    .map((l) => l.split('|').map((c) => c.trim()))
+    .map((c) => ({ date: c[1], decision: c[2], why: c[3] ?? '' }))
+    .filter((d) => /^\d{4}-\d{2}-\d{2}$/.test(d.date) && d.decision);
+}
+
+/** Who gave an approval, from the reason its log entry carries: the person, or the lead within limits. */
+export function approverOf(entry) {
+  const reason = String(entry.reason ?? '');
+  if (/approved by the lead within the delegated rules/.test(reason)) return 'lead';
+  if (entry.approval === 'lead') return 'lead';
+  return 'person';
+}
+
+/** The words an approval's name stands for: "dep-pdfjs-dist" → "adding the package pdfjs-dist". */
+export function approvalWords(name) {
+  if (name.startsWith('dep-')) return `adding the package ${name.slice(4)}`;
+  if (name === 'dependency') return 'adding a new package';
+  if (name === 'kit') return "a change to code-kit's own rules or agents";
+  if (name === 'merge') return 'a merge';
+  return `a change to the protected ${name.replace(/-/g, ' ')}`;
+}
+
+/** The person's own words, without the note the hooks add about how it was given. */
+const ownWords = (reason) =>
+  String(reason ?? '')
+    .replace(
+      /\s*\((given in chat, recorded by the lead|approved in the [\w ]+ pane|approved by the lead within the delegated rules[^)]*)\)\s*$/,
+      '',
+    )
+    .trim();
+
+/**
+ * JOURNAL-1: the events, oldest first: [{ at, kind, text, story? }]. Kinds: request, decision, spec,
+ * setup, dispatch, sentBack, merge, approval, milestone. `status` is buildStatus's; `base` the branch
+ * stories merge into; `docs` the config's docs (brief beside the specs).
+ */
+export function journal(root, status, base, docs = {}) {
+  const git = gitIn(root);
+  const events = [];
+  const at = (iso) => (iso ? Date.parse(`${iso}T12:00:00Z`) : null);
+  // What the person asked for, and the decisions the brief records.
+  const briefPath = ['docs/brief.md', docs.specs ? join(docs.specs, '..', 'brief.md') : null]
+    .filter(Boolean)
+    .find((p) => existsSync(join(root, p)));
+  if (briefPath) {
+    const text = readFileSync(join(root, briefPath), 'utf8');
+    const { title, problem } = briefRequest(text);
+    const when = addedAt(git, briefPath);
+    if (title || problem)
+      events.push({
+        at: when,
+        kind: 'request',
+        text: `You asked for ${title ? `“${title}”` : 'a build'}${problem ? `: ${problem}` : ''}`,
+      });
+    // The decisions were made while the brief was written: they follow the request, in the log's order.
+    briefDecisions(text).forEach((d, n) =>
+      events.push({
+        at: (when ?? at(d.date)) + n + 1,
+        kind: 'decision',
+        text: `Decided: ${d.decision}${d.why ? `, because ${d.why.replace(/\.$/, '').replace(/^./, (c) => c.toLowerCase())}` : ''}.`,
+      }),
+    );
+  }
+  // The specification and the plan.
+  const reqs = status.requirements.filter((r) => !r.removed).length;
+  const milestones = [...new Set(status.stories.map((s) => s.milestone).filter(Boolean))];
+  if (docs.plan && status.stories.length)
+    events.push({
+      at: addedAt(git, docs.plan),
+      kind: 'spec',
+      text: `The specification was written: ${reqs} requirement${reqs === 1 ? '' : 's'}, split into ${status.stories.length} stor${status.stories.length === 1 ? 'y' : 'ies'}${milestones.length ? ` across ${milestones.length} milestone${milestones.length === 1 ? '' : 's'}` : ''}.`,
+    });
+  const switchedOn = addedAt(git, '.claude/code-kit.json');
+  if (switchedOn)
+    events.push({
+      at: switchedOn,
+      kind: 'setup',
+      text: "code-kit's rules were switched on, as you approved them.",
+    });
+  // Each story: handed out, sent back, merged.
+  const times = storyTimes(root, status.stories, base);
+  const byId = new Map(status.stories.map((s) => [s.id, s]));
+  const backs = sendBacks(root);
+  for (const t of times) {
+    const s = byId.get(t.id);
+    const name = `${t.id} ${s?.title ?? ''}`.trim();
+    const reqText = s?.requirements?.length ? ` (${s.requirements.join(', ')})` : '';
+    if (t.started)
+      events.push({
+        at: t.started,
+        kind: 'dispatch',
+        story: t.id,
+        text:
+          t.lane === 'lead'
+            ? `The lead started ${name}${reqText} itself.`
+            : `${name}${reqText} was handed to the ${t.lane} lane.`,
+      });
+    for (const b of backs.filter((x) => x.branch === t.branch))
+      events.push({
+        at: Date.parse(b.at),
+        kind: 'sentBack',
+        story: t.id,
+        text:
+          t.lane === 'lead'
+            ? `${t.id} needed more work from the lead${b.reason ? `: ${b.reason}` : '.'}`
+            : `The lead sent ${t.id} back to the ${t.lane} lane${b.reason ? `: ${b.reason}` : '.'}`,
+      });
+    if (t.merged)
+      events.push({
+        at: t.merged,
+        kind: 'merge',
+        story: t.id,
+        text: `${name} was merged into ${base}.`,
+      });
+  }
+  // Approvals on the base, once each (one approval can log several files), and who gave them.
+  const seen = new Set();
+  for (const line of git('show', `${base}:${APPROVAL_LOG}`).split('\n').filter(Boolean)) {
+    let e;
+    try {
+      e = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (!e.approval || e.approval === 'lead') continue;
+    const key = `${e.approval}|${e.grantedAt ?? e.at}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const who = approverOf(e);
+    const words = ownWords(e.reason);
+    events.push({
+      at: Date.parse(e.grantedAt ?? e.at),
+      kind: 'approval',
+      who,
+      text:
+        who === 'lead'
+          ? `The lead approved ${approvalWords(e.approval)}, within the limits you set${words ? `: ${words}` : '.'}`
+          : `You approved ${approvalWords(e.approval)}${words ? `: “${words}”` : '.'}`,
+    });
+  }
+  // Milestones finished: when the last of their stories merged.
+  for (const m of milestones) {
+    const mine = status.stories.filter((s) => s.milestone === m);
+    if (!mine.every((s) => s.state === 'done')) continue;
+    const last = Math.max(...mine.map((s) => times.find((t) => t.id === s.id)?.merged ?? 0));
+    if (last)
+      events.push({
+        at: last + 1,
+        kind: 'milestone',
+        text: `${m} was finished: all ${mine.length} of its stories merged.`,
+      });
+  }
+  // The request, its decisions, the spec and the switch-on come first, whatever the commits' times: work
+  // can start on a branch before the brief that asked for it is committed.
+  const ORDER = ['request', 'decision', 'spec', 'setup'];
+  const opening = events.filter((e) => ORDER.includes(e.kind));
+  const rest = events.filter((e) => !ORDER.includes(e.kind) && e.at);
+  const firstWork = rest.length ? Math.min(...rest.map((e) => e.at)) : Infinity;
+  const opened = opening
+    .filter((e) => e.at)
+    .sort((a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind) || a.at - b.at)
+    .map((e, n, all) => ({ ...e, at: Math.min(e.at, firstWork - (all.length - n)) }));
+  return [...opened, ...rest.sort((a, b) => a.at - b.at)];
+}

package/hooks/lib/loop-state.mjs

@@ -0,0 +1,26 @@
+// Whether the person has paused the lead loop (spec 05, LOOP-6), kept beside the merge queue so other
+// tools sharing the project can hold their own background work while it's paused. The mod records it
+// through the CLI; a session that starts begins unpaused.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { projectWorktrees } from './rules.mjs';
+
+export const LOOP_FILE = '.claude/state/loop.json';
+
+const loopFile = (root) => join(projectWorktrees(root)[0] ?? root, LOOP_FILE);
+
+/** { paused, at }: not paused when nothing was recorded. */
+export function readLoop(root) {
+  try {
+    const state = JSON.parse(readFileSync(loopFile(root), 'utf8'));
+    return { paused: state?.paused === true, at: state?.at ?? null };
+  } catch {
+    return { paused: false, at: null };
+  }
+}
+
+export function writeLoop(root, paused, now = Date.now()) {
+  const file = loopFile(root);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify({ paused, at: new Date(now).toISOString() })}\n`);
+}