cc-codeconductor 1.1.0 → 1.3.0

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

@@ -0,0 +1,156 @@
+---
+name: cc-review
+description: Run a structured code review — produces a Review Report with CRITICAL, WARNING, and SUGGESTION findings; CRITICAL findings block merge.
+---
+
+# review
+
+Invoke as `$cc-review`. The user request follows the skill mention.
+
+# Code Review Workflow
+
+Review target: $ARGUMENTS
+
+Specify what to review. Accepted formats:
+
+- A branch name: `feature/my-branch`
+- A file or set of files: `src/api/UserController.kt`
+- A pull request reference: `PR #42`
+- Empty — defaults to the current working diff (`git diff`)
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `review` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command review "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command review "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile review --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command review --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.
+
+---
+
+## Step 1 — Diff collection
+
+Before adopting the Reviewer role, collect the diff for the specified target.
+
+If $ARGUMENTS is empty or not provided:
+
+- Use `git diff HEAD` as the review target.
+
+If $ARGUMENTS is a branch name:
+
+- Use `git diff main...$ARGUMENTS` (or `develop` if main is not the base).
+
+If $ARGUMENTS is a PR reference:
+
+- Retrieve the PR diff and the PR description for context.
+
+If $ARGUMENTS is a file path:
+
+- Use `git diff HEAD -- $ARGUMENTS`.
+
+Show the diff summary (files changed, lines added/removed) before proceeding.
+
+---
+
+## Step 2 — Code review (Reviewer role)
+
+Adopt the `reviewer` role as defined in `AGENTS.md`.
+
+Evaluate the diff against the following checklist:
+
+**Correctness**
+
+- Does the implementation match the stated intent?
+- Are there logic errors, off-by-one errors, or unhandled edge cases?
+
+**Architecture alignment**
+
+- Does the change follow existing module boundaries?
+- Does it introduce unplanned coupling or layering violations?
+
+**Security**
+
+- Are inputs validated before use?
+- Is there any credential, token, or secret in the diff?
+- Are there SQL injection, XSS, or injection risks?
+
+**Performance**
+
+- Does the change introduce N+1 queries, blocking I/O, or O(n²) loops?
+
+**Test coverage**
+
+- Do tests exist for the new or changed behavior?
+- Are assertions meaningful (not just checking that no exception is thrown)?
+
+**Documentation**
+
+- Are public interfaces documented?
+- Is CHANGELOG updated if behavior changed?
+
+---
+
+## Step 3 — Review Report
+
+Produce a structured Review Report with findings in three categories:
+
+```markdown
+## Review Report
+
+### CRITICAL
+[Findings that must be fixed before merge — file:line, description, suggested resolution]
+
+### WARNING
+[Findings that should be resolved before merge — same format as CRITICAL]
+
+### SUGGESTION
+[Optional improvements — style, readability, future-proofing. These do not block merge.]
+
+### Summary
+- Files reviewed: N
+- Total findings: N (X critical, Y warnings, Z suggestions)
+- Merge recommendation: APPROVED | BLOCKED
+```
+
+---
+
+## Step 4 — Merge decision
+
+If any CRITICAL findings exist:
+
+- The Review Report status is **BLOCKED**.
+- Report all CRITICAL findings.
+- Do not proceed until each CRITICAL finding is resolved.
+- After resolution, run `/review` again on the same target.
+
+If no CRITICAL findings exist:
+
+- The Review Report status is **APPROVED**.
+- Report any WARNINGs and SUGGESTIONs for human awareness.
+- The human makes the final merge decision.
+
+---
+
+## Completion
+
+Deliver the complete Review Report. Never summarize or omit findings.
+
+---
+
+## Step 5 — Scorecard and outcome
+
+```bash
+npx cc-codeconductor scorecard create --from-diff --agent reviewer
+npx cc-codeconductor scorecard record --verdict PASS|REVISE|REJECT --score <weighted>
+npx cc-codeconductor scorecard regression
+```
+
+Map merge recommendation to scorecard verdict. Record outcome for trend tracking.
+
+## Next
+
+Approved: merge. Blocked: return the findings to `$cc-fix` or `$cc-feature`.

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

