CCDD

Let verification define the project. Give each Artifact its own criteria and the tools a reviewer needs to inspect it. An Artifact can be code, tests, a specification, an image or any other folder of project material.

Put a ccdd.json in that folder. It owns the Artifact's name, view tools and Critics. CCDD finds those declarations, connects references and collects actual review evidence.

project/
  why/ccdd.json
  spec/ccdd.json
  tests/ccdd.json
  implementation/ccdd.json

A Critic can ask an Agent to compare Spec with Why, ask a person to compare two images, or run tests against an implementation. It belongs to the Artifact it evaluates. References such as {spec} connect it to the other Artifacts it uses.

flowchart LR
  subgraph Project[Your project]
    Why[Why] -. instruction .-> Spec[Spec]
    Spec -. instruction .-> Tests[Tests]
    Tests -. mount / instruction .-> Implementation[Implementation]
  end
  Project -. folder declarations .-> CCDD
  CCDD --> Agent[Agent review]
  CCDD --> Human[Human review]
  CCDD --> Runtime[Runtime tests]
  Agent --> Evidence[Actual evidence]
  Human --> Evidence
  Runtime --> Evidence
  Evidence --> CCDD
  style Project fill:#eef6ff,stroke:#5c83aa
  style CCDD fill:#eef9ef,stroke:#588060

Loading

These relationships define required input, verification and default dependency-GREEN gates. A Critic waits for current GREEN evidence from dependencies outside its cycle. Mutual dependencies are allowed: Critics in the same cycle may run together after external gates pass, and final validation requires all matching results. Child Artifact folders are automatic dependencies. Logical mounts connect other folders without copies or symlinks.

Local computing, explicit caching

CCDD 7 reuses identity -> completed result across repositories, paths and profiles. Your identity function defines whether results are interchangeable. Without an explicit function, every submission executes without reusable caching. CCDD manages shared executions, Provider recovery and cache GC. See the cache contract and 7.x migration.

Start with a runtime check

Use Node.js 22 LTS, version 22.19.0 or later.

npm install --ignore-scripts @ccdd/ccdd
# or: pnpm add --ignore-scripts @ccdd/ccdd

The single public package installs exact matching core, Project and default-tools modules as normal dependencies. Its ccdd, ccdd-project and ccdd-view commands delegate to those modules. Use @ccdd/ccdd/core, /project and /tools imports; see installation choices.

Inside an Artifact folder, create ccdd.json:

{
  "name": "implementation",
  "critics": [{
    "id": "tests",
    "title": "Pass the implementation tests",
    "profile": { "kind": "runtime", "command": "node", "args": ["--test", "check.test.mjs"] },
    "payload": { "instruction": "Run the tests for {implementation}." }
  }]
}

Add your actual check.test.mjs, then run from the workspace root:

npx ccdd-project config check
npx ccdd-project plan implementation --recursive
npx ccdd-project verify implementation --recursive --wait
npx ccdd-project status implementation

The getting-started guide includes a complete runnable example. For an existing installation, follow the upgrade instructions.

Read the result

Every actual review returns a verdict and any owner-defined fields required by its optional passSchema/failSchema. There is no built-in summary or evidence field. GREEN means its criteria were met; RED means they were not. Execution problems produce ERROR. Final validation needs matching PASS evidence for all required Critics and dependencies. A folder without Critics stays UNREVIEWED unless explicitly declared basis: true.

By default, Critics wait for current GREEN evidence from dependency Critics outside their strongly connected component. RED dependencies block descendants; operational failures leave them waiting without a fabricated verdict. Use --ignore-gates only when intentionally reviewing despite dependency verdicts. If other required evidence is missing, their results are saved and the request is INCOMPLETE. Add --recursive to include those other evaluations. With an explicit identity, CCDD reuses GREEN and RED results (RED remains unsatisfied) and shares active computations across projects. Without identity, inspect the completed Run to read its noncached result. No stale flags are stored.

Reviews run in the workspace you supply. Keep it unchanged until completion, including Human waiting. Records, caches and generated output live outside it. To keep editing elsewhere, create your own worktree and pass it with --repo.

Next steps

• Define a custom view script with JSON stdin/stdout, using any language.
• Register optional text, image and desktop tools.
• Compose folders and mounts, including coding-style and blind image comparison Critics.
• Compute views on demand from scenario material.
• Declare an Artifact family: many Artifacts sharing one folder, script and Critic.
• Design reviewer tools that return only what the reviewer requests.
• Configure Agent and Human reviewers.
• Try Why → Spec → Tests → Implementation.
• Look up commands and evidence rules.

The optional local monitor shows folders, relationships, cycles, review progress and saved results. Start it with npx ccdd-project monitor.

Package	Responsibility
@ccdd/ccdd	Single-install entrypoint, public module subpaths and CLI delegates.
@ccdd/core	Public definitions and logical path resolution.
@ccdd/project	Validation, CLI, Broker, Executors and monitor.
@ccdd/default-tools	Optional common view scripts; no automatic registration.

See Contributing, the context map, detailed contracts and release instructions. Repository content and review prompts use English.

License

MIT.

CCDD 7.1.0: large cached submissions no longer create a workspace observer per owner. The owner identity is re-run before publication, and publication separates accepted evidence from pending or rejected audit verdicts. Callers must keep identity-covered input unchanged while execution is in flight; see the integrity contract and release notes.

Existing Pi AI API

@ccdd/ccdd/pi re-exports Pi AI unchanged; @ccdd/ccdd/pi/providers/all re-exports its public builtinModels and builtinProviders catalog API. These are ESM and type forwards, not a new authentication manager or coding agent. The umbrella declares Pi AI directly, so both paths work under strict pnpm.

The existing official CLI remains npx @earendil-works/pi-ai@0.87.1 list and npx @earendil-works/pi-ai@0.87.1 login [provider]. Its current CLI lists/logs in OAuth providers and saves auth.json in the current directory; use it only from an appropriate private directory outside reviewed input. API-key login is available through Pi's library API, not that OAuth-only CLI. These exports do not create new CCDD login commands, persistence or credential precedence.

Review resources and budgets

Machine-wide provider pools, weighted owner identities, submission execution budgets, original runtime provenance and guarded offline load checks share one review-management contract. See the guide, including the required old-worker shutdown and option migration.