@yeison.restrepo.r/code-conductor 1.24.1 → 1.31.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 +17 -7
- package/bin/code-conductor.mjs +4 -4
- package/global/commands/cc-compact.md +17 -2
- package/global/hooks/graphify-ast-refresh.mjs +91 -0
- package/global/settings.json +0 -13
- package/lib/installer/config.mjs +0 -8
- package/lib/installer/deploy.mjs +45 -20
- package/lib/installer/host-owned.mjs +94 -0
- package/lib/installer/settings-merge.mjs +118 -0
- package/lib/installer/settings.mjs +27 -3
- package/package.json +1 -1
- package/project-template/.claude/commands/cc-implement.md +28 -0
- package/project-template/.claude/commands/cc-init.md +50 -18
- package/project-template/.claude/commands/cc-plan.md +142 -1
- package/project-template/.claude/hooks/pre-tool-use.mjs +509 -0
- package/project-template/.claude/settings.json +2 -2
- package/project-template/CLAUDE.md +3 -1
- package/scripts/claude-md-fields.mjs +42 -0
- package/scripts/conductor-db.mjs +93 -1
- package/scripts/detect-stack.mjs +5 -1
- package/scripts/init-wizard.mjs +195 -0
- package/scripts/resume-read.mjs +22 -12
- package/scripts/snap-build.mjs +4 -7
- package/scripts/snap-contract.mjs +39 -0
- package/scripts/snap-validate.mjs +8 -8
- package/project-template/.claude/hooks/pre-tool-use.sh +0 -81
package/package.json
CHANGED
|
@@ -162,3 +162,31 @@ After the hook: if the task state is `[!]`, halt with the failure report from St
|
|
|
162
162
|
---
|
|
163
163
|
|
|
164
164
|
Confirm between tasks unless the developer explicitly says to proceed without confirmation.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Phase exit - session row
|
|
169
|
+
|
|
170
|
+
Step 1 returned no `[ ]` match at `offset = 0`, so every task is complete and the
|
|
171
|
+
implementation phase has finished. Write that fact here, at its own boundary, after
|
|
172
|
+
the completion summary has been output.
|
|
173
|
+
|
|
174
|
+
<!-- SESSION-ROW-TAIL:BEGIN -->
|
|
175
|
+
**Preconditions.** `c` is the full-40 `git rev-parse HEAD`, lowercased, matching `/^[0-9a-f]{7,40}$/`, `"0000000"` on any failure; `s` is the active spec stem or `"none"`. Both are derived exactly as this command's body already specifies.
|
|
176
|
+
|
|
177
|
+
1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
|
|
178
|
+
2. Resolve the session id: `id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
|
|
179
|
+
3. Probe how to launch `node:sqlite`, the same probe the `cc-implement` Step 6 hook runs: no flag first, else `--experimental-sqlite --no-warnings`, else skip the write.
|
|
180
|
+
4. Upsert the session row. Every argv scalar is double-quoted, because a repository path can contain spaces:
|
|
181
|
+
|
|
182
|
+
`node <probe-flags> .claude/scripts/conductor-db.mjs session "$id" "impl" "$s" "$c" >> .conductor/last-write.log 2>&1`
|
|
183
|
+
5. **Loud degrade.** If the probe skipped the write, or the write exited non-zero, append one line naming the reason:
|
|
184
|
+
|
|
185
|
+
`printf '%s\n' "CC_DB_TAIL: session row not written (<reason>)" >> .conductor/last-write.log`
|
|
186
|
+
|
|
187
|
+
A row that is simply absent is the shape that let the recorded phase go stale across two boundaries unnoticed. The absence is always reported.
|
|
188
|
+
|
|
189
|
+
Every redirect uses append mode (`>>`), never `>`, so a rapid or parallel second run never truncates a preceding trace. Any failure in this block is **non-fatal**: the command reports its normal outcome regardless.
|
|
190
|
+
|
|
191
|
+
**Cross-platform note.** The forms above are Unix-canonical; the `.md` file is an agent instruction, not a literal script. On Windows/PowerShell realize the same semantics: set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` first, capture `$id = node .claude/scripts/session-id.mjs`, and append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log`, never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace. Ensure the directory with `New-Item -ItemType Directory -Force .conductor`.
|
|
192
|
+
<!-- SESSION-ROW-TAIL:END -->
|
|
@@ -10,38 +10,71 @@ If the count is 0 or only `CLAUDE.md` / config files exist, treat this as a **ne
|
|
|
10
10
|
|
|
11
11
|
## Step 2 — Auto-detect and collect project identity
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
If the stack detector is present in the project, run it:
|
|
14
14
|
|
|
15
15
|
```bash
|
|
16
|
-
node scripts/detect-stack.mjs "$PWD"
|
|
16
|
+
node .claude/scripts/detect-stack.mjs "$PWD"
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
**Environment flags:** `CC_GLOB_DEPTH` and any other `CC_*` env vars the user may have set are automatically inherited by the child `node` process — no explicit export or forwarding is required. The `/cc-init` command must NOT reset or unset these variables before calling detect-stack.
|
|
20
20
|
|
|
21
21
|
Capture the JSON output. For each field in the JSON (name, description, stack, build, test, lint, format, setup), check the corresponding line in CLAUDE.md:
|
|
22
|
-
- If the CLAUDE.md line contains `<command>`
|
|
22
|
+
- If the CLAUDE.md line contains `<command>` or is blank after `Key:` → replace with the detected value using a single `Edit` call.
|
|
23
23
|
- If the CLAUDE.md line already has a non-placeholder value → skip (never overwrite).
|
|
24
24
|
|
|
25
25
|
Apply all replacements in a **single `Edit` call** after collecting all detected values.
|
|
26
26
|
|
|
27
|
-
If
|
|
27
|
+
If the detector is absent or returns `{}`, skip auto-detection and continue below.
|
|
28
28
|
|
|
29
|
-
|
|
29
|
+
### Step 2b — Resolve what detection could not
|
|
30
30
|
|
|
31
|
-
|
|
31
|
+
Ask about the fields detection could not fill, and never about the ones it did. The script decides which is which; this prose only asks.
|
|
32
32
|
|
|
33
|
-
|
|
33
|
+
```bash
|
|
34
|
+
node .claude/scripts/init-wizard.mjs report
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
stdout is JSON and nothing else:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"unresolved": [{ "field": "build", "raw": "- Build: <command>", "reason": "placeholder" }],
|
|
42
|
+
"resolved": ["name", "description", "stack", "test"],
|
|
43
|
+
"absent": [{ "field": "setup", "expected": "- Setup:" }]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
`reason` is only ever `empty` or `placeholder`. stderr carries an advisory summary — never parse it. A non-zero exit means `CLAUDE.md` is missing or unreadable: stop and report it, do not continue.
|
|
48
|
+
|
|
49
|
+
**Non-interactive callers** (CI, scripted installs — anywhere no one can answer): print one line naming the `unresolved` field names, then continue to Step 3. Make no `apply` call. The placeholders survive, which is the truth — nobody was asked.
|
|
50
|
+
|
|
51
|
+
**Interactive:** if `unresolved` is empty, ask nothing. Otherwise ask about all of its fields in one batch, quoting each entry's `raw` line so the developer sees what is in the file. Ask one further question only if context suggests the default is wrong:
|
|
52
|
+
|
|
53
|
+
- Response language preference? (default: `en`)
|
|
34
54
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
55
|
+
`Language` is not one of the script's fields — write it with a plain `Edit`, like any other prose field.
|
|
56
|
+
|
|
57
|
+
For each answer to `build`, `test`, `lint` or `format` other than `N/A`, run `check` first and pass any warning through verbatim. It is advisory; the value is written either way:
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
node .claude/scripts/init-wizard.mjs check build --value-stdin <<'CC_VALUE'
|
|
61
|
+
npm run build
|
|
62
|
+
CC_VALUE
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Then write the answer, one call per field:
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
node .claude/scripts/init-wizard.mjs apply build --value-stdin <<'CC_VALUE'
|
|
69
|
+
npm run build
|
|
70
|
+
CC_VALUE
|
|
71
|
+
```
|
|
39
72
|
|
|
40
|
-
|
|
73
|
+
The value travels on **stdin** inside a heredoc whose delimiter is quoted (`<<'CC_VALUE'`), which disables every form of shell expansion — backticks, `$(...)` and quotes in an answer are inert. Never pass a value as an argv word; `apply` refuses it.
|
|
41
74
|
|
|
42
|
-
|
|
75
|
+
A skipped question applies the literal `N/A`. Never leave a `<command>` placeholder behind.
|
|
43
76
|
|
|
44
|
-
|
|
77
|
+
Finally, for every entry in `absent`, tell the developer that the line is gone from `CLAUDE.md` and quote its `expected` text as the line to restore by hand. `apply` refuses an absent field; it never inserts one.
|
|
45
78
|
|
|
46
79
|
## Step 3 — Stack detection *(skip if IS_NEW=true)*
|
|
47
80
|
|
|
@@ -57,16 +90,15 @@ Run `/graphify .` to build or refresh the project knowledge graph from the curre
|
|
|
57
90
|
|
|
58
91
|
## Step 6 — Hook integrity check
|
|
59
92
|
|
|
60
|
-
Verify `.claude/hooks/pre-tool-use.
|
|
93
|
+
Verify `.claude/hooks/pre-tool-use.mjs` exists. It is launched as `node <path>`, so it needs no execute bit:
|
|
61
94
|
|
|
62
95
|
```bash
|
|
63
|
-
HOOK=".claude/hooks/pre-tool-use.
|
|
96
|
+
HOOK=".claude/hooks/pre-tool-use.mjs"
|
|
64
97
|
if [ ! -f "$HOOK" ]; then
|
|
65
98
|
echo "⚠️ Hook missing: $HOOK"
|
|
66
|
-
echo "Run:
|
|
99
|
+
echo "Run: npx code-conductor --project (or copy from project-template/.claude/hooks/)"
|
|
67
100
|
exit 1
|
|
68
101
|
fi
|
|
69
|
-
[ -x "$HOOK" ] || chmod +x "$HOOK"
|
|
70
102
|
echo "✓ Hook OK: $HOOK"
|
|
71
103
|
```
|
|
72
104
|
|
|
@@ -87,6 +87,17 @@ Each step must include:
|
|
|
87
87
|
- Action (create / modify / delete)
|
|
88
88
|
- What changes and why
|
|
89
89
|
- Whether it has a dependency on a previous step
|
|
90
|
+
- **Step ordering within a task.** A step that stages a file - any form of `git add` (`-f`,
|
|
91
|
+
`-A`, `-u`, `--all`, `.`, or an explicit path) - must come after every step in the same
|
|
92
|
+
commit group that edits that file. A commit group is the contiguous run of steps ending at a
|
|
93
|
+
`git commit` step; a task with two commits has two groups. A step that stages implicitly,
|
|
94
|
+
such as `git commit -a`, counts as its own staging step, so every edit of a file it will
|
|
95
|
+
commit must precede it. A task that mixes edits with a commit orders its steps edit, then
|
|
96
|
+
stage, then commit. A staging step for a file the task never edits is unaffected by this
|
|
97
|
+
rule; never invent an edit step to satisfy it. `cc-implement` executes checkbox lines in file
|
|
98
|
+
order, so a staging step placed above its edit commits the file's previous content while
|
|
99
|
+
every checkbox still reports `[X]`, and the divergence surfaces only at whatever later task
|
|
100
|
+
asserts on that file's expected state, pointing at the wrong task.
|
|
90
101
|
|
|
91
102
|
## Test List
|
|
92
103
|
- [ ] Unit tests for [unit]
|
|
@@ -107,8 +118,138 @@ Execute one step at a time. Confirm between steps unless the developer explicitl
|
|
|
107
118
|
|
|
108
119
|
## Phase exit
|
|
109
120
|
|
|
110
|
-
|
|
121
|
+
### Branch gate (runs before Task 0)
|
|
122
|
+
|
|
123
|
+
Once the plan is approved and saved, work through this gate, then print the exit
|
|
124
|
+
instruction in step 7.
|
|
125
|
+
|
|
126
|
+
**Precondition on Task 0.** This gate runs to completion — the warning, the offer, and
|
|
127
|
+
either the confirmed `git switch` or an explicit decline —
|
|
128
|
+
**before any step of the approved plan's Task 0 executes**, including its `git add` /
|
|
129
|
+
`git add -f` and its `git commit`. Its position in this file is not the guarantee; the
|
|
130
|
+
execution order is.
|
|
131
|
+
Under the plan-commit ritual, Task 0 runs at approval, which is exactly when a plan commit
|
|
132
|
+
lands on the wrong branch.
|
|
133
|
+
|
|
134
|
+
Skip the whole gate silently when `git rev-parse --git-dir` fails or `git` is absent. The
|
|
135
|
+
gate is advisory: it must never block a completed plan from exiting its phase.
|
|
136
|
+
|
|
137
|
+
**1. Read the current branch** — `git branch --show-current`.
|
|
138
|
+
|
|
139
|
+
Empty output with exit 0 means **detached HEAD**. Warn with its own wording — "HEAD is
|
|
140
|
+
detached at `<short sha>`; a commit here belongs to no branch" — and never read empty as
|
|
141
|
+
"not on the default branch".
|
|
142
|
+
|
|
143
|
+
**2. Resolve the default branch** — `git symbolic-ref --short refs/remotes/origin/HEAD`,
|
|
144
|
+
stripping the leading `origin/`. On any non-zero exit, fall back to the literal set
|
|
145
|
+
`{main, master}`. Never hardcode `main`. When the current branch equals it, warn: "You are
|
|
146
|
+
on the default branch `<name>`; the plan commit would land there."
|
|
147
|
+
|
|
148
|
+
**3. Derive the proposed branch name** from the active spec stem already in phase context
|
|
149
|
+
(the same value `/cc-compact` writes as `sys.s`):
|
|
150
|
+
|
|
151
|
+
- strip the leading `YYYY-MM-DD-` and the trailing `-design`;
|
|
152
|
+
- read the leading id token — `feat025` → `FEAT-025`, `bug029` → `BUG-029`, `arch008` → `ARCH-008`;
|
|
153
|
+
- prefix: `FEAT`/`ARCH` → `feat/`, `BUG` → `fix/` (`CONTRIBUTING.md:23`);
|
|
154
|
+
- body: the rest of the stem, with the id token re-spelled `feat-025`;
|
|
155
|
+
- `2026-09-22-feat025-conductor-db-retention-purge-design` → `feat/feat-025-conductor-db-retention-purge`.
|
|
156
|
+
|
|
157
|
+
If the stem is missing or `none`, fall back to a root `AGENT-READABLE BACKLOG.md`: grep it
|
|
158
|
+
for the id under discussion and derive from that heading's title. If neither source yields
|
|
159
|
+
a name, still run steps 1-2 and their warnings, then ask the developer for a name rather
|
|
160
|
+
than proposing one.
|
|
161
|
+
|
|
162
|
+
**Sanitize before interpolating:** lowercase; collapse non-alphanumerics to a single `-`;
|
|
163
|
+
trim leading and trailing `-`; cap the part after the prefix at 60 characters, truncated on
|
|
164
|
+
a `-` boundary; always interpolate double-quoted. Then `git check-ref-format --branch
|
|
165
|
+
"<name>"` is the authority — if it fails, or the sanitized name is empty, ask the developer
|
|
166
|
+
for a name. **Do not write per-character reject passes** for `..`, `@{`, `~`, `^`, `\`, or a
|
|
167
|
+
trailing `.lock`: the collapse rule already removes every one of them, so such passes are
|
|
168
|
+
unreachable code.
|
|
169
|
+
|
|
170
|
+
**4. Decide whether to stay silent.** Silence requires one of exactly two conditions:
|
|
171
|
+
|
|
172
|
+
- (a) the current branch equals the derived name; or
|
|
173
|
+
- (b) the current branch is feature-shaped (`feat/`, `fix/`, `chore/`, `docs/`) **and** the
|
|
174
|
+
id token embedded in its name matches the current item's id — `feat/feat-026-…` while
|
|
175
|
+
planning `FEAT-026`.
|
|
176
|
+
|
|
177
|
+
Only then: no warning, no offer — go to step 7, because firing on every plan run is noise.
|
|
178
|
+
In every other case, report both the current branch and the derived one and ask which to
|
|
179
|
+
use; never switch silently. That explicitly includes a feature-shaped branch carrying a
|
|
180
|
+
**different** id (`feat/feat-025-…` while planning `FEAT-026`) — shape never wins over id,
|
|
181
|
+
or the new plan commit lands on the previous feature's branch. A feature-shaped branch with
|
|
182
|
+
no extractable id token (a hand-made `feat/retention-purge`) fails (b) by design and falls
|
|
183
|
+
through to report-and-ask; do not substitute fuzzy title matching.
|
|
184
|
+
|
|
185
|
+
**5. Validate the Task 0 commit message from the approved plan.** The plan is the single
|
|
186
|
+
source of truth for that message and Task 0 runs it verbatim, so this gate **validates** —
|
|
187
|
+
it does not duplicate. Check the subject for:
|
|
188
|
+
|
|
189
|
+
- **Conventional-Commits shape**, anchored to what `CONTRIBUTING.md:37` literally says:
|
|
190
|
+
"Commit messages follow Conventional Commits: `feat:`, `fix:`, `docs:`, `chore:`". Those
|
|
191
|
+
four are the documented set; another Conventional-Commits type this repository has shipped
|
|
192
|
+
(`test:`, `ci:`, `refactor:`) passes with a note, since `CONTRIBUTING.md` neither lists nor
|
|
193
|
+
forbids it.
|
|
194
|
+
- **The id appears somewhere in the subject.** Bracketed suffix (`feat: bound raw_history
|
|
195
|
+
with the shared retention purge [FEAT-025]`) and inline prose (`docs: add the FEAT-025
|
|
196
|
+
retention purge implementation plan`) both pass. Do not demand the suffix.
|
|
197
|
+
|
|
198
|
+
Report a malformed or absent message **before Task 0 begins**, proposing the corrected
|
|
199
|
+
subject, so the plan is fixed at its source rather than patched at commit time.
|
|
200
|
+
|
|
201
|
+
**Synthesize a message only when the plan carries none:** `<type>: <imperative summary>
|
|
202
|
+
[<ID>]` — the suffix form, chosen for synthesis because it is unambiguous to generate; `type`
|
|
203
|
+
is `docs` for a plan commit, since the plan file is documentation. On confirmation, write the
|
|
204
|
+
synthesized message into the plan's Task 0 commit step; never hold it only in this gate.
|
|
205
|
+
|
|
206
|
+
**6. Ask once, then act.** Present a single confirmation covering the current branch, the
|
|
207
|
+
warning if one applies, the proposed branch name, and the validated or corrected Task 0
|
|
208
|
+
subject.
|
|
209
|
+
|
|
210
|
+
- Pre-check with `git rev-parse --verify --quiet "refs/heads/<name>"` before offering `-c`.
|
|
211
|
+
If the ref already exists, offer `git switch "<name>"` without `-c` instead, and name the
|
|
212
|
+
distinction in the prompt.
|
|
213
|
+
- On **yes**: run `git switch -c "<name>"` (or the plain `git switch "<name>"`) and report
|
|
214
|
+
the resulting branch.
|
|
215
|
+
- On **no**: print nothing further and continue. Declining is a no-op and the workflow
|
|
216
|
+
proceeds exactly as it did before this gate existed.
|
|
217
|
+
- No git write — `switch -c`, `switch`, or `commit` — happens without this explicit
|
|
218
|
+
confirmation.
|
|
219
|
+
- If `git switch` refuses because a tracked file would be overwritten, report git's own
|
|
220
|
+
message verbatim and stop. Do not stash, do not force, do not retry.
|
|
221
|
+
- Any other git failure: warn once and continue to step 7.
|
|
222
|
+
|
|
223
|
+
**7. Exit.** Only now instruct the user:
|
|
111
224
|
|
|
112
225
|
> "Plan complete. Run `/cc-compact` now before starting implementation."
|
|
113
226
|
|
|
114
227
|
Do not proceed to implementation without user confirmation that `/cc-compact` has been run.
|
|
228
|
+
|
|
229
|
+
---
|
|
230
|
+
|
|
231
|
+
## Phase exit - session row
|
|
232
|
+
|
|
233
|
+
The plan phase has completed, which is the only moment at which "phase `plan` just
|
|
234
|
+
finished" is a fact rather than a deduction. Write it here, at its own boundary.
|
|
235
|
+
Run this after step 7's exit instruction has been printed.
|
|
236
|
+
|
|
237
|
+
<!-- SESSION-ROW-TAIL:BEGIN -->
|
|
238
|
+
**Preconditions.** `c` is the full-40 `git rev-parse HEAD`, lowercased, matching `/^[0-9a-f]{7,40}$/`, `"0000000"` on any failure; `s` is the active spec stem or `"none"`. Both are derived exactly as this command's body already specifies.
|
|
239
|
+
|
|
240
|
+
1. Ensure `.conductor/` exists (`mkdir -p .conductor`, best-effort). If that fails, skip the tail entirely.
|
|
241
|
+
2. Resolve the session id: `id="$(node .claude/scripts/session-id.mjs 2>>.conductor/last-write.log)"`.
|
|
242
|
+
3. Probe how to launch `node:sqlite`, the same probe the `cc-implement` Step 6 hook runs: no flag first, else `--experimental-sqlite --no-warnings`, else skip the write.
|
|
243
|
+
4. Upsert the session row. Every argv scalar is double-quoted, because a repository path can contain spaces:
|
|
244
|
+
|
|
245
|
+
`node <probe-flags> .claude/scripts/conductor-db.mjs session "$id" "plan" "$s" "$c" >> .conductor/last-write.log 2>&1`
|
|
246
|
+
5. **Loud degrade.** If the probe skipped the write, or the write exited non-zero, append one line naming the reason:
|
|
247
|
+
|
|
248
|
+
`printf '%s\n' "CC_DB_TAIL: session row not written (<reason>)" >> .conductor/last-write.log`
|
|
249
|
+
|
|
250
|
+
A row that is simply absent is the shape that let the recorded phase go stale across two boundaries unnoticed. The absence is always reported.
|
|
251
|
+
|
|
252
|
+
Every redirect uses append mode (`>>`), never `>`, so a rapid or parallel second run never truncates a preceding trace. Any failure in this block is **non-fatal**: the command reports its normal outcome regardless.
|
|
253
|
+
|
|
254
|
+
**Cross-platform note.** The forms above are Unix-canonical; the `.md` file is an agent instruction, not a literal script. On Windows/PowerShell realize the same semantics: set `$OutputEncoding = [System.Text.UTF8Encoding]::new($false)` first, capture `$id = node .claude/scripts/session-id.mjs`, and append the log with `… 2>&1 | Out-File -Append -Encoding utf8 .conductor/last-write.log`, never the bare `*>>`, whose default encoding is UTF-16LE on PS 5.1 and would corrupt the trace. Ensure the directory with `New-Item -ItemType Directory -Force .conductor`.
|
|
255
|
+
<!-- SESSION-ROW-TAIL:END -->
|