cdf-harness

v1.0.0-alpha.2

Published

15 days ago

A governed agent harness: governance is the kernel, everything else is a plugin.

0High
0Medium
0Low

ai harness agent-harness mcp copilot claude codex gemini governance audit spec-driven ai-assisted-development agent review

CDF Harness

A governed agent harness in the making. CDF Harness is the VS Code extension formerly published as the Cognitive Delivery VSC Plugin, refocused on 14 September 2026 around one idea: governance is the kernel, everything else is a plugin. It does not replace Copilot, Codex, Claude Code, or Gemini — it hosts and governs them. What remains after the refocus is the governance kernel (steering, specs, phase gates, provenance, reviews, the tamper-evident audit journal and CDI signals), the cdf-governance MCP server and the agent bridges that put every assistant behind the same write gate, the manifested runtimes through which governed agent runs write files, the Bar A gatekeeper daemon, the structural code map, the Compliance Evidence Report, the Reporting hub, Solution Architecture, the docs governance pack, the integrations and hooks layer, the guided planning copilot, and the business-analyst tooling.

Five subsystems were removed on 2026-09-14: the Tracker Mirror, the Scrum subsystem, the Living Blueprint, the Deployment Centre, and the Security Centre. They were product surfaces on top of the kernel rather than part of it, and together they were a quarter of the source; a standalone harness needs the kernel, the runtimes, and a plugin seam more than it needs those screens. The reasoning is in docs/product/CDF-Harness-Direction-2026-09-14.md. The per-tracker cdf.<provider>.readEnabled settings and the tracker provider registry stay as the seam for the tracker plugins to come; older workspaces with deployment_assurance or security_centre config blocks are tolerated, not failed.

What that plan called "next" has since shipped. The agent lease model and the governor, the native model-agnostic turn loop, the plugin loader and marketplace, the forge and tracker ports, the cdf command line with a resident host and a signed trajectory log, ten model providers, multi-project support, and wrapped vendor CLIs — see The harness kernel below and the phase table in the direction document.

📖 New to CDF? There's a full manual built in. The Getting Started walkthrough opens automatically on first install — or run CDF: Getting Started (guided walkthrough) and CDF: Open Manual (the 11-section in-product guide: Getting Started · Workflow · Concepts · Phases & Gates · Adoption Tiers · Commands · Reviews · Recovery · Legal) from the Command Palette. In the sidebar, the Guide tile (Quick Actions) and Guide & Help (Settings) open the same manual; every rich view has a "?" button that jumps to the relevant section.

