cc-codeconductor 1.1.0 → 1.2.0

package/presets/codex/skills/evaluation/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: evaluation
+description:
+  Guides agents through scorecards, outcomes, model profiles, and eval suites.
+  Use when running /cc-scorecard or /cc:scorecard, measuring a deliverable, or
+  checking workflow gates with suite-run.
+---
+
+# Evaluation
+
+## Overview
+
+A scorecard measures the deliverable against eight weighted criteria. Spec
+quality checklists are reviewer-owned. "Seems right" is not a verdict.
+
+Pass threshold: weighted score >= 2.0 and no criterion at 0.
+
+## When to Use
+
+- After implement/review, before `openspec archive`
+- Comparing models or prompt versions
+- Proving the workflow tools still work (`suite-run`)
+
+**NOT** for rewriting specs (reviewer checklist) or for implementing code.
+
+## Process
+
+Local: `bun run dev`. Published: `npx cc-codeconductor`.
+
+```text
+scorecard create --task BC-001 --from-diff
+scorecard record --task BC-001 --verdict PASS --score 2.5
+scorecard list | aggregate | models | regression | matrix | compare-models
+scorecard prompt-diff 0.4.0 0.5.0 --agent architect
+scorecard experiment start --suite harness-v1
+scorecard suite-run --suite workflow-gates
+scorecard suite-run --suite hook-guardrails
+scorecard suite-run --suite scorecard-signals
+```
+
+`openspec analyze` can auto-suggest `acceptance` / `tests` on `--from-diff`.
+Archive needs PASS when review is required.
+
+Outcomes append to `.codeconductor/evaluation/outcomes.jsonl`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| I'll fill the scorecard by hand without a diff | Use `--from-diff` and runner evidence. |
+| Suites are optional toys | `suite-run` is the workflow tool that proves gates. |
+| Handmade TDD JSON is fine | The runner rejects it. |
+
+## Red Flags
+
+- PASS with a criterion at 0
+- Archive without a recorded scorecard when review is required
+- Declaring the workflow ready without `suite-run` or `scorecard record`
+
+## Verification
+
+- [ ] Scorecard created from diff (or explicit scores)
+- [ ] Verdict PASS / REVISE / REJECT recorded
+- [ ] For process changes: `scorecard suite-run --suite hook-guardrails` (and
+      `workflow-gates` / `scorecard-signals` when those gates changed)

package/presets/codex/skills/openspec/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: openspec
+description:
+  Guides agents through OpenSpec delivery from BACKLOG.md (validate, analyze,
+  test-before-implement, scorecard, archive). Use when running /cc-openspec,
+  /cc:openspec, or delivering an existing backlog item. Authoring BACKLOG.md
+  is skill backlog, not this skill.
+---
+
+# OpenSpec delivery
+
+## Overview
+
+This skill delivers an existing `BACKLOG.md` item. It is a workflow with CLI
+gates, not a reference doc. Specs describe WHAT; `design.md` describes HOW.
+
+## When to Use
+
+- `/cc-openspec` or `openspec next` / `plan` / `done` / `archive`
+- An item is `READY` or later and must move through the state machine
+
+**NOT** for creating `BACKLOG.md` (use skill `backlog`) or for stack-specific
+coding rules.
+
+## Process
+
+Local CLI is `bun run dev`. Published package is `npx cc-codeconductor`.
+
+1. `openspec validate` — must pass before delivery.
+2. `openspec plan BC-xxx` if the item is not yet `PLANNED`.
+3. `openspec analyze --output json` — CRITICAL findings exit 1. Do not implement.
+4. Phases: discover (`repo-explorer`) → design (`architect`) → test (`tester`) →
+   implement (`implementer`) → review (`reviewer`). If Global `TDD required: yes`,
+   test runs before implement.
+5. `openspec done` on test/implement requires `captureTddSuiteEvidence`. Handmade
+   evidence JSON is rejected.
+6. `scorecard create --task BC-xxx --from-diff` then record a verdict.
+7. `openspec archive` only after human review when `Review required: yes` and
+   the scorecard is PASS.
+
+Status machine: `TODO` → `READY` → `PLANNED` → `IN_PROGRESS` → `REVIEW` → `DONE`
+→ Archive. `BLOCKED` returns to `READY`. Reviewer rejection: `REVIEW` →
+`IN_PROGRESS`.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| Validate is bureaucracy | `openspec validate` is the gate. Skipping it is a defect. |
+| I'll add tests after green | Global TDD required means tester before implementer. |
+| I'll write the evidence JSON myself | Handmade TDD JSON is rejected. Use the verification runner. |
+| The item is small; skip analyze | `openspec analyze` CRITICAL still stops implement. |
+
+## Red Flags
+
+- Implementing while analyze reports CRITICAL
+- Archive without a PASS scorecard when review is required
+- Acceptance like "improve UX" with no measurable check
+
+## Verification
+
+- [ ] `openspec validate` exit 0
+- [ ] `openspec analyze --output json` has no CRITICAL
+- [ ] TDD evidence from the runner when TDD is required
+- [ ] `scorecard create --from-diff` recorded
+- [ ] Suite check (optional): `bun run dev scorecard suite-run --suite workflow-gates`

package/presets/codex/skills/testing-tdd/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: testing-tdd
+description:
+  Guides agents through Red-Green-Refactor with runner-captured evidence.
+  Use when running /cc-tdd-cycle, writing tests before implementation, or
+  Global TDD required is yes.
+---
+
+# Test-Driven Development
+
+## Overview
+
+Red (failing test) → Green (minimal code) → Refactor. Evidence comes from
+`captureTddSuiteEvidence`, not handmade JSON.
+
+## When to Use
+
+- `/cc-tdd-cycle`, new behavior, bug fixes, TDD-required OpenSpec items
+
+**NOT** for docs-only changes or when the Task Card forbids tests.
+
+## Process
+
+1. Write the failing test that encodes one acceptance criterion. Run the suite.
+   It MUST fail (`suiteFails === true`).
+2. Implement the minimum that turns it green. Do not expand scope.
+3. Refactor only with a green suite.
+4. Capture evidence via the verification runner (`openspec done` on test/implement
+   when TDD is required).
+5. Cover happy path, edge, and error for each behavior.
+
+Local: `bun run dev`. Pyramid default: many unit, fewer integration, rare E2E.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| I'll add tests later | Later means never. Red first. |
+| This is too small to test | If it can break, it needs a failing test first. |
+| I'll write the evidence JSON | Handmade TDD JSON is rejected. |
+
+## Red Flags
+
+- Tests that assert implementation details instead of behavior
+- Green without a recorded red
+- Skipping error cases
+
+## Verification
+
+- [ ] Suite failed before implement
+- [ ] Suite passed after implement
+- [ ] Runner evidence exists (not handmade)
+- [ ] Optional: `bun run dev scorecard suite-run --suite workflow-gates`

package/presets/codex/skills/using-cc-skills/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: using-cc-skills
+description:
+  Maps incoming work to the CodeConductor slash command and workflow skill.
+  Use when starting a session or deciding which /cc-* command applies.
+---
+
+# Using CodeConductor skills
+
+## Overview
+
+Pick one slash command. Follow its skill. Invoke CLI for gates. Do not invent
+a parallel process.
+
+## When to Use
+
+- Start of a session, ambiguous request, or "which /cc should I run?"
+
+## Process
+
+| Intent | Command | Skill |
+| --- | --- | --- |
+| New backlog item | `/cc-backlog` | `backlog` |
+| Deliver a BC-xxx item | `/cc-openspec` | `openspec` |
+| New feature | `/cc-feature` | `openspec` + `testing-tdd` |
+| Bug fix | `/cc-fix` | `testing-tdd` |
+| Review a diff | `/cc-review` | `evaluation` |
+| TDD cycle only | `/cc-tdd-cycle` | `testing-tdd` |
+| Scorecard / suites | `/cc-scorecard` | `evaluation` |
+
+Then run the matching CLI (`openspec validate`, `scorecard create --from-diff`,
+`hook pre-tool`, `scorecard suite-run`).
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| I'll skip the slash and just code | Skipping the workflow is a defect. |
+
+## Red Flags
+
+- Two slash commands in parallel that mutate the same files
+- Implementing before `openspec analyze` when a change folder is active
+
+## Verification
+
+- [ ] One command selected and shown to the user
+- [ ] Matching skill loaded before edits

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

@@ -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)
 
 Invoke the `task-coach` subagent via the Task tool.

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

@@ -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)
 
 Invoke the `task-coach` subagent via the Task tool.

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

@@ -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

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

@@ -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
@@ -146,3 +160,6 @@ 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.

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

@@ -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)
 
 If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and

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

@@ -27,6 +27,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 — Validate (mandatory gate)
 
 Run:

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

@@ -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/cursor/commands/cc/spec-mutation.md

@@ -0,0 +1,190 @@
+---
+description: >-
+  [cc: alias] 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).

package/presets/cursor/commands/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