@ccdd/core 3.3.0 → 4.0.0

package/examples/computed-views/checkout/ccdd.json

@@ -0,0 +1,133 @@
+{
+  "name": "checkout",
+  "views": {
+    "agentTools": {
+      "overview": {
+        "metadata": {
+          "description": "Inspect {artifactName} with overview.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "overview"
+          ]
+        }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Inspect {artifactName} with detail.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "id"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "detail"
+          ]
+        }
+      }
+    },
+    "humanTools": {
+      "overview": {
+        "metadata": {
+          "description": "Inspect {artifactName} with overview.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "overview"
+          ]
+        }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Inspect {artifactName} with detail.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "id"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "detail"
+          ]
+        }
+      }
+    }
+  },
+  "critics": [
+    {
+      "id": "review",
+      "title": "Review the checkout scenario",
+      "profile": {
+        "kind": "human"
+      },
+      "payload": {
+        "instruction": "Read the overview of {checkout}, then inspect every listed detail. Decide whether observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence."
+      }
+    }
+  ]
+}

package/examples/computed-views/search/ccdd.json

@@ -0,0 +1,133 @@
+{
+  "name": "search",
+  "views": {
+    "agentTools": {
+      "overview": {
+        "metadata": {
+          "description": "Inspect {artifactName} with overview.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "overview"
+          ]
+        }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Inspect {artifactName} with detail.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "id"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "detail"
+          ]
+        }
+      }
+    },
+    "humanTools": {
+      "overview": {
+        "metadata": {
+          "description": "Inspect {artifactName} with overview.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {},
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "overview"
+          ]
+        }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Inspect {artifactName} with detail.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "id"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "detail"
+          ]
+        }
+      }
+    }
+  },
+  "critics": [
+    {
+      "id": "review",
+      "title": "Review the search scenario",
+      "profile": {
+        "kind": "human"
+      },
+      "payload": {
+        "instruction": "Read the overview of {search}, then inspect every listed detail. Decide whether observations satisfy each criterion. Cite detail IDs and explain missing or contradictory evidence."
+      }
+    }
+  ]
+}

package/examples/computed-views/view.mjs

@@ -0,0 +1,13 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+let text = '';
+for await (const chunk of process.stdin) text += chunk;
+const { version, context, args } = JSON.parse(text);
+if (version !== 1) throw new Error('Unsupported request version.');
+const scenario = JSON.parse(await readFile(join(context.artifactPath, 'scenario.json'), 'utf8'));
+if (!Array.isArray(scenario.details) || !Array.isArray(scenario.criteria)) throw new Error('Invalid scenario.');
+const data = process.argv[2] === 'overview'
+  ? { name: scenario.name, objective: scenario.objective, criteria: scenario.criteria, detailIds: scenario.details.map(item => item.id) }
+  : scenario.details.find(item => item.id === args.id);
+if (!data) throw new Error('Unknown scenario detail.');
+process.stdout.write(JSON.stringify({ content: [{ type: 'json', data }], observation: { kind: 'content' } }));

package/examples/custom-text-reader/README.md

@@ -1,25 +1,13 @@
-# Custom Reader
+# Custom text reader
 
-This example directly registers `{ metadata, execute }` without the default tool library. `customTextReader()` creates a definition; actual file reading occurs when an Agent calls `read_spec` or `read_why`.
+`why/ccdd.json` declares an explicit basis. `spec/ccdd.json` owns its alignment Critic and reader. The instruction `{why}` derives the dependency; no `target`, `deps`, type registry or config factory is needed.
 
-Each project must include its own dependencies. Copy this folder into a new project outside the repository, then install core and Project. The commands below work after npm v3.1.0 publication; before that, use the local tarballs described below. The example is included in the source repository and the core package's `examples/custom-text-reader`. It does not rely on CCDD installed in a parent repository.
+Install `@ccdd/core` and `@ccdd/project` in this example directory. The custom `view.mjs` requires only Node; default tools are optional.
 
 ```sh
-# Copy the example from the CCDD source repository.
-cp -R examples/custom-text-reader /tmp/ccdd-custom-reader
-cd /tmp/ccdd-custom-reader
-npm init -y
-npm pkg set type=module
-npm install --ignore-scripts @ccdd/core@3.1.0 @ccdd/project@3.1.0
-npx ccdd tools check --artifact spec --for agent --tool read
-npx ccdd tools check --artifact spec --for agent --tool read --execute --args '{"startLine":1,"lineCount":20}'
-npx ccdd run --copy --critic spec-why --codex-auth-file "$HOME/.codex/auth.json" --wait
+ccdd-project config check
+ccdd-project tools check --artifact spec --for agent --tool read --execute --args '{"startLine":1,"lineCount":20}'
+ccdd-project verify spec --recursive --wait
 ```
 
