cc-codeconductor 0.5.0 → 1.1.0

package/README.md

@@ -2,6 +2,8 @@
 
 **Stop prompting. Start orchestrating.**
 
+[![Socket Badge](https://badge.socket.dev/npm/package/cc-codeconductor/1.0.0)](https://badge.socket.dev/npm/package/cc-codeconductor/1.0.0)
+
 CodeConductor is an open-source framework for building structured, reproducible
 AI-assisted software engineering workflows.
 
@@ -13,93 +15,65 @@ contracts, task cards, and risk-based routing.
 >
 > ## Current Scope
 >
-> What works today:
+> Published package is **1.0.0**. Limitations matrix:
+> [docs/current-status.md](docs/current-status.md). This repository:
+> `bun run dev …` (not `npx`) while iterating.
+>
+> Shipped in 1.0.0:
 >
 > - `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>` —
->   generates and writes preset files; supports `--global` to install to
->   `~/.opencode/`, `~/.claude/`, `~/.codex/`, `~/.agents/`
-> - `npx cc-codeconductor install lsp --target <opencode|claude|codex|gemini|cursor|agy|all>` —
->   installs LSP servers and configures AI coding tools; auto-detects project
->   languages or use `--lang` to override
-> - `npx cc-codeconductor detect` — detects project stack and recommends presets
-> - `npx cc-codeconductor doctor` — validates configuration and installed runner
->   directories
-> - `npx cc-codeconductor update` — re-applies the council preset for the configured
->   target
-> - `npx cc-codeconductor seo audit --url <url>` — runs a comprehensive SEO audit
->   on a single page (meta tags, schema.org, GEO readiness) and generates a
->   markdown report
-> - `npx cc-codeconductor seo audit --sitemap <url>` — batch audits all URLs from
->   a sitemap.xml with rate limiting and SSRF prevention
-> - `npx cc-codeconductor seo llms --sitemap <url>` — generates a `llms.txt` file
->   for AI-search readiness from sitemap content
-> - `npx cc-codeconductor help` (alias: `cc-help`) — shows preset inventory
->   (skills, subagents, commands) for the active or specified target
-> - `npx cc-codeconductor debt-harvest` (alias: `harvest`) — scans source files
->   for `// defer` comments and writes `.codeconductor/debt-ledger.md`
-> - `npx cc-codeconductor goal "<objective>"` (alias: `cc-goal`) — decomposes an
->   objective into a dependency-ordered task graph, writes
->   `.codeconductor/current-goal.yml`
-> - `/cc-pagespeed --url <url>` — audits web performance using the PageSpeed
->   Insights API; applies the 80/20 principle to produce a prioritized report of
->   Core Web Vitals (LCP, TBT, CLS, FCP, TTFB) with framework-specific fixes;
->   requires `PAGESPEED_API_KEY` env var for full CrUX field data (optional but
->   recommended)
-> - `npx cc-codeconductor install preset --target <opencode|claude|codex|agy|all>` —
->   installs the full preset (agents, prompts, skills, commands, settings) for the
->   chosen runner; use `--locale=es` to inject Spanish-aware instructions into
->   agent files, or rely on the locale saved during `init`
-> - **Stack-specific presets (v0.4.0)**: `ts-next-drizzle`, `spring-kotlin-jpa`,
->   `laravel-tall`, `python-data-api` — bundle `architect` + `implementer`
->   contracts tuned to a single framework so `install preset` drops in the right
->   defaults for that stack.
-> - **9 specialized skills (v0.4.0)**: `drizzle-schema-architect`,
->   `tailwind-responsive-auditor`, `seo-analytics-injector`,
->   `jpa-nplusone-detector`, `spring-auth-auditor`, `livewire-alpine-bridge`,
->   `fastapi-pydantic-strict`, `tdd-mutation-tester`, `auth-token-inspector` —
->   loaded automatically by the matching preset.
-> - **Workflow Loop Core (v0.4.0)** — 8-phase pipeline
->   (`intake → structure → design → test → implement → validate → council →
->   compact`) with operational guardrails (wall-clock timeout, max files
->   modified, max lines changed) and human-in-the-loop STOP gates after Design
->   and Council Verdict.
-> - **Council consensus v0.4.0** — agent confidence thresholds
->   (`< 0.6` per-agent or `< 0.7` average escalates) and a `complianceVeto`
->   channel that overrides majority the same way `securityVeto` does.
-> - **Goal orchestration (v0.4.0)** — `goal` planner writes
->   `.codeconductor/current-goal.yml`; the orchestrator delegates tasks in
->   dependency order and blocks dependents when a prerequisite is `blocked`.
-> - **Memory compression + escalation emitter (v0.4.0)** — Phase 5 memory index
->   + token budget hook keeps inter-agent context below the configured budget;
->   the loop controller emits escalation reports when guardrails fire.
-> - **Parallel subagents (v0.4.0)** — risk-based routing policy v0.4.0 enables
->   parallel execution for eligible agent sequences (architect + implementer
->   pattern, council verdict fan-out).
-> - Manual presets for OpenCode, Claude Code, and Codex
-> - Versioned Agent Contracts
-> - Routing Policy documentation
-> - Task Card, Scorecard, and workflow templates
-> - Spring Boot/Kotlin and Python/Django workflow guidance
+> - `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 seo audit` / `seo llms` (SSRF-guarded fetch)
+> - `npx cc-codeconductor help` / `cc-help` (distinct contracts — see breaking
+>   changes below)
+> - `npx cc-codeconductor ask "<problem>"` — recommends a `/cc:` slash command
+> - `npx cc-codeconductor debt-harvest` (alias: `harvest`)
+> - `npx cc-codeconductor ccep …` — CCEP is the canonical consumer workflow loop
+>   (`parse` / `profile` / `resolve` / `compile` / `validate` / `evaluate` /
+>   `consensus` / `taskcard`)
+> - `npx cc-codeconductor openspec …` — OpenSpec delivery loop and backlog tool
+>   (`validate` / `scan` / `plan` / `status` / `next` / `start` / `done` /
+>   `block` / `archive`)
+> - `npx cc-codeconductor scorecard …`
+> - `npx cc-codeconductor goal` / `ingest` / `product` / `orchestrate` /
+>   `impact` / `verify` — Product OS (see
+>   [docs/v1.0.0-release-notes.md](docs/v1.0.0-release-notes.md))
+> - Slash commands after `install preset` — 20 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`
+>   for delivery and TDD
+> - `/cc-pagespeed --url <url>` — PageSpeed Insights / Core Web Vitals after
+>   `install preset`; `PAGESPEED_API_KEY` is optional but recommended for CrUX
+>   field data (see [docs/pagespeed-usage.md](docs/pagespeed-usage.md))
+> - `/cc-security` / `/cc:security` — authorized defensive security workflow
+>   with domain `security-*` skills and an authorization gate
+> - Stack-specific skill selection (`ts-next-drizzle`, `spring-kotlin-jpa`,
+>   `laravel-tall`, `python-data-api`)
+> - Council consensus: quorum, required confidence, `criticalFindingsPolicy`,
+>   plus `securityVeto` / `complianceVeto`
+> - 15 Conductor Agents, including `reviewer`, `security-reviewer`, and
+>   `complexity-auditor`
 >
-> See [docs/v0.4.0-release-notes.md](docs/v0.4.0-release-notes.md) for the
-> full v0.4.0 feature breakdown.
+> Experimental (library only, not a CLI runtime):
 >
-> What does not exist yet:
+> - `runWorkflowPipeline()` — 8-phase loop in
+>   `src/core/pipeline/workflow-loop.ts`
 >
-> - Runtime sandbox enforcement
-> - Policy compiler
-> - Automated agent evaluation
-> - Safe Merger
+> What does not exist yet:
 >
-> Security note:
+> - Runtime sandbox / OS-level isolation
+> - Policy compiler / uniform target enforcement
+> - Full stack-specific asset pruning
 >
-> CodeConductor currently provides declarative policies and documented
-> guardrails. It does not yet enforce OS-level isolation, shell sandboxing, or
-> runtime permission boundaries by itself. Treat all agent execution as
-> dependent on the capabilities and limitations of the target tool.
+> Security note: policies are declarative. Agent execution depends on the target
+> runner. `install preset --target cursor` overwrites runner command dirs;
+> maintainer-only stubs (`cc-self-review`, `cc-update-preset-models`) are
+> skipped so this repo can dogfood `install preset`.
 
 ---
 
@@ -122,6 +96,107 @@ This is not a prompt collection. It is a workflow framework.
 
 ---
 
+## What's new in v1.0.0
+
+v1.0.0 is a **major** bump from v0.5.0 because the workflow contracts changed,
+not only because features were added. Re-install presets after upgrading.
+
+### Breaking changes vs v0.5.0
+
+- **`help` vs `cc-help`.** `help` prints the CLI command list. Inventory of
+  skills, subagents, and commands is `cc-help --target`. `help --target` no
+  longer lists that inventory.
+- **Canonical TaskCard.** Delivery intake is `ccep taskcard`. OpenSpec cards
+  remain a phase view (`phase`, `backlogId`, `prompt`, `agent`) and are not
+  collapsed into Canonical.
+- **Council consensus.** Gate with `ccep consensus --input @verdicts.json` (exit
+  `0`/`1`/`2` = APPROVED / REJECTED / ESCALATED). Majority requires quorum,
+  explicit `confidence`, and `criticalFindingsPolicy` (default: escalate). There
+  is no top-level `cc council` command.
+- **OpenSpec state machine.** `start` / `done` / `block` / `archive` write
+  `BACKLOG.md` and `openspec-state.json` atomically. Illegal transitions fail
+  closed.
+- **Schemas.** `ExecutionContext.ast.source` includes `product-graph`.
+  `ReviewerOutput` finding `axis` is extended with Staff Engineer axes.
+- **CCEP bootstrap.** Installed slash commands run `ccep parse` → `resolve` →
+  `profile` → `evaluate` before delegating to agents. Agent JSON must validate
+  against Zod; unknown output schemas fail closed.
+
+### Slash commands
+
+After `install preset`, 18 CCEP workflows plus `/cc-ask`:
+
+| Group          | Commands                                                                                                                     |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Delivery       | `/cc-feature`, `/cc-fix`, `/cc-refactor`, `/cc-api-contract`, `/cc-db-migration`                                             |
+| Quality        | `/cc-tdd-cycle`, `/cc-test-plan`, `/cc-review`, `/cc-council`, `/cc-scorecard`                                               |
+| OpenSpec / ops | `/cc-openspec`, `/cc-iterative`, `/cc-triage`, `/cc-explore`, `/cc-prototype`, `/cc-handoff`, `/cc-clarify`, `/cc-pagespeed` |
+| Entry          | `/cc-ask` — CLI `ask` recommends a slash command; it does not start the workflow                                             |
+
+Prefer `/cc-iterative`, `/cc-triage`, and `/cc-handoff` for wayfinding.
+
+### OpenSpec and TDD
+
+OpenSpec is the delivery loop for `BACKLOG.md`:
+
+```text
+validate → scan → plan → status → next → start → done | block → archive
+```
+
+Agent phases: validate-backlog → discover → design → **test** → implement →
+review. Test-before-implement is required whenever both phases apply.
+`/cc-tdd-cycle` enforces Red → Green → Refactor (`tester` then `implementer`).
+
+### Review agents
+
+15 Conductor Agents ship in `presets/<target>/agents/`. Review path:
+
+- `reviewer` — Review Report with CRITICAL / WARNING / SUGGESTION; CRITICAL
+  blocks merge
+- `security-reviewer` — dedicated security analysis; `securityVeto` overrides
+  majority consensus
+- `complexity-auditor` — bloat and non-native abstractions; runs before
+  `reviewer` on refactor, API change, and database migration routes
+
+New v1.0.0 agents: `business-agent`, `continuous-architect`, `impact-analyst`.
+
+### Deterministic TypeScript validation (CCEP)
+
+CCEP is CLI + Zod, not extra prompts. Source: `src/core/ccep/` and
+`src/validation/schemas.ts`.
+
+```text
+parseCommand → resolveContext → resolveWorkflowPhase → compilePrompt → validateAgentOutputBySchema
+```
+
+```bash
+npx cc-codeconductor ccep parse --command review "PR #42" --output json
+npx cc-codeconductor ccep profile tdd-cycle --output json
+npx cc-codeconductor ccep validate --command feature --phase implement --role implementer --output json \
+  '{"status":"success","confidence":0.9,"warnings":[],"artifacts":[],"next_actions":[],"filesChanged":[],"tests":{"runner":"bun test","result":"passed"}}'
+npx cc-codeconductor ccep consensus --input @verdicts.json
+npx cc-codeconductor ccep taskcard --command feature --input @card.json
+```
+
+`ccep validate` checks each role's JSON against the named schema
+(`planner-output`, `implementer-output`, `review-report`, `technical-plan`,
+`council-verdict`, …). See [docs/CCEP.md](docs/CCEP.md).
+
+### Product OS
+
+Also in 1.0.0: `goal` / `ingest` / `product` / `orchestrate` / `impact` /
+`verify`, plus `.codeconductor/product-graph.json` and related artifacts.
+Details: [docs/v1.0.0-release-notes.md](docs/v1.0.0-release-notes.md) and
+[docs/product-os.md](docs/product-os.md).
+
+### Migrate from v0.5.0
+
+```bash
+npx cc-codeconductor install preset --target=<opencode|claude|cursor|codex|gemini|agy> --force
+```
+
+---
+
 ## Core Concepts
 
 | Concept            | Name in CodeConductor |
@@ -154,25 +229,114 @@ Task Card → Risk Classification → Routing Policy → Conductor Agent → Del
 
 ## Current Support
 
-- OpenCode preset
-- Claude Code-compatible preset (see [Claude Environment Options & Best Practices](file:///c:/Users/R2D2/Documents/GitHub/codeconductor/docs/claude-env-options.md))
-- Codex preset
+- OpenCode, Claude, Codex, Gemini, Cursor, and Agy presets
+- Claude Code-compatible preset (see
+  [Claude Environment Options & Best Practices](docs/claude-env-options.md))
 - Spring Boot / Kotlin workflow
 - Python / Django workflow guidance
-- 12 core Conductor Agents
-- Routing Policy v0.4.0
+- **15 Conductor Agents** — including `reviewer`, `security-reviewer`,
+  `complexity-auditor`, `business-agent`, `continuous-architect`, and
+  `impact-analyst`
+- 18 CCEP slash-command workflows plus `/cc-ask` after `install preset`
+- OpenSpec delivery loop (`validate` … `archive`) with test-before-implement
+- Deterministic CCEP validation (Zod schemas per agent role)
 - Task Card template
 - Scorecard template
 - End-to-end example
 - YAML-driven model configuration
-- Provider-agnostic `AgentContract` abstraction with target renderers for Claude, OpenCode, Codex, and Agy
-- Council consensus engine (`councilConsensus()`) for multi-agent governance with majority/unanimous algorithms, security veto, **compliance veto**, and **agent confidence thresholds** (v0.4.0)
-- Phase 5 runtime modules — scoped context injection, TDD history compaction, concise inter-agent messaging, and token budget enforcement in the compile-fix loop
-- **Workflow Loop Core (v0.4.0)** — 8-phase pipeline (`runWorkflowPipeline`) with wall-clock / files-modified / lines-changed guardrails and STOP gates at Design and Council Verdict
-- **Stack-specific presets (v0.4.0)** — `ts-next-drizzle`, `spring-kotlin-jpa`, `laravel-tall`, `python-data-api`
-- **9 specialized skills (v0.4.0)** — drizzle-schema-architect, tailwind-responsive-auditor, seo-analytics-injector, jpa-nplusone-detector, spring-auth-auditor, livewire-alpine-bridge, fastapi-pydantic-strict, tdd-mutation-tester, auth-token-inspector
-- **Goal orchestration (v0.4.0)** — `goal` planner + `goal-state` writer feed the orchestrator's dependency-order delegation loop
-- **Memory compression + escalation emitter (v0.4.0)** — keeps inter-agent context within token budget and surfaces guardrail breaches as escalation reports
+- Provider-agnostic `AgentContract` abstraction with target renderers for
+  Claude, OpenCode, Codex, and Agy
+- Council consensus engine (`councilConsensus()`) for multi-agent governance
+  with majority/unanimous algorithms, quorum, required confidence,
+  `criticalFindingsPolicy`, security veto, and compliance veto
+- Phase 5 runtime modules — scoped context injection, TDD history compaction,
+  concise inter-agent messaging, and token budget enforcement in the compile-fix
+  loop
+- **Workflow Loop Core (experimental)** — 8-phase pipeline
+  (`runWorkflowPipeline`) with wall-clock / files-modified / lines-changed
+  guardrails and STOP gates at Design and Council Verdict (library-only; not a
+  shipped CLI runtime)
+- **Stack-specific presets** — `ts-next-drizzle`, `spring-kotlin-jpa`,
+  `laravel-tall`, `python-data-api`
+- **Specialized skills** — drizzle-schema-architect,
+  tailwind-responsive-auditor, seo-analytics-injector, jpa-nplusone-detector,
+  spring-auth-auditor, livewire-alpine-bridge, fastapi-pydantic-strict,
+  tdd-mutation-tester, auth-token-inspector
+- **Goal orchestration** — `goal` planner + `goal-state` writer feed the
+  orchestrator's dependency-order delegation loop
+- **Memory compression + escalation emitter** — keeps inter-agent context within
+  token budget and surfaces guardrail breaches as escalation reports
+
+---
+
+## Supply chain
+
+Published **1.0.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.0.0"]
+  zod["zod@^3.23.8"]
+  yaml["yaml@^2.4.5"]
+  cc --> zod
+  cc --> yaml
+```
+
+Expected runtime capabilities (user-invoked CLI commands, **not** `npm
+install`):
+
+- **Network** — `seo audit` / `seo llms` (`safeFetch` with SSRF guards);
+  `install lsp` binary downloads (pinned URL + SHA-256)
+- **Process spawn (no shell)** — git (`scorecard`, OpenSpec, loop guards);
+  `verify` / compile-check; `doctor`; `install lsp` (`tar` / `npm` / `pip`)
+
+There are no `preinstall` / `postinstall` lifecycle scripts. Socket may still
+flag network and shell **capability presence** in the published bundle; that is
+expected for this CLI and is not install-time execution.
+
+For live vulnerability scanning, dependency alerts, and runtime behavior
+analysis, see
+[Socket — cc-codeconductor dependencies](https://socket.dev/npm/package/cc-codeconductor/dependencies).
+
+---
+
+## Programmatic API
+
+`cc-codeconductor` ships a library entry in addition to the CLI. The `bin`
+commands still resolve to `dist/index.js`. Application code should import the
+package root:
+
+```ts
+import {
+  LoopEngine,
+  runLoop,
+  runVerification,
+  getNextTask,
+  startTask,
+  completeTask,
+  loopStateMachine,
+  createInitialState,
+} from 'cc-codeconductor';
+```
+
+Exported surface (stable for this minor):
+
+- Orchestrator: `getReadyTasks`, `getNextTask`, `startTask`, `completeTask`,
+  `goalTaskToCanonicalCard`, `buildTaskEnvelope`, `formatGoalStatus`
+- Loop engine (TC3): `LoopEngine`, `runLoop`, `runLoopForProject`,
+  `shouldRunAgentLoop`, `formatFeedback`
+- Verification: `runVerification`, `gateTaskCompletion`, `validateEvidenceIds`
+- Zod contracts: everything from `src/validation/schemas.ts`
+- Domain loop: `createInitialState`, `loopStateMachine` and their types
+
+`infrastructure/` and `*-internal` modules are not part of the public API.
+
+```bash
+bun run build   # CLI → dist/index.js, library → dist/library.js + .d.ts
+```
 
 ---
 
@@ -208,8 +372,8 @@ files. `install` reads from there first.
 >
 > **`--locale` is remembered.** Once you run `init --locale=es`, the value is
 > saved to `.codeconductor/config.yml`. Every subsequent `install preset` will
-> automatically use that locale — no need to repeat the flag. To change it,
-> run `init --locale=en --force` or edit `defaults.locale` in your config.
+> automatically use that locale — no need to repeat the flag. To change it, run
+> `init --locale=en --force` or edit `defaults.locale` in your config.
 
 #### `detect` — detect project stack
 
@@ -252,27 +416,27 @@ Locale resolution order (first match wins):
 
 Files installed per target:
 
-| Target     | Notable files                                                    |
-| ---------- | ---------------------------------------------------------------- |
+| Target     | Notable files                                                   |
+| ---------- | --------------------------------------------------------------- |
 | `claude`   | `.claude/CLAUDE.md`, `.claude/settings.json`, `.claude/agents/` |
-| `opencode` | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/`  |
-| `codex`    | `.codex/AGENTS.md`, `.codex/skills/`, `.codex/prompts/`          |
+| `opencode` | `.opencode/agents/`, `.opencode/commands/`, `.opencode/skills/` |
+| `codex`    | `.codex/AGENTS.md`, `.codex/skills/`, `.codex/prompts/`         |
 
 With `--global`, files are written under `~/` instead of `./`.
 
 #### Stack-specific presets (v0.4.0)
 
 Four stack-specific presets now ship in `presets/` and are registered in
-`src/core/presets/preset-registry.ts`. Each one bundles a tuned
-`architect.md` and `implementer.md` for a single stack, plus the matching
-specialized skills (see below).
+`src/core/presets/preset-registry.ts`. Each one bundles a tuned `architect.md`
+and `implementer.md` for a single stack, plus the matching specialized skills
+(see below).
 
-| Preset              | Stack                                                      | Contracts included        |
-| ------------------- | ---------------------------------------------------------- | ------------------------- |
-| `ts-next-drizzle`   | Next.js / Astro, Tailwind, Drizzle ORM, Bun, Postgres      | `architect`, `implementer`|
-| `spring-kotlin-jpa` | Spring Boot, Kotlin/Java, Gradle, JPA, Hibernate           | `architect`, `implementer`|
-| `laravel-tall`      | Laravel, Blade, Livewire, Alpine.js                        | `architect`, `implementer`|
-| `python-data-api`   | Python, FastAPI, Django, uv                                | `architect`, `implementer`|
+| Preset              | Stack                                                 | Contracts included         |
+| ------------------- | ----------------------------------------------------- | -------------------------- |
+| `ts-next-drizzle`   | Next.js / Astro, Tailwind, Drizzle ORM, Bun, Postgres | `architect`, `implementer` |
+| `spring-kotlin-jpa` | Spring Boot, Kotlin/Java, Gradle, JPA, Hibernate      | `architect`, `implementer` |
+| `laravel-tall`      | Laravel, Blade, Livewire, Alpine.js                   | `architect`, `implementer` |
+| `python-data-api`   | Python, FastAPI, Django, uv                           | `architect`, `implementer` |
 
 ```ts
 // Programmatic access via the registry
@@ -291,8 +455,13 @@ listPresets();
 const next = getPreset('ts-next-drizzle');
 ```
 
-`init` / `detect` identifies the stack from the project and wires the
-matching specialized skills automatically when you run `install preset`.
+`init` / `detect` identifies the stack from the project and wires the matching
+specialized skills onto the **generic** target workflow when you run
+`install preset`. Full stack-specific asset pruning/replacement (swapping the
+entire agent/command tree for a stack pack) is **not implemented yet** — the
+registry and skill wiring are real; treat claims of a full stack install swap as
+aspirational until that lands.
+
 The full set of assets for a stack-specific preset is in
 `presets/<preset-name>/agents/` — copy them manually if you need to apply a
 preset by name.
@@ -325,8 +494,8 @@ npx cc-codeconductor install lsp --target cursor --dry-run  # preview
 npx cc-codeconductor install lsp --target all --force       # overwrite existing configs
 ```
 
-Supported languages: TypeScript, PHP, Python via Pyright, Kotlin.
-Supported targets: opencode, claude, codex, gemini, cursor, agy.
+Supported languages: TypeScript, PHP, Python via Pyright, Kotlin. Supported
+targets: opencode, claude, codex, gemini, cursor, agy.
 
 #### `doctor` — validate configuration
 
@@ -334,7 +503,10 @@ Supported targets: opencode, claude, codex, gemini, cursor, agy.
 npx cc-codeconductor doctor
 ```
 
-Checks config exists and is valid, reports runner directory status, validates that `AGENTS.md` and `CLAUDE.md` do not exceed the 40KB size limit, and checks if updates are available for installed presets, target runner configurations, or skills.
+Checks config exists and is valid, reports runner directory status, validates
+that `AGENTS.md` and `CLAUDE.md` do not exceed the 40KB size limit, and checks
+if updates are available for installed presets, target runner configurations, or
+skills.
 
 #### `update` — smart update preset
 
@@ -345,19 +517,24 @@ npx cc-codeconductor update --dry-run
 npx cc-codeconductor update --global
 ```
 
-Smart updates all currently installed target presets, council configurations, and skills (from `skills-lock.json`), preserving user edits outside managed blocks. Also validates that `AGENTS.md` and `CLAUDE.md` do not exceed the 40KB size limit.
+Smart updates all currently installed target presets, council configurations,
+and skills (from `skills-lock.json`), preserving user edits outside managed
+blocks. Also validates that `AGENTS.md` and `CLAUDE.md` do not exceed the 40KB
+size limit.
 
-#### `help` — show preset inventory
+#### `help` / `cc-help` — distinct help contracts
 
 ```bash
-npx cc-codeconductor help                    # show inventory for active target
-npx cc-codeconductor help --target claude    # show inventory for specific target
-npx cc-codeconductor cc-help                 # alias
-npx cc-codeconductor help --output json      # machine-readable output
+npx cc-codeconductor help                    # general CLI usage
+npx cc-codeconductor --help                  # same general usage text
+npx cc-codeconductor cc-help                 # preset inventory for active target
+npx cc-codeconductor cc-help --target claude # inventory for a specific target
+npx cc-codeconductor cc-help --output json   # machine-readable inventory
 ```
 
-Lists the skills, subagents, commands, and workflows available in the active
-preset. Reads from `presets/<target>/` in the project root.
+`help` prints the CLI command list. `cc-help` lists skills, subagents, commands,
+and workflows for the active preset (or a specified `--target`). Reads inventory
+from `presets/<target>/` in the project root.
 
 #### `debt-harvest` — collect deferred debt items
 
@@ -368,8 +545,8 @@ npx cc-codeconductor harvest                 # alias
 npx cc-codeconductor debt-harvest --output json
 ```
 
-Scans source files for `// defer - [reason]` comments and consolidates them
-into `.codeconductor/debt-ledger.md`, grouped by optional tag
+Scans source files for `// defer - [reason]` comments and consolidates them into
+`.codeconductor/debt-ledger.md`, grouped by optional tag
 (`// defer - reason --tag`). Read-only on source files; only writes the ledger.
 
 Supported extensions: `.ts`, `.tsx`, `.js`, `.jsx`, `.go`, `.rs`, `.java`,
@@ -389,16 +566,75 @@ notification, migration) or falls back to a generic 4-task chain. Writes the
 resulting task graph to `.codeconductor/current-goal.yml` with dependency
 ordering. The orchestrator uses this file to delegate tasks in dependency order.
 
+#### `ask` — recommend a slash command
+
+```bash
+npx cc-codeconductor ask "login fails on Safari"
+npx cc-codeconductor ask "add invoice CRUD" --output json
+```
+
+Recommends a `/cc:` slash command from a natural-language problem. Does **not**
+start the workflow; wait for human confirmation.
+
+#### `ccep` — deterministic workflow contracts
+
+```bash
+npx cc-codeconductor ccep parse --command review "PR #42" --output json
+npx cc-codeconductor ccep profile tdd-cycle --output json
+npx cc-codeconductor ccep resolve --command feature "Add CRUD" --output json
+npx cc-codeconductor ccep compile --command feature --phase intake --role task-coach "Add CRUD" --output json
+npx cc-codeconductor ccep validate --command feature --phase implement --role implementer --output json \
+  --input @implementer-output.json
+npx cc-codeconductor ccep evaluate --command feature --input @planner.json --output json
+npx cc-codeconductor ccep consensus --input @verdicts.json
+npx cc-codeconductor ccep taskcard --command feature --input @card.json
+```
+
+Subcommands: `parse` / `profile` / `resolve` / `compile` / `validate` /
+`evaluate` / `consensus` / `taskcard`. `validate` checks agent JSON against the
+Zod schema for that role. `consensus` exit codes: `0` APPROVED, `1` REJECTED,
+`2` ESCALATED. Full protocol: [docs/CCEP.md](docs/CCEP.md).
+
+#### `openspec` — backlog delivery loop
+
+```bash
+npx cc-codeconductor openspec validate
+npx cc-codeconductor openspec scan
+npx cc-codeconductor openspec plan BC-001
+npx cc-codeconductor openspec status
+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 archive BC-001
+```
+
+Subcommands: `validate` / `scan` / `plan` / `status` / `next` / `start` / `done`
+/ `block` / `archive`. Illegal status transitions fail closed. See
+[docs/SDD.md](docs/SDD.md) and the OpenSpec skill.
+
+#### Product OS — `ingest` / `product` / `orchestrate` / `impact` / `verify`
+
+```bash
+npx cc-codeconductor ingest
+npx cc-codeconductor product graph
+npx cc-codeconductor orchestrate status
+npx cc-codeconductor impact --files src/cli/router.ts
+npx cc-codeconductor verify --task TC-001
+```
+
+Builds and queries the product graph in `.codeconductor/`. Details:
+[docs/product-os.md](docs/product-os.md).
 
 ### Global options
 
-| Flag             | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `--force`        | Overwrite existing files                                 |
-| `--dry-run`      | Preview actions without writing                          |
-| `--global`       | Target home directory instead of project                 |
-| `--output json`  | Machine-readable JSON output                             |
-| `--locale=en`    | Agent instruction language: `en` (default) or `es`      |
+| Flag            | Description                                        |
+| --------------- | -------------------------------------------------- |
+| `--force`       | Overwrite existing files                           |
+| `--dry-run`     | Preview actions without writing                    |
+| `--global`      | Target home directory instead of project           |
+| `--output json` | Machine-readable JSON output                       |
+| `--locale=en`   | Agent instruction language: `en` (default) or `es` |
 
 ### Config directory
 
@@ -437,12 +673,12 @@ src/presets/models/
 
 Agent template files contain placeholders replaced during `install`:
 
-| Placeholder                    | Description                                   |
-| ------------------------------ | --------------------------------------------- |
-| `{{MODEL_CLAUDE}}`             | Model for the Claude provider                 |
-| `{{MODEL_OPENCODE}}`           | Model for the OpenCode provider               |
-| `{{MODEL_CODEX}}`              | Model for the Codex provider                  |
-| `{{LANGUAGE_INSTRUCTIONS}}`    | Locale-aware instruction injected by `locale` |
+| Placeholder                 | Description                                   |
+| --------------------------- | --------------------------------------------- |
+| `{{MODEL_CLAUDE}}`          | Model for the Claude provider                 |
+| `{{MODEL_OPENCODE}}`        | Model for the OpenCode provider               |
+| `{{MODEL_CODEX}}`           | Model for the Codex provider                  |
+| `{{LANGUAGE_INSTRUCTIONS}}` | Locale-aware instruction injected by `locale` |
 
 To customize models, edit the YAML file for your target before running
 `install`. Each file maps agent roles to provider-specific model names.
@@ -453,10 +689,10 @@ Agent markdown files (`CLAUDE.md`, `AGENTS.md`, `README.md`) include a
 `{{LANGUAGE_INSTRUCTIONS}}` placeholder that is replaced at install time based
 on the active locale:
 
-| Locale | Injected instruction |
-| ------ | -------------------- |
-| `en`   | *Prose/docs/code comments: be terse and direct. Prefer concrete nouns over abstract ones. Omit filler phrases. One idea per sentence.* |
-| `es`   | *Spanish prose/docs/reports/Markdown: preserve natural Spanish orthography, including accents, `ñ`, `¿`, `¡`, and normal Unicode. The ASCII-only editing preference does not apply to these artifacts.* |
+| Locale | Injected instruction                                                                                                                                                                                    |
+| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `en`   | _Prose/docs/code comments: be terse and direct. Prefer concrete nouns over abstract ones. Omit filler phrases. One idea per sentence._                                                                  |
+| `es`   | _Spanish prose/docs/reports/Markdown: preserve natural Spanish orthography, including accents, `ñ`, `¿`, `¡`, and normal Unicode. The ASCII-only editing preference does not apply to these artifacts._ |
 
 The locale is **sticky**: set it once with `init --locale=es` and every
 subsequent `install preset` will use it automatically. Override per-run with
@@ -492,8 +728,11 @@ codeconductor/
 │
 ├── src/                    ← CLI source (TypeScript + Bun)
 │   ├── cli/                ← entry point, router, error codes
-│   ├── commands/           ← init, detect, install, doctor, update
+│   ├── commands/           ← init, detect, install, ccep, openspec, …
 │   ├── core/               ← config, detection, filesystem, presets, goal
+│   │   ├── ccep/           ← CCEP parse/profile/validate/evaluate
+│   │   ├── openspec/       ← backlog loop and state machine
+│   │   ├── product/        ← Product OS ingest and console
 │   │   ├── context/        ← scoped context injection (Phase 5)
 │   │   ├── compaction/     ← TDD history compaction hook (Phase 5)
 │   │   ├── messages/       ← concise inter-agent formatter (Phase 5)
@@ -506,7 +745,7 @@ codeconductor/
 │   └── presets/council/    ← bundled council.yml preset
 │
 ├── test/
-│   ├── cli.test.ts         ← integration tests (32 tests)
+│   ├── cli.test.ts         ← integration tests
 │   └── fixtures/           ← bun, node, django, spring projects
 │
 ├── docs/
@@ -519,9 +758,10 @@ codeconductor/
 │   ├── agent-scorecard.md
 │   └── guides/
 │
-├── presets/                ← manual preset files (pre-CLI)
+├── presets/                ← runner presets (agents, commands, skills)
 │   ├── opencode/
-│   └── claude/
+│   ├── claude/
+│   └── cursor/
 │
 └── examples/
     └── spring-boot-kotlin/
@@ -531,15 +771,12 @@ codeconductor/
 
 ## Roadmap
 
-| Version    | Focus                                                       |
-| ---------- | ----------------------------------------------------------- |
-| **v0.2.0** | **CLI: init, detect, install, doctor, update — shipped** ✅ |
-| v0.3.0     | Next.js, FastAPI, generic presets, monorepo support         |
-| **v0.4.0** | **Workflow Loop Core, stack-specific presets, 9 specialized skills, confidence thresholds + compliance veto in council consensus, goal orchestration, memory compression — shipped** ✅ |
-| v0.5.0     | Scorecard CLI, prompt contracts v0.5.0 (Evaluation gate, 3 new agents, Grok fallback) — shipped ✅ |
-| v1.0.0     | Stable contracts, stable routing, documented evaluation     |
+Published package: **1.0.0**. Remaining gaps (sandbox, policy compiler, full
+stack-specific asset pruning): [docs/current-status.md](docs/current-status.md).
+Product OS surface:
+[docs/v1.0.0-release-notes.md](docs/v1.0.0-release-notes.md).
 
-See [ROADMAP.md](ROADMAP.md) for details.
+See [ROADMAP.md](ROADMAP.md) for historical notes.
 
 ---