@yeison.restrepo.r/code-conductor 1.33.0 → 1.34.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
@@ -4,7 +4,103 @@
4
4
  [![License](https://img.shields.io/github/license/yeisonrestrepo/code-conductor.svg)](https://github.com/yeisonrestrepo/code-conductor/blob/main/LICENSE)
5
5
  [![GitHub issues](https://img.shields.io/github/issues/yeisonrestrepo/code-conductor.svg)](https://github.com/yeisonrestrepo/code-conductor/issues)
6
6
 
7
- A spec-first, token-efficient Claude Code configuration that turns AI-assisted coding into a disciplined, repeatable engineering workflow.
7
+ **A governance layer for Claude Code sessions.** Hooks, guards, memory and release discipline that make an agent's work verifiable: what it 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 is a spec-first workflow, but the part worth your sixty seconds is that every claim below is checkable against a commit in this repository.
8
+
9
+ ---
10
+
11
+ ## Quickstart
12
+
13
+ Three commands, from nothing to a guarded session. The output below is **real**, captured by running exactly these commands in a scratch directory.
14
+
15
+ ```bash
16
+ mkdir demo && cd demo && git init -q && npm init -y >/dev/null
17
+ npx @yeison.restrepo.r/code-conductor --project
18
+ ```
19
+
20
+ 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").
21
+
22
+ You now have `.claude/` with `commands/`, `hooks/`, `memory/`, `scripts/` and `settings.json`. The third command is any command at all, because the guard is already live:
23
+
24
+ ```bash
25
+ # scene 1: a mass content dump is denied, with a message that says what to do instead
26
+ cat *.ts
27
+ ```
28
+
29
+ ```
30
+ BASH SCAN BLOCKED. The command triggered a mass content-dump pattern. Pattern ids: P4.
31
+ Authorized alternatives: 1. Grep for targeted content search with file and pattern scope.
32
+ 2. Glob for path listing without file content. 3. Read with an explicit offset and limit.
33
+ A permanent exception is operator policy, not a self-serve step: entries live in
34
+ .claude/memory/bash-scan-allowlist.txt, are reviewed in git, and an agent may propose one
35
+ but must not add it to clear its own denial.
36
+ ```
37
+
38
+ ```bash
39
+ # scene 2: the decomposed form runs
40
+ grep -n 'export' src/index.ts
41
+ ```
42
+
43
+ Nothing is printed by the hook. The command runs.
44
+
45
+ ---
46
+
47
+ ## Guard 3, and what it learned
48
+
49
+ Guard 3 scans every Bash command for **mass content dumps**: `cat *.ts`, `find` without a depth bound, a pager over a glob, a shell loop reading files. It denies before the command runs and names an alternative. It is not a sandbox and not a security boundary (see [What this is not](#what-this-is-not)).
50
+
51
+ The interesting part is what it got wrong, because that is what the record documents.
52
+
53
+ **It read quoted content as code.** A grep pattern, a commit message, an English sentence with a period: all scanned as though they were shell. Fixed in `1.31.x` by masking quoted spans before the checks, with two checks kept unmasked on purpose because a grep pattern and an alias value are the data those checks exist to read.
54
+
55
+ **It read heredoc bodies as code.** Writing a file whose content contained `[`, `?`, a `$(...)`, or an odd number of apostrophes was denied by patterns written to catch *reads*. Four specimens accumulated across four consecutive working sessions before it was fixed in `1.33.0` by giving both scanners a sixth state. The argument is one sentence: **a heredoc body is content being written and is already inside the command string the scanner is holding, so it cannot flood anything.**
56
+
57
+ ### The honest numbers
58
+
59
+ Every figure here is cited, and none of them is rounded in the project's favour.
60
+
61
+ | measurement | value | source |
62
+ |---|---|---|
63
+ | Guard 3 denials recovered from one real working session | **47 events, 43 unique commands** | `.claude/memory/project.md:991` |
64
+ | ...of which flipped `deny` to `allow` after the `1.31.x` fixes | **36 of 43** | same table |
65
+ | unplanned regressions from those fixes | **0** | same table |
66
+ | this session's own denials, replayed verbatim against today's hook | **3: one now allowed, two still denied** | reproducible, below |
67
+ | ...of the two still denied, the guard being **right** | **1** (a genuine shell loop) | corpus control row |
68
+ | ...the guard being **wrong** | **1** (a surviving `P7` parity inversion) | recorded in `[BUG-041]`'s entry |
69
+
70
+ The population in row 1 grew from 41 to 43 *mid-measurement, because two of the scripts written to perform the measurement were themselves denied by the bug they were measuring.* That sentence is in the record, not in the marketing.
71
+
72
+ **One known false positive remains**, and it is named rather than buried: a mixed `grep` with pager pipelines still denies under `P7`. It is the residual the `[BUG-041]` entry describes, where the fragment starts inside an enclosing quoted region and every subsequent quote is parity-inverted.
73
+
74
+ ---
75
+
76
+ ## Instruments: releases that verify their own record
77
+
78
+ Three checks live in `tools/` as tracked repository infrastructure, and two of them run against the live repository in CI, so a divergence blocks the merge rather than waiting for someone to remember:
79
+
80
+ - **`version-gate.mjs`** takes `VERSION` as the authority and checks four other locations against it. 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.
81
+ - **`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.
82
+ - **`id-ceiling.mjs`** reports the highest filed id over the working tree **union** `origin/main`, counting only filed headings. Its predecessor counted id-shaped tokens anywhere, so it once read a plan file's prediction of its own output back as evidence.
83
+
84
+ **The example worth checking.** `[BUG-046]`'s own release ran those instruments against itself, then proved the green rather than trusting it: with the item's backlog heading deliberately flipped to `[ ]`, `record-parity` reported `FAIL [A] 1.32.2 claims BUG-046 but its heading reads [ ]` once per claim bullet and exited 1; flipped back, `RECORD_PARITY_OK`. The first release whose record cannot silently diverge is the release that made divergence detectable.
85
+
86
+ `tools/README.md` carries a **registry of five retired instruments**, each with the failure mode that retired it, so the sixth one gets written by someone who has met the list.
87
+
88
+ ---
89
+
90
+ ## What this is not
91
+
92
+ - **Not a sandbox and not a security boundary.** Guard 3 is advisory tooling against context exhaustion and sloppy habits. It does not contain a hostile process and was never built to.
93
+ - **Not a model.** It is configuration, hooks and scripts around Claude Code.
94
+ - **Not finished.** See the limits below.
95
+
96
+ ## Known limits
97
+
98
+ - **`[BUG-045]` is the one open filed defect**: the Guard 3 allowlist cannot cover a quoted path, because the boundary sets it interpolates contain no quote character, so an entry `docs/` does not cover `cat "docs/x.md" *.md`. Filed with its ritual priced, untouched pending its own change.
99
+ - **The `P7` false positive above**, still live.
100
+ - **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.
101
+ - **Two open dossiers**, which are the evidence-collection pipeline working rather than a backlog: a session denial tally, and one for interleaved-artifact reports. 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.
102
+
103
+ **The living artifact is `AGENT-READABLE BACKLOG.md`.** It is not a tidy issue list. It carries amendments above the text they amend, premises that measurement later corrected, and wrong guesses recorded beside the probe that overturned them.
8
104
 
9
105
  ---
10
106
 
@@ -66,7 +162,7 @@ By default, the installer installs only the global core files. Use flags to exte
66
162
 
67
163
  Re-run the same install command. User-configured files are never overwritten; agent-managed files are always updated.
68
164
 
69
- > **Note:** Do not clone this repository into a parent directory named `graphify-out` or `node_modules`. Guard 4 checks path components and will block agent `Read` calls on source files if the repository root is nested inside such a directory. Use relative paths if this layout is unavoidable.
165
+ > **Note:** Do not clone this repository into a parent directory named `node_modules`. Guard 4 checks path components and will block agent `Read` calls on source files if the repository root is nested inside such a directory.
70
166
 
71
167
  ---
72
168
 
@@ -99,7 +195,7 @@ All commands are tagged `(Conductor)` in the Claude Code command palette so they
99
195
  | Command | Description |
100
196
  |---------|-------------|
101
197
  | `/cc-resume` | Restore full session context in one command: reads project identity, memory, latest spec and plan, git state, and loads the stack profile. Scans the active plan for `[>]` (interrupted) and `[!]` (failed) task markers and surfaces them in the session report. Run at the start of every session after initialization. |
102
- | `/cc-init` | Initialize or re-sync the project environment: detect stack, checkpoint memory, refresh the project graph, and verify hook integrity. Run at the start of every session. |
198
+ | `/cc-init` | Initialize or re-sync the project environment: detect stack, checkpoint memory, and verify hook integrity. Run at the start of every session. |
103
199
  | `/cc-spec [name]` | Search the codebase first, ask only for missing context, generate a full feature spec, and wait for your approval before any plan is made. |
104
200
  | `/cc-plan` | Require an approved spec, map the codebase, and generate an ordered implementation plan with exact file paths, a test list, a commit order, and identified risks. Every generated task line carries a unique `[T-NNN]` ID (min 3 digits, unlimited suffix depth) using plain ASCII checkboxes — enforced at generation time. |
105
201
  | `/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, when Node `>= 22.5` is available, a git-hash-keyed row in the local `.conductor/cache.db` — then prompts you to run `/compact` to clear conversation history. Run at the end of every phase to prevent context overflow. |
@@ -156,9 +252,8 @@ Controls how much Claude writes per turn. The level is set at install time via `
156
252
  Before reading any file, Claude walks a priority lookup chain and stops at the first step that answers the question:
157
253
 
158
254
  1. **Project memory**: `.claude/memory/project.md`
159
- 2. **Graphify graph** — structural/relational queries (`what calls X`, `what depends on Y`)
160
- 3. **Grep / Glob** — pattern searches
161
- 4. **Targeted read** — last resort, always with `offset` + `limit`, max 150 lines
255
+ 2. **Grep / Glob** — pattern searches
256
+ 3. **Targeted read** — last resort, always with `offset` + `limit`, max 150 lines
162
257
 
163
258
  ### agent-delegation — always active
164
259
 
@@ -170,17 +265,11 @@ Keeps the main context clean. Sub-agents handle exploration and parallel work; t
170
265
 
171
266
  Hooks run automatically at specific points in a Claude Code session. They require no manual setup.
172
267
 
173
- ### graphify-ast-refresh *(global)*
174
-
175
- Fires on every `UserPromptSubmit`. A small Node wrapper (`graphify-ast-refresh.mjs`) checks whether `graphify-out/.graphify_ast_done` is fresh (default: 60 min, override with `GRAPHIFY_STALE_MINUTES`). If it is stale or missing, the wrapper looks for a `python3` or `python` on `PATH` (override with `GRAPHIFY_PYTHON`) and spawns the Python payload (`graphify-ast-refresh.py`) in the background to run file detection and AST extraction - no LLM calls, no tokens. The main session inherits a ready graph without paying the generation cost.
176
-
177
- Node hosts the check because Python is what is being probed: on a machine with no Python the wrapper exits 0 in silence rather than printing an interpreter error on every prompt. Set `CC_GRAPHIFY_DEBUG=1` to see the one line it would otherwise swallow. Works on Windows, Linux, and macOS, and returns immediately when the graph is current.
178
-
179
268
  ### pre-tool-use
180
269
 
181
270
  Fires before `Read`, `Write`, `Edit`, `create_file`, `write_file` and `Bash`. A single zero-dependency Node front door (`pre-tool-use.mjs`) 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 an exit code.
182
271
 
183
- **Large-file Read guard (Guard 1)** - a `Read` of a file over 150 lines that names no `limit` is denied, and the reason redirects Claude to the orchestrator lookup chain (memory, graph, grep, targeted read). Prevents reading entire codebases when a targeted search would do.
272
+ **Large-file Read guard (Guard 1)** - a `Read` of a file over 150 lines that names no `limit` is denied, and the reason redirects Claude to the orchestrator lookup chain (memory, grep, targeted read). Prevents reading entire codebases when a targeted search would do.
184
273
 
185
274
  **Duplicate file guard (Guard 2)** - a `Write`, `create_file` or `write_file` naming a path that already exists returns `ask`, showing the path, line count and last-modified timestamp with three options: edit in place, confirm the overwrite, or cancel. `Edit` is deliberately not gated, because editing in place is the action this guard recommends.
186
275
 
@@ -190,7 +279,7 @@ Permanent exceptions live in `.claude/memory/bash-scan-allowlist.txt`, one entry
190
279
 
191
280
  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.
192
281
 
193
- **graphify-out and node_modules guard (Guard 4)** - a `Read` whose path carries `graphify-out` or `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks and the graphify skill for graph questions.
282
+ **node_modules guard (Guard 4)** - a `Read` whose path carries `node_modules` as an exact path component is denied, with backslashes and `..` resolved first. Use Glob for existence checks.
194
283
 
195
284
  Input the hook cannot parse 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.
196
285
 
@@ -284,8 +373,7 @@ code-conductor/
284
373
  │ │ ├── cc-stack.md /cc-stack
285
374
  │ │ └── cc-lang.md /cc-lang
286
375
  │ ├── hooks/
287
- │ │ ├── graphify-ast-refresh.mjs Node wrapper: freshness + interpreter check
288
- │ │ └── graphify-ast-refresh.py Background AST refresh on UserPromptSubmit
376
+ │ │ └── verbosity-remind.sh Verbosity reminder on UserPromptSubmit
289
377
  │ └── memory/
290
378
  │ └── personal.md Template (never committed)
291
379
  ├── project-template/
@@ -306,7 +394,7 @@ code-conductor/
306
394
  │ │ ├── cc-test.md /cc-test
307
395
  │ │ └── cc-docs.md /cc-docs
308
396
  │ ├── hooks/
309
- │ │ ├── pre-tool-use.mjs Node front door: large-file, duplicate-write and graphify-out guards
397
+ │ │ ├── pre-tool-use.mjs Node front door: large-file, duplicate-write and node_modules guards
310
398
  │ │ ├── context-guard.sh Turn-counter warning (.sh + .ps1)
311
399
  │ │ └── post-compact.sh Checkpoint reminder + cache sweep after `/compact` (.sh + .ps1)
312
400
  │ └── memory/
@@ -323,7 +411,7 @@ code-conductor/
323
411
  ├── code-simplifier/SKILL.md Always active — complexity and simplicity rules
324
412
  ├── critical-review/SKILL.md Always active — 4-phase adversarial review protocol
325
413
  ├── verbosity/SKILL.md Always active — MIN/INFO/VERBOSE response rules
326
- ├── memory-first/SKILL.md Always active — memory → graph → grep → read chain
414
+ ├── memory-first/SKILL.md Always active — memory → grep → read chain
327
415
  └── agent-delegation/SKILL.md Always active — sub-agent spawn rules
328
416
  # Claude Code registers personal skills only at ~/.claude/skills/<name>/SKILL.md
329
417
  # ui-ux-pro-max installed from github.com/nextlevelbuilder/ui-ux-pro-max-skill
@@ -4,7 +4,8 @@ import { join } from 'node:path';
4
4
  import { pathToFileURL } from 'node:url';
5
5
  import { resolveAssetRoot, resolveHome, nodeMajorAtLeast } from '../lib/installer/env.mjs';
6
6
  import { assertAssets, assertMergeTargets, deployGlobal, deployProject, chmodHooks } from '../lib/installer/deploy.mjs';
7
- import { verbosityHookCommand, mergeVerbosityHook, graphifyHookCommand, mergeGraphifyHook } from '../lib/installer/settings.mjs';
7
+ import { verbosityHookCommand, mergeVerbosityHook } from '../lib/installer/settings.mjs';
8
+ import { healGraphifyHook } from '../lib/installer/heal.mjs';
8
9
  import { writeVerbosity, writeVersionFile } from '../lib/installer/config.mjs';
9
10
 
10
11
  const USAGE = `Usage: code-conductor [--project] [--verbosity MIN|INFO|VERBOSE] [--version] [--help]`;
@@ -95,7 +96,10 @@ export function run(argv, env = process.env, { cwd = process.cwd(), log } = {})
95
96
  const v = writeVerbosity(home, assetRoot, opts.verbosity, opts.verbosityGiven);
96
97
  if (v.warn) emit('stderr', v.warn);
97
98
  mergeVerbosityHook(join(claudeDir, 'settings.json'), verbosityHookCommand(home));
98
- mergeGraphifyHook(join(claudeDir, 'settings.json'), graphifyHookCommand(home));
99
+ // Never throws and never changes the exit code: see healGraphifyHook.
100
+ const heal = healGraphifyHook(home);
101
+ if (heal.status === 'removed') emit('stdout', 'code-conductor: removed the retired graphify-ast-refresh hook from settings.json (backup written beside it)');
102
+ for (const line of heal.lines) emit('stderr', `code-conductor: ${line}`);
99
103
  writeVersionFile(home, pkgVersion(assetRoot));
100
104
  if (opts.project) deployProject(assetRoot, cwd, { warn: (m) => emit('stderr', m) });
101
105
  return 0;
package/global/CLAUDE.md CHANGED
@@ -24,11 +24,10 @@ Never write code without an approved spec. Never start implementing without an a
24
24
  Before reading any file or spawning any search, classify the task and walk this chain. Stop at the first step that answers the question.
25
25
 
26
26
  1. **Memory**: check `.claude/memory/project.md`. If the answer is there, stop.
27
- 2. **Graph** — structural question? Run `graphify query "<question>"` if `graphify` is installed. Stop.
28
- 3. **Grep / Glob** — pattern search? Use `Grep` or `Glob` inline. Stop.
29
- 4. **Explore sub-agent** — need 3+ files to answer one question? Spawn an `Explore` sub-agent. It returns a ≤200-word summary. Main context receives only the summary. Stop.
30
- 5. **Parallel agents** — 2+ independent implementation tasks? Spawn parallel agents in worktrees. Each returns a ≤200-word summary.
31
- 6. **Targeted read** — last resort. Always use `offset` + `limit`. Max 150 lines per call.
27
+ 2. **Grep / Glob** — pattern search? Use `Grep` or `Glob` inline. Stop.
28
+ 3. **Explore sub-agent** — need 3+ files to answer one question? Spawn an `Explore` sub-agent. It returns a ≤200-word summary. Main context receives only the summary. Stop.
29
+ 4. **Parallel agents** — 2+ independent implementation tasks? Spawn parallel agents in worktrees. Each returns a ≤200-word summary.
30
+ 5. **Targeted read** — last resort. Always use `offset` + `limit`. Max 150 lines per call.
32
31
 
33
32
  Never jump to a later step if an earlier one can answer the question.
34
33
 
@@ -0,0 +1,98 @@
1
+ import { readFileSync, existsSync, unlinkSync } from 'node:fs';
2
+ import { createHash } from 'node:crypto';
3
+ import { join } from 'node:path';
4
+ import { backupMalformed } from './settings.mjs';
5
+ import { resolveRealTarget, backupFile, writeAtomic } from './file-merge.mjs';
6
+
7
+ // FEAT-021 retired the graph rung. Deleting the hook from the package deletes nothing
8
+ // from hosts, because deployGlobal copies and never removes, and it merges settings.json
9
+ // without touching `hooks` (plan M1). This module is the only thing that ever removes
10
+ // what earlier releases installed. It follows the BUG-020 purge (remove what we put
11
+ // there) and the 1.24.0 flat-skill sweep (remove only on an exact content match).
12
+ export const GRAPHIFY_FINGERPRINT = 'graphify-ast-refresh';
13
+
14
+ // Each file shipped exactly one version (.py @968dc6f, .mjs @5b4a1af), and no published
15
+ // tarball carries a CRLF copy (plan M2). The files are gone from the tree, so these
16
+ // constants are the only surviving record; tests/installer/heal.test.js pins them.
17
+ export const SHIPPED_GRAPHIFY_HASHES = new Map([
18
+ ['graphify-ast-refresh.py', '761199f1650b9a38273ce04b91fffdc8dcd5f73bd9adad957b7bbc1c3e9a800b'],
19
+ ['graphify-ast-refresh.mjs', 'c78e4e5e6989731f8a8ef60e7039c0b17b8e5feaa8ac30ee595441c215282e36'],
20
+ ]);
21
+
22
+ const isGraphifyHook = (h) => h && typeof h.command === 'string' && h.command.includes(GRAPHIFY_FINGERPRINT);
23
+
24
+ // Hooks sharing an entry with ours were never ours: remove only the matching hook and
25
+ // drop the entry only when that empties it. Returns null when nothing matched.
26
+ function pruneEntries(entries) {
27
+ let changed = false;
28
+ const out = [];
29
+ for (const entry of entries) {
30
+ if (!entry || !Array.isArray(entry.hooks) || !entry.hooks.some(isGraphifyHook)) { out.push(entry); continue; }
31
+ changed = true;
32
+ const kept = entry.hooks.filter((h) => !isGraphifyHook(h));
33
+ if (kept.length > 0) out.push({ ...entry, hooks: kept });
34
+ }
35
+ return changed ? out : null;
36
+ }
37
+
38
+ // UserPromptSubmit only: no release ever wrote the hook under another event.
39
+ export function unmergeGraphifyHook(settingsPath, now = new Date()) {
40
+ const target = resolveRealTarget(settingsPath);
41
+ if (!target.exists) return 'absent';
42
+ const raw = readFileSync(target.realPath, 'utf8');
43
+ if (raw.trim() === '') return 'absent';
44
+ let obj;
45
+ try { obj = JSON.parse(raw); } catch { obj = undefined; }
46
+ if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
47
+ backupMalformed(target.realPath, now);
48
+ return 'malformed-skipped';
49
+ }
50
+ const entries = obj.hooks?.UserPromptSubmit;
51
+ if (!Array.isArray(entries)) return 'absent';
52
+ const pruned = pruneEntries(entries);
53
+ if (!pruned) return 'absent';
54
+ backupFile(target.realPath, now);
55
+ obj.hooks.UserPromptSubmit = pruned;
56
+ writeAtomic(target.realPath, `${JSON.stringify(obj, null, 2)}\n`);
57
+ return 'removed';
58
+ }
59
+
60
+ function sha256(path) {
61
+ return createHash('sha256').update(readFileSync(path)).digest('hex');
62
+ }
63
+
64
+ // An unreadable file counts as modified: keeping it is the safe side of the match.
65
+ function sweepOne(path, shippedHash) {
66
+ if (!existsSync(path)) return null;
67
+ let hash = null;
68
+ try { hash = sha256(path); } catch { /* treated as modified below */ }
69
+ if (hash !== shippedHash) return `kept ${path} (modified since install); it is no longer used and can be deleted`;
70
+ try { unlinkSync(path); return null; }
71
+ catch (e) { return `could not remove ${path} (${e.code ?? e.message}); it is no longer used and can be deleted`; }
72
+ }
73
+
74
+ export function sweepGraphifyHooks(hooksDir, shipped = SHIPPED_GRAPHIFY_HASHES) {
75
+ const lines = [];
76
+ for (const [name, hash] of shipped) {
77
+ const line = sweepOne(join(hooksDir, name), hash);
78
+ if (line) lines.push(line);
79
+ }
80
+ return lines;
81
+ }
82
+
83
+ // Cleanup of our own leftovers, not deployment, so it is the one deliberate exception to
84
+ // run()'s mid-copy failure policy: every failure becomes a line and none escapes. The
85
+ // files go only after the entry is gone (or was never there), because deleting a file a
86
+ // live entry still names turns a silent hook into an error on every prompt.
87
+ export function healGraphifyHook(home, { shipped = SHIPPED_GRAPHIFY_HASHES, now = new Date() } = {}) {
88
+ const claudeDir = join(home, '.claude');
89
+ try {
90
+ const status = unmergeGraphifyHook(join(claudeDir, 'settings.json'), now);
91
+ if (status === 'malformed-skipped') {
92
+ return { status, lines: ['left the graphify-ast-refresh hook files in place: settings.json is malformed and may still reference them'] };
93
+ }
94
+ return { status, lines: sweepGraphifyHooks(join(claudeDir, 'hooks'), shipped) };
95
+ } catch (e) {
96
+ return { status: 'error', lines: [`graphify cleanup skipped: ${e.message}`] };
97
+ }
98
+ }
@@ -2,7 +2,6 @@ import { readFileSync, writeFileSync, copyFileSync, existsSync, readdirSync, unl
2
2
  import { join, dirname, basename } from 'node:path';
3
3
 
4
4
  const FINGERPRINT = 'verbosity-remind.sh';
5
- const GRAPHIFY_FINGERPRINT = 'graphify-ast-refresh';
6
5
  const MAX_MALFORMED_BACKUPS = 5;
7
6
  const MALFORMED_SUFFIX = '.malformed-backup.';
8
7
 
@@ -24,16 +23,6 @@ export function verbosityHookCommand(home) {
24
23
  return `bash ${hookPath}`;
25
24
  }
26
25
 
27
- export function graphifyHookCommand(home) {
28
- // Same absolute-path rule as verbosityHookCommand, for a second reason: a hook
29
- // `command` with no `args` runs under PowerShell on a Windows host without Git
30
- // Bash, and PowerShell does not expand a bare `~/...` passed to an external
31
- // program. The installer is the only party that knows the host's home, so the
32
- // shipped settings.json carries no graphify entry at all.
33
- const hookPath = join(home, '.claude', 'hooks', 'graphify-ast-refresh.mjs').replace(/\\/g, '/');
34
- return `node ${hookPath}`;
35
- }
36
-
37
26
  function entryHasCommand(entry, predicate) {
38
27
  return entry && Array.isArray(entry.hooks) && entry.hooks.some(h => h && predicate(h));
39
28
  }
@@ -61,7 +50,7 @@ export function pruneMalformedBackups(settingsPath, keep = MAX_MALFORMED_BACKUPS
61
50
  pruneBackups(settingsPath, MALFORMED_SUFFIX, keep);
62
51
  }
63
52
 
64
- // One merge serves both hooks: same malformed-file handling, same idempotency
53
+ // One merge serves the verbosity hook: same malformed-file handling, same idempotency
65
54
  // rule, same canonical two-space write. `fingerprint` is the substring naming
66
55
  // the entry this repo OWNS. Every entry matching it is replaced by hookCmd, so
67
56
  // manual edits to an owned entry are discarded by design; every entry that does
@@ -106,7 +95,3 @@ function mergeHook(settingsPath, hookCmd, fingerprint, now) {
106
95
  export function mergeVerbosityHook(settingsPath, hookCmd, now = new Date()) {
107
96
  return mergeHook(settingsPath, hookCmd, FINGERPRINT, now);
108
97
  }
109
-
110
- export function mergeGraphifyHook(settingsPath, hookCmd, now = new Date()) {
111
- return mergeHook(settingsPath, hookCmd, GRAPHIFY_FINGERPRINT, now);
112
- }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yeison.restrepo.r/code-conductor",
3
- "version": "1.33.0",
3
+ "version": "1.34.0",
4
4
  "description": "A spec-first, token-efficient Claude Code configuration and installer CLI.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -11,7 +11,7 @@ Skill({ skill: "subagent-driven-development", args: "$ARGUMENTS" })
11
11
  Skill({ skill: "critical-review" })
12
12
  ```
13
13
 
14
- `subagent-driven-development` delegates investigation to sub-agents (graph query + git log — no inline file reads). `critical-review` Phase 2 RESILIENCE check then runs on the proposed fix before it is applied — confirm the fix doesn't introduce a silent failure or new boundary condition. The fix must pass Phase 3 self-correction before being committed. End with `[VALIDATION]`.
14
+ `subagent-driven-development` delegates investigation to sub-agents (grep + git log — no inline file reads). `critical-review` Phase 2 RESILIENCE check then runs on the proposed fix before it is applied — confirm the fix doesn't introduce a silent failure or new boundary condition. The fix must pass Phase 3 self-correction before being committed. End with `[VALIDATION]`.
15
15
 
16
16
  ---
17
17
 
@@ -84,11 +84,7 @@ Run `/cc-stack`. Wait for stack profile confirmation before continuing.
84
84
 
85
85
  Run `/cc-checkpoint`. Persist current architectural state to `.claude/memory/project.md`.
86
86
 
87
- ## Step 5 — Graph sync *(skip if IS_NEW=true)*
88
-
89
- Run `/graphify .` to build or refresh the project knowledge graph from the current working directory.
90
-
91
- ## Step 6 — Hook integrity check
87
+ ## Step 5 — Hook integrity check
92
88
 
93
89
  Verify `.claude/hooks/pre-tool-use.mjs` exists. It is launched as `node <path>`, so it needs no execute bit:
94
90
 
@@ -104,13 +100,12 @@ echo "✓ Hook OK: $HOOK"
104
100
 
105
101
  If the hook file is absent, stop and report. Do not proceed silently.
106
102
 
107
- ## Step 7 — Confirm
103
+ ## Step 6 — Confirm
108
104
 
109
105
  Report:
110
106
  - Project identity: [name / stack / language — written to CLAUDE.md]
111
107
  - Stack profile loaded: [name / skipped — new project]
112
108
  - Memory checkpoint: [saved / skipped — new project]
113
- - Graph: [built / refreshed / skipped — new project]
114
109
  - Hook: [OK / MISSING]
115
110
 
116
111
  `/cc-init complete.`
@@ -8,7 +8,7 @@ import { readFileSync, statSync } from 'node:fs';
8
8
  import { posix, join } from 'node:path';
9
9
 
10
10
  const LINE_LIMIT = 150;
11
- const BLOCKED_COMPONENTS = new Set(['graphify-out', 'node_modules']);
11
+ const BLOCKED_COMPONENTS = new Set(['node_modules']);
12
12
 
13
13
  let emitted = false;
14
14
 
@@ -53,7 +53,7 @@ function stamp(ms) {
53
53
  return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}`;
54
54
  }
55
55
 
56
- // Guard 4: reads of graphify-out/ and node_modules/ (BUG-017). Runs before Guard 1 for
56
+ // Guard 4: reads of node_modules/ (BUG-017; FEAT-021 narrowed it to this one component). Runs before Guard 1 for
57
57
  // Read: a forbidden path is forbidden whatever its size, and deciding here spares a stat
58
58
  // and a full file read on a path that is about to be denied anyway.
59
59
  function guard4BlockedRead(input) {
@@ -63,8 +63,7 @@ function guard4BlockedRead(input) {
63
63
  const parts = normalized.split('/').filter(p => p && p !== '.');
64
64
  if (!parts.some(p => BLOCKED_COMPONENTS.has(p.toLowerCase()))) return null;
65
65
  return deny(
66
- 'Guard 4: direct reads of graphify-out/ and node_modules/ are forbidden. ' +
67
- 'Use Glob for existence checks or the graphify skill: /graphify query "<question>".'
66
+ 'Guard 4: direct reads of node_modules/ are forbidden. Use Glob for existence checks.'
68
67
  );
69
68
  }
70
69
 
@@ -81,8 +80,8 @@ function guard1LargeRead(input) {
81
80
  return deny(
82
81
  `Guard 1: LARGE FILE READ BLOCKED. File: ${path}. Lines: ${lines} ` +
83
82
  `(>${LINE_LIMIT}, no limit specified). Follow the orchestrator lookup chain: ` +
84
- '1. Check .claude/memory/project.md 2. Query graphify for structural questions ' +
85
- '3. Use Grep/Glob for pattern searches 4. Read with explicit offset + limit.'
83
+ '1. Check .claude/memory/project.md 2. Use Grep/Glob for pattern searches ' +
84
+ '3. Read with explicit offset + limit.'
86
85
  );
87
86
  }
88
87
 
@@ -34,14 +34,13 @@ Extends global CLAUDE.md. Project-specific rules take precedence over global one
34
34
  You are a Senior Full-Stack Architect and Orchestrator specialized in spec-driven, modular engineering. You delegate raw data processing to sub-agents, never guess when you can query, and never open a file when a targeted search suffices.
35
35
 
36
36
  ## Session Initialization
37
- - At session start: use **Glob** (NEVER use Read) to check that `project.md` and
38
- `graphify-out/graph.json` exist; run `/cc-init` if absent.
37
+ - At session start: use **Glob** (NEVER use Read) to check that `project.md`
38
+ exists; run `/cc-init` if absent.
39
39
  - Guard 3 scans every `Bash` command for mass content-dump patterns and denies a match;
40
40
  prefer Grep, Glob and a bounded Read. See README.md for the pattern list.
41
- - NEVER read raw files under `graphify-out/` or `node_modules/` — Guard 4 blocks such
42
- reads at the hook level. For graph queries, invoke the graphify skill:
43
- `/graphify query "<question>"`.
44
- - Do not accept implementation tasks without valid project memory and graph.
41
+ - NEVER read raw files under `node_modules/` — Guard 4 blocks such reads at the
42
+ hook level.
43
+ - Do not accept implementation tasks without valid project memory.
45
44
 
46
45
  ## Dynamic Specialization
47
46
  | Mode | Trigger | Persona focus |
@@ -51,16 +50,16 @@ You are a Senior Full-Stack Architect and Orchestrator specialized in spec-drive
51
50
  | FULLSTACK | Both layers detected | Frontend/backend contract, type safety |
52
51
 
53
52
  ## Operational Philosophy
54
- - Token efficiency: query the graph before reading; search before opening; never ingest what can be looked up.
53
+ - Token efficiency: search before opening; never ingest what can be looked up.
55
54
  - Modular autonomy: delegate raw output (grep, file content, intermediates) to sub-agents; keep main context clean.
56
55
  - State synchronization: run /cc-checkpoint after feature completion and before /compact.
57
56
 
58
57
  ## Execution Rules
59
58
 
60
- ### Graph-First
59
+ ### Search-First
61
60
  Before modifying any file:
62
- 1. Query graphify-out/graph.json for all callers, dependents, and related nodes of the target symbol.
63
- 2. If graph absent, run /cc-init. Fallback: spawn Explore sub-agent (≤150 words, callers + file paths).
61
+ 1. Grep for all callers, dependents, and related usages of the target symbol.
62
+ 2. If the answer spans 3+ files, spawn an Explore sub-agent (≤150 words, callers + file paths).
64
63
  3. Open a file only when you have a specific line range. Always pass limit on files > 150 lines.
65
64
 
66
65
  ### Dependency Integrity
@@ -75,7 +74,6 @@ After modifying any method, variable, class, or component:
75
74
  | Refactoring | code-simplifier skill |
76
75
  | Frontend UI/UX | ui-ux-pro-max skill |
77
76
  | Pre-flight / adversarial | critical-review skill |
78
- | Graph querying | Explore sub-agent |
79
77
  | Codebase exploration (3+) | Explore sub-agent |
80
78
  | Parallel independent tasks | Multiple Agent calls |
81
79
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: memory-first
3
- description: "Lookup chain enforced before any file read or search: project memory, code graph, grep/glob, Explore sub-agent, targeted read — stop at the first step that answers"
3
+ description: "Lookup chain enforced before any file read or search: project memory, grep/glob, targeted read — stop at the first step that answers"
4
4
  type: skill
5
5
  ---
6
6
 
@@ -21,28 +21,11 @@ Grep pattern="<keyword>" path=".claude/memory/project.md"
21
21
 
22
22
  If Grep returns matches, use that information and stop. If no matches, proceed to step 2.
23
23
 
24
- ### 2. Graphify Graph
25
- For structural or relational questions, query the code graph.
26
-
27
- **Use when asking:**
28
- - "What calls function X?"
29
- - "What does module Y depend on?"
30
- - "Where is interface Z implemented?"
31
- - "What is the path between component A and B?"
32
-
33
- ```bash
34
- graphify query "<your question>"
35
- ```
36
-
37
- Skip this step if `graphify` is not installed or the command returns no results. Proceed to step 3.
38
-
39
- **Do not use for:** literal string patterns, variable names, import statements.
40
-
41
- ### 3. Grep / Glob
24
+ ### 2. Grep / Glob
42
25
  For pattern searches, use the `Grep` or `Glob` tools inline. Never read a full file to find a pattern.
43
26
 
44
- ### 4. Targeted Read
45
- Last resort. Only when steps 1–3 cannot answer.
27
+ ### 3. Targeted Read
28
+ Last resort. Only when steps 1–2 cannot answer.
46
29
  - Always specify `offset` and `limit`.
47
30
  - Max 150 lines per call.
48
31
  - Know approximately which lines to read before calling.
@@ -1,91 +0,0 @@
1
- #!/usr/bin/env node
2
- // UserPromptSubmit hook: Node wrapper over the Python AST-refresh payload.
3
- //
4
- // Node hosts the decision because Python is the thing being probed: a Python
5
- // script cannot report that Python is missing. Every path exits 0 and prints
6
- // nothing unless CC_GRAPHIFY_DEBUG is set (the CC_VERBOSITY_DEBUG and
7
- // CC_GUARD4_DEBUG precedent), so a machine without the toolchain is silent.
8
-
9
- import { statSync, accessSync, constants } from 'node:fs';
10
- import { spawn } from 'node:child_process';
11
- import { join, dirname, delimiter } from 'node:path';
12
- import { fileURLToPath } from 'node:url';
13
-
14
- const HOOK_DIR = dirname(fileURLToPath(import.meta.url));
15
- const PAYLOAD = join(HOOK_DIR, 'graphify-ast-refresh.py');
16
-
17
- function debug(msg) {
18
- if (process.env.CC_GRAPHIFY_DEBUG) process.stderr.write(`GRAPHIFY_HOOK: ${msg}\n`);
19
- }
20
-
21
- // Mirrors the payload's int(os.environ.get("GRAPHIFY_STALE_MINUTES", "60")) and
22
- // its ValueError fallback. Python's int() accepts surrounding whitespace and a
23
- // sign and rejects everything else, while parseInt would read "120abc" as 120;
24
- // the regex keeps the two readers of this variable in agreement.
25
- function staleMinutes() {
26
- const raw = process.env.GRAPHIFY_STALE_MINUTES;
27
- if (typeof raw !== 'string' || !/^\s*[+-]?\d+\s*$/.test(raw)) return 60;
28
- return Number.parseInt(raw, 10);
29
- }
30
-
31
- function isFresh(cwd) {
32
- try {
33
- const { mtimeMs } = statSync(join(cwd, 'graphify-out', '.graphify_ast_done'));
34
- return (Date.now() - mtimeMs) / 60000 < staleMinutes();
35
- } catch {
36
- return false; // absent or unreadable sentinel counts as stale
37
- }
38
- }
39
-
40
- function isExecutableFile(candidate) {
41
- try {
42
- if (!statSync(candidate).isFile()) return false;
43
- accessSync(candidate, constants.X_OK);
44
- return true;
45
- } catch {
46
- return false;
47
- }
48
- }
49
-
50
- // A PATH scan, never an execution: starting an interpreter to learn whether an
51
- // interpreter exists is the cost this hook is meant to avoid, and it is the
52
- // reason no negative cache is needed.
53
- function resolveInterpreter() {
54
- const override = process.env.GRAPHIFY_PYTHON;
55
- if (override && isExecutableFile(override)) return override;
56
- const exts = process.platform === 'win32' ? ['.exe', '.bat', '.cmd'] : [''];
57
- const dirs = (process.env.PATH || '').split(delimiter).filter(Boolean);
58
- for (const name of ['python3', 'python']) {
59
- for (const dir of dirs) {
60
- for (const ext of exts) {
61
- const candidate = join(dir, `${name}${ext}`);
62
- if (isExecutableFile(candidate)) return candidate;
63
- }
64
- }
65
- }
66
- return null;
67
- }
68
-
69
- function main() {
70
- const cwd = process.cwd();
71
- if (isFresh(cwd)) return;
72
- const python = resolveInterpreter();
73
- if (!python) {
74
- debug('no python3 or python on PATH; graph refresh skipped');
75
- return;
76
- }
77
- // Detached with stdio ignored and unref'd: the child's exit status can never
78
- // surface as a hook error, which is what keeps the `import graphify` guard in
79
- // the payload where it already lives.
80
- const child = spawn(python, [PAYLOAD], { cwd, detached: true, stdio: 'ignore', windowsHide: true });
81
- child.on('error', (e) => debug(`spawn failed: ${e.message}`));
82
- child.unref();
83
- }
84
-
85
- // No explicit process.exit: the unref'd child holds nothing open, so the default
86
- // exit code 0 stands, and the deferred 'error' event above still gets to fire.
87
- try {
88
- main();
89
- } catch (e) {
90
- debug(`unexpected: ${e && e.message}`);
91
- }
@@ -1,81 +0,0 @@
1
- #!/usr/bin/env python3
2
- """UserPromptSubmit hook: runs detect + AST extraction in background when graph is stale."""
3
- import os
4
- import sys
5
- import subprocess
6
- import platform
7
- import time
8
- from pathlib import Path
9
-
10
- try:
11
- STALE_MINUTES = int(os.environ.get("GRAPHIFY_STALE_MINUTES", "60"))
12
- except ValueError:
13
- STALE_MINUTES = 60
14
-
15
- AST_SCRIPT = """
16
- import json, sys
17
- from pathlib import Path
18
- from graphify.detect import detect
19
- from graphify.extract import collect_files, extract
20
-
21
- out = Path("graphify-out")
22
-
23
- try:
24
- result = detect(Path("."))
25
- code = result.get("files", {}).get("code", [])
26
- if not code:
27
- sys.exit(0)
28
-
29
- out.mkdir(exist_ok=True)
30
- (out / ".graphify_detect.json").write_text(json.dumps(result))
31
-
32
- code_files = []
33
- for f in code:
34
- p = Path(f)
35
- code_files.extend(collect_files(p) if p.is_dir() else [p])
36
-
37
- if code_files:
38
- ast_result = extract(code_files)
39
- (out / ".graphify_ast.json").write_text(json.dumps(ast_result))
40
-
41
- (out / ".graphify_ast_done").write_text("")
42
- except Exception:
43
- pass
44
- """
45
-
46
-
47
- def is_fresh(cwd: Path) -> bool:
48
- sentinel = cwd / "graphify-out" / ".graphify_ast_done"
49
- if not sentinel.exists():
50
- return False
51
- age_minutes = (time.time() - sentinel.stat().st_mtime) / 60
52
- return age_minutes < STALE_MINUTES
53
-
54
-
55
- def main() -> None:
56
- cwd = Path.cwd()
57
-
58
- if is_fresh(cwd):
59
- sys.exit(0)
60
-
61
- try:
62
- import graphify # noqa: F401
63
- except ImportError:
64
- sys.exit(0)
65
-
66
- kwargs: dict = {
67
- "stdin": subprocess.DEVNULL,
68
- "stdout": subprocess.DEVNULL,
69
- "stderr": subprocess.DEVNULL,
70
- "env": os.environ.copy(),
71
- }
72
- if platform.system() == "Windows":
73
- kwargs["creationflags"] = subprocess.CREATE_NO_WINDOW
74
- else:
75
- kwargs["start_new_session"] = True
76
-
77
- subprocess.Popen([sys.executable, "-c", AST_SCRIPT], cwd=str(cwd), **kwargs)
78
-
79
-
80
- if __name__ == "__main__":
81
- main()