-This example installs core and Project without the default tool library. Alternatively, in the source repository run `npm run release:npm -- --commit <40-character SHA> --dry-run` to verify and generate matching `ccdd-core-3.1.0.tgz` and `ccdd-project-3.1.0.tgz` files, then install with `npm install --ignore-scripts <core.tgz> <project.tgz>`. This local verification requires no GitHub authentication. If CCDD is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/custom-text-reader`.
-
-The tool omits `preflight`. The default check distinguishes confirmed registration from unverified execution; `--execute` actually reads the file. Agent review requires valid Provider authentication.
-
-This Reader is a small implementation illustrating the structure. It reads the file into memory before checking the 1MiB limit and limits returned text to 64KiB. A streaming reader is more appropriate for large files. It preserves UTF-8, CRLF, and the final newline, and distinguishes an empty file from a read past EOF. It returns an observation receipt only when actual content or an empty file was observed.
-
-There is no Human duplicate of the Agent Reader. This type has no Human tools, so a Human Critic cannot use it. To add human viewing, write a custom tool that opens a desktop application or explicitly register `human.desktop.open()` from `@ccdd/default-tools`.
+The last command makes a real Agent request and needs configured Provider credentials outside this workspace. `view.mjs` receives the standard JSON request on stdin and returns one `ToolResult` on stdout. The fixed filename is an argv value from each Artifact's declaration. The shared script is explicitly fingerprinted by `executionPaths`.

package/examples/custom-text-reader/spec/ccdd.json

@@ -0,0 +1,60 @@
+{
+  "name": "spec",
+  "views": {
+    "agentTools": {
+      "read": {
+        "metadata": {
+          "description": "Inspect {artifactName} with read.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "startLine": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "lineCount": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 80
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "startLine",
+              "lineCount"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "spec.md"
+          ]
+        }
+      }
+    }
+  },
+  "critics": [
+    {
+      "id": "alignment",
+      "title": "Does Spec match Why?",
+      "profile": {
+        "kind": "agent",
+        "provider": "openai-codex",
+        "model": "gpt-6-astra",
+        "reasoning": "medium"
+      },
+      "payload": {
+        "instruction": "Read {spec} and {why}; decide whether Spec satisfies the maximum task count in Why."
+      }
+    }
+  ]
+}

package/examples/custom-text-reader/view.mjs

@@ -0,0 +1,20 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// A small standard-protocol script with no SDK or Provider dependency.
+let input = '';
+for await (const chunk of process.stdin) input += chunk;
+const { version, context, args } = JSON.parse(input);
+if (version !== 1) throw new Error('Unsupported request version.');
+const bytes = await readFile(join(context.artifactPath, process.argv[2]));
+if (bytes.length > 1024 * 1024) throw new Error('This example accepts files up to 1 MiB.');
+const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+if (text.includes('\0')) throw new Error('This example accepts text, not binary data.');
+const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
+const selected = lines.slice(args.startLine - 1, args.startLine - 1 + args.lineCount);
+const content = selected.join('');
+if (Buffer.byteLength(content) > 64 * 1024) throw new Error('Select a smaller line range.');
+process.stdout.write(JSON.stringify({
+  content: [{ type: 'json', data: { content, startLine: args.startLine, lineCount: selected.length, totalLines: lines.length } }],
+  ...(selected.length ? { observation: { kind: 'content' } } : lines.length === 0 ? { observation: { kind: 'empty' } } : {}),
+}));

package/examples/custom-text-reader/why/ccdd.json

@@ -0,0 +1,46 @@
+{
+  "name": "why",
+  "views": {
+    "agentTools": {
+      "read": {
+        "metadata": {
+          "description": "Inspect {artifactName} with read.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "startLine": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "lineCount": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 80
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "startLine",
+              "lineCount"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "view.mjs"
+          ]
+        },
+        "script": {
+          "command": "node",
+          "args": [
+            "../view.mjs",
+            "why.md"
+          ]
+        }
+      }
+    }
+  },
+  "basis": true
+}

package/package.json

@@ -1,14 +1,28 @@
 {
   "name": "@ccdd/core",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "license": "MIT",
-  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
-  "repository": { "type": "git", "url": "git+https://github.com/lhj6102/ccdd.git" },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lhj6102/ccdd.git"
+  },
   "description": "Artifact, Critic, relationship and tool definitions for CCDD",
   "type": "module",
   "types": "./dist/src/sdk.d.ts",
-  "exports": { ".": { "types": "./dist/src/sdk.d.ts", "import": "./dist/src/sdk.js" } },
-  "workspaces": ["packages/default-tools", "packages/project"],
+  "exports": {
+    ".": {
+      "types": "./dist/src/sdk.d.ts",
+      "import": "./dist/src/sdk.js"
+    }
+  },
+  "workspaces": [
+    "packages/default-tools",
+    "packages/project"
+  ],
   "engines": {
     "node": "^22.19.0"
   },
@@ -27,13 +41,13 @@
     "release": "node scripts/local-release.mjs",
     "release:npm": "node scripts/local-release.mjs --npm",
     "release:npm:check": "node scripts/check-npm.mjs",
-    "demo:prepare": "npm run build && node dist/src/cli.js prepare-demo",
-    "demo": "npm run build && node dist/src/cli.js run --demo --copy --wait"
+    "demo:prepare": "npm run build && node dist/src/cli.js prepare-demo"
   },
   "files": [
     "dist/src/sdk.*",
     "dist/src/definitions.*",
     "dist/src/tools/contracts.*",
+    "dist/src/artifact-scope.*",
     "LICENSE",
     "README.md",
     "examples/"

package/examples/artifact-groups/README.md

@@ -1,60 +0,0 @@
-# Default image tool and Artifact groups
-
-The `effect` document and `preview` image are independent Artifacts. `explosion` is a group referencing both IDs, with no path or type. Tools for the document and image are explicitly registered. This example is a static sample, not an actual VFX asset.
-
-- `preview-review`: Evaluates one image. Only `view_image_preview` is supplied.
-- `explosion-review`: Evaluates the group. `read_effect` and `view_image_preview` are supplied. Tools are not duplicated when `preview` is both a member and a dependency.
-- `explosion-human`: Opens the group's document and image in desktop applications, then accepts a submitted verdict.
-
-In a full Run, both group Critics must wait for the image review to pass because of explicit `deps: ['preview']`. Membership alone does not require prior evaluation. Once both group Critics are GREEN, `explosion` is GREEN while `effect` remains unreviewed.
-
-## Running the example
-
-Install the three v3.1.0 packages on Node 22 LTS (22.19.0 or later). The following command works after npm publication; before that, use the local source build below. Start in the CCDD source repository and copy the example into a new project outside it.
-
-```sh
-CCDD_EXAMPLE_ROOT=$(mktemp -d /tmp/ccdd-groups.XXXXXX)
-cp -R examples/artifact-groups "$CCDD_EXAMPLE_ROOT/project"
-cd "$CCDD_EXAMPLE_ROOT/project"
-npm init -y
-npm pkg set type=module
-npm install --ignore-scripts @ccdd/core@3.1.0 @ccdd/project@3.1.0 @ccdd/default-tools@3.1.0
-
-# Check group member tool readiness without calling a Provider.
-npx ccdd tools check --artifact explosion --for agent
-# Select an individual Artifact for actual image reading.
-npx ccdd tools check --artifact preview --for agent --tool view_image --execute
-
-# Review one Critic; this legacy command skips waiting for prerequisite verdicts.
-npx ccdd run --copy --critic explosion-review --codex-auth-file "$HOME/.codex/auth.json" --wait
-```
-
-Actual Agent review requires authentication and access to a model supporting image input. See the [reviewer guide](../../docs/reviewers.md) for authentication methods. Tool checks do not call a model. The `--execute` output above includes actual image blocks in base64.
-
-If core is already installed, change the first `cp` source to `node_modules/@ccdd/core/examples/artifact-groups`.
-
-Start a full Run with Human review by registering a local notification:
-
-```sh
-npx ccdd run --copy --human-inbox --codex-auth-file "$HOME/.codex/auth.json"
-npx ccdd monitor
-```
-
-Select a project and Run in the monitor, then click the group node in Graph to inspect its members. Claim the Human request, click `{explosion}`, execute each member's `open` tool, and submit a verdict with evidence. Default desktop opening targets macOS; explicitly register an executable on other operating systems.
-
-`view_image` reuses Pi `read` image results. It detects PNG/JPEG/WebP from file content, with a 4MiB limit. GIF, BMP, animated PNG, and text results fail; no automatic conversion or resizing occurs. When registered on a directory Artifact, pass an internal path such as `{"path":"frames/preview.png"}`.
-
-## Using a local source build
-
-To test modified source, prepare three tarballs in the CCDD repository:
-
-```sh
-npm ci
-npm run build
-CCDD_LOCAL_PACKAGES=$(mktemp -d /tmp/ccdd-group-packages.XXXXXX)
-npm pack --ignore-scripts --pack-destination "$CCDD_LOCAL_PACKAGES"
-npm pack --ignore-scripts --workspace @ccdd/project --pack-destination "$CCDD_LOCAL_PACKAGES"
-npm pack --ignore-scripts --workspace @ccdd/default-tools --pack-destination "$CCDD_LOCAL_PACKAGES"
-```
-
-In the same shell, create the new example project from the steps above, then replace the npm version installation with `npm install --ignore-scripts "$CCDD_LOCAL_PACKAGES"/*.tgz`. Subsequent tool checks and review commands are the same. To also run the full test suite and separate installation checks on source fixed to a commit, use `--dry-run` with the [local Release command](../../docs/releases.md#releasing-a-specific-commit-locally).

package/examples/artifact-groups/ccdd.config.ts

@@ -1,37 +0,0 @@
-import { defineConfig } from '@ccdd/core';
-import { agent, human } from '@ccdd/default-tools';
-
-export default defineConfig({
-  artifacts: {
-    effect: { type: 'markdown', path: 'effect.md' },
-    preview: { type: 'image', path: 'preview.png' },
-    explosion: { kind: 'group', members: ['effect', 'preview'] },
-  },
-  artifactTypes: {
-    markdown: {
-      agentTools: { read: agent.text.read() },
-      humanTools: { open: human.desktop.open() },
-    },
-    image: {
-      agentTools: { view_image: agent.image.view() },
-      humanTools: { open: human.desktop.open() },
-    },
-  },
-  critics: [
-    {
-      id: 'preview-review', title: 'Image visibility', target: 'preview', deps: [],
-      profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-      payload: { instruction: 'Check whether {preview} has a bright center and an orange ring distinguishable from the dark background. Review the image itself; matching the effect specification is outside this review.' },
-    },
-    {
-      id: 'explosion-review', title: 'Match the effect description and preview', target: 'explosion', deps: ['preview'],
-      profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-      payload: { instruction: 'Observe every member of {explosion} and evaluate whether {preview} matches the static appearance specified in {effect}. Animation timing and actual VFX runtime behavior are outside the scope of this static example.' },
-    },
-    {
-      id: 'explosion-human', title: 'Review the group on the desktop', target: 'explosion', deps: ['preview'],
-      profile: { kind: 'human' },
-      payload: { instruction: 'Open the document and image in {explosion} with their desktop programs, compare them, and submit your verdict.' },
-    },
-  ],
-});

package/examples/custom-text-reader/ccdd.config.ts

@@ -1,64 +0,0 @@
-import { readFile } from 'node:fs/promises';
-import { defineConfig, defineTool } from '@ccdd/core';
-
-// This factory defines a tool. It does not read the Artifact or execute an app.
-function customTextReader() {
-  return defineTool({
-    metadata: {
-      description: 'Read the specified line range from {artifactName}.',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          startLine: { type: 'integer', minimum: 1 },
-          lineCount: { type: 'integer', minimum: 1, maximum: 80 },
-        },
-        required: ['startLine', 'lineCount'],
-        additionalProperties: false,
-      } as const,
-      resultKinds: ['json'],
-      observation: 'content',
-      artifactKind: 'file',
-    },
-    async execute(context, args) {
-      // Deliberately small teaching example: it accepts files up to 1 MiB.
-      const file = await context.resolvePath();
-      const bytes = await readFile(file, { signal: context.signal });
-      if (bytes.length > 1024 * 1024) throw new Error('This example reader supports files up to 1 MiB.');
-      const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
-      if (text.includes('\0')) throw new Error('This example reader accepts text, not binary data.');
-      const lines = text.match(/[^\n]*\n|[^\n]+$/g) ?? [];
-      const offset = args.startLine - 1;
-      const selected = lines.slice(offset, offset + args.lineCount);
-      const content = selected.join('');
-      if (Buffer.byteLength(content) > 64 * 1024) throw new Error('Select a smaller line range.');
-      const nextOffset = offset + selected.length;
-      return {
-        content: [{ type: 'json', data: {
-          content,
-          startLine: args.startLine,
-          endLine: selected.length ? nextOffset : null,
-          lineCount: selected.length,
-          totalLines: lines.length,
-          nextStartLine: nextOffset < lines.length ? nextOffset + 1 : null,
-        } }],
-        ...(selected.length ? { observation: { kind: 'content' as const } }
-          : lines.length === 0 ? { observation: { kind: 'empty' as const } } : {}),
-      };
-    },
-  });
-}
-
-export default defineConfig(() => ({
-  artifactTypes: {
-    document: { agentTools: { read: customTextReader() } },
-  },
-  artifacts: {
-    why: { type: 'document', path: 'why.md', basis: true },
-    spec: { type: 'document', path: 'spec.md' },
-  },
-  critics: [{
-    id: 'spec-why', title: 'Does Spec match Why?', target: 'spec', deps: ['why'],
-    profile: { kind: 'agent', provider: 'openai-codex', model: 'gpt-6-astra', reasoning: 'medium' },
-    payload: { instruction: 'Read both documents and evaluate whether Spec satisfies the maximum task count in Why.' },
-  }],
-}));