Build Project Capability Compiler v1

.github/scripts/validate-repository.mjs

@@ -19,6 +19,7 @@ const requiredDocs = [
   "docs/CONFIG_SAFETY.md",
   "docs/USAGE.md",
   "docs/VALIDATION.md",
+  "docs/USEFULNESS_COMPARISON.md",
 ];
 
 const requiredFiles = [

.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   pull_request:
+  merge_group:
   push:
     branches:
       - main
@@ -25,8 +26,8 @@ jobs:
           - macos-latest
           - windows-latest
         node:
-          - 20
           - 22
+          - 24
     runs-on: ${{ matrix.os }}
     steps:
       - name: Check out repository
@@ -50,11 +51,18 @@ jobs:
       - name: Verify deterministic bundled CLI
         run: node .github/scripts/check-deterministic-build.mjs
 
+      - name: Verify deterministic complete plugin archive
+        run: npm run archive:verify
+
       - name: Verify source payload checksums
         run: npm run checksums:verify
 
       - name: Verify deterministic SBOM
         run: npm run sbom:verify
 
+      - name: Confirm generated artifacts are clean
+        shell: bash
+        run: git diff --exit-code
+
       - name: Audit locked dependencies
         run: npm audit --audit-level=high

.gitignore

@@ -5,6 +5,7 @@ coverage/
 *.log
 *.tmp
 *.zip
-*.tgz
+*.tar
+!artifacts/*.tar
 .codex-log/
 tests/.tmp/

AGENTS.md

@@ -2,9 +2,9 @@
 
 ## Mission
 
-Build and verify Codesemble as an offline-first Codex plugin that audits a workspace,
-recommends a small evidence-backed specialist team from a 111-role catalog, and
-generates native project-scoped Codex configuration safely.
+Build and verify Codesemble as an offline-first Codex plugin that compiles typed
+workspace evidence and explicit user goals into the smallest capable project-specific
+Codex team, then generates native project-scoped configuration safely.
 
 ## Working agreements
 

CHANGELOG.md

@@ -7,6 +7,28 @@ until a release is explicitly published.
 
 ## Unreleased
 
+### Added
+
+- Voice-friendly plan approval with a strict six-word spoken challenge derived
+  from the unchanged full confirmation digest.
+- A read-only `approval` command that clearly separates terminal preview plans
+  from apply-capable plans.
+- Project Capability Compiler v1 with atomic typed EvidenceRefs, a Project
+  Capability Map, bounded Work Packages, generated-role admission, and Team IR v2.
+- Coverage-driven Focused, Recommended, and Extended proposals with no
+  desired-count filler.
+- Referenced-evidence freshness checks at approval and apply.
+- Strict v2 manifest provenance while retaining v1 plan, receipt, doctor, and
+  rollback compatibility.
+
+### Changed
+
+- The bundled 111-role catalog is now an extensible primitive library, not a
+  recommendation ceiling, installed-team target, or concurrency limit.
+- Concurrency uses an independently named safety ceiling and retains the
+  explicit acknowledgement gate above 16 workers.
+- CI targets Node 22 and 24 on Ubuntu, macOS, and Windows.
+
 ## 0.1.0 - 2026-07-31
 
 ### Added

PROJECT_GOAL.md

@@ -1,28 +1,60 @@
-# Codesemble Goal
+# Codesemble v0.2 Goal
 
-Build a clean Apache-2.0, offline-first, open-source Codex plugin that:
+## Mission
 
-1. Audits a selected workspace without mutating it or reading sensitive material.
-2. Interviews the user only for information the audit cannot determine.
-3. Recommends Lean, Balanced, and Full teams from exactly 111 versioned role blueprints.
-4. Lets the user search, customize, add, or exclude specialist roles.
-5. Generates native `.codex/agents/*.toml`, a bounded managed `AGENTS.md` section,
-   and an optional version-aware project concurrency setting.
-6. Shows exact diffs and applies only the confirmed transaction.
-7. Preserves unrelated content, detects concurrent modification, and supports safe rollback.
-8. Validates models, permissions, tools, configuration, discovery, and real native delegation.
-9. Produces a reproducible `v0.1.0` release candidate with complete open-source documentation.
+Turn repository evidence and explicit human goals into the smallest capable,
+tested, project-specific native Codex team.
+
+## Vision
+
+Every Codex project can assemble trustworthy specialist agents as naturally as
+it configures tests: adaptive to the work, understandable to people,
+least-privileged by default, and continuously maintainable as the project
+changes.
+
+## Master goal
+
+Deliver Project Capability Compiler v1: a deterministic, offline-first pipeline
+that converts a bounded audit into typed evidence, a Project Capability Map,
+Work Packages, an admitted Team IR, and coverage-driven Focused, Recommended,
+and Extended team proposals.
 
 ## Product promise
 
-> Audit the work. Build the smallest useful Codex team. Keep every change reviewable.
+> Audit the work. Generate the smallest capable team. Keep every change reviewable.
+
+## Required outcomes
+
+1. Repository prose remains untrusted data and never becomes persistent policy.
+2. Every installed role is bound to typed repository evidence or an explicit user goal.
+3. Generated roles have bounded ownership, deliverables, verification contracts,
+   model profiles, and least-privilege sandboxes.
+4. Focused is the minimum complete capability cover. Recommended adds independent
+   verification only for justified risk. Extended adds only evidenced lifecycle work.
+5. The bundled role catalog remains an extensible primitive library and fallback,
+   not a team-size or product-output ceiling.
+6. Installed role count and concurrent workers remain independent. High concurrency
+   requires a human-visible, digest-bound acknowledgement.
+7. Preview, evidence freshness, capability freshness, exact full-ID or voice-safe
+   confirmation, no-clobber apply, doctor, update, and rollback remain mandatory.
+8. v0.1 manifests and transaction receipts remain diagnosable and rollback-safe.
+9. Representative fixtures, semantic goldens, properties, adversarial tests,
+   three-OS CI, and fresh-session runtime evidence remain separate proof levels.
+10. The plugin bundle, SBOM, checksums, documentation, and PR evidence bind to the
+    exact v0.2 candidate.
+
+## Governance
+
+The user is final authority. The primary Codex thread owns scope, integration,
+approvals, external writes, and completion claims. The project orchestrator may
+coordinate bounded specialists but cannot merge, release, publish, handle
+credentials, alter trust, or modify global Codex configuration.
 
-## Non-goals for v0.1.0
+## Non-goals
 
-- Replacing Codex's native agent runtime.
-- Persistent remote scheduling, dashboards, or hosted state.
-- Editing global Codex configuration automatically.
-- Marking projects trusted.
-- Installing third-party plugins, skills, hooks, MCP servers, or credentials.
-- Telemetry, remote repository uploads, or account creation.
-- Publishing code or submitting to the OpenAI plugin directory without explicit authorization.
+- Replacing the native Codex runtime or creating a remote scheduler.
+- Executing repository scripts during audit.
+- Treating generated prompt guidance as filesystem enforcement.
+- Installing third-party plugins, hooks, MCP servers, providers, or credentials.
+- Silent global configuration, trust, deployment, publication, or release actions.
+- Telemetry or repository upload in deterministic mode.

README.md

@@ -9,9 +9,12 @@
 <p align="center">
   <a href="#quick-start">Quick start</a> ·
   <a href="docs/USAGE.md">Usage</a> ·
+  <a href="docs/PROJECT_CAPABILITY_COMPILER.md">Compiler</a> ·
   <a href="docs/ARCHITECTURE.md">How it works</a> ·
   <a href="docs/CONFIG_SAFETY.md">Safety</a> ·
-  <a href="docs/ROLE_CATALOG.md">111-role catalog</a>
+  <a href="docs/VOICE_APPROVAL.md">Voice approval</a> ·
+  <a href="docs/ROLE_CATALOG.md">Primitive library</a> ·
+  <a href="docs/USEFULNESS_COMPARISON.md">Comparison</a>
 </p>
 
 ---
@@ -20,10 +23,10 @@
 
 Codesemble is an open-source, repository-aware team builder for Codex.
 
-It reads bounded project signals, asks what you are trying to accomplish, and
-selects a small set of specialists from 111 role blueprints. It then compiles
-that team into native, project-scoped Codex configuration you can review before
-anything changes.
+It reads bounded project signals, asks what outcome you want, and compiles a
+Project Capability Map, Work Packages, and the smallest capable set of
+project-specific specialists. Every role explains why it exists before
+Codesemble generates native project configuration.
 
 Codesemble configures Codex. It does not replace the Codex runtime.
 
@@ -40,28 +43,30 @@ without installing a generic army of agents.
 ## How does it work?
 
 ```text
-Repository evidence  →  Small team recommendation  →  Exact preview  →  Confirmed apply
+Typed evidence → Capability map → Work packages → Admitted team → Exact preview → Confirmed apply
 ```
 
 1. **Audit** — reads bounded, typed project signals offline.
-2. **Recommend** — proposes Lean, Balanced, and Full teams with reasons.
-3. **Preview** — shows every agent, instruction, and configuration change.
-4. **Apply** — writes only the exact plan you confirm, with doctor and rollback support.
+2. **Compile** — derives capabilities and independently delegable Work Packages.
+3. **Generate** — proposes Focused, Recommended, and Extended teams with coverage evidence.
+4. **Preview** — shows every agent, sandbox, instruction, and configuration change.
+5. **Apply** — writes only the fresh exact plan you confirm, with doctor and rollback support.
 
 [Read the complete workflow →](docs/USAGE.md)
 
 ## Why is it different?
 
-Most agent packs start with a fixed roster. Codesemble starts with your work.
+Most agent packs start with a fixed roster. Codesemble starts with your goal and
+the typed evidence that can safely specialize it.
 
-The 111 roles are a search space—not a team size. A typical project receives a
-small, non-overlapping group whose responsibilities match the repository and the
-goal. Installed roles and live concurrency stay separate, so 12 available roles
-might still mean only 4 workers can run at once.
+The bundled catalog is an extensible primitive library, not the set of teams
+Codesemble can produce. Project roles are generated and admitted from Work
+Packages. Installed roles and live concurrency stay separate, so a project may
+install 12 specialists while allowing only 4 spawned workers at once.
 
 > **Evidence in. Native team out.**
 
-[Explore the role catalog →](docs/ROLE_CATALOG.md)
+[Explore the primitive library →](docs/ROLE_CATALOG.md)
 
 [See the architecture →](docs/ARCHITECTURE.md)
 
@@ -70,7 +75,7 @@ might still mean only 4 workers can run at once.
 ### Install
 
 ```bash
-codex plugin marketplace add VAMFI/codsemble --ref v0.1.0
+codex plugin marketplace add VAMFI/codsemble --ref <reviewed-release-or-commit>
 codex plugin add codsemble@codsemble
 ```
 
@@ -79,11 +84,12 @@ Start a fresh Codex session so the plugin and project agents are reloaded.
 ### Build your team
 
 ```text
-$initialize-team Set up a balanced Codex team for this workspace.
+$initialize-team Build the recommended Codex team for this workspace.
 ```
 
 Codesemble audits and prepares a side-effect-free plan first. It applies project
-files only after showing the exact diff and receiving the plan's confirmation ID.
+files only after showing the exact diff and receiving the plan's confirmation ID
+or its strictly matched, voice-friendly spoken alias.
 
 ### Keep it healthy
 
@@ -120,20 +126,24 @@ credentials, broaden permissions, or publish anything for you.
 | --- | --- |
 | Install, initialize, update, diagnose, or roll back | [Usage](docs/USAGE.md) |
 | Understand the compiler and native Codex outputs | [Architecture](docs/ARCHITECTURE.md) |
+| Inspect the EvidenceRef, capability, Work Package, and admission contracts | [Project Capability Compiler](docs/PROJECT_CAPABILITY_COMPILER.md) |
+| Migrate a v0.1 team safely | [v0.2 migration](docs/MIGRATION_V0_2.md) |
 | Review concurrency, no-clobber apply, and recovery behavior | [Configuration safety](docs/CONFIG_SAFETY.md) |
-| Browse the 111 specialist blueprints | [Role catalog](docs/ROLE_CATALOG.md) |
+| Approve an apply-capable plan from a realtime voice session | [Voice-friendly approval](docs/VOICE_APPROVAL.md) |
+| Understand reusable role primitives and dynamic generation | [Primitive library](docs/ROLE_CATALOG.md) |
 | Understand local data handling | [Privacy](docs/PRIVACY.md) |
 | Review trust boundaries and abuse cases | [Threat model](docs/THREAT_MODEL.md) |
 | See what has actually been tested | [Validation evidence](docs/VALIDATION.md) |
+| Compare the compiler with catalog-surface and single-primary baselines | [Bounded usefulness comparison](docs/USEFULNESS_COMPARISON.md) |
 | Understand the project promise and release gate | [Definition of Done](docs/DEFINITION_OF_DONE.md) |
 | Reuse the visual identity correctly | [Brand guide](docs/BRAND.md) |
 
 ## Project status
 
-Codesemble v0.1.0 is the initial public release. Structural and simulated checks
-do not prove that every Codex version, policy, model, or operating system will
-accept a generated team. Runtime claims are documented separately and tied to
-the environment that produced them.
+Codesemble v0.2.0 is the Project Capability Compiler candidate. It is not merged,
+released, or published by this branch. Structural and simulated checks never
+prove that every Codex version, policy, model, or operating system will accept a
+generated team; runtime claims remain tied to the exact tested payload and host.
 
 [See validation evidence →](docs/VALIDATION.md)
 

ROADMAP.md

@@ -1,39 +1,57 @@
 # Roadmap
 
-The roadmap describes intent, not a compatibility or delivery promise.
+The roadmap describes intent and evidence gates, not a compatibility promise.
 
-## v0.1 — initial public release
+## v0.2 — Project Capability Compiler v1
 
-- Bounded, offline-first workspace audit.
-- Exact 111-role catalog with evidence-backed recommendations.
-- Lean, Balanced, and Full proposals.
-- Native project agent and managed `AGENTS.md` generation.
-- Separate role-count and spawned-worker decisions.
-- Side-effect-free previews, locked no-clobber project apply, doctor, update,
-  and rollback.
-- Cross-platform fixtures, adversarial tests, official validators, and isolated
-  fresh-session runtime evidence.
+### 1. Foundations
 
-## v0.2 — hardening and portability
+- Remove every functional dependency on the bundled primitive count.
+- Keep installed roles independent from spawned-worker capacity.
+- Probe native Codex behavior and fail closed when required capabilities disappear.
+- Install and fresh-session verify a project-local orchestrator under primary authority.
 
-- Catalog and generated-schema migrations from real-world feedback.
-- Broader monorepo and non-code project fixtures.
-- Stronger configuration adapters across supported Codex versions.
-- Accessibility review of interactive onboarding.
-- Idempotent automatic recovery for interrupted mutation journals.
-- Signed release artifacts, SBOM, provenance, and reproducibility reporting.
+### 2. Capability model
 
-## Later, only with a new threat model
+- Compile atomic typed EvidenceRefs from bounded audit facts.
+- Derive a Project Capability Map without treating passive files as work requests.
+- Build bounded Work Packages with risk, scope guidance, dependencies, and validation.
+- Canonicalize Team IR v2 and bind it to the audit and human-confirmed plan.
 
-- Optional visual team topology editor.
-- Organization-managed role and policy packs.
-- Cross-harness export.
-- Workflow effectiveness evaluation using explicitly opted-in local data.
-- Optional integrations that remain separately reviewed and confirmed.
+### 3. Synthesis and admission
 
-## Explicitly not planned for v0.1
+- Generate project-specific roles from Work Packages and reusable catalog primitives.
+- Admit roles through strict path, tool, model, permission, and output policies.
+- Produce coverage-driven Focused, Recommended, and Extended options with no filler.
+
+### 4. Human experience
+
+- Show what was found, what can be generated, why each role exists, and what changes.
+- Keep customization natural-language friendly while freezing admitted structured data.
+- Preserve full-digest and exact voice-friendly approval for apply-capable plans.
+
+### 5. Lifecycle
+
+- Recheck referenced evidence and live Codex capabilities before mutation.
+- Preserve manifest ownership, no-clobber updates, drift refusal, doctor, and rollback.
+- Maintain strict v0.1 manifest and transaction compatibility.
+
+### 6. Validation and delivery
+
+- Add representative, golden, property, adversarial, migration, and usefulness suites.
+- Pass Node 22 and 24 on Ubuntu, macOS, and Windows.
+- Build deterministic plugin artifacts, SBOM, checksums, and exact-payload runtime proof.
+- Open a focused PR with CI evidence. Merge, release, and publication remain separate.
+
+## Later, only with a new threat and privacy review
+
+- Optional assisted semantic synthesis with an exact redacted egress preview.
+- Visual team-topology editing.
+- Organization-managed policy and primitive packs.
+- Hosted evaluation or integrations with explicit opt-in and separate authority.
+
+## Explicitly out of scope
 
 - A replacement agent runtime or persistent remote scheduler.
-- Silent edits to global Codex configuration or project trust.
-- Automatic third-party installation.
-- Credentials, telemetry, repository uploads, deployment, or publication.
+- Silent edits to user-level Codex configuration or project trust.
+- Automatic connectors, credentials, deployment, release, or publication.