@yeison.restrepo.r/code-conductor 1.41.0 → 1.43.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,9 +7,9 @@
7
7
 
8
8
  **Make Claude Code work like a senior engineer, not an enthusiastic intern.**
9
9
 
10
- code-conductor is a drop-in governance layer for [Claude Code](https://www.anthropic.com/claude-code): slash commands, hooks, guardrails and a persistent memory system that turn free-form AI coding sessions into a disciplined, repeatable engineering workflow. What an agent may run is checked before it runs, what it decided is written where the next session will read it, and what shipped is asserted against the record by instruments that run in CI. It cuts token usage along the way.
10
+ code-conductor is a drop-in governance layer for [Claude Code](https://www.anthropic.com/claude-code): slash commands, hooks, guardrails, and a persistent memory system that turn free-form AI coding sessions into a disciplined, repeatable engineering workflow. What an agent may run is checked before it runs, what it decided is written where the next session will read it, and what shipped is asserted against the record by instruments that run in CI. It cuts token usage along the way.
11
11
 
12
- One command to install. No code changes to your project. Works with any stack. And every claim below is checkable against a commit in this repository.
12
+ One command to install: `npx @yeison.restrepo.r/code-conductor@latest --project`. No code changes to your project. Works with any stack. And every claim below is checkable against a commit in this repository.
13
13
 
14
14
  ---
15
15
 
@@ -32,7 +32,7 @@ None of these are model problems. They are *process* problems, and process is ex
32
32
  | Conventions re-explained every session | Project memory and the detected stack loaded at session start |
33
33
  | Context fills up until it breaks | A turn counter warns at 80%, and `/cc-compact` snapshots state before you compact |
34
34
  | Verbose markdown handoffs eat context | **SNAP**: minified single-line JSON handoffs, schema-validated by `scripts/snap-validate.mjs`, at least 15% smaller than the markdown snapshot they replaced |
35
- | Hand-tuned CLAUDE.md per project | **Stack auto-detection** fills in your build/test/lint/format commands from `package.json`, `go.mod`, `Cargo.toml` and friends |
35
+ | Hand-tuned CLAUDE.md per project | **Stack auto-detection** fills in your build/test/lint/format commands from `package.json`, `go.mod`, `Cargo.toml`, and friends |
36
36
 
37
37
  ---
38
38
 
@@ -40,7 +40,7 @@ None of these are model problems. They are *process* problems, and process is ex
40
40
 
41
41
  Three commands, from nothing to a guarded session. The output below is **real**, captured by running exactly these commands in a scratch directory.
42
42
 
43
- **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Always install `code-conductor@latest`, as below.
43
+ **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file (a `CLAUDE.md` whose installer-managed field lines, `- Stack:` and friends, it fills in) with damaged lines. Always install `code-conductor@latest`, as below.
44
44
 
45
45
  ```bash
46
46
  mkdir demo && cd demo && git init -q && npm init -y >/dev/null
@@ -49,7 +49,7 @@ npx @yeison.restrepo.r/code-conductor@latest --project
49
49
 
50
50
  The installer prints **nothing** and exits 0. That silence is deliberate and is asserted by a test: the stub-detection check runs *before* the seed, so a fresh scaffold cannot warn about the file it was just given (`tests/installer/deploy.test.js`, "says nothing on a fresh scaffold, whose stub it just wrote").
51
51
 
52
- You now have `.claude/` with `commands/`, `hooks/`, `memory/`, `scripts/` and `settings.json`, and the guardrails are already live. The third command is any command at all:
52
+ You now have `.claude/` with `commands/`, `hooks/`, `memory/`, `scripts/`, and `settings.json`, and the guardrails are already live. The third command is any command at all:
53
53
 
54
54
  ```bash
55
55
  # scene 1: a mass content dump is denied, with a message that says what to do instead
@@ -72,7 +72,7 @@ grep -n 'export' src/index.ts
72
72
 
73
73
  Nothing is printed by the hook. The command runs.
74
74
 
75
- Commit `.claude/` to your repository and your whole team gets the same workflow, the same guardrails and the same shared memory.
75
+ Commit `.claude/` to your repository and your whole team gets the same workflow, the same guardrails, and the same shared memory.
76
76
 
77
77
  ### Dependencies
78
78
 
@@ -81,10 +81,10 @@ code-conductor assumes these are already in place; the installer does not set th
81
81
  | Dependency | Required for | How to get it |
82
82
  |---|---|---|
83
83
  | Node.js `>= 20` | Running the `code-conductor` CLI itself | Any current Node LTS |
84
- | Claude Code | The environment every command, skill and hook here runs inside | See Anthropic's Claude Code docs |
84
+ | Claude Code | The environment every command, skill and hook here runs inside | See [Anthropic's Claude Code docs](https://code.claude.com/docs) |
85
85
  | **superpowers plugin** | `/cc-spec` (`brainstorming`), `/cc-plan` (`writing-plans`), and `/cc-debug`, `/cc-refactor`, `/cc-review`, `/cc-test` (all four via `subagent-driven-development`) | Install from Claude Code's `/plugin` marketplace, then run `/reload-plugins`, **before** using these commands; without it, their `Skill(...)` calls fail |
86
86
  | GitHub CLI (`gh`), authenticated | Only `/cc-orchestrate --ticket` and `ticket.mjs writeback`. code-conductor holds no credential; `gh` owns authentication | Install GitHub CLI, then run `gh auth login` |
87
- | ui-ux-pro-max skill | Nothing: retired guidance | No shipped code downloads, installs or activates it. Its replacement is filed as `[FEAT-037]` |
87
+ | ui-ux-pro-max skill | Nothing: retired guidance | No shipped code downloads, installs, or activates it. Its replacement is filed as `[FEAT-037]` |
88
88
 
89
89
  ---
90
90
 
@@ -104,11 +104,11 @@ A typical session looks like this:
104
104
  /cc-compact # snapshots phase state to a one-line JSON, then you /compact safely
105
105
  ```
106
106
 
107
- The key idea: **nothing gets built until a human approved what will be built.** The spec gate and the plan gate are cheap, a page of markdown to review, and they eliminate the single most expensive failure mode of AI coding: perfectly executed solutions to the wrong problem.
107
+ The key idea: **nothing gets built until a human approved what will be built.** The spec gate and the plan gate are cheap, each a page of markdown to review, and they eliminate the single most expensive failure mode of AI coding: perfectly executed solutions to the wrong problem.
108
108
 
109
109
  Two things make this cheaper than it sounds:
110
110
 
111
- - **Every phase opens with a resume read.** `/cc-spec`, `/cc-plan` and `/cc-implement` restore any context stored for the current git commit, so work survives branch switches, rollbacks and multi-day gaps (see [Local state cache and session persistence](#local-state-cache-and-session-persistence)).
111
+ - **Every phase opens with a resume read.** `/cc-spec`, `/cc-plan` and `/cc-implement` restore any context stored for the current git commit, so work survives branch switches, rollbacks, and multi-day gaps (see [Local state cache and session persistence](#local-state-cache-and-session-persistence)).
112
112
  - **Memory does the remembering.** Decisions land in `.claude/memory/project.md` (committed, shared with the team) and preferences in `~/.claude/memory/personal.md` (local). The next session reads them instead of asking you.
113
113
 
114
114
  ---
@@ -142,19 +142,19 @@ Useful variations:
142
142
  - `--auto` skips the pause between role dispatches. The spec and plan approvals always pause.
143
143
  - `--ticket 42` (or an issue URL) binds the run to a GitHub issue. `start` fetches it once through `gh`, halts on a pull request, a closed issue, or an empty or over-65536-byte body, and writes the body into a fenced, hashed snapshot at `.conductor/ticket/<ITEM>.md`, which **only the spec role reads, as untrusted requirement input**. After release, the owner runs `node .claude/scripts/ticket.mjs writeback <ITEM> --version <v> --pr <N|url> [--changelog <file>] [--close]`, which posts one outcome comment to the bound issue, never twice for the same version, and closes it only with `--close`.
144
144
 
145
- What it needs: agent definitions named `spec`, `plan`, `code`, `audit` and `qa` in `.claude/agents/` or `~/.claude/agents/` (they ship from `1.37.0`); a resolvable test command, as above; and plans in the writing-plans format (`### Task N` with a `**Files:**` block). A failed validation halts the run, terminally in this version: recover with `end`, then `start`.
145
+ What it needs: agent definitions named `spec`, `plan`, `code`, `audit`, and `qa` in `.claude/agents/` or `~/.claude/agents/` (they ship from `1.37.0`); a resolvable test command, as above; and plans in the writing-plans format (`### Task N` with a `**Files:**` block). A failed validation halts the run, terminally in this version: recover with `end`, then `start`.
146
146
 
147
147
  While a run is live, hooks enforce the boundaries: the orchestrator itself cannot write tracked files, role agents can only write inside their envelope, and only the orchestrator can dispatch agents. These are process guardrails for cooperative agents, not a security sandbox; see [What this is not](#what-this-is-not) and [Known limits](#known-limits).
148
148
 
149
149
  ### Review loop configurations
150
150
 
151
- Before each define approval, `/cc-orchestrate` runs a review loop (`[FEAT-041]`): a fresh read-only `define-review` agent checks the spec or plan against a declared checklist, and while rows stay open the orchestrator sends them back to the role that wrote the document, up to three reviewer passes and two revisions. It is advisory: it never gates, never halts the run, and never replaces your approval, which only a message you send gives. What a round costs depends on how you launched Claude Code, measured on `claude` 2.1.292:
151
+ Before each define approval, `/cc-orchestrate` runs a review loop (`[FEAT-041]`): a fresh read-only `define-review` agent checks the spec or plan against a declared checklist, and while rows stay open the orchestrator sends them back to the role that wrote the document, up to three reviewer passes and two revisions. It is advisory: it never gates, never halts the run, and never replaces your approval, which comes only from a message you send. What a round costs depends on how you launched Claude Code, measured on `claude` 2.1.292:
152
152
 
153
153
  | Configuration | Per round |
154
154
  |---|---|
155
155
  | Auto mode with the shipped exception: `claude --permission-mode auto --settings .claude/review-loop.settings.json` | 0 owner wakes, 0 prompts |
156
156
  | Default (ask) permission mode | 0 wakes; one approval per revision write, plus the orchestrator's `review` calls and report writes |
157
- | Plain auto mode | the auto mode classifier denies the first revision request; the loop closes `skipped:denied`, and you get round 1's findings, unrevised |
157
+ | Plain auto mode | The auto mode classifier denies the first revision request; the loop closes `skipped:denied`, and you get round 1's findings, unrevised |
158
158
 
159
159
  `.claude/review-loop.settings.json` holds one auto mode allow rule that names this protocol. The installer never writes `autoMode` into `~/.claude/settings.json`, and Claude Code ignores `autoMode` in project settings, so the rule applies only when you pass the file yourself. Read it before you pass it: a cloned repository could ship a different file under the same name.
160
160
 
@@ -168,7 +168,7 @@ Most AI debugging goes: paste the error, watch the agent grep around, accept wha
168
168
  /cc-debug "checkout total is wrong when a coupon is applied twice"
169
169
  ```
170
170
 
171
- 1. **Characterize first.** The agent states the symptom, expected behavior, reproduction steps, frequency and context, before touching anything.
171
+ 1. **Characterize first.** The agent states the symptom, expected behavior, reproduction steps, frequency, and context, before touching anything.
172
172
  2. **Hypothesize.** It lists 2 to 4 root-cause hypotheses **ordered by probability** and asks which to investigate first. You stay in control of where the tokens go.
173
173
  3. **Investigate surgically.** Sub-agents do the digging with grep and `git log`; whole files are never read inline, and raw file contents never flood the main context. For visual or UI bugs, it offers to inspect through Playwright MCP.
174
174
  4. **Report with evidence.** Root cause at `file:line`, why it happens, what else could be affected, and the exact proposed change.
@@ -184,9 +184,9 @@ Claude Code is priced in tokens, and unstructured sessions waste them in predict
184
184
 
185
185
  | Mechanism | What it does |
186
186
  |---|---|
187
- | **memory-first lookup chain** | Before reading any file, the agent checks project and personal memory, then grep/glob, and only then does a targeted read, always bounded, max 150 lines. |
187
+ | **memory-first lookup chain** | Before reading any file, the agent checks project and personal memory, then Grep/Glob, and only then does a targeted read, always bounded, max 150 lines. |
188
188
  | **Guard 1: large-file reads** | A `Read` of a file over 150 lines with no `limit` is **denied before it runs**, with a redirect to the lookup chain. |
189
- | **Guard 3: mass content dumps** | Every Bash command is scanned against twelve dump patterns (`cat *.ts`, unbounded `find`, recursive match-all greps, shell read-loops and more) and denied with a targeted alternative. In one measured real-world session it caught **47 denial events across 43 unique commands**. |
189
+ | **Guard 3: mass content dumps** | Every Bash command is scanned against twelve dump patterns (`cat *.ts`, unbounded `find`, recursive match-all greps, shell read-loops, and more) and denied with a targeted alternative. In one measured real-world session it caught **47 denial events across 43 unique commands**. |
190
190
  | **Guard 4: node_modules** | Reads into `node_modules` are denied outright. Your context window is not for vendored code. |
191
191
  | **Agent delegation** | Exploration runs in sub-agents that return a summary of at most 200 words. Intermediate data never enters the main context. |
192
192
  | **SNAP handoffs** | Phase state is serialized as minified single-line JSON, schema-validated, at least 15% smaller than the markdown format it replaced. |
@@ -207,9 +207,9 @@ The interesting part is what it got wrong, because that is what the record docum
207
207
 
208
208
  ### The honest numbers
209
209
 
210
- Every figure here is cited, and none of them is rounded in the project's favour.
210
+ Every figure here is cited, and none of them is rounded in the project's favor.
211
211
 
212
- | measurement | value | source |
212
+ | Measurement | Value | Source |
213
213
  |---|---|---|
214
214
  | Guard 3 denials recovered from one real working session | **47 events, 43 unique commands** | `.claude/memory/project.md:991` |
215
215
  | ...of which flipped `deny` to `allow` after the `1.31.x` fixes | **36 of 43** | same table |
@@ -228,8 +228,8 @@ The population in row 1 grew from 41 to 43 *mid-measurement, because two of the
228
228
 
229
229
  code-conductor operates at three layers:
230
230
 
231
- - **Global core** (`~/.claude/`) applies to every project on your machine: the spec-first workflow, token-efficiency rules, safety checks, simplicity rules and memory conventions. Installed once; always active.
232
- - **Project template** (`.claude/`) lives in your repository and is shared with your team through git: project slash commands, write-guarding hooks, role agent definitions and the shared memory file for decisions, conventions and technical debt.
231
+ - **Global core** (`~/.claude/`) applies to every project on your machine: the spec-first workflow, token-efficiency rules, safety checks, simplicity rules, and memory conventions. Installed once; always active.
232
+ - **Project template** (`.claude/`) lives in your repository and is shared with your team through git: project slash commands, write-guarding hooks, role agent definitions, and the shared memory file for decisions, conventions, and technical debt.
233
233
  - **Dynamic stack discovery and skills.** `/cc-stack` runs the bundled `detect-stack.mjs` scanner and writes your detected build/test/lint/format commands, plus a concise generated ruleset, straight into your project `CLAUDE.md`, so the agent never guesses them. Skills enforce cross-cutting behavior (code simplicity, adversarial self-review, verbosity, memory-first, delegation) in every session.
234
234
 
235
235
  ---
@@ -242,9 +242,9 @@ All commands are tagged `(Conductor)` in the Claude Code command palette, so the
242
242
 
243
243
  | Command | What it does |
244
244
  |---|---|
245
- | `/cc-checkpoint` | Read the current session, extract decisions, conventions and debt, and write them to `project.md` and `personal.md` with a timestamp. Run before `/compact`, after completing a feature, and after key architectural decisions. |
245
+ | `/cc-checkpoint` | Read the current session, extract decisions, conventions, and debt, and write them to `project.md` and `personal.md` with a timestamp. Run before `/compact`, after completing a feature, and after key architectural decisions. |
246
246
  | `/cc-stack` | Run the dynamic detector and write the detected commands and a generated ruleset into your project `CLAUDE.md` (the `- Stack:` line and the `## Active Stack Profiles` block). On later sessions it asks whether anything changed before re-detecting. |
247
- | `/cc-lang [code]` | Switch response language for this session (`en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`). Code identifiers, filenames and commit messages stay English. |
247
+ | `/cc-lang [code]` | Switch response language for this session (`en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`). Code identifiers, file names, and commit messages stay English. |
248
248
  | `/cc-compact` | Phase-boundary command. Serializes the current phase's essential state (decisions, pending steps, files touched, constraints) into a single-line SNAP JSON snapshot at `.claude/memory/session-snapshot.json` and, on Node `>= 22.5`, a git-hash-keyed row in the local `.conductor/cache.db`, then prompts you to run `/compact`. Run it at the end of every phase. |
249
249
 
250
250
  ### Project (requires `--project` install)
@@ -252,16 +252,18 @@ All commands are tagged `(Conductor)` in the Claude Code command palette, so the
252
252
  | Command | What it does |
253
253
  |---|---|
254
254
  | `/cc-init` | Initialize or re-sync the project environment: detect stack, checkpoint memory, verify hook integrity. Run at the start of every session. |
255
- | `/cc-resume` | Restore full session context in one command: project identity, memory, latest spec and plan, git state and the detected stack. Scans the active plan for `[>]` (interrupted) and `[!]` (failed) task markers and surfaces them. |
255
+ | `/cc-resume` | Restore full session context in one command: project identity, memory, latest spec and plan, git state, and the detected stack. Scans the active plan for `[>]` (interrupted) and `[!]` (failed) task markers and surfaces them. |
256
256
  | `/cc-spec [name]` | Search the codebase first, ask only for missing context, write a full feature spec, and **wait for your approval** before any plan is made. |
257
- | `/cc-plan` | From an approved spec, map the codebase and write an ordered plan with exact file paths, a test list, a commit order and risks. Every task line carries a unique `[T-NNN]` ID (at least 3 digits, unlimited suffix depth) with plain ASCII checkboxes. |
257
+ | `/cc-plan` | From an approved spec, map the codebase and write an ordered plan with exact file paths, a test list, a commit order, and risks. Every task line carries a unique `[T-NNN]` ID (at least 3 digits, unlimited suffix depth) with plain ASCII checkboxes. |
258
258
  | `/cc-implement` | Execute plan tasks with a surgical 5-step ritual: grep-locate pending tasks, single-line Read verify, pre-flip `[ ]` to `[>]`, execute, post-flip to `[X]` or `[!]`. Never reads or rewrites the full plan file. Includes dependency evaluation, drift detection, and a Step 6 hook that records each task's final state to the local SQLite cache. |
259
259
  | `/cc-orchestrate <ITEM> [--auto] [--ticket <N\|issue URL>]` | Route one backlog item through Define, Build and Verify with role agents, validated SNAP envelopes, a review loop and human approval gates. See the [walkthrough](#walkthrough-hands-off-delivery-with-cc-orchestrate). |
260
260
  | `/cc-review [file\|dir]` | Review in three layers (Critical / Important / Suggestion), deliver a verdict, and offer to auto-fix. |
261
261
  | `/cc-debug [problem]` | Hypothesis-driven debugging. See the [walkthrough](#walkthrough-diagnosis-before-surgery-with-cc-debug). |
262
262
  | `/cc-refactor [file\|module]` | Diagnose complexity, plan ordered changes, apply one step at a time, and verify tests pass after each step. |
263
263
  | `/cc-test [scope]` | Find coverage gaps, write AAA-pattern tests (plus Playwright E2E where applicable), run after confirmation, and report results. |
264
- | `/cc-docs [scope]` | Audit documentation, write inline docs in your stack's format (JSDoc / docstrings / JavaDoc / GoDoc), and preview before writing. |
264
+ | `/cc-docs [scope]` | Audit documentation, write inline docs in your stack's format (JSDoc / docstrings / Javadoc / GoDoc), and preview before writing. |
265
+ | `/cc-metrics [--dir <path>]` | Read-only report of token and time spend from Claude Code's local session logs, grouped by tool, command, phase, branch, pillar and session, with recommendations that quote the numbers they rest on. Registers no hook and writes no file. |
266
+ | `/cc-flow` | Print the guard lanes with per-guard pass, deny and ask counts, then the newest 20 hook decisions. See [Flow status](#flow-status). |
265
267
 
266
268
  ---
267
269
 
@@ -270,7 +272,7 @@ All commands are tagged `(Conductor)` in the Claude Code command palette, so the
270
272
  Skills extend agent behavior for cross-cutting concerns that apply regardless of stack.
271
273
 
272
274
  - **code-simplifier (always active).** Applied to every piece of code written or reviewed: no speculative abstractions; functions of at most 30 lines doing one thing; flat over nested, with guard clauses and early returns; descriptive names (no `Base`, `Abstract`, `Manager`, `Handler`); comments explain why, never what.
273
- - **critical-review (always active during implementation).** A 4-phase adversarial protocol: (1) **Pre-Flight**, identifying the happy path, failure points and boundary conditions before any code is written; (2) **Adversarial Review** for RESILIENCE (silent failures), EFFICIENCY (code smells) and FRICTION (happy-path friction); (3) **Self-Correction**, each weakness refactored and re-verified in isolation; (4) a required **`[VALIDATION]`** closing section: edge cases covered, justification, residual risks.
275
+ - **critical-review (always active during implementation).** A 4-phase adversarial protocol: (1) **Pre-Flight**, identifying the happy path, failure points, and boundary conditions before any code is written; (2) **Adversarial Review** for RESILIENCE (silent failures), EFFICIENCY (code smells) and FRICTION (happy-path friction); (3) **Self-Correction**, each weakness refactored and re-verified in isolation; (4) a required **`[VALIDATION]`** closing section: edge cases covered, justification, residual risks.
274
276
  - **verbosity (always active).** Controls how much Claude writes per turn. The level is set at install time with `--verbosity` and stored in `~/.claude/memory/verbosity.md`; the default is `MIN`.
275
277
 
276
278
  | Level | Behavior |
@@ -279,7 +281,7 @@ Skills extend agent behavior for cross-cutting concerns that apply regardless of
279
281
  | `INFO` | Bullet list of what changed and why, at most 5 bullets. `[CHANGES]` + `[REASON]`. |
280
282
  | `VERBOSE` | Full explanation, prose allowed. All response tags. |
281
283
 
282
- - **memory-first (always active).** Before reading any file, Claude walks a lookup chain and stops at the first step that answers: (1) memory, both `.claude/memory/project.md` and `~/.claude/memory/personal.md`; (2) Grep / Glob; (3) a targeted read, last resort, always with `offset` + `limit`, at most 150 lines.
284
+ - **memory-first (always active).** Before reading any file, Claude walks a lookup chain and stops at the first step that answers: (1) memory, both `.claude/memory/project.md` and `~/.claude/memory/personal.md`; (2) Grep/Glob; (3) a targeted read, last resort, always with `offset` + `limit`, at most 150 lines.
283
285
  - **agent-delegation (always active).** Keeps the main context clean. Sub-agents handle exploration and parallel work and return a summary of at most 200 words; raw file contents and intermediate data never enter the main context.
284
286
  - **ui-ux-pro-max (retired guidance, pending `[FEAT-037]`).** Earlier releases described this skill as installed from GitHub and switched on when `/cc-stack` detects a frontend stack. No shipped code does either. The `CLAUDE.md` templates still name it; `[FEAT-037]` replaces it with a frontend design skill stack, and this entry changes when that ships.
285
287
 
@@ -287,35 +289,45 @@ Skills extend agent behavior for cross-cutting concerns that apply regardless of
287
289
 
288
290
  ## Guardrails (hooks)
289
291
 
290
- Hooks run automatically at specific points in a Claude Code session and need no manual setup. The pre-tool-use front door is a single zero-dependency Node script (`pre-tool-use.mjs`): it fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`, reads the `PreToolUse` payload from stdin, dispatches on `tool_name`, and returns its verdict as `hookSpecificOutput.permissionDecision`. Every path exits 0: a denial is data, never a crash.
292
+ Hooks run automatically at specific points in a Claude Code session and need no manual setup. The pre-tool-use front door is a single zero-dependency Node script (`pre-tool-use.mjs`): it fires before `Read`, `Write`, `Edit`, `create_file`, `write_file`, and `Bash`, reads the `PreToolUse` payload from stdin, dispatches on `tool_name`, and returns its verdict as `hookSpecificOutput.permissionDecision`. Every path exits 0: a denial is data, never a crash.
291
293
 
292
294
  | Guard | Fires on | What it enforces |
293
295
  |---|---|---|
294
296
  | **1: Large-file read** | `Read` | A file over 150 lines needs an explicit `limit`; otherwise denied with a redirect to memory, grep, then a bounded read. |
295
- | **2: Duplicate write** | `Write`, `create_file`, `write_file` | Writing to an existing path asks first, showing the path, line count and last-modified time: edit in place, confirm the overwrite, or cancel. `Edit` is deliberately not gated, because editing in place is what this guard recommends. |
296
- | **3: Bash scan** | `Bash` | Twelve mass content-dump patterns denied before execution. Commands over 8192 characters and unclosed quotes are denied fail-closed. |
297
- | **4: node_modules** | `Read` | A path carrying `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks. |
297
+ | **2: Duplicate write** | `Write`, `create_file`, `write_file` | Writing to an existing path asks first, showing the path, line count, and last-modified time: edit in place, confirm the overwrite, or cancel. `Edit` is deliberately not gated, because editing in place is what this guard recommends. |
298
+ | **3: Bash scan** | `Bash` | Twelve mass content-dump patterns denied before execution. Commands over 8192 characters, and commands with unclosed quotes, are denied fail-closed. |
299
+ | **4: node_modules** | `Read` | A path carrying `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks. `.claude/.flow-events.jsonl` is denied too: see [Flow status](#flow-status). |
298
300
  | **5: Band scope** | role-agent writes | During orchestration, a band role can only write inside its installed envelope's scope. |
299
301
  | **6: Orchestrator writes** | live orchestrate runs | The orchestrator session can only write its own run-state surface; nested agent dispatch is denied. |
300
302
  | **7: Role shell** | role-agent `Bash` | `spec`, `plan` and `audit` get no shell; `code` and `qa` may run exactly one command, the recorded test command, byte for byte, no chaining. |
301
303
 
302
- **Guard 3 in detail.** The twelve patterns are: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` or a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, `eval`, `source` and the dot operator, alias remapping to a reader, and obfuscation sequences.
304
+ **Guard 3 in detail.** The twelve patterns are: deep `find` without `-maxdepth 1`, `find -exec` with readers or shells, `xargs` with readers, `cat` followed by an unquoted glob, a pager followed by an unquoted glob, command substitution as a reader's argument, `grep -r` with a match-all pattern, `ls -R`, shell loops, `mapfile` and `readarray`, dynamic execution (`eval`, `source`, and the dot operator, one pattern), and alias remapping to a reader. A separate thirteenth check catches obfuscation sequences.
303
305
 
304
306
  Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry per line, blank lines and `#` comments ignored and whitespace trimmed. An entry ending in `/` covers paths under that prefix, rejecting any suffix that walks up the tree with `..`; any other entry matches a whole command token. **Entries match literally: regex metacharacters carry no special meaning, so `file.ts` matches `file.ts` and nothing else.** The installer ships this file once as a commented template and creates it only when it is absent; it never overwrites an existing one. Every line in it disarms patterns for matching commands, so give each entry a comment saying why it exists; an uncommented entry is a review smell. An agent may *propose* an entry but must never add one to clear its own denial.
305
307
 
306
308
  Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and the guard asks instead of denying, carrying the same pattern ids. That is a triage aid for reporting a false positive while you keep working, not a configuration mode: the allowlist is the sanctioned permanent exception. The variable affects Guard 3 alone.
307
309
 
308
- **Guard 5 in detail.** A `Write`, `Edit`, `create_file` or `write_file` from a subagent whose `agent_type` names a band role (`spec`, `plan`, `code`, `audit`, `qa`) is checked against the nearest `.claude/memory/band-envelope.json` above its working directory, a SNAP v3 envelope. A malformed envelope, an agent that is not the envelope's role, a role not holding `RW`, or a path outside the envelope's `scope` globs (anchored at the band root, the directory whose `.claude/` holds the envelope) is denied with a named reason. The main session, any other agent, and any project without an envelope are untouched. It assumes cooperative agents: `agent_type` is a name taken on trust, and `Bash`, `NotebookEdit`, MCP write tools and symlinked paths are not covered.
310
+ **Guard 5 in detail.** A `Write`, `Edit`, `create_file` or `write_file` from a sub-agent whose `agent_type` names a band role (`spec`, `plan`, `code`, `audit`, `qa`) is checked against the nearest `.claude/memory/band-envelope.json` above its working directory, a SNAP v3 envelope. A malformed envelope, an agent that is not the envelope's role, a role not holding `RW`, or a path outside the envelope's `scope` globs (anchored at the band root, the directory whose `.claude/` holds the envelope) is denied with a named reason. The main session, any other agent, and any project without an envelope are untouched. It assumes cooperative agents: `agent_type` is a name taken on trust, and `Bash`, `NotebookEdit`, MCP write tools, and symlinked paths are not covered.
309
311
 
310
- **Guard 6 in detail.** While a `/cc-orchestrate` run is live, its run file `.claude/memory/orchestrator-run.json` binds it to one session by `session_id`. In that session, a `Write`, `Edit`, `create_file` or `write_file` from anything but a band role (the main session, a payload carrying only `agent_id`, any other agent) is denied with `ORCH_WRITE_DENIED` unless its target lies inside the orchestrator's write surface, anchored at the run root: `.claude/memory/orchestrator-run.json`, `.claude/memory/band-envelope.json`, `.claude/memory/session-snapshot.json` and `.conductor/**`. Band roles stay under Guard 5. A run file from another session is stale and an unreadable one is invalid: both warn (`ORCH_RUN_STALE`, `ORCH_RUN_INVALID`) with the cleanup command and never block. While the run is live, a subagent's `Agent` or `SendMessage` call is denied with `ORCH_NESTED_DISPATCH`, so only the orchestrator dispatches or messages agents (R7; the hook's matcher names both tools). Outside a live run there is no Guard 6. Its limits are listed under [Known limits](#known-limits).
312
+ **Guard 6 in detail.** While a `/cc-orchestrate` run is live, its run file `.claude/memory/orchestrator-run.json` binds it to one session by `session_id`. In that session, a `Write`, `Edit`, `create_file` or `write_file` from anything but a band role (the main session, a payload carrying only `agent_id`, any other agent) is denied with `ORCH_WRITE_DENIED` unless its target lies inside the orchestrator's write surface, anchored at the run root: `.claude/memory/orchestrator-run.json`, `.claude/memory/band-envelope.json`, `.claude/memory/session-snapshot.json` and `.conductor/**`. Band roles stay under Guard 5. A run file from another session is stale and an unreadable one is invalid: both warn (`ORCH_RUN_STALE`, `ORCH_RUN_INVALID`) with the cleanup command and never block. While the run is live, a sub-agent's `Agent` or `SendMessage` call is denied with `ORCH_NESTED_DISPATCH`, so only the orchestrator dispatches or messages agents (R7, `[FEAT-011]`'s nested-dispatch requirement; the hook's matcher names both tools). Outside a live run there is no Guard 6. Its limits are listed under [Known limits](#known-limits).
311
313
 
312
- **Guard 7 in detail.** A `Bash` call from a subagent whose `agent_type` names a band role is decided before Guard 3, so Guard 3's `CC_GUARD3_WARN` ask can never outrank it. `spec`, `plan` and `audit` have no shell (`ROLE_SHELL_DENIED`). `code` and `qa` may run exactly one command, byte for byte: the `test_command` that `orchestrate.mjs start` recorded in the run file of a run live in their session. A command carrying `;`, `&`, `|`, a backtick, `$(`, `<`, `>` or a line break is denied first (`ROLE_SHELL_CHAINING`). No run file, a run of another session, or no recorded command is denied (`ROLE_SHELL_UNRESOLVED`), and any other command is denied naming the allowed one (`ROLE_SHELL_NOT_ALLOWED`). An error inside the guard denies too, and `CC_HOOK_ALLOW` does not reach it. The main session and every other agent are untouched.
314
+ **Guard 7 in detail.** A `Bash` call from a sub-agent whose `agent_type` names a band role is decided before Guard 3, so Guard 3's `CC_GUARD3_WARN` ask can never outrank it. `spec`, `plan` and `audit` have no shell (`ROLE_SHELL_DENIED`). `code` and `qa` may run exactly one command, byte for byte: the `test_command` that `orchestrate.mjs start` recorded in the run file of a run live in their session. A command carrying `;`, `&`, `|`, a backtick, `$(`, `<`, `>`, or a line break is denied first (`ROLE_SHELL_CHAINING`). No run file, a run of another session, or no recorded command is denied (`ROLE_SHELL_UNRESOLVED`), and any other command is denied naming the allowed one (`ROLE_SHELL_NOT_ALLOWED`). An error inside the guard denies too, and `CC_HOOK_ALLOW` does not reach it. The main session and every other agent are untouched.
313
315
 
314
316
  **Unparseable input fails closed.** It is denied with one stderr line naming `CC_HOOK_ALLOW=1`, which overrides that denial alone and leaves every guard fully active on every payload the hook can read. Set `CC_HOOK_DEBUG=1` to see the diagnostic lines it otherwise swallows.
315
317
 
318
+ ### Flow status
319
+
320
+ After each decision is written, the pre-tool-use hook appends one JSON line to `.claude/.flow-events.jsonl`: the tool, the verdict, the deciding guard and its reason code, the guards that passed before it, and a short target (a path relative to the project, an agent type, or the first word of a Bash command after any `VAR=value` words, never the full command; quotes are honored when finding that word, and an unclosed quote or a `$( )`, backtick or `${ }` substitution among those words records an empty target instead of a guess). The file is capped at about 160 KiB and rotated to its last 250 lines, it is git-ignored by the managed `.gitignore` block, and Guard 4 keeps the agent from reading it into context. Writing it can never block or change a tool call: any error is swallowed.
321
+
322
+ - **Status line.** `--project` sets `"statusLine": {"type": "command", "command": "node .claude/flow-status.mjs"}` in `.claude/settings.json`. It shows one line below the prompt for the current session, for example `⛔ G3 P9 · 12 calls · 3 deny` after a denial or `✓ 12 calls · 3 deny` after an allow. Claude Code refreshes it when a new assistant message arrives, not on every tool call.
323
+ - **`/cc-flow`.** Prints one lane per tool family with each guard's pass, deny and ask counts, then the newest 20 events.
324
+ - **What Guard 4 covers.** It denies the `Read` tool on `.claude/.flow-events.jsonl` and on rotation's `.flow-events.jsonl.tmp`. A plain `cat .claude/.flow-events.jsonl` through Bash is not caught: Guard 3 looks for mass-dump shapes, not this file's name.
325
+ - **`CC_FLOW_OFF=1`** stops the hook from writing events; the status line goes blank and `/cc-flow` says the log is off.
326
+ - **An existing status line wins.** If your project or user `settings.json` already has a `statusLine`, the installer leaves both files untouched and prints a line saying the flow status line was skipped; `/cc-flow` still works, and you can set the entry above by hand. An entry whose command names `flow-status.mjs` is treated as the installer's own and kept current.
327
+
316
328
  ### The other hooks
317
329
 
318
- - **context-guard** (global + project). Fires on every `UserPromptSubmit` and atomically increments a turn counter in `.claude/memory/turn-count.txt`. At 80% of the threshold it emits a CONTEXT WARNING; at or above the threshold, CONTEXT CRITICAL. The threshold is read from `.claude/memory/context-threshold.txt` (default 25). Ships for Unix (`context-guard.sh`) and Windows (`context-guard.ps1`). `CC_GUARD_DEBUG=1` prints debug info to stderr; `CC_PROJECT_ROOT` overrides the project root used for the memory directory.
330
+ - **context-guard** (project). Fires on every `UserPromptSubmit` and atomically increments a turn counter in `.claude/memory/turn-count.txt`. At 80% of the threshold it emits a CONTEXT WARNING; at or above the threshold, CONTEXT CRITICAL. The threshold is read from `.claude/memory/context-threshold.txt` (default 25). Ships for Unix (`context-guard.sh`) and Windows (`context-guard.ps1`). `CC_GUARD_DEBUG=1` prints debug info to stderr; `CC_PROJECT_ROOT` overrides the project root used for the memory directory.
319
331
  - **post-compact.** Fires after `/compact`. Resets the turn counter to 0, reads `project.md`, shows the timestamp of the last `/cc-checkpoint`, and reminds you to checkpoint if this session's context has not been saved. Ships for Unix and Windows.
320
332
  - **verbosity-remind** (global + project). Fires on every `UserPromptSubmit` and re-injects the active MIN/INFO/VERBOSE constraint, so the level does not drift as the window fills (BUG-014). The global hook defers to a project-level hook if one exists (upward traversal from `$PWD`), and the level is read from the nearest `.claude/memory/verbosity.md` ancestor file. Set `CC_VERBOSITY_SKIP=1` to disable it in CI/CD.
321
333
 
@@ -335,13 +347,13 @@ Hit a block you believe is wrong? Re-run the command with `CC_GUARD3_WARN=1` and
335
347
  debt, workarounds
336
348
  ```
337
349
 
338
- `/cc-checkpoint` writes to both. Run it before `/compact`, after completing a feature, and after any key architectural decision. The payoff compounds: every decision captured once is a conversation, and a few thousand tokens, the team never has again.
350
+ `/cc-checkpoint` writes to both. Run it before `/compact`, after completing a feature, and after any key architectural decision. The payoff compounds: every decision captured once is a conversation (and a few thousand tokens) the team never has again.
339
351
 
340
352
  ### Local state cache and session persistence
341
353
 
342
354
  On top of the markdown memory, `/cc-implement`'s Step 6 hook records each task's final state to a local SQLite cache at `.conductor/cache.db`, written by the bundled `scripts/conductor-db.mjs` engine, a zero-dependency ES module wrapping Node's built-in `node:sqlite`.
343
355
 
344
- - **Schema (v2, ARCH-008):** `task_state(plan_file, task_id, state, updated_at)` keyed by `(plan_file, task_id)`, with `plan_file` normalized to a repo-relative POSIX path so the same plan de-duplicates across working directories; plus `sessions`, `snapshots` (one verbatim SNAP blob per git commit, newest wins) and `raw_history`. Upserts on every write.
356
+ - **Schema (v2, ARCH-008):** `task_state(plan_file, task_id, state, updated_at)` keyed by `(plan_file, task_id)`, with `plan_file` normalized to a repo-relative POSIX path so the same plan de-duplicates across working directories; plus `sessions`, `snapshots` (one verbatim SNAP blob per git commit, newest wins), and `raw_history`. Upserts on every write.
345
357
  - **Runtime-gated:** `node:sqlite` needs Node `>= 22.5`, so every caller probes the Node version and self-disables below it. `engines.node` stays `>=20`; the cache is an optimization, never a requirement.
346
358
  - **Non-authoritative and fail-safe:** the plan markdown and the `.claude/memory/session-snapshot.json` handoff remain the sources of truth. Every failure path (absent `node:sqlite`, a corrupt or non-regular file at the db path, `SQLITE_BUSY`, a newer schema, CLI misuse) degrades to a single `CONDUCTOR_DB:` stderr line and exit 0. A corrupt db is renamed aside, never deleted, and recreated.
347
359
  - **Gitignored:** `.conductor/` is local-only and never committed.
@@ -352,7 +364,7 @@ On top of the markdown memory, `/cc-implement`'s Step 6 hook records each task's
352
364
 
353
365
  ## Install
354
366
 
355
- **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file with damaged lines. Install `code-conductor@latest`, as below.
367
+ **Minimum safe version: `1.34.4`.** Older versions can strip or damage an existing `CLAUDE.md`: every release before `1.24` overwrote it with no backup, `1.24` through `1.34.3` silently removed your sections whose headings matched the managed block's, and an older pre-sentinel version left at least one field file (a `CLAUDE.md` whose installer-managed field lines, `- Stack:` and friends, it fills in) with damaged lines. Always install `code-conductor@latest`, as below.
356
368
 
357
369
  ```bash
358
370
  npx @yeison.restrepo.r/code-conductor@latest # one-shot global setup
@@ -366,13 +378,13 @@ npm install -g @yeison.restrepo.r/code-conductor && code-conductor
366
378
  npx @yeison.restrepo.r/code-conductor@latest --project # global setup + scaffold ./.claude
367
379
  ```
368
380
 
369
- By default, the installer installs only the global core files. Flags extend that:
381
+ By default, only the global core files are installed. Flags extend that:
370
382
 
371
383
  | Flag | Description |
372
384
  |---|---|
373
385
  | `--project` / `-Project` | Also install the project template into the current directory |
374
- | `--no-deps` / `-NoDeps` | Skip dependency installation (Node tooling, Playwright MCP, plugins); copy agent files only |
375
- | `--verbosity MIN\|INFO\|VERBOSE` / `-Verbosity` | Default response verbosity (default `MIN`). `MIN` = one sentence per response, `INFO` = bullet list, `VERBOSE` = full explanation. Re-run the installer to change it. |
386
+ | `--no-deps` / `-NoDeps` | Accepted for compatibility with the retired shell installers; a no-op, since the npm CLI installs no dependencies and copies agent files only |
387
+ | `--verbosity MIN\|INFO\|VERBOSE` / `-Verbosity LEVEL` | Default response verbosity (default `MIN`). `MIN` = one sentence per response, `INFO` = bullet list, `VERBOSE` = full explanation. Re-run the installer to change it. PowerShell's `-Verbosity:INFO` form is not supported; it warns and the level stays `MIN`. |
376
388
 
377
389
  **Updating:** re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
378
390
 
@@ -385,7 +397,7 @@ Two cautions:
385
397
 
386
398
  `CLAUDE.md` and `.gitignore` are **merged**, never overwritten. Everything else the installer ships (`settings.json`, hooks, commands, `scripts/`) is replaced on every run.
387
399
 
388
- - **code-conductor owns one block and nothing else.** Its content lives between `<!-- cc:managed:start -->` and `<!-- cc:managed:end -->`, and those two markers alone decide ownership; a heading's name never does. Every upgrade replaces the block's contents wholesale, so released improvements reach existing installs. Edits inside the block are lost, and recoverable from the backup.
400
+ - **code-conductor owns one block and nothing else.** Its content lives between `<!-- cc:managed:start -->` and `<!-- cc:managed:end -->`, and those two markers alone decide ownership; a heading's name never does. Every upgrade replaces the block's contents wholesale, so released improvements reach existing installs. Edits inside the block are lost, but recoverable from the backup.
389
401
  - **Everything outside the block is yours, byte for byte.** Nothing outside it is removed, rewritten, reordered or added.
390
402
  - **A file without the markers gets the block appended at the end**, after one blank line and in your file's line endings, and nothing else changes. If your file already has sections named like the block's (`## Agent Identity`, `## Hard Constraints` and so on), you will see both: yours above, code-conductor's inside the block. That is deliberate. The installer never decides which of your sections are really its own; reconciling them is planned for `/cc-stack` as `[FEAT-040]`.
391
403
  - **Before any change, the installer copies your file to `CLAUDE.md.installer-backup.<UTC timestamp>`**, keeps the five most recent, and prints where it put it:
@@ -402,7 +414,7 @@ If the markers in your file are damaged (a `start` with no `end`, two blocks, an
402
414
 
403
415
  ### The .gitignore block
404
416
 
405
- When installed with `--project`, the installer keeps its rules in one labelled block in your project's `.gitignore`:
417
+ When installed with `--project`, the installer keeps its rules in one labeled block in your project's `.gitignore`:
406
418
 
407
419
  ```
408
420
  # Code Conductor (added by the installer; safe to keep)
@@ -423,18 +435,20 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
423
435
  ## What this is not
424
436
 
425
437
  - **Not a sandbox and not a security boundary.** The guards are advisory tooling against context exhaustion and sloppy habits, built for cooperative agents. They do not contain a hostile process and were never built to.
426
- - **Not a model.** It is configuration, hooks and scripts around Claude Code.
438
+ - **Not a model.** It is configuration, hooks, and scripts around Claude Code.
427
439
  - **Not finished.** See the limits below.
428
440
 
441
+ ---
442
+
429
443
  ## Known limits
430
444
 
431
445
  - **The orchestrator (`1.36.0`) assumes cooperative agents.**
432
446
  - Guard 6 does not cover `Bash` writes, `claude -p` children included.
433
447
  - Inside a live run, a non-role agent the main session dispatched may write the orchestrator's write surface, the band envelope included.
434
- - R7 protects live runs only.
448
+ - The nested-dispatch rule (R7) protects live runs only.
435
449
  - An agent writing after its hand-back is bounded only by the envelope in force, so a same-role next task inherits it.
436
450
  - Under auto permission mode no human stands behind a Bash write or a hook `ask`.
437
- - A Guard 6 warning reaches you, never the model's tool result, and not in every case. Measured on `claude` 2.1.287:
451
+ - A Guard 6 warning reaches you, never the model's tool result, and not in every case. Measured on `claude` 2.1.292:
438
452
 
439
453
  | Channel | Permission mode | A prompting decision rides along | You see the warning |
440
454
  |---|---|---|---|
@@ -457,7 +471,7 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
457
471
  - **`[BUG-057]`, open:** `.claude/memory/project.md` is append-only and the phase commands instruct a full read of it, which collides with Guard 1's 150-line read limit once the file grows; on a long-lived project the read cost rises with project age. Until it is fixed, prune or archive old checkpoint sections by hand when the file gets large.
458
472
  - **`[BUG-058]`, open:** the test suite does not pass on a Windows checkout (CRLF checkout of `.mjs` files, `--import` given a bare path, symlink and `chmod` fixtures, `spawnSync('npm')` without a shell), and CI has no Windows leg to show it. Until it is fixed, develop against the suite on Linux/macOS or WSL; the shipped product itself is unaffected.
459
473
  - **`[BUG-059]`, open:** the test helper that fakes the `gh` CLI is POSIX-only, so on a Windows machine where the suites load, tests can reach a real, logged-in `gh` and perform live GitHub writes. Until it is fixed, do not run `npm test` on Windows while authenticated to `gh`, or log out (`gh auth logout`) first.
460
- - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned), still live.
474
+ - **The `P7` false positive** described under [Guard 3, and what it learned](#guard-3-and-what-it-learned) is still live.
461
475
  - **A re-run against an untouched `project.md` prints a recovery hint it cannot prove is needed.** If you install, never write anything into `.claude/memory/project.md`, and install again, you get a line suggesting the file may have been overwritten by a pre-`1.30.0` re-run. It was not; it equals the stub because it was seeded and never edited. The check compares content and **cannot distinguish "seeded and untouched" from "clobbered"**, which is why the wording is hedged to "may have been" rather than "was". This residual is named and accepted in [`BUG-039`'s spec at `:129`](docs/superpowers/specs/2026-09-27-bug039-installer-host-owned-state-design.md), where the alternative (restoring from the host's own git history) was rejected as writing host files out of the host's history with new failure modes. A **fresh** install is silent, which the Quickstart shows.
462
476
  - **Three open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, one for interleaved-artifact reports, and an intermittent commit-hook hang in the `snap-build` suite. A dossier holds specimens until a mechanism is characterized by probe; an id is minted only when the written condition is met. `[BUG-047]` is what that pipeline produces when it completes: an out-of-scope note, then a dossier, then four specimens across four sessions, then a mint, then a release.
463
477
 
@@ -467,7 +481,7 @@ The backup and temp rules keep the installer's own backups and crash-stranded te
467
481
 
468
482
  ## Instruments: releases that verify their own record
469
483
 
470
- Four checks live in `tools/` as tracked repository infrastructure. Three of them run on every pull request, so a divergence blocks the merge rather than waiting for someone to remember, and the fourth is a query run by hand:
484
+ Four checks live in `tools/` as tracked repository infrastructure. Three of them run in full on every pull request, so a divergence blocks the merge rather than waiting for someone to remember; the fourth, `id-ceiling.mjs`, runs its duplicate-free half on every pull request too, and its ceiling query by hand before each mint:
471
485
 
472
486
  - **`version-gate.mjs`** takes `VERSION` as the authority and checks four other locations against it, five in all. Agreement reports as agreement, which sounds trivial until you learn that its predecessor reported `FAIL` on five locations that agreed, because it compared against a literal frozen two releases earlier. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
473
487
  - **`record-parity.mjs`** asserts that every item the `CHANGELOG` claims has a closed backlog entry naming the version it shipped in. It exists because `[BUG-044]` shipped, was closed out in memory, and left its backlog entry reading `[ ]` for an entire release with no instrument comparing the two documents. It runs at the merge gate through `tests/tools/repo-invariants.test.js`, and by hand at closeout.
@@ -491,7 +505,7 @@ Four checks live in `tools/` as tracked repository infrastructure. Three of them
491
505
 
492
506
  **Supported codes:** `en` `es` `pt` `fr` `de` `it` `zh` `ja` `ko`
493
507
 
494
- Code identifiers, file names and commit messages are always English.
508
+ Code identifiers, file names, and commit messages are always English.
495
509
 
496
510
  ---
497
511
 
@@ -501,7 +515,7 @@ Code identifiers, file names and commit messages are always English.
501
515
  code-conductor/
502
516
  +-- README.md
503
517
  +-- VERSION
504
- +-- bin/code-conductor.mjs npm CLI entry (npx code-conductor)
518
+ +-- bin/code-conductor.mjs npm CLI entry (npx @yeison.restrepo.r/code-conductor)
505
519
  +-- lib/installer/ CLI modules (env, deploy, settings, merges, heal)
506
520
  +-- global/
507
521
  | +-- CLAUDE.md Global agent behavior (all projects)
@@ -562,7 +576,7 @@ Claude Code registers personal skills only at `~/.claude/skills/<name>/SKILL.md`
562
576
 
563
577
  Hook removal (`rm ~/.claude/hooks/verbosity-remind.sh`) and `settings.json` cleanup work identically in every environment; no git is required.
564
578
 
565
- Uninstall steps that use `git checkout <tag>` or `git revert <sha>` need a git working tree. In CI/CD pipelines, Docker containers, or directories that are not git repositories, they fail with `fatal: not a git repository`. That is expected and non-fatal: in those environments, manually delete or restore `skills/verbosity/SKILL.md` and remove the `verbosity-remind` entry from `~/.claude/settings.json`.
579
+ No uninstall step needs a git working tree. In CI/CD pipelines, Docker containers, or directories that are not git repositories, uninstall the same way as anywhere else: delete `~/.claude/skills/verbosity/SKILL.md` (and any other skill directories you want gone) and remove the `verbosity-remind` entry from `~/.claude/settings.json`.
566
580
 
567
581
  ---
568
582
 
@@ -570,6 +584,8 @@ Uninstall steps that use `git checkout <tag>` or `git revert <sha>` need a git w
570
584
 
571
585
  GitHub Issues are the inbox: an issue or PR is a candidate until the owner mints it an id. Nothing merges without a minted id and owner review, one item per PR. Versions, release branches, tags and GitHub Releases are owner-only. Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR; its hard constraints bind AI agents working on a contributor's behalf as well.
572
586
 
587
+ ---
588
+
573
589
  ## License
574
590
 
575
- See [LICENSE](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE).
591
+ See [LICENSE](LICENSE).
@@ -8,9 +8,14 @@ import { verbosityHookCommand, mergeVerbosityHook } from '../lib/installer/setti
8
8
  import { healGraphifyHook } from '../lib/installer/heal.mjs';
9
9
  import { writeVerbosity, writeVersionFile } from '../lib/installer/config.mjs';
10
10
 
11
- const USAGE = `Usage: code-conductor [--project] [--verbosity MIN|INFO|VERBOSE] [--version] [--help]`;
11
+ const USAGE = `Usage: code-conductor [--project|-Project] [--no-deps|-NoDeps] [--verbosity|-Verbosity MIN|INFO|VERBOSE] [--version] [--help]`;
12
12
 
13
- // Hand-rolled parser (four flags only). Deliberately NOT node:util's parseArgs —
13
+ // -Verbosity is the spelling the retired install.ps1 documented. Both spellings share
14
+ // every form (space-separated, inline `=`, missing value) and last-wins across them.
15
+ const VERBOSITY_FLAGS = ['--verbosity', '-Verbosity'];
16
+ const isVerbosityFlag = (a) => VERBOSITY_FLAGS.some((f) => a === f || a.startsWith(`${f}=`));
17
+
18
+ // Hand-rolled parser (five flags only). Deliberately NOT node:util's parseArgs —
14
19
  // the CLI honors the zero-runtime-dependency rule and node:util adds no value for
15
20
  // this tiny surface, so nothing is imported for argument handling.
16
21
  // Conflict policy: flags are LAST-WINS. `--verbosity MIN --verbosity VERBOSE`
@@ -18,24 +23,32 @@ const USAGE = `Usage: code-conductor [--project] [--verbosity MIN|INFO|VERBOSE]
18
23
  // is idempotent. No "conflicting flags" error is raised — last-wins is the least
19
24
  // surprising CLI convention and keeps the parser branchless.
20
25
  function parseArgs(argv) {
21
- const opts = { project: false, verbosity: undefined, verbosityGiven: false, version: false, help: false, unknown: [] };
26
+ const opts = { project: false, noDeps: false, verbosity: undefined, verbosityGiven: false, version: false, help: false, unknown: [] };
22
27
  for (let i = 0; i < argv.length; i++) {
23
28
  const a = argv[i];
24
- if (a === '--project') opts.project = true;
25
- else if (a === '--verbosity' || a.startsWith('--verbosity=')) {
29
+ // -Project is the spelling the retired install.ps1 documented; matched exact-case
30
+ // like every other flag here.
31
+ if (a === '--project' || a === '-Project') opts.project = true;
32
+ // Accepted no-op: the npm CLI installs no dependencies since FEAT-023 removed the
33
+ // shell installers, so there is nothing to skip. Recognized so callers carried over
34
+ // from install.sh get no misleading "unrecognized" warning.
35
+ else if (a === '--no-deps' || a === '-NoDeps') opts.noDeps = true;
36
+ else if (isVerbosityFlag(a)) {
26
37
  opts.verbosityGiven = true;
27
- if (a.startsWith('--verbosity=')) {
38
+ if (a.includes('=')) {
28
39
  // Inline form: --verbosity=INFO. Empty (`--verbosity=`) leaves value ''.
29
40
  // Surrounding whitespace (e.g. a quoted `--verbosity= VERBOSE `) is NOT
30
41
  // stripped here — normalizeVerbosity() trims before matching, so whitespace
31
42
  // is tolerated and a whitespace-only/`=`-only value normalizes to null → MIN+warn.
32
- opts.verbosity = a.slice('--verbosity='.length);
43
+ opts.verbosity = a.slice(a.indexOf('=') + 1);
33
44
  } else {
34
45
  // Space-separated form: consume the next token only if it is a real value,
35
46
  // not another flag or the end of argv (`--verbosity` passed last). A missing
36
47
  // value stays undefined and falls back to MIN + warning in writeVerbosity.
48
+ // Any `-` prefix marks a flag, so single-dash aliases are never eaten as the
49
+ // level; no valid level starts with `-`.
37
50
  const next = argv[i + 1];
38
- if (next !== undefined && !next.startsWith('--')) { opts.verbosity = next; i++; }
51
+ if (next !== undefined && !next.startsWith('-')) { opts.verbosity = next; i++; }
39
52
  }
40
53
  }
41
54
  else if (a === '--version' || a === '-v') opts.version = true;
@@ -104,7 +117,7 @@ export function run(argv, env = process.env, { cwd = process.cwd(), log, nodeVer
104
117
  if (heal.status === 'removed') emit('stdout', 'code-conductor: removed the retired graphify-ast-refresh hook from settings.json (backup written beside it)');
105
118
  for (const line of heal.lines) emit('stderr', `code-conductor: ${line}`);
106
119
  writeVersionFile(home, pkgVersion(assetRoot));
107
- if (opts.project) deployProject(assetRoot, cwd, { warn: (m) => emit('stderr', m), report: (m) => emit('stdout', m) });
120
+ if (opts.project) deployProject(assetRoot, cwd, { warn: (m) => emit('stderr', m), report: (m) => emit('stdout', m), home });
108
121
  return 0;
109
122
  } catch (err) {
110
123
  // Pre-flight failures (nothing written yet) → exit 1.
@@ -14,6 +14,24 @@ Identify and extract:
14
14
  - Add a timestamped section: `## Checkpoint [YYYY-MM-DD HH:MM]`
15
15
  - List decisions, conventions, and debt from this session
16
16
 
17
+ **Then update its `## Current State` section**, the bounded digest at the top of `project.md` that phase commands read with a `limit` instead of the whole file:
18
+ - If the section is absent, make the one-time bootstrap insert: add this skeleton directly after the file's `# Project Memory` intro paragraph, in one Edit. It inserts a new section and never rewrites an existing line, so it keeps the BUG-003 invariant.
19
+
20
+ ```markdown
21
+ ## Current State
22
+ <!-- Bounded digest, max 40 lines, each line max 200 characters. History below is append-only. -->
23
+ - Active spec: none
24
+ - Last checkpoint: none
25
+ ### Conventions
26
+ ### Debt
27
+ <!-- end current state -->
28
+ ```
29
+
30
+ - Replace the single `- Last checkpoint:` line with the heading text of the entry just appended, without its leading `## `.
31
+ - Add each new convention as a bullet under `### Conventions` and each new debt item or workaround as a bullet under `### Debt`, one Edit per bullet.
32
+ - Caps: the section stays within 40 lines, each list within 12 bullets, each line within 200 characters. Before adding to a full list, remove the one bullet that is superseded or resolved, in its own Edit. A removed or shortened bullet loses nothing: the history entry holds the full text.
33
+ - If the `<!-- end current state -->` line is missing, report the malformed section and leave it as it is. Never rewrite it in bulk.
34
+
17
35
  **Staging that update, where the workflow commits it:** stage by tracked-ness, with an explicit path. A `project.md` that is already tracked takes `git add -u ".claude/memory/project.md"`; one that is not yet tracked takes plain `git add ".claude/memory/project.md"`, or `git add -f` where the project ignores `.claude/`. **Never an unconditional `-u` here.** This command is global and also runs in freshly scaffolded projects, which do not ignore `.claude/` and whose `project.md` is not yet tracked: there `-u` exits 128 and would halt the checkpoint before its DB tail, trading a defect those projects never had for one they would.
18
36
 
19
37
  **Update `.claude/memory/personal.md`** (local only):
@@ -1,9 +1,11 @@
1
1
  import { cpSync, mkdirSync, chmodSync, existsSync, lstatSync, readdirSync, readFileSync, statSync, rmSync, unlinkSync } from 'node:fs';
2
2
  import { join, relative, isAbsolute, sep } from 'node:path';
3
+ import { createHash } from 'node:crypto';
3
4
  import { mergeFileInto, resolveRealTarget } from './file-merge.mjs';
4
5
  import { mergeClaudeMdText, mergeGitignoreText } from './merge-md.mjs';
5
6
  import { GLOBAL_HOST_OWNED, PROJECT_HOST_OWNED, GLOBAL_SETTINGS_FINGERPRINTS, PROJECT_SETTINGS_FINGERPRINTS, hostOwnedFilter, seedHostOwned } from './host-owned.mjs';
6
7
  import { mergeSettingsFile } from './settings-merge.mjs';
8
+ import { mergeFlowStatusLine, FLOW_STATUS_COMMAND } from './settings.mjs';
7
9
 
8
10
  // Host-authored data, not managed assets: these are merged, never force-copied —
9
11
  // everything else in the template keeps its overwrite. Keyed by the name the file
@@ -154,14 +156,24 @@ function sweepStaleRootScripts(assetRoot, cwd) {
154
156
  // host's own history, with new failure modes (detached HEAD, shallow clone,
155
157
  // submodule, dirty index, no git at all) for a path that fires in one narrow
156
158
  // case. Print the two commands and write nothing.
159
+ // (#94) Those releases wrote the stub as it stood at b018793, which carried
160
+ // code-conductor's own history. The neutral stub replaced it, so the old bytes are
161
+ // recognized by digest rather than re-shipped.
162
+ export const LEGACY_PROJECT_MEMORY_STUB_SHA256 = '01e65fdecfd0a842dc1269cb0a5ff59718978830c94d5815b09c3a0454f261f9';
163
+
157
164
  function warnIfProjectMemoryIsStub(templateClaude, target, emit) {
158
165
  const rel = '.claude/memory/project.md';
159
166
  const stub = join(templateClaude, 'memory', 'project.md');
160
167
  const host = join(target, 'memory', 'project.md');
161
- if (!existsSync(stub) || !existsSync(host)) return false;
162
- if (readFileSync(host, 'utf8') !== readFileSync(stub, 'utf8')) return false;
168
+ if (!existsSync(host)) return false;
169
+ const text = readFileSync(host, 'utf8');
170
+ const isCurrentStub = existsSync(stub) && text === readFileSync(stub, 'utf8');
171
+ // The digest is of the LF bytes; an autocrlf=true clone wrote the stub as CRLF.
172
+ const lf = text.replace(/\r\n/g, '\n');
173
+ const isLegacyStub = createHash('sha256').update(lf).digest('hex') === LEGACY_PROJECT_MEMORY_STUB_SHA256;
174
+ if (!isCurrentStub && !isLegacyStub) return false;
163
175
  emit([
164
- `code-conductor: ${rel} matches the bundled stub; it may have been overwritten by an installer re-run before 1.30.0.`,
176
+ `code-conductor: ${rel} matches a bundled stub; it may have been overwritten by an installer re-run before 1.30.0.`,
165
177
  ` Find a committed copy: git log --oneline -- ${rel}`,
166
178
  ` Restore it: git checkout <commit> -- ${rel}`,
167
179
  ].join('\n'));
@@ -195,7 +207,35 @@ function packageName(path) {
195
207
  try { return JSON.parse(text).name ?? null; } catch { return null; }
196
208
  }
197
209
 
198
- export function deployProject(assetRoot, cwd, { warn = toStderr, report = toStdout } = {}) {
210
+ // One line per outcome of the flow status line merge. 'unchanged' has none, so a re-run of
211
+ // an unchanged release stays as quiet as every other managed file.
212
+ // The replaced line names the entry it overwrote, so a host who hand-tuned it can restore it.
213
+ const FLOW_STATUS_REPORT = {
214
+ added: () => `code-conductor: added the flow status line to .claude/settings.json (${FLOW_STATUS_COMMAND})`,
215
+ replaced: (previous) =>
216
+ `code-conductor: updated the flow status line in .claude/settings.json to ${FLOW_STATUS_COMMAND} ` +
217
+ `(replaced ${JSON.stringify(previous)})`,
218
+ 'host-skipped': () =>
219
+ 'code-conductor: kept your existing statusLine, so the flow status line was skipped (/cc-flow still works). ' +
220
+ `To use it, set "statusLine": {"type": "command", "command": "${FLOW_STATUS_COMMAND}"} in .claude/settings.json`,
221
+ 'malformed-skipped': () =>
222
+ 'code-conductor: .claude/settings.json is not valid JSON; it was backed up and left as is, so the flow status line was not added',
223
+ 'unreadable-skipped': () => 'code-conductor: .claude/settings.json could not be read, so the flow status line was not added',
224
+ };
225
+
226
+ // Only when the template ships the script the entry points at: a statusLine naming a
227
+ // missing file would blank the host's line for nothing. Runs after mergeSettingsFile, so
228
+ // it sees the settings.json that merge leaves behind.
229
+ function mergeFlowStatus(templateClaude, target, home, report) {
230
+ if (!existsSync(join(templateClaude, 'flow-status.mjs'))) return;
231
+ const userPath = home ? join(home, '.claude', 'settings.json') : null;
232
+ const { status, previous } = mergeFlowStatusLine(join(target, 'settings.json'), userPath);
233
+ if (FLOW_STATUS_REPORT[status]) report(FLOW_STATUS_REPORT[status](previous));
234
+ }
235
+
236
+ // `home` is where the user-level settings.json lives, consulted only by the flow status
237
+ // line rule. A caller that passes none gets the project-level check alone.
238
+ export function deployProject(assetRoot, cwd, { warn = toStderr, report = toStdout, home = null } = {}) {
199
239
  const emit = warn;
200
240
  // Also run by the CLI's pre-flight; kept here for direct callers.
201
241
  assertNotSelfInstall(assetRoot, cwd);
@@ -233,6 +273,7 @@ export function deployProject(assetRoot, cwd, { warn = toStderr, report = toStdo
233
273
  mkdirSync(join(target, 'memory'), { recursive: true });
234
274
  seedHostOwned(templateClaude, target, PROJECT_HOST_OWNED);
235
275
  mergeSettingsFile(join(templateClaude, 'settings.json'), join(target, 'settings.json'), PROJECT_SETTINGS_FINGERPRINTS);
276
+ mergeFlowStatus(templateClaude, target, home, report);
236
277
  // scripts/ is a sibling of project-template/ under assetRoot (source layout),
237
278
  // but is deployed as a CHILD of .claude/ (target) - it must stay inside the
238
279
  // project's self-contained .claude footprint, not spill into the host's own