@yeison.restrepo.r/code-conductor 1.24.1 → 1.30.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.
@@ -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
- Check if `scripts/detect-stack.mjs` exists in the project root. If it does, run:
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>` (any case) or is blank after `Key:` → replace with the detected value using a single `Edit` call.
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 `scripts/detect-stack.mjs` is missing or returns `{}`, skip auto-detection.
27
+ If the detector is absent or returns `{}`, skip auto-detection and continue below.
28
28
 
29
- After auto-detection (or if skipped), check which identity fields remain blank:
29
+ ### Step 2b — Resolve what detection could not
30
30
 
31
- Read `CLAUDE.md`. Check the `## Project Identity` section.
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
- If **Name** is still empty, ask the user all of these questions at once (not one at a time):
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
- 1. What is the project name?
36
- 2. One sentence: what does it do?
37
- 3. Primary tech stack (e.g. "TypeScript + React", "Python + FastAPI") — **only ask if `IS_NEW=false` AND stack was not auto-detected**
38
- 4. Response language preference? (default: `en` — only ask if context suggests otherwise)
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
- If Name was already filled (by auto-detection or previous run), skip directly to Step 3 without asking.
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
- Once any manual fields are collected, update CLAUDE.md with a single `Edit` call covering all remaining blank fields.
75
+ A skipped question applies the literal `N/A`. Never leave a `<command>` placeholder behind.
43
76
 
44
- **CI mode:** If `CI=true` or stdin is not a TTY, skip all interactive questions. Leave unresolved `<command>` placeholders in place.
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.sh` exists and is executable:
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.sh"
96
+ HOOK=".claude/hooks/pre-tool-use.mjs"
64
97
  if [ ! -f "$HOOK" ]; then
65
98
  echo "⚠️ Hook missing: $HOOK"
66
- echo "Run: bash install.sh (or copy from project-template/.claude/hooks/)"
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,7 +118,109 @@ Execute one step at a time. Confirm between steps unless the developer explicitl
107
118
 
108
119
  ## Phase exit
109
120
 
110
- Once the plan is approved and saved, instruct the user:
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