@@ -0,0 +1,82 @@
+---
+name: cc-scorecard
+description: Evaluate deliverable quality — scorecard, outcome tracking, regression checklist, and aggregate stats.
+---
+
+# scorecard
+
+Invoke as `$cc-scorecard`. The user request follows the skill mention.
+
+# Scorecard Evaluation Workflow
+
+Scope: $ARGUMENTS
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `scorecard` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command scorecard "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command scorecard "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile scorecard --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command scorecard --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.
+
+---
+
+## Step 1 — Identify task
+
+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
+
+```bash
+npx cc-codeconductor scorecard create --task <id> --agent reviewer --from-diff
+```
+
+Review auto-suggested criteria (minimal diff, cc-gain). Complete remaining scores 0–3 per [`docs/agent-scorecard.md`](docs/agent-scorecard.md).
+
+---
+
+## Step 3 — Regression (optional)
+
+```bash
+npx cc-codeconductor scorecard regression
+```
+
+If required checks fail, **STOP** and report failures.
+
+---
+
+## Step 4 — Record outcome
+
+```bash
+npx cc-codeconductor scorecard record --task <id> --agent reviewer --model <model> --verdict PASS --score 2.5
+```
+
+Include `--cost` and `--tokens` when available from session metrics.
+
+---
+
+## Step 5 — Aggregate
+
+```bash
+npx cc-codeconductor scorecard aggregate
+```
+
+Report pass rate and average weighted score.
+
+---
+
+## Routing on verdict
+
+- **PASS** — accept deliverable; update backlog if applicable
+- **REVISE** — return to implementer/tester with findings
+- **REJECT** — route to task-coach for re-scoping
+
+Apply skill `evaluation`.

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

