cc-codeconductor 1.4.1 → 1.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Stop prompting. Start orchestrating.**
 
-[![Socket Badge](https://badge.socket.dev/npm/package/cc-codeconductor/1.3.0)](https://badge.socket.dev/npm/package/cc-codeconductor/1.3.0)
+[![Socket Badge](https://badge.socket.dev/npm/package/cc-codeconductor/1.5.0)](https://badge.socket.dev/npm/package/cc-codeconductor/1.5.0)
 
 CodeConductor is an open-source framework for building structured, reproducible
 AI-assisted software engineering workflows.
@@ -15,19 +15,22 @@ contracts, task cards, and risk-based routing.
 >
 > ## Current Scope
 >
-> Published package is **1.3.x (current stable: 1.3.0)**. Limitations matrix:
+> Published package is **1.5.0** (current stable line: **1.5.x**). Limitations
+> matrix:
 > [docs/current-status.md](docs/current-status.md). This repository:
 > `bun run dev …` (not `npx`) while iterating.
 >
-> Shipped in the 1.3.x stable line:
+> Shipped in the 1.5.x stable line:
 >
+> - `npx cc-codeconductor setup --target <target> --yes` — onboarding flow
 > - `npx cc-codeconductor init` — detects project stack, writes
 >   `.codeconductor/config.yml`, copies `council.yml` and `policy.yml` into
 >   `.codeconductor/presets/`
 > - `npx cc-codeconductor install council --target <opencode|claude|codex|agy|all>`
 > - `npx cc-codeconductor install preset --target <opencode|claude|codex|gemini|cursor|agy|all>`
 > - `npx cc-codeconductor install lsp --target <…>`
-> - `npx cc-codeconductor detect` / `doctor` / `update`
+> - `npx cc-codeconductor detect` / `status` / `version` / `doctor` / `update` /
+>   `migrate`
 > - `npx cc-codeconductor seo audit` / `seo llms` (SSRF-guarded fetch)
 > - `npx cc-codeconductor help` / `cc-help` (distinct contracts — see breaking
 >   changes below)
@@ -42,7 +45,7 @@ contracts, task cards, and risk-based routing.
 > - `npx cc-codeconductor scorecard …`
 > - `npx cc-codeconductor goal` / `ingest` / `product` / `orchestrate` /
 >   `impact` / `verify` — Product OS (see
->   [docs/v1.3.0-release-notes.md](docs/v1.3.0-release-notes.md))
+>   [docs/product-os.md](docs/product-os.md))
 > - Slash commands after `install preset` — 21 CCEP workflows plus `/cc-ask`;
 >   prefer `/cc-iterative`, `/cc-triage`, `/cc-handoff` for wayfinding;
 >   `/cc-backlog` authors `BACKLOG.md`; `/cc-openspec` and `/cc-tdd-cycle`
@@ -75,6 +78,29 @@ contracts, task cards, and risk-based routing.
 > maintainer-only stubs (`cc-self-review`, `cc-update-preset-models`) are
 > skipped so this repo can dogfood `install preset`.
 
+## Recommended CLI flow
+
+Start with the high-level onboarding command, then use the maintenance commands
+to inspect and reconcile the installed harness:
+
+```bash
+npx cc-codeconductor setup --target claude --yes
+npx cc-codeconductor status
+npx cc-codeconductor version
+npx cc-codeconductor doctor
+npx cc-codeconductor update --check
+npx cc-codeconductor migrate --dry-run
+```
+
+- `setup` detects the project, initializes the harness, installs the selected
+  target, and runs `doctor`.
+- `status` is the lightweight installation dashboard; `version` reports the CLI
+  and project harness versions.
+- `doctor` diagnoses configuration and managed files. `update` safely reconciles
+  installed harness files, while `migrate` applies compatibility repairs.
+- `init` and `install` remain available as lower-level primitives for automation
+  and targeted installations.
+
 ---
 
 ## Why CodeConductor?
@@ -96,9 +122,9 @@ This is not a prompt collection. It is a workflow framework.
 
 ---
 
-## What's new in v1.3.0
+## Historical: v1.3.0
 
-v1.3.0 is the current **stable** release in the 1.3.x line. It retains the
+v1.3.0 was a **stable** release in the 1.3.x line. It retained the
 v1.0.0 workflow contract baseline and adds cross-target preset fixes, centralized
 skill versioning, runner parity improvements, and the contextual web design
 engineering skill. Re-install presets after upgrading.
@@ -134,12 +160,21 @@ what they do rather than which subsystem they touch:
 | Entry         | `/cc-ask`, `/cc-triage`, `/cc-explore`                                                                          | Recommend a next command and stop — no writes.  |
 | Delivery      | `/cc-feature`, `/cc-fix`, `/cc-refactor`, `/cc-tdd-cycle`, `/cc-api-contract`, `/cc-db-migration`, `/cc-spec-mutation` | Implement, test-before-implement where both apply. |
 | Verification  | `/cc-review`, `/cc-council`, `/cc-scorecard`, `/cc-test-plan`, `/cc-security`                                    | Gate a diff or a decision before merge.         |
-| Management    | `/cc-backlog`, `/cc-openspec`, `/cc-handoff`, `/cc-clarify`, `/cc-prototype`, `/cc-pagespeed`, `/cc-iterative`   | Author BACKLOG.md, deliver it, or one-off ops.  |
+| Management    | `/cc-backlog`, `/cc-openspec`, `/cc-handoff`, `/cc-clarify`, `/cc-prototype`, `/cc-pagespeed`, `/cc-iterative`, `/cc-odd`   | Author BACKLOG.md, deliver it, or one-off ops.  |
 
 Prefer `/cc-iterative`, `/cc-triage`, and `/cc-handoff` for wayfinding.
 `/cc-ask` recommends a command from a natural-language problem; it does not
 start the workflow.
 
+### ODD adoption and escalation
+
+ODD is opt-in until paired delivery evidence shows non-inferior acceptance,
+tests, and findings with lower context than OpenSpec. Run
+`bun run dev scorecard suite-run --suite odd-adoption` to keep that decision
+reproducible. The [ODD adoption guide](docs/odd-adoption.md) explains route
+selection, ledger-based resumption, and when to return to OpenSpec, TDD, or
+Council.
+
 ### OpenSpec and TDD
 
 OpenSpec is the delivery loop for `BACKLOG.md`:
@@ -152,6 +187,18 @@ Agent phases: validate-backlog → discover → design → **test** → implemen
 review. Test-before-implement is required whenever both phases apply.
 `/cc-tdd-cycle` enforces Red → Green → Refactor (`tester` then `implementer`).
 
+### Receipt-Driven Development
+
+RDD binds local verification evidence to the exact code, tests, contracts,
+lockfiles, and configuration it observed. Use `bun run dev rdd capture --task
+<id>`, `bun run dev rdd verify --receipt <id>`, and `bun run dev rdd status` to
+inspect that evidence. A changed candidate invalidates its receipt and requires
+the affected verification to run again. RDD complements TDD and Mutation
+Testing: it checks evidence freshness rather than behavioral coverage.
+Run `bun run dev rdd install-hooks` in a Git repository to install preserving
+pre-commit and pre-push checks; the hook runs `rdd git-check` against the latest
+receipt.
+
 ### Review agents
 
 15 Conductor Agents ship in `presets/<target>/agents/`. Review path:
@@ -277,14 +324,14 @@ Task Card → Risk Classification → Routing Policy → Conductor Agent → Del
 
 ## Supply chain
 
-Published **1.3.0** declares two production dependencies (`package.json`
+Published **1.5.0** declares two production dependencies (`package.json`
 `dependencies`; same on
 [npm](https://www.npmjs.com/package/cc-codeconductor)). Neither has further
 npm transitive dependencies.
 
 ```mermaid
 graph LR
-  cc["cc-codeconductor@1.3.0"]
+  cc["cc-codeconductor@1.5.0"]
   zod["zod@^3.23.8"]
   yaml["yaml@^2.4.5"]
   cc --> zod
@@ -630,7 +677,9 @@ npx cc-codeconductor openspec next
 npx cc-codeconductor openspec start BC-001-discover
 npx cc-codeconductor openspec done BC-001-discover
 npx cc-codeconductor openspec block BC-001-implement --reason "waiting on design"
+npx cc-codeconductor openspec unblock BC-001-implement
 npx cc-codeconductor openspec archive BC-001
+npx cc-codeconductor odd read delivery-001
 ```
 
 Subcommands: `validate` / `scan` / `plan` / `analyze` / `status` / `next` /
@@ -798,10 +847,9 @@ codeconductor/
 
 ## Roadmap
 
-Published package: **1.3.x (current stable: 1.3.0)**. Remaining gaps (sandbox, policy compiler, full
+Published package: **1.5.x (current stable: 1.5.0)**. Remaining gaps (sandbox, policy compiler, full
 stack-specific asset pruning): [docs/current-status.md](docs/current-status.md).
-Release details:
-[docs/v1.3.0-release-notes.md](docs/v1.3.0-release-notes.md).
+Release history: [CHANGELOG.md](CHANGELOG.md).
 
 See [ROADMAP.md](ROADMAP.md) for historical notes.
 

package/dist/core/verification/rdd-receipt.d.ts

@@ -0,0 +1,39 @@
+export type RddPhase = 'red' | 'green' | 'refactor' | 'verification' | 'mutation' | 'review';
+export interface RddReceiptPath {
+    readonly path: string;
+    readonly hash: string;
+}
+export interface RddReceipt {
+    readonly version: 1;
+    readonly taskId: string;
+    readonly phase: RddPhase;
+    readonly paths: readonly RddReceiptPath[];
+    readonly coverage: 'paths' | 'project';
+    readonly manifestHash: string;
+    readonly command?: string;
+    readonly outcome: 'passed' | 'failed';
+    readonly capturedAt: string;
+}
+export interface ReceiptVerification {
+    readonly valid: boolean;
+    readonly expectedHash: string;
+    readonly actualHash: string;
+    readonly changedPaths: readonly string[];
+}
+export declare function isRddReceipt(value: unknown): value is RddReceipt;
+export declare function captureReceipt(projectRoot: string, input: {
+    readonly taskId: string;
+    readonly phase: RddPhase;
+    readonly paths: readonly string[];
+    readonly command?: string;
+    readonly outcome: 'passed' | 'failed';
+    /** Include additions and deletions across the complete project candidate. */
+    readonly coverage?: 'paths' | 'project';
+}): Promise<RddReceipt>;
+/**
+ * Collect the versioned-input candidate for a local verification run. Runtime
+ * state and generated output are deliberately excluded because recording a
+ * receipt itself must not invalidate the candidate it describes.
+ */
+export declare function collectReceiptPaths(projectRoot: string): Promise<string[]>;
+export declare function verifyReceipt(projectRoot: string, receipt: RddReceipt): Promise<ReceiptVerification>;

package/dist/core/verification/verification-runner.d.ts

@@ -1,6 +1,7 @@
 import type { GoalGraphInput } from '../../validation/schemas';
 import type { TddSuiteEvidence } from '../../domain/loop/loop-state';
 import { type Result } from '../../utils/result';
+import { type RddReceipt } from './rdd-receipt';
 export interface VerificationCheck {
     name: string;
     passed: boolean;
@@ -42,6 +43,8 @@ export declare const TDD_CAPTURED_BY = "verification-runner";
 export interface CaptureTddSuiteOptions extends RunVerificationOptions {
     /** Allowlisted test command (`bun test`, `npm test`, …). */
     readonly command: string;
+    /** The TDD transition this runner invocation is expected to prove. */
+    readonly phase?: 'red' | 'green' | 'refactor';
 }
 /**
  * Run a test suite and store TDD evidence. Only this function writes records
@@ -51,14 +54,17 @@ export declare function captureTddSuiteEvidence(projectRoot: string, taskId: str
     evidenceId: string;
     suiteFailed: boolean;
     suitePassed: boolean;
+    receipt: RddReceipt;
 }, Error>>;
 /**
  * Load TDD suite evidence written by `captureTddSuiteEvidence`. Hand-edited
  * files (wrong source/type/`capturedBy`) are rejected.
  */
-export declare function loadTddSuiteEvidence(projectRoot: string, taskId: string, evidenceId: string): Promise<Result<TddSuiteEvidence, Error>>;
+export declare function loadTddSuiteEvidence(projectRoot: string, taskId: string, evidenceId: string): Promise<Result<TddSuiteEvidence & {
+    receipt: RddReceipt;
+}, Error>>;
 /**
  * True when the verification runner stored TDD evidence for this task.
  * Handmade JSON (wrong source/type/capturedBy) does not count.
  */
-export declare function hasTddRunnerEvidence(projectRoot: string, taskId: string): Promise<boolean>;
+export declare function hasTddRunnerEvidence(projectRoot: string, taskId: string, expectedPhase?: 'red' | 'green'): Promise<boolean>;

package/dist/index.d.ts

@@ -9,6 +9,8 @@ export type { OrchestratorNextResult } from './core/orchestrator/runtime-orchest
 export { LoopEngine, runLoop, runLoopForProject, shouldRunAgentLoop, formatFeedback, advanceTddPhase, } from './core/loop/loop-engine';
 export type { LoopConfig, LoopResult, EscalationReport, GuardrailHit, GenerateFn, CompileCheckFn, } from './core/loop/loop-engine';
 export { runVerification, gateTaskCompletion, validateEvidenceIds, captureTddSuiteEvidence, loadTddSuiteEvidence, hasTddRunnerEvidence, } from './core/verification/verification-runner';
+export { captureReceipt, collectReceiptPaths, isRddReceipt, verifyReceipt, } from './core/verification/rdd-receipt';
+export type { RddPhase, RddReceipt, RddReceiptPath, ReceiptVerification } from './core/verification/rdd-receipt';
 export type { RunVerificationOptions, VerificationCheck, CaptureTddSuiteOptions, } from './core/verification/verification-runner';
 export * from './validation/schemas';
 export { createInitialState, loopStateMachine, createInitialTddState, tddCycleStateMachine, } from './domain/loop/loop-state';