cc-codeconductor 1.1.0 → 1.3.0

package/presets/agy/workflows/cc-spec-mutation.md

@@ -0,0 +1,195 @@
+---
+name: cc-spec-mutation
+description: >-
+  Spec-locked TDD with a mutation-testing gate — refine the intent
+  into an immutable Gherkin contract (SHA-256 frozen), implement under the
+  three laws of TDD, pass a judge audit, and merge only if every mutant dies.
+---
+
+# Spec-Mutation — Hard Spec → TDD → Judge → Mutation Gate
+
+Scope: $ARGUMENTS
+
+Describe what behavior you want to implement. Include:
+
+- The function, method, or feature to implement
+- The expected behavior (inputs, outputs, invariants, edge cases)
+- The allowed file scope (production files that may change)
+- The test command for the affected suite (e.g. `pytest tests/test_billing.py`)
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `spec-mutation` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command spec-mutation "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command spec-mutation "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile spec-mutation --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command spec-mutation --input <planner.json> --output json`. If `stop` is true, show questions or risks and wait for human input.
+5. Delegate to subagents using compiled CCEP prompts — never forward raw `$ARGUMENTS` to planners.
+   Canonical delivery order is test-before-implement whenever both phases apply.
+
+---
+
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc-spec-mutation`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+## Contract
+
+The Gherkin specification is the **immutable contract** of the system. No code
+merges unless it survives intentional source mutations. The loop is closed:
+
+```
+[Human + spec_partner] ──> [gherkin_author] ──> [Test Freeze: SHA-256]
+                                                       │
+┌──────────────────────────────────────────────────────┘
+▼
+[tdd_craftsman] <───────────────┐ (surviving mutant)
+   (Red-Green-Refactor)         │
+        │                       │
+        ▼                       │
+     [judge] ───────────> [mutation_testing] ───> [Safe Merge]
+```
+
+Role mapping onto Conductor Agents (AGENTS.md):
+
+| Workflow role      | Conductor Agent   | Deliverable                                |
+| ------------------ | ----------------- | ------------------------------------------ |
+| `craftsman_lead`   | `orchestrator`    | Routed Task Cards, per-stage scorecards    |
+| `spec_partner`     | `task-coach`      | Spec draft with invariants and boundaries  |
+| `gherkin_author`   | `contract-builder`| Strict `.feature` file (Given/When/Then)   |
+| `tdd_craftsman`    | `tester` → `implementer` | Failing test, then minimal production code |
+| `judge`            | `reviewer`        | Binary verdict (PASS/REJECT) with scoring  |
+| `mutation_testing` | `tester` (runner) | Killed/survived mutant report              |
+
+## Stage 1 — Interactive refinement (`spec_partner` / task-coach)
+
+Do not jump to implementation. Apply Socratic questioning to the initial intent:
+
+- Preconditions, postconditions, and edge cases.
+- Invariant matrix: what must always be true.
+- Scope boundaries: explicit `Scope / Files` and `Scope / Out` for the Task Card.
+
+Stop gate: human confirms the draft before formalization.
+
+## Stage 2 — Hard Spec formalization (`gherkin_author` / contract-builder)
+
+Formalize the agreed draft into `specs/<task>.feature` using strict Gherkin:
+
+- No vague language ("must respond fast" is forbidden — use measurable Then steps).
+- Every scenario declares preconditions (`Given`), actions (`When`), and
+  observable states (`Then`).
+- Once the human approves the `.feature`, freeze it:
+
+```bash
+shasum -a 256 specs/<task>.feature tests/ > .codeconductor/tasks/<task_id>.lock
+```
+
+From this point `specs/` and `tests/` are **read-only** for implementation
+agents. Before every later gate, recompute the hash; any single-byte difference
+aborts the pipeline with scorecard 0 (Specification Gaming).
+
+## Stage 3 — TDD under the three laws (`tdd_craftsman`)
+
+Delegates to the `/cc-tdd-cycle` state machine (`tddCycleStateMachine` in
+`domain/loop`). Evidence must be captured with `captureTddSuiteEvidence` — do
+not hand-edit JSON under `.codeconductor/evidence/`.
+
+1. **Law 1 (RED):** no production code except to make a failing test pass. A
+   compile error from a missing interface counts as a failure.
+2. **Law 2:** write exactly one failing assertion or scenario at a time.
+3. **Law 3 (GREEN):** write only the minimal production code to pass. No
+   speculative code, no preventive heuristics, stdlib-first.
+
+Hard rule: any write attempt against `specs/` or `tests/` during GREEN/REFACTOR
+is a harness violation — stop execution and report.
+
+## Stage 4 — Judge audit (`judge` / reviewer)
+
+Deterministic gates before spending compute on mutation:
+
+- Clean compile / diagnostics exit code 0.
+- Traceability: every Gherkin step maps to an implemented test step.
+- Scope Gaming audit: `git diff --name-only` must match the Task Card
+  `Scope / Files` exactly. Relaxed types, weakened assertions, or out-of-scope
+  edits → REJECT with findings.
+
+Verdict is binary: PASS continues to the mutation gate; REJECT returns to the
+`implement` phase with the findings attached.
+
+## Stage 5 — Mutation gate (`mutation_testing`)
+
+Run the deterministic AST mutator shipped with this preset:
+
+```bash
+python3 presets/shared/mutation_runner.py \
+  --target <production_file.py> \
+  --test-command "<test command>" \
+  --spec-folder specs
+```
+
+The runner applies deterministic operator mutations (`>` → `<=`, `==` → `!=`,
+`is` → `is not`, …) one at a time, re-runs the suite per mutant, and restores
+the original source unconditionally (`finally` rollback).
+
+- **Mutant killed (tests fail):** the suite detects the corruption. Continue.
+- **Mutant survived (tests pass):** the tests are blind to this branch. The
+  runner writes `specs/handover.md` + appends to
+  `specs/implementation-summary.md` and exits with code **2**.
+
+Non-Python stacks: substitute Stryker (JS/TS), PITest (JVM), or Mutmut
+(Python full-suite) with the same contract — 100% kill rate or hands-off.
+
+### Hands-off protocol (exit code 2)
+
+1. Do NOT modify production code to "fix" a surviving mutant.
+2. Route back to `tdd_craftsman` with `specs/handover.md` as input: write the
+   missing failing test (Law 1 & 2) that asserts the mutated branch.
+3. Re-run stages 3–5.
+
+### Circuit breaker (max 3 loops)
+
+The orchestrator keeps a persistent counter per Task Card. If the
+`tdd_craftsman ↔ mutation_testing` loop does not reach a 100% kill rate after
+**3 iterations**:
+
+- Cancel active subagents (stop token/context spend).
+- `git checkout -- <scope>` rollback to the last clean state.
+- Scorecard: `STATUS = BLOCKED`; escalate to a human operator. The branch stays
+  frozen until human arbitration.
+
+## Guardrails (harness-enforced, not prompt-enforced)
+
+- **Test Freezing:** SHA-256 of `specs/` + `tests/` stored in
+  `.codeconductor/tasks/<task_id>.lock`; hash mismatch aborts the pipeline.
+- **Scope Guardian:** `fs_write`/`fs_patch` paths are validated against the Task
+  Card `Scope / Files`; path escapes (`../`) and critical files (`**/.env*`,
+  `**/credentials*`, infrastructure roots) are denied per `policy.yml`.
+- **RBAC per role:** `gherkin_author` writes only `specs/`; `tdd_craftsman`
+  reads specs/tests and writes only scoped `src/`; `judge` and
+  `mutation_testing` are read-only except the runner's rolled-back patch.
+- **Worktree isolation:** run the whole flow in a dedicated `git worktree`;
+  protected branches (`main`, `master`, `develop`) are never touched.
+
+## Completion criteria
+
+- [ ] `.feature` approved and frozen (SHA-256 lock file exists and matches).
+- [ ] RED → GREEN → REFACTOR evidence captured per phase.
+- [ ] Judge verdict PASS (compile clean, traceability complete, scope clean).
+- [ ] Mutation runner exits 0 with `total_mutants_killed == total_points`.
+- [ ] Scorecard records the kill rate and iteration count (≤ 3).
+
+## Next
+
+Run `/cc-review` on the diff before merging.