The surfaces (what you'll see)

The activity-bar sidebar is the cockpit, in three lifecycle modes (Planning, Development, Reporting); these editor surfaces are where the work happens:

Workbench — the main dashboard: intake, spec management, metrics, activity, roadmaps, and the FG-mode routing tab.
Planning and the Requirements Cockpit — the guided planning copilot (@cdf /plan) and the business-analyst story map with the requirements linter and quality pack.
Solution Architecture — the Plan-mode C4/arc42 screen with its advisor and offline tech radar.
Compliance Evidence Report — control coverage across EU AI Act / ISO 42001 / SOC 2, signed and exportable (OSCAL / PDF).
Reporting hub — every outward report as a card, including the evidence-derived Weekly Delivery Highlight.
Docs hub — living HLD/LLD/ADRs plus regulatory docs (DPIA, RoPA, AI Act Annex IV, CRA, SBOM…) assembled from your governed substrate.
Development Journal — narrative notes (incl. a Research tab), decision records, and continuity handoffs.
Code Map and the Spec-Code Drift view — the live dependency structure of the codebase and requirement-to-symbol provenance.
Audit Hub — the governance audit journal, CDI signals, provenance timeline, and Decision Log.

Before you start

You need:

VS Code 1.109 or newer
At least one AI assistant for the chat surface and FG-mode runtime:
- GitHub Copilot subscription (provides vscode.lm for chat), OR
- Claude Code CLI (install), OR
- OpenAI Codex CLI, OR
- Gemini Code Assist
Git (CDF stores governance evidence in your repo)
macOS, Linux, or Windows — the Bar A enforcement daemon is bundled for darwin-arm64, darwin-x64, linux-x64, and win32-x64. The macOS binaries are ad-hoc signed until a Developer ID signing identity is in place, so Gatekeeper refuses them on any Mac other than the one that built them; Windows SmartScreen may warn on first launch. When the daemon cannot start, the extension degrades gracefully: governance flows still work, and Bar A runtime enforcement stays disabled until a properly signed build ships. Do not strip the quarantine attribute to work around this.

Get started in 5 minutes

Install the VSIX. The Marketplace listing is pending, so download cdf-harness-<version>.vsix from the latest GitHub Release and install it:
- Command line: code --install-extension cdf-harness-<version>.vsix, or
- In VS Code: Extensions view → … menu → Install from VSIX…
Reload the VS Code window.
Set up the workspace. Open the CDF activity-bar icon and click Set Up CDF, or run CDF: Set Up Workspace from the Command Palette (Cmd/Ctrl + Shift + P). This is a sequential, step-at-a-time flow: initialise the workspace → choose which AI agents you use (only those get governed) → draft steering. It resumes where you left off.
Draft steering the guided way (recommended). On the steering step, click Start Guided Setup in Chat, or type @cdf /setup in the chat view. CDF walks the governance decisions one at a time — intake, technical baseline, then architecture, conventions, standards, testing, workflow, security review, and traceability — proposing options with trade-offs and recording each choice as a Decision Record. Use @cdf /setup quick for the four essentials.
Start work. Open the Workbench (CDF: Open Workbench) — the main human entry point — and paste your ask; CDF classifies it as simple or governed. From chat, @cdf works the same way.

Prefer a guided tour? Run the built-in walkthrough: Command Palette → Welcome: Open Walkthrough → Get started with CDF.

Full user guide: docs/easy-guide.md. High-level overview: docs/plugin-overview.md. Working-with-agents guide: docs/working-with-the-plugin.md. Command reference: docs/commands-reference.md. Settings guide: docs/settings-guide.md.

The harness kernel

Everything in this section is headless: it runs in the editor, in cdf serve, and in CI, and none of it imports vscode. Four independent checks prove that boundary on every build.

Agent leases. Every worker, chat turn and MCP session is dispatched under a signed Agent Lease narrowed from its parent — allow intersects, deny unions, budgets clamp, depth decrements. No manifest, no lease; no lease, no dispatch, and every refusal is recorded. The manifest is specified normatively, with schemas, a conformance corpus and canonical-bytes test vectors, at Cognitive-Delivery/contract (Apache-2.0, and on npm as @cognitive-delivery/contract). One implementation exists — this one; the corpus is there so a second can be checked rather than asserted.
The governor. A per-lease egress proxy, a process-group supervisor with tree kill, OS sandbox profiles generated from the granted manifest, and a seven-rung enforcement ladder. Containment is enforced on macOS, files-only on Linux, advisory on Windows — a claim without that matrix is wrong on two platforms out of three.
A native turn loop. The harness runs the turn itself over plain fetch, so budgets are enforced inside the loop rather than checked afterwards. Ten providers behind two wire protocols.
Evidence. An append-only audit journal, CDI signals, a lease journal and a trajectory log, sealed by an HMAC-SHA256 hash chain and anchored into an in-toto attestation bundle. The trajectory commits to message hashes and never bodies — it refuses an entry carrying content rather than stripping it.
A plugin layer. Loader, marketplace and mounting, where plugin code never enters the kernel process: the only plugin code that runs is a spawned process under a leaf lease.
Ports, not assumptions. A ForgeProvider for GitHub, GitLab and Bitbucket with no fallback in the source, and a tracker registry behind the same shape.

The `cdf` command line

The harness is usable without the editor:

npm i -g cdf-harness        # once published — see the note below
cdf run "why does the build fail on Windows?"

cdf <group> <action>, six groups:

| Group | What it does | |---|---| | cdf run | one governed turn, from a terminal | | cdf agents | the agent map, the governor's headless controls, and the vendor CLIs this build can wrap | | cdf projects | the projects you have adopted, and their hosts | | cdf plugin | marketplaces, and the plugins this workspace has installed | | cdf gate | the headless governance gate, for a pipeline | | cdf serve | a resident host for one workspace, on a local socket and never a port |

cdf run is the one that starts an agent. Until it existed the CLI had nineteen actions across five groups and not one of them dispatched: the harness could govern, contain, observe and stop an agent from a terminal, and could not begin one.

cdf run "why does the build fail on Windows?"        # reads and answers
cdf run --spec add-health-endpoint "add the route"   # reads, and writes

A run with no --spec cannot write code, and that is the governance model rather than a limit of the command. An ungoverned turn declares the read subset and the evidence set and no code write paths — the lease-shaped form of no ungoverned edit. A run with a spec writes under a token, like every other governed write.

It presents a lease manifest and is refused without one, the gate sees every tool call, and the budget is enforced inside the loop. It prints the resolved provider and base URL before the first call, because a workspace decides that URL and cdf run makes "clone and run" a plausible first action. Exit codes: 0 the turn ended, 1 it stopped on a budget, denial, repeat, quarantine or provider error, 2 bad arguments, 3 refused before dispatch, 70 the harness itself failed.

cdf <group> --help prints that group's own usage.

Getting the command. The npm package is cdf-harness — not yet published; DR-157 records the decision to publish it publicly under PolyForm Noncommercial on the alpha dist-tag once the clean-machine proof passes and the macOS daemon is signed. The name is unscoped because a VS Code extension manifest cannot carry a scoped name (vsce rejects it), and this one manifest builds both artefacts. Until then, install the shim with CDF: Install cdf CLI; nothing else depends on it being installed.

The package carries the five CLI bundles and the MCP server — 11 files, 3.7 MB. It carries no extension host bundle, no webview, no test, no source and no sourcemap: a sourcemap embeds the source verbatim, so shipping one would publish src/ while the file list appeared to exclude it.

It carries no Rust daemon either, and that is not a containment gap. Containment comes from sandbox-exec on macOS and bwrap on Linux — OS tools, not CDF's daemon — and cdf run reports the computed mode, falling back to advisory when the tool is absent rather than claiming one it has not got. The daemon is the Bar A gatekeeper the extension uses; the whole CLI surface was run against an install with it deleted and behaved identically. The VSIX still bundles all four targets.

Many projects at once. One host holds one workspace — several projects mean several processes, so no project's keys, leases or evidence share an address space with another's. cdf projects status shows every adopted project with its state and containment mode, and the cockpit shows the same.

Two governance tiers. The harness can run a turn itself, or wrap a vendor's agent CLI. Both are governed; they are not governed to the same depth, and docs/native-runtime.md section 7a is the one table that says how they differ. A wrapped CLI holds its own key, so the harness governs what it may reach, write and how long it runs — not whose key it used.

What The Plugin Does

The plugin helps a team move from idea to implementation in a structured way:

Run a guided first-time setup from the CDF side panel to create config, draft steering, and agent guidance.
Classify incoming asks as simple work or governed development work.
Create a governed spec only when the ask needs it.
Progress that spec through governed phases.
Record provenance on artefacts (including coding assistant and model auto-detection).
Provide a governance dashboard (Workbench) with metrics, velocity insights, activity feed, and spec management.
Watch saved spec artefacts and offer the next action automatically.
Coordinate implementation tasks, including safe parallel batches and task claims.
Maintain an append-only governance audit journal for recovery and traceability.
Capture reviews and governance signals locally in the repository.
Run CDI assessments with one 90-day improvement priority.
Apply shared governance policy when a workspace points at an external governance source.
Provide transparent configuration through a Settings webview.
Offer rich data viewers for audit journal, CDI signals, provenance, spec overview, and task board.
Track and visualize local multi-spec roadmaps for sequencing spec-linked work and candidate initiatives.

The main outcome is consistency and auditability, not autonomous coding for its own sake.

Licence

PolyForm Noncommercial 1.0.0 — see LICENSE. Source-available: read it, change it, share it, use it for any noncommercial purpose. Commercial use requires written approval.

Two things are deliberately not under that licence:

contract/ is Apache-2.0 — the governance schemas, the Agent Lease Manifest specification, the conformance corpus and the reference runner. It is a git submodule here and is published independently as @cognitive-delivery/contract. The format is meant to be implemented by anyone, including commercially. A contract only one party may implement is not a contract.
elkjs keeps its EPL-2.0 rights, including commercial use. Required by EPL §3.1 and explained in THIRD-PARTY-NOTICES.md.

Privacy and security

No telemetry: CDF does not phone home. All audit and CDI evidence stays in your workspace as JSONL files under .cdf/. See PRIVACY.md.
Secrets are stored in VS Code SecretStorage (OS-level credential storage), never in .cdf/, workspace settings, or source control. See .cdf/steering/security.md.
Vulnerability disclosure: see SECURITY.md.

Contributing

Issues and PRs welcome. See CONTRIBUTING.md.

Core Concepts

Steering: project-level context in .cdf/steering/ — product.md, tech.md, structure.md, governance.md (required) plus security.md, privacy.md, and testing.md (optional). Each file has a canonical section set that steering health scores; decision-bearing sections are expected to cite the Decision Record (DR/ADR) that authorises them
Spec: a governed work item under .cdf/specs/<slug>/
Roadmap: a local multi-spec plan under .cdf/roadmaps/<slug>/roadmap.yaml, visualized in the Workbench Roadmaps tab
Phase: one of Draft, RequirementsApproved, DesignApproved, TasksApproved, InProgress, Complete
Provenance: structured front matter plus provenance.jsonl records showing who or what produced an artefact
Work intake: the first agent-native decision step, exposed as cdf_begin_work, that decides whether an ask is simple or requires a full spec
Task claim: an Execution line in tasks.md that records who is working a task and where
Parallel execution plan: .cdf/specs/<slug>/execution-plan.yaml, used only when tasks have safe dependencies and non-overlapping scope
Task review: approval evidence under .cdf/specs/<slug>/reviews/tasks/<task-id>.yaml
CDI assessment: a six-dimension governance assessment under .cdf/cdi/assessments/
Governance audit: append-only operational timeline at .cdf/audit/governance.jsonl
Adoption tier: how much autonomy the team is willing to allow, from assistive to agent-led
Governance source: optional shared policy, usually from a cdf-governance branch or repo

Quick Start

Open the repository or target workspace in VS Code.
Open the CDF side panel and click Set Up CDF (CDF: Set Up Workspace), or run it from the Command Palette.
Walk the sequential steps. On the steering step, use the guided @cdf /setup conversation (recommended) or the form. If VS Code has a language model available, CDF can use it to draft steering and propose decision options; otherwise it falls back to structured templates.
Review the drafted files under .cdf/steering/.
If you have a shared governance repository, add it to .cdf/config.yaml.
Open the Workbench from the CDF side panel when you need the human workspace, or let agents start with cdf_begin_work, so CDF can decide whether the ask is simple or requires a spec.
Open the Workbench Roadmaps tab, or run CDF: Open Roadmap, when coordinating several specs or deciding which candidate initiative should become a spec next.
When a spec is needed, produce governed artefacts by writing normally in the spec files. On save, CDF refreshes provenance and offers the next action when review or advancement is available.
During implementation, execute tasks.md in order, or run CDF: Plan Parallel Execution when tasks have declared dependencies and non-overlapping scope.
Claim each task before work starts, mark it Completed after verification, and record its per-task review before moving to dependent work.
Use CDF: Open Review when a task or implementation needs a recorded review.
Run CDF: Run CDI Assessment quarterly to keep the governance measurement current.

Normal Workflow

CDF is intended to sit beside normal editing, not replace it with a command ritual. The Workbench is the main Kiro-like surface: open it once from the CDF side panel when you want the guided workspace, type asks there, then use the same panel for phases, artefacts, task claims, task status, review, parallel planning, roadmap visualization, and health. Agents should start by calling cdf_begin_work, which classifies the ask and starts a spec only when the work is risky or developmental enough to need one. Once the workspace is initialised, saving .cdf/specs/<slug>/requirements.md, design.md, tasks.md, or implementation.md refreshes CDF provenance automatically and shows the next useful action when the gate is ready or a review is missing.

1. Set up the workspace

Run CDF: Set Up Workspace from the CDF activity-bar panel (Set Up CDF) or the Command Palette.

Set-Up is a sequential, step-at-a-time flow with a clickable rail and Back/Continue (progress persists, so reopening resumes):

Workspace — initialise the CDF scaffolding.
Coding tools — "Which coding agents do you use?" (detected agents pre-checked). CDF registers only the detected agents you select; assistant installation and authentication remain user-controlled.
Steering — draft steering either via the guided conversation (Start Guided Setup in Chat / @cdf /setup) or the Simple/Advanced form; the import routes (Kiro, GitHub, existing CDF files, prompts/design docs) are also available here.
Jurisdiction → Review → Finish.

Initialising the workspace creates .cdf/config.yaml, .cdf/steering/, .github/agents/, plugins/cdf-governance/, .agents/plugins/marketplace.json, .cdf/codex/bootstrap.json, AGENTS.md, and the unified onboarding state at .cdf/onboarding/initial-setup.yaml. The plugin also makes sure .cdf/.cache/ is ignored by Git.

CDF: Initialise Workspace remains available as a lower-level scaffolding command. Historical cdf.setupWizard keybindings and command links now open this same reviewed Set-Up surface.

Agent bridge sessions

CLI-style assistants do not automatically see VS Code vscode.lm tools. CDF exposes the same governed workflows through a local cdf-governance MCP bridge for Codex, Claude Code, and Gemini Code Assist. The bridge covers intake, artefact writes, phase transitions, reviews, archive, CDI assessment, governance refresh, hook triggering, and prompt translation.

Run CDF: Register All Agent Bridges after installing supported assistants, or keep cdf.bridges.autoRegister enabled so CDF can register detected bridges on activation and when Claude Code or Gemini Code Assist is installed later. Auto-approval is limited to the CDF MCP server/tools only.

Break Glass has the same rule in every assistant path: the exact phrase Break Glass is required, the override is limited to one active spec and one non-final review gate, and final completion still requires implementation review.

At the start of any MCP-backed assistant session, run cdf_tool_health. Details are in docs/codex-cdf-bridge.md and the parity contract is in docs/cdf-parity-matrix.md.

2. Write the steering files

Before using agents heavily, review and refine the steering files (each is a tab in the Steering panel and has a canonical section set):

product.md: what you are building and for whom
tech.md: stack, coding conventions, and the security/privacy baseline
structure.md: module boundaries, safe change scope, and cross-area contracts
governance.md: adoption tier, review policy, Definition of Done, and the traceability scheme
security.md (optional): secure-by-design principles, secrets handling, and security-review triggers
privacy.md (optional): privacy-by-design, personal data, lawful basis, retention
testing.md (optional): test types in scope, frameworks (dated), coverage targets, organisation, and CI gates

This is the context the plugin keeps syncing into AGENTS.md. The guided @cdf /setup conversation populates these for you and records a Decision Record per choice.

3. Intake the work

Most of the time, let the agent decide. In Copilot, Codex, Claude, or another agent that can see AGENTS.md and CDF tools, the first move should be cdf_begin_work. CDF returns either:

simple: proceed directly
full_spec: CDF creates the spec and the agent starts with requirements

For the same flow from the human UI, use the richer Workbench. It can stay open for the whole session; if it is already open, the command reveals the existing panel:

CDF: Open Workbench

The lighter command-only intake is:

CDF: Start From Ask

If you already know you want a spec, use:

CDF: Start Governed Work

This creates .cdf/specs/payment-retry-policy/ with initial state and opens requirements.md. The chat participant is still available when an agent is driving the setup:

@cdf /new-spec payment-retry-policy

4. Produce artefacts and advance the spec

Typical artefacts are:

requirements.md — includes Non-functional Requirements and a Traceability section (requirement-ID scheme → design → tasks)
design.md — includes a Requirements Traceability section (which requirement IDs it satisfies)
tasks.md — each task carries Test Approach, Security Review, and Traces To fields
implementation.md

cdf_write_artefact and the phase gates validate this structure on write, so new artefacts carry the traceability spine (existing approved artefacts are not retroactively failed). Write in those files normally, or open them from the Workbench artefact shortcuts. On save, CDF refreshes provenance and offers the next useful action. When you prefer an explicit command, use:

@cdf /advance payment-retry-policy

The plugin checks the next gate before allowing the phase transition, whether advancement came from a prompt, the Command Palette, or chat.

5. Record review

Run CDF: Open Review for the active spec. The review panel lets a reviewer record:

review target
reviewer name
outcome
notes
whether the reviewer model differs from the implementer model

The plugin writes review.md with provenance, writes gate evidence under reviews/<target>.yaml or reviews/tasks/<task-id>.yaml, updates the task review marker in tasks.md for task reviews, and emits a CDI review signal.

6. Coordinate implementation

The default implementation path is still sequential. For larger specs, run CDF: Plan Parallel Execution to write .cdf/specs/<slug>/execution-plan.yaml. The plan only batches tasks whose dependencies are satisfied, whose scopes do not overlap, and whose scope avoids shared/global files. Batch peers can be marked complete in either order; later batches still wait for earlier batches.

Before an agent or developer starts a task, run CDF: Claim Task Execution or use cdf_claim_task_execution. This stamps the task's Execution line in tasks.md, giving the next agent a durable recovery point if VS Code crashes or the chat context resets.

7. Run CDI assessments

Run CDF: Run CDI Assessment to score the six CDI dimensions, record evidence, and commit to one 90-day priority. Assessment records are written under .cdf/cdi/assessments/. The status bar shows whether the latest assessment is fresh, due, or stale.

8. Use the audit journal for recovery

CDF writes governance-significant events to .cdf/audit/governance.jsonl. This is the operational timeline for intake, classification, spec creation, provenance refreshes, phase gates, task execution, reviews, CDI assessments, and governance refreshes.

Request records include timestamps, request IDs, hashes, and short summaries. The journal avoids full prompt dumping by default so it remains useful without becoming a privacy trap.

Task-specific events carry the task ID when CDF can infer it, which makes the journal useful for resuming after a crash or context reset.

9. Refresh governance when needed

If your workspace uses a shared governance source, run CDF: Refresh Governance to refresh the cached org policy. The status bar shows whether governance is fresh, stale, unreachable, or local-only.

Main Commands

CDF: Set Up Workspace (the sequential first-run flow; Set Up CDF in the side panel)
@cdf /setup (guided conversational steering decisions; @cdf /setup quick for the essentials)
CDF: Initialise Workspace
CDF: Open Workbench
CDF: Open Roadmap
CDF: Create Roadmap
CDF: Seed Product Roadmap
CDF: View Settings
CDF: Start From Ask
CDF: Start Governed Work
CDF: Sync AGENTS.md
CDF: Open Review
CDF: Run CDI Assessment
CDF: Refresh Governance
CDF: Advance Spec
CDF: Update Task Status
CDF: Plan Parallel Execution
CDF: Claim Task Execution
CDF: Show Spec Health
CDF: View Audit Journal
CDF: View CDI Signals
CDF: View Provenance
CDF: View Spec Overview
CDF: View Task Board
cdf_begin_work
@cdf /new-spec
@cdf /advance

The Workbench is the preferred human entry point. It now functions as a full governance dashboard with metrics, velocity insights, activity feed, and a visual Roadmaps tab backed by .cdf/roadmaps/<slug>/roadmap.yaml. View Settings provides transparent access to all configuration. The data viewers (Audit Journal, CDI Signals, Provenance, Spec Overview, Task Board) give deep visibility into specific governance data.

Guidance For Teams

Start simple. Fill out steering before trying to automate the whole lifecycle.
Treat the plugin as a guardrail system, not a replacement for engineering judgment.
Keep one spec per meaningful change, not one giant spec for the whole project.
Use adoption tier intentionally. Higher tiers are not always better.
Keep governance and security expectations explicit in steering, especially for compliance-sensitive work.
Review phase failures as useful signals. If a gate blocks progress, the repo is telling you what governance evidence is missing.

Guidance For Working With Agents

Ask agents to read steering before producing governed artefacts.
Ask agents to call cdf_begin_work at the start of a request so simple asks stay lightweight and governed work gets a spec.
Use CDF: Open Workbench when a human wants the Kiro-like experience for intake, phases, artefacts, and tasks.
Use the Workbench Roadmaps tab, or CDF: Open Roadmap, when a human wants to sequence multi-spec work visually. The YAML roadmap remains the source of truth and does not replace phase gates, task reviews, provenance, or external planning tools.
Keep prompts anchored to a specific spec slug once CDF has decided a spec is needed.
Prefer small, phase-appropriate steps over asking for everything in one go.
Write normally in the spec artefacts; CDF auto-refreshes provenance on save once the workspace is initialised.
Record provenance on generated artefacts instead of keeping important context only in chat when an agent creates files outside the normal save flow.
Use cdf_update_task_status after each implementation task completes so tasks.md remains the provenance-valid source of truth.
Use cdf_plan_parallel_execution and cdf_claim_task_execution when coordinating multiple agents; parallelize only planned batches with non-overlapping task scope.
Use task review records so a restarted agent can see which completed tasks are approved and where to resume.
Use .cdf/audit/governance.jsonl when you need the chronological story of what happened across agents, tools, and VS Code sessions.
Use CDI assessments to turn governance evidence into one 90-day improvement priority.
Use review records to capture decisions and concerns, not just approval.

More practical guidance is in docs/working-with-the-plugin.md.

Enforcement scope (known limitation)

CDF's enforcement strength is not uniform across agents, and we want that to be explicit rather than implied by the "CDF Enforced" shield. The determining factor is who owns the process, not a per-agent toggle:

Hard-enforced — CDF owns the launch. For Codex and any CDF-dispatched run, CDF spawns the agent inside an OS sandbox and a mediated worktree, so native edits are structurally blocked (Codex) or vetoed per-tool (canUseTool, dispatched Claude via the SDK). The boundary can't be prompt-injected out of.
Advisory — CDF is a guest. For user-driven, interactive Claude Code (you open Claude yourself; CDF didn't launch it), CDF can only inject MCP tools and write .claude/settings* hooks the host chooses to honour. In normal Governed mode those native edits are detect-and-quarantine after the fact, not pre-blocked, and the settings are user-removable. The PreToolUse deny hook only hard-blocks in Audit-Only/breached mode. The same guest limitation applies to other chat surfaces CDF bridges but does not launch.
Bash hardening (v2.13.0). CDF: Enable Claude Code Sandbox adds Claude Code's native OS sandbox for its Bash subprocesses — real kernel confinement, but it covers Bash only and does not change the topology above; interactive Read/Edit/Write stay advisory.

What this means in practice: the enforcement status-bar shield reports whether the governance bridges are installed, not that every agent's edits are un-bypassable. Interactive Claude Code is governed, audited, and quarantined — but it is not hermetically sandboxed unless CDF owns its launch. True parity would require routing interactive Claude through the same owned-launch path Codex uses (mediated worktree + sandbox + per-tool veto), at the cost of the native interactive experience — a deliberate trade we have not taken.

Current Status

CDF Harness is at 1.0.0-alpha.2. The rename and the five-subsystem strip are complete, and phases 2 through 11 of the direction document have been built: the kernel boundary, agent leases, the governor, the native turn loop, the plugin layer, the forge and tracker ports, the cdf command line with a resident host and a signed trajectory log, ten model providers, multi-project support, the vendor conformance pack, and wrapped vendor CLIs. The phase table in that document is the current state; CHANGELOG.md is the detail.

Known and stated rather than implied: containment is enforced on macOS, files-only on Linux and advisory on Windows; a wrapped vendor CLI authenticates itself, so the harness does not know whose key it used; and the Marketplace listing is not live, so releases ship as a VSIX attached to a GitHub Release. The plugin line continues separately at 2.67.0. Earlier implementation history is in docs/implementation-tracker.md.

Installing and publishing

Until the Marketplace listing is live, CDF ships as a signed-by-GitHub VSIX attached to each GitHub Release:

Install: download the .vsix and run code --install-extension cdf-harness-<version>.vsix, or use Extensions → … → Install from VSIX….
Build a VSIX locally: npm run cdf:package-vsix-local (runs the version-log gate + production build).
Cut a release: bump the version in package.json, add a CHANGELOG.md entry, then tag v<version> and push — the publish.yml workflow builds the multi-platform VSIX and attaches it to the GitHub Release.
Enable Marketplace publishing: register the cdf publisher, create an Azure DevOps Personal Access Token (Marketplace → Manage), and add it as the VSCE_PAT repository secret. The publish step is a no-op until that secret is set. Full step-by-step: docs/marketplace-publishing.md.

Development

npm install
npm run build
npm run test
npm run typecheck

To run the extension in development mode, open this workspace in VS Code and press F5.

Helpful Docs

docs/product/CDF-Harness-Direction-2026-09-14.md — why the harness, what was removed, what comes next
docs/commands-reference.md
docs/codex-cdf-bridge.md and docs/cdf-parity-matrix.md
docs/easy-guide.md
docs/working-with-the-plugin.md
docs/testing.md
docs/implementation-tracker.md
docs/design-decisions.md