cc-codeconductor 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-codeconductor",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "A multi-agent orchestration framework for AI-assisted software engineering workflows.",
   "keywords": [
     "ai",
@@ -49,7 +49,10 @@
     "build:lib": "bun build src/index.ts --target=node --outfile=dist/library.js --packages=external",
     "build:types": "tsc -p tsconfig.lib.json --emitDeclarationOnly",
     "test": "bun test",
+    "test:fast": "bun run scripts/test-fast.ts",
     "typecheck": "tsc --noEmit",
+    "lint": "bun run scripts/lint.ts",
+    "check:coverage": "bun run scripts/check-coverage.ts",
     "check:prompt-changelog": "bun run scripts/check-prompt-changelog.ts",
     "release:patch": "bash release.sh patch",
     "release:minor": "bash release.sh minor",

package/presets/agy/AGENTS.md

@@ -72,6 +72,7 @@ Antigravity CLI loads custom slash commands from `.agents/workflows/*.md`. The f
 | `/cc-review`     | Runs a structured, multi-perspective code review and audit         |
 | `/cc-test-plan`  | Generates a structured test plan for a given scope                 |
 | `/cc-tdd-cycle`  | Runs a Test-Driven Development (TDD) cycle                         |
+| `/cc-spec-mutation` | Spec-locked TDD with SHA-256 freeze and mutation-testing gate   |
 | `/cc-api-contract`| Handles API contract modification and validation                  |
 | `/cc-db-migration`| Coordinates database schema migrations safely                      |
 | `/cc-iterative`  | Advanced iterative workflow — wayfinding, grilling, TDD, council |
@@ -80,7 +81,10 @@ Antigravity CLI loads custom slash commands from `.agents/workflows/*.md`. The f
 | `/cc-prototype`  | Disposable spike in an isolated worktree                         |
 | `/cc-handoff`    | Compact the session to `.codeconductor/` Markdown                |
 | `/cc-clarify`    | Re-explain the last deliverable in Task Card vocabulary          |
+| `/cc-backlog`    | Author or append BACKLOG.md and plan OpenSpec change folders   |
+| `/cc-openspec`   | OpenSpec delivery loop from BACKLOG.md                         |
 | `/cc-pagespeed`  | Performs a web performance and Core Web Vitals audit               |
+| `/cc-security`   | Authorized defensive security workflow (authorization gate)   |
 
 ---
 
@@ -138,7 +142,7 @@ When multiple signals apply, take the highest risk level. Do not average.
 
 **Does not:** Write code. Execute tests. Push to any branch.
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Responsibilities:**
 1. Validate the Task Card before doing anything else.
@@ -186,7 +190,7 @@ High-risk checkpoint: [yes | no — if yes, describe what triggers a stop]
 - bash: `deny`
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Intake process:**
 1. Read the entire request before asking anything.
@@ -231,7 +235,7 @@ High-risk checkpoint: [yes | no — if yes, describe what triggers a stop]
 - bash: `allow` (git log, git diff, git status)
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Repo Map format:**
 ```markdown
@@ -266,7 +270,7 @@ High-risk checkpoint: [yes | no — if yes, describe what triggers a stop]
 - bash: `deny`
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Does not:** Write files. Execute commands. Make routing decisions.
 
@@ -290,7 +294,7 @@ When the orchestrator receives a GoalGraph, it delegates tasks in dependency ord
 - bash: `deny`
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Technical Plan format:**
 ```markdown
@@ -327,7 +331,7 @@ When the orchestrator receives a GoalGraph, it delegates tasks in dependency ord
 - bash: `allow` (build, test, and lint commands only)
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Pre-implementation checklist:**
 1. Create a Git Worktree: `git worktree add ../<branch>-session <branch>`
@@ -368,7 +372,7 @@ When the orchestrator receives a GoalGraph, it delegates tasks in dependency ord
 - bash: `allow` (test commands only)
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Coverage Summary format:**
 ```markdown
@@ -397,7 +401,7 @@ When the orchestrator receives a GoalGraph, it delegates tasks in dependency ord
 - bash: `allow` (git diff, git status, test commands)
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 **Review Axes & Gates:**
 - **Simplicity Gate**: Flag overcomplicated/speculative code. Ask: "Would a senior engineer say this is overbuilt?"
@@ -455,7 +459,7 @@ When the orchestrator receives a GoalGraph, it delegates tasks in dependency ord
 - bash: `deny`
 - network: `deny`
 
-**Model:** `{{MODEL_GEMINI}}`
+**Model:** `{{MODEL}}`
 
 ---
 

package/presets/agy/gates/pre-commit/GATE.md

@@ -1,6 +1,6 @@
-# Pre-commit Gate: Typecheck and Test
+# Pre-commit Gate: Typecheck, Lint, and Test
 
-Este gate instala un hook `pre-commit` que ejecuta `bun run typecheck` y `bun run test` antes de permitir commits en el repositorio. Si cualquiera de estos comandos falla, el commit es bloqueado.
+Este gate instala un hook `pre-commit` que ejecuta `bun run typecheck`, `bun run lint` y `bun run test` antes de permitir commits en el repositorio. Si cualquiera de estos comandos falla, el commit es bloqueado.
 
 ## Cuándo usar
 
@@ -63,6 +63,7 @@ mkdir -p "$GIT_DIR/hooks"
 cat > "$HOOK_PATH" << 'HOOK_EOF'
 #!/bin/bash
 bun run typecheck || exit 1
+bun run lint || exit 1
 bun run test || exit 1
 HOOK_EOF
 
@@ -78,7 +79,7 @@ echo "Pre-commit hook installed successfully."
 - **Resolución dinámica de git dir**: Usa `git rev-parse --git-dir` para localizar el directorio correcto, incluso en worktrees.
 - **Detección de conflictos**: Si Husky o lint-staged ya está en `package.json`, el script avisa y no instala para evitar conflictos.
 - **Protección de hooks existentes**: Si ya existe un `.git/hooks/pre-commit`, el script no lo sobrescribe.
-- **Solo Bun**: El hook ejecuta `bun run typecheck` y `bun run test`. Asegúrate de que estos scripts están definidos en `package.json`.
+- **Solo Bun**: El hook ejecuta `bun run typecheck`, `bun run lint` y `bun run test`. Asegúrate de que estos scripts están definidos en `package.json`.
 
 ## Verificación
 
@@ -121,7 +122,7 @@ Verifica que el hook es ejecutable:
 
     chmod +x .git/hooks/pre-commit
 
-Verifica que `bun run typecheck` y `bun run test` existen en `package.json`:
+Verifica que `bun run typecheck`, `bun run lint` y `bun run test` existen en `package.json`:
 
     cat package.json | grep -A 5 '"scripts"'
 

package/presets/agy/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f \"./.agents/scripts/post-tool.sh\" ]; then bash ./.agents/scripts/post-tool.sh; else bash \"$HOME/.gemini/config/scripts/post-tool.sh\"; fi"
+            "command": "node -e \"const fs=require('fs'),p=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'].find(f=>fs.existsSync(f));if(p)require(require('path').resolve(p));else{if(process.argv.includes('--format=agy')){process.stdout.write(process.argv.includes('post-tool')?'{}\\n':'{\\\"decision\\\":\\\"allow\\\"}\\n');}process.exit(0);}\" post-tool --format=agy"
           }
         ]
       }
@@ -21,7 +21,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "if [ -f \"./.agents/scripts/pre-tool.sh\" ]; then bash ./.agents/scripts/pre-tool.sh; else bash \"$HOME/.gemini/config/scripts/pre-tool.sh\"; fi"
+            "command": "node -e \"const fs=require('fs'),p=['scripts/invoke-hook.cjs','.agents/scripts/invoke-hook.cjs'].find(f=>fs.existsSync(f));if(p)require(require('path').resolve(p));else{if(process.argv.includes('--format=agy')){process.stdout.write(process.argv.includes('post-tool')?'{}\\n':'{\\\"decision\\\":\\\"allow\\\"}\\n');}process.exit(0);}\" pre-tool --format=agy"
           }
         ]
       }

package/presets/agy/scripts/invoke-hook.cjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+'use strict';
+
+const { spawnSync } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const { join, resolve } = require('node:path');
+
+const VALID_EVENTS = ['pre-tool', 'post-tool', 'session-start'];
+const SPAWN_TIMEOUT = 10000;
+
+const rawArgs = process.argv.slice(1);
+const args = rawArgs.filter((arg) => {
+  if (VALID_EVENTS.includes(arg) || arg.startsWith('-')) return true;
+  return false;
+});
+
+const event = args.find((a) => VALID_EVENTS.includes(a)) || 'pre-tool';
+const extra = args.filter((a) => a !== event);
+const isAgy = process.argv.some((a) => a === '--format=agy') || extra.includes('--format=agy');
+
+function findProjectRoot() {
+  const candidates = [
+    process.env.PROJECT_ROOT,
+    process.env.WORKSPACE_DIR,
+    resolve(__dirname, '..', '..'),
+    process.cwd(),
+  ].filter(Boolean);
+
+  for (const dir of candidates) {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, '.agents')) ||
+      existsSync(join(dir, '.claude'))
+    ) {
+      return dir;
+    }
+  }
+  return resolve(__dirname, '..', '..');
+}
+
+const projectRoot = findProjectRoot();
+
+function canRun(bin) {
+  try {
+    const result = spawnSync(bin, ['--version'], {
+      encoding: 'utf8',
+      windowsHide: true,
+      stdio: 'ignore',
+      timeout: SPAWN_TIMEOUT,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function tryRun(bin, runArgs) {
+  try {
+    const result = spawnSync(bin, runArgs, {
+      cwd: projectRoot,
+      stdio: 'inherit',
+      windowsHide: true,
+      env: process.env,
+      timeout: SPAWN_TIMEOUT,
+    });
+    if (result.error) {
+      return false;
+    }
+    if (result.status === 0) {
+      process.exit(0);
+    }
+    if (!isAgy && result.status === 2) {
+      process.exit(2);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+function fallback() {
+  if (isAgy) {
+    if (event === 'post-tool' || event === 'session-start') {
+      process.stdout.write('{}\n');
+    } else {
+      process.stdout.write('{"decision":"allow"}\n');
+    }
+  }
+  process.exit(0);
+}
+
+try {
+  const srcMain = join(projectRoot, 'src', 'cli', 'main.ts');
+  if (existsSync(srcMain) && canRun('bun')) {
+    tryRun('bun', ['run', srcMain, 'hook', event, ...extra]);
+  }
+
+  const packaged = join(projectRoot, 'node_modules', 'cc-codeconductor', 'dist', 'index.js');
+  if (existsSync(packaged)) {
+    tryRun(process.execPath, [packaged, 'hook', event, ...extra]);
+  }
+
+  const localDist = join(projectRoot, 'dist', 'index.js');
+  if (existsSync(localDist)) {
+    tryRun(process.execPath, [localDist, 'hook', event, ...extra]);
+  }
+
+  tryRun('npx', ['--no-install', 'cc-codeconductor', 'hook', event, ...extra]);
+} catch {
+  // Ignore errors in runner attempts
+}
+
+fallback();
+

package/presets/agy/skills/backlog/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: backlog
+description: >
+  Guides agents through authoring BACKLOG.md and OpenSpec change folders.
+  Use when running /cc-backlog or /cc:backlog, creating or appending backlog
+  items, or preparing work for /cc-openspec. Delivery is skill openspec.
+---
+
+# Backlog authoring
+
+## Overview
+
+Create or append `BACKLOG.md`, then `openspec validate` / `plan`. Do not deliver
+the item here.
+
+## When to Use
+
+- `/cc-backlog`, first backlog in a repo, or appending `### BC-xxx` items
+
+**NOT** for executing an item (`openspec`) or for scorecards (`evaluation`).
+
+## Process
+
+1. If `graphify-out/graph.json` exists, `graphify query "<objectives>"`. Then
+   `repo-explorer`. Scope names real files.
+2. Invoke `task-coach`. One grilling question per assumption. Reject vague
+   acceptance ("improve UX"). At most 3 `[NEEDS CLARIFICATION]`.
+3. `ccep evaluate --command backlog`. If `stop`, wait for the human.
+4. Create `BACKLOG.md` from `presets/templates/BACKLOG.md` or append under
+   `## Items`. Do not rewrite `## Global` or `## Archive`.
+5. Next ID = max numeric suffix in Items + Archive + 1, zero-padded (`BC-013`).
+6. `bun run dev openspec validate` (or `npx cc-codeconductor`). Fix until valid.
+7. `openspec plan BC-xxx` for each **new** item this run. Then tell the user
+   to run `/cc-openspec`.
+
+Required sections: `## Global`, `## Items`, `## Archive`. Each item:
+`### BC-001 | Title` with Priority, Status (`READY` after grilling), Type,
+Depends on, Description, Scope, Out of scope, Acceptance.
+
+Local artifacts (`BACKLOG.md`, `openspec/`, `.codeconductor/openspec-state.json`)
+are gitignored in consumer projects. Do not `git add` them.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| This fix is small; skip the Task Card | Every item needs measurable acceptance. |
+| I'll validate later | Do not plan until `openspec validate` passes. |
+| Archive can be rewritten | Archive is history. Never rewrite or re-execute. |
+
+## Red Flags
+
+- Acceptance that cannot fail a check
+- Editing `openspec-state.json` by hand
+- Planning an invalid backlog
+
+## Verification
+
+- [ ] `openspec validate` exit 0
+- [ ] New items have `FR`/`SC`-ready measurable acceptance
+- [ ] User pointed at `/cc-openspec` for delivery

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

@@ -0,0 +1,165 @@
+---
+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`)
+
+---
+
+## 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/agy/skills/cc-tdd-cycle/SKILL.md

@@ -41,6 +41,9 @@ runner) — do not hand-edit JSON under `.codeconductor/evidence/`.
 
 Do not advance phases until that evidence exists.
 
+When delivering a BACKLOG item, `openspec done` on the test or implement card
+uses the same runner evidence.
+
 ---
 
 ## Phase 1 — RED (Tester role)

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

@@ -1,6 +1,65 @@
 ---
 name: evaluation
-description: Scorecard and outcome tracking for CodeConductor workflows.
+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.
 ---
 
-Record outcomes via `scorecard record`. Use `scorecard models` before OpenSpec phases.
+# 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/agy/skills/openspec/SKILL.md

@@ -1,32 +1,66 @@
 ---
 name: openspec
 description:
-  OpenSpec backlog format, state machine, and delivery workflow for CodeConductor.
-  Use when running /cc-openspec or editing BACKLOG.md.
+  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 / BACKLOG Skill
+# OpenSpec delivery
 
-## BACKLOG.md contract
+## Overview
 
-`BACKLOG.md` at repo root is the operational queue. Required sections:
+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.
 
-- `## Global` — Product, Strategy, Policy, Review required, TDD required
-- `## Items` — active backlog entries
-- `## Archive` — completed entries (do not re-execute)
+## When to Use
 
-Each item: `### BC-001 | Short title` with Priority (P0–P3), Status, Type, Depends on, Description, Scope, Out of scope, Acceptance (measurable checklist).
+- `/cc-openspec` or `openspec next` / `plan` / `done` / `archive`
+- An item is `READY` or later and must move through the state machine
 
-## Status machine
+**NOT** for creating `BACKLOG.md` (use skill `backlog`) or for stack-specific
+coding rules.
 
-`TODO` → `READY` → `PLANNED` → `IN_PROGRESS` → `REVIEW` → `DONE` → Archive
+## Process
 
-## CLI
+Local CLI is `bun run dev`. Published package is `npx cc-codeconductor`.
 
-`openspec validate | scan | plan | status | next`
+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.
 
-## Agent phases
+Status machine: `TODO` → `READY` → `PLANNED` → `IN_PROGRESS` → `REVIEW` → `DONE`
+→ Archive. `BLOCKED` returns to `READY`. Reviewer rejection: `REVIEW` →
+`IN_PROGRESS`.
 
-discover → repo-explorer, design → architect, test → tester, implement → implementer, review → reviewer.
+## Common Rationalizations
 
-TDD required: test before implement.
+| 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`