package/presets/agy/workflows/cc-tdd-cycle.md

@@ -31,6 +31,20 @@ Command: `tdd-cycle` (fixed for this workflow — do not infer from user text)
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc-tdd-cycle`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Before you begin — mandatory pre-check
 
 This command enforces strict TDD discipline. The three phases are sequential and
@@ -246,5 +260,5 @@ The TDD cycle is complete when:
 **Cycle status**: complete | blocked (reason)
 ```
 
-If the behavior requires additional test cases, start a new `/cc:tdd-cycle` with
+If the behavior requires additional test cases, start a new `/cc-tdd-cycle` with
 the next scenario. One cycle = one behavior.

package/presets/agy/workflows/cc-test-plan.md

@@ -143,7 +143,7 @@ tester produces the plan in this format:
 Show the Test Plan to the human before any tests are written.
 
 The Test Plan is an artifact for review and approval. Writing test code is a
-separate action — invoke `/cc:feature` or add a test task to the board to
+separate action — invoke `/cc-feature` or add a test task to the board to
 implement from this plan.
 
 ---
@@ -155,3 +155,7 @@ Deliver the complete Test Plan document. Save it as
 
 This command produces a plan, not test files. No production code and no test
 code is written during this command.
+
+## Next
+
+Implement against this plan with `/cc-tdd-cycle` or `/cc-feature`.