@@ -0,0 +1,186 @@
+---
+name: cc-security
+description: Run the authorized defensive security workflow — domain security-* skills, authorization gate, risk-based routing, hardening, and review.
+---
+
+# security
+
+Invoke as `$cc-security`. The user request follows the skill mention.
+
+# Defensive Security Workflow
+
+Security objective: $ARGUMENTS
+
+Provide the following information in $ARGUMENTS:
+
+- What must be reviewed or hardened, and why
+- Domain: a `security-*` skill id (recon, vuln-assessment, web, cloud, IR,
+  hunting, GRC, …) or `web-app` / `api` / `cloud-config` /
+  `dependency-supply-chain` / `secrets`
+- Authorization: who authorized this work on this target, and the scope boundary
+- Risk classification (`low`, `medium`, or `high`), if known
+- Scope: which files, modules, repos, or environments are in and out of bounds
+
+---
+
+## Scope and authorization
+
+This workflow performs **authorized defensive security work only**: threat
+modeling, hardening, secure configuration, dependency and supply-chain review,
+secret hygiene, and detection coverage.
+
+Refuse outright and offer the defensive equivalent instead (threat model,
+hardening, detection coverage, dependency audit):
+
+- Exploit or proof-of-concept development
+- Malware authoring, or malware analysis intended for reuse
+- Reverse engineering aimed at bypassing a control
+- Red-team playbooks
+- Any unauthorized-access procedure
+
+Scope is limited to the repository under analysis. Do not scan, probe, or
+perform reconnaissance against third-party hosts.
+
+Do not proceed without an authorization statement. Do not produce exploit
+payloads, malware, or attack procedures.
+
+---
+
+## Step 0 — CCEP Bootstrap
+
+Command: `security` (fixed for this workflow — do not infer from user text)
+
+1. Run: `npx cc-codeconductor ccep parse --command security "$ARGUMENTS" --output json`
+2. Run: `npx cc-codeconductor ccep resolve --command security "$ARGUMENTS" --output json`
+3. Run: `npx cc-codeconductor ccep profile security --output json`
+4. After planner/intake JSON is available, run: `npx cc-codeconductor ccep evaluate --command security --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 1 — Wayfinding (repo-explorer)
+
+If `graphify-out/graph.json` exists, run `graphify query "$ARGUMENTS"` (and
+`graphify path` / `graphify explain` when needed). Then invoke `repo-explorer`
+to map modules, conventions, and impact radius. Do not write code in this step.
+Record a Repo Map artifact before intake. Load the matching `security-*` skill
+for the named domain (see `.claude/skills/security-*/SKILL.md`). Keep the OWASP
+`security` skill for application-security reviews.
+
+---
+
+## Step 2 — Task Card validation (task-coach)
+
+Invoke `task-coach` with the security objective above.
+
+task-coach must produce a Task Card that includes:
+
+- Objective: what must be reviewed or hardened, in one sentence
+- Domain: which `security-*` skill applies, or `web-app` / `api` /
+  `cloud-config` / `dependency-supply-chain` / `secrets`
+- Authorization: who authorized this work on this target, and the scope boundary
+- Risk classification: `low`, `medium`, or `high`
+- Scope: which files or modules are likely affected
+
+If authorization is absent, unclear, or names a system the requester does not
+own or operate, **STOP and refuse. Do not route the task.**
+
+Redact secrets, tokens, and credentials from any evidence before it enters the
+Task Card. Summarize logs; do not paste env files.
+
+**STOP here. Show the Task Card and wait for human confirmation.**
+
+---
+
+## Step 3 — Route by risk
+
+Read the risk field from the Task Card and follow the corresponding route.
+
+### Low-risk route
+
+Applies when: the weakness is isolated, not exploitable in the current
+configuration, and no authentication, secret, or dependency boundary is
+involved.
+
+Route: `task-coach` → `tester` → `implementer`
+
+Proceed directly to Step 4 (tests), then Step 5a.
+
+### Medium or high-risk route
+
+Applies when: the work touches authentication, authorization, secrets,
+cryptography, trust-boundary input validation, or a dependency upgrade.
+
+Route: `task-coach` → `architect` → `tester` → `implementer` → `reviewer`
+
+Invoke `architect` before implementation. architect must:
+
+- Identify the weakness and the affected trust boundary
+- Define the hardening approach and affected files
+- Flag any regression risk to adjacent components
+- Produce a Technical Plan
+
+On **high** risk, also invoke `security-reviewer` before Reviewer.
+
+**STOP here if high-risk. Show the Technical Plan and wait for human approval
+before continuing.**
+
+---
+
+## Step 4 — Tests (tester)
+
+Invoke `tester` for all risk levels.
+
+tester must:
+
+1. Write a regression test that proves the weakness exists and confirm it fails
+   before any change (RED)
+2. Verify that existing tests still pass
+3. Produce a Coverage Summary: test added, case covered
+
+---
+
+## Step 5a — Implementation, low-risk (implementer)
+
+Invoke `implementer` with the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must:
+
+1. Apply the minimal hardening change — no unrelated changes
+2. Run the suite and make the RED regression test pass
+3. Produce an Implementation Summary: weakness, change applied, files changed
+
+---
+
+## Step 5b — Implementation, medium/high-risk (implementer)
+
+Invoke `implementer` with the approved Technical Plan and the Task Card.
+Implementer creates a Git Worktree before touching any file; all edits happen inside it.
+
+implementer must follow the plan exactly. Any deviation requires a new Technical
+Plan approval. After implementation, run the full test suite. No exploit code.
+
+---
+
+## Step 6 — Review (Reviewer role) — medium/high-risk only
+
+Invoke `reviewer` with the diff and Task Card. The Reviewer must apply the OWASP
+rules in the `security` skill.
+
+reviewer produces a Review Report with CRITICAL / WARNING / SUGGESTION findings.
+If any CRITICAL findings exist, **STOP**. Do not close the task until they are
+resolved.
+
+---
+
+## Completion
+
+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.

package/presets/codex/skills/cc-spec-mutation/SKILL.md

@@ -0,0 +1,196 @@
+---
+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
+
+Invoke as `$cc-spec-mutation`. The user request follows the skill mention.
+
+# 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.