package/presets/claude/commands/cc/api-contract.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the API contract workflow for public interface changes,
+  Run the API contract workflow for public interface changes,
   compatibility constraints, contract tests, documentation, and review.
 ---
 
@@ -20,6 +20,20 @@ Command: `api-contract` (fixed for this workflow — do not infer from user text
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:api-contract`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Step 1 — Task Card validation (Task Coach role)
 
 Adopt the **Task Coach** role as defined in `CLAUDE.md`.
@@ -68,3 +82,7 @@ Adopt the **Reviewer** role as defined in `CLAUDE.md`.
 
 Block on missing contract tests, undocumented breaking changes, or docs/OpenAPI
 drift.
+
+## Next
+
+Run `/cc:review` on the diff before merging.

package/presets/claude/commands/cc/ask.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Recommend one CodeConductor slash command from a natural-language
+  Recommend one CodeConductor slash command from a natural-language
   problem. Does not start that workflow.
 ---
 

package/presets/claude/commands/cc/backlog.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Author BACKLOG.md — wayfinding, grilling, create or append items,
+  Author BACKLOG.md — wayfinding, grilling, create or append items,
   validate with openspec, and plan OpenSpec change folders for /cc:openspec.
 ---
 

package/presets/claude/commands/cc/clarify.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Re-explain the last deliverable in Task Card vocabulary when it did not land.
+  Re-explain the last deliverable in Task Card vocabulary when it did not land.
 ---
 
 # Clarify Workflow

package/presets/claude/commands/cc/council.md

@@ -85,3 +85,7 @@ If APPROVED (no CRITICAL findings):
 ## Completion
 
 Deliver the complete Council Verdict. The feature is only complete when tests pass and the council explicitly approves the implementation according to the specification.
+
+## Next
+
+Approved: merge. Blocked: return the findings to `/cc:fix` or `/cc:feature`.

package/presets/claude/commands/cc/db-migration.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the database migration workflow for schema/data changes,
+  Run the database migration workflow for schema/data changes,
   operational sequencing, tests, and review.
 ---
 
@@ -21,6 +21,20 @@ Command: `db-migration` (fixed for this workflow — do not infer from user text
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:db-migration`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Step 1 — Task Card validation (Task Coach role)
 
 Adopt the **Task Coach** role as defined in `CLAUDE.md`.
@@ -69,3 +83,7 @@ Adopt the **Reviewer** role as defined in `CLAUDE.md`.
 
 Block on missing migration tests, missing data-risk notes, undocumented
 deployment sequencing, or model/migration drift.
+
+## Next
+
+Run `/cc:review` on the diff before merging.

package/presets/claude/commands/cc/explore.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Map the repository and recommend the next CodeConductor slash command. Read-only.
+  Map the repository and recommend the next CodeConductor slash command. Read-only.
 ---
 
 # Explore Workflow

package/presets/claude/commands/cc/feature.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the full feature workflow — task validation, technical design,
+  Run the full feature workflow — task validation, technical design,
   implementation, testing, review, and documentation.
 ---
 
@@ -23,6 +23,24 @@ Command: `feature` (fixed for this workflow — do not infer from user text)
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:feature`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+Skills: `using-cc-skills`, `openspec`, `testing-tdd`, `evaluation`.
+Do not skip `openspec analyze` when a change folder is active.
+"I'll add tests later" is not allowed — tester before implementer.
+
+---
+
+
 ## Step 1 — Wayfinding (repo-explorer)
 
 If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and
@@ -140,3 +158,7 @@ Report the following:
 
 The feature is complete only when: all tests pass, no CRITICAL review findings
 remain, and documentation reflects the implemented behavior.
+
+## Next
+
+Run `/cc:review` on the diff before merging.

package/presets/claude/commands/cc/fix.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the bug fix workflow — risk-based routing through task
+  Run the bug fix workflow — risk-based routing through task
   validation, implementation, testing, and optional review.
 ---
 
@@ -31,6 +31,20 @@ Command: `fix` (fixed for this workflow — do not infer from user text)
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:fix`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Step 1 — Wayfinding (repo-explorer)
 
 If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and
@@ -173,3 +187,10 @@ Report: Task Card, Implementation Summary, regression test added, Review Report
 
 The fix is complete only when: the regression test passes, the full suite
 passes, and no CRITICAL review findings remain.
+
+Skills: `testing-tdd`, `evaluation`. Record `scorecard create --from-diff`.
+A small fix still needs a Task Card and a failing regression test first.
+
+## Next
+
+Run `/cc:review` on the diff before merging.

package/presets/claude/commands/cc/handoff.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Compact the session into gitignored `.codeconductor/sessions/handoff.md` (redact secrets).
+  Compact the session into gitignored `.codeconductor/sessions/handoff.md` (redact secrets).
 ---
 
 # Handoff Workflow

package/presets/claude/commands/cc/iterative.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the advanced iterative workflow — Wayfinding AST discovery,
+  Run the advanced iterative workflow — Wayfinding AST discovery,
   Relentless Grilling, contract and spec design, TDD, council review, and docs.
 ---
 
@@ -23,6 +23,20 @@ Command: `iterative` (fixed for this workflow — do not infer from user text)
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:iterative`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Step 1 — Wayfinding (Repo Explorer role)
 
 If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and

package/presets/claude/commands/cc/openspec.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run OpenSpec backlog delivery — validate BACKLOG.md, plan TaskCards,
+  Run OpenSpec backlog delivery — validate BACKLOG.md, plan TaskCards,
   orchestrate agents by phase, review gate, and update backlog state.
 ---
 
@@ -53,6 +53,20 @@ Command: `openspec` (fixed for this workflow — do not infer from user text)
 
 ---
 
+## Step 0b — OpenSpec quality gates
+
+If `openspec status` reports an active change folder:
+
+1. Run: `npx cc-codeconductor openspec validate --output json`
+2. Run: `npx cc-codeconductor openspec analyze --output json`
+3. If analyze `stop` is true or any finding is CRITICAL, stop. Do not delegate to implementer.
+4. Next command spelling on this runner: `/cc:openspec`
+
+Local development: `bun run dev <same argv>`. Published package: `npx cc-codeconductor`.
+
+---
+
+
 ## Step 1 — Scan
 
 Run:

package/presets/claude/commands/cc/prototype.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Disposable spike in an isolated worktree. Not a merge candidate.
+  Disposable spike in an isolated worktree. Not a merge candidate.
 ---
 
 # Prototype Workflow

package/presets/claude/commands/cc/refactor.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the refactor workflow — mandatory architectural justification,
+  Run the refactor workflow — mandatory architectural justification,
   test verification, risk-based implementation, and scope enforcement.
 ---
 
@@ -297,3 +297,7 @@ findings remain.
 If using expand-migrate-contract: completion occurs only after all batches
 (expand, migrate, contract) are DONE and no BLOCKED items remain in the
 sequencing chain.
+
+## Next
+
+Run `/cc:review` on the diff before merging.

package/presets/claude/commands/cc/review.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run a structured code review — produces a Review Report with
+  Run a structured code review — produces a Review Report with
   CRITICAL, WARNING, and SUGGESTION findings; CRITICAL findings block merge.
 ---
 
@@ -197,3 +197,10 @@ npx cc-codeconductor scorecard regression
 Example: if the combined verdict is `blocked` (either axis found CRITICAL), record with `--verdict REJECT`.
 
 Map each review outcome for trend tracking and decision audit.
+
+Skill: `evaluation`. "Looks fine" is not a verdict. Run
+`scorecard create --from-diff` and record PASS|REVISE|REJECT.
+
+## Next
+
+Approved: merge. Blocked: return the findings to `/cc:fix` or `/cc:feature`.

package/presets/claude/commands/cc/scorecard.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Evaluate deliverable quality — scorecard, outcome tracking, regression
+  Evaluate deliverable quality — scorecard, outcome tracking, regression
   checklist, and aggregate stats.
 ---
 
@@ -26,6 +26,8 @@ Command: `scorecard` (fixed for this workflow — do not infer from user text)
 
 Use `$ARGUMENTS` as task id (e.g. `BC-001`) or read active item from `npx cc-codeconductor openspec status`.
 
+If a change folder exists, run `npx cc-codeconductor openspec analyze --output json` first. `--from-diff` overlays FR/SC coverage onto `acceptance` and TDD evidence onto `tests`.
+
 ---
 
 ## Step 2 — Create scorecard with auto-signals

package/presets/claude/commands/cc/security.md

@@ -1,6 +1,6 @@
 ---
 description: >-
-  [cc: alias] Run the authorized defensive security workflow — domain
+  Run the authorized defensive security workflow — domain
   security-* skills, authorization gate, risk-based routing, hardening, and review.
 ---
 
@@ -177,3 +177,7 @@ resolved.
 Report: Task Card, Implementation Summary, regression test added, Review Report
 (if applicable). The task is complete only when: the regression test passes, the
 full suite passes, and no CRITICAL review findings remain.
+
+## Next
+
+Run `/cc:review` on the diff before merging.