@ccdd/core 3.3.1 → 4.1.0

package/examples/artifact-folders/theme-image/ccdd.json

@@ -0,0 +1,128 @@
+{
+  "name": "theme-image",
+  "views": {
+    "agentTools": {
+      "read": {
+        "metadata": {
+          "description": "Inspect {artifactName} with read.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "path"
+            ]
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "read"
+          ]
+        }
+      },
+      "list": {
+        "metadata": {
+          "description": "Inspect {artifactName} with list.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "json"
+          ],
+          "observation": "none",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "list"
+          ]
+        }
+      },
+      "image": {
+        "metadata": {
+          "description": "Inspect {artifactName} with image.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false,
+            "required": [
+              "path"
+            ]
+          },
+          "resultKinds": [
+            "image"
+          ],
+          "observation": "content",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "image"
+          ]
+        }
+      }
+    },
+    "humanTools": {
+      "open": {
+        "metadata": {
+          "description": "Inspect {artifactName} with open.",
+          "inputSchema": {
+            "type": "object",
+            "properties": {
+              "path": {
+                "type": "string"
+              }
+            },
+            "additionalProperties": false
+          },
+          "resultKinds": [
+            "launch"
+          ],
+          "observation": "none",
+          "executionPaths": [
+            "node_modules/@ccdd/core/dist",
+            "node_modules/@ccdd/default-tools/dist"
+          ]
+        },
+        "script": {
+          "command": "ccdd-view",
+          "args": [
+            "open"
+          ]
+        }
+      }
+    }
+  },
+  "basis": true
+}

package/examples/computed-views/README.md

@@ -0,0 +1,12 @@
+# Computed views
+
+Each scenario is an actual Artifact folder with its own `ccdd.json`. `view.mjs` computes an overview or selects one detail when the reviewer calls its registered tool. CCDD does not generate or freeze JSON data during discovery.
+
+```sh
+ccdd-project config check
+ccdd-project tools check --artifact checkout --for human --tool overview --execute
+ccdd-project verify checkout --human-inbox
+ccdd-project monitor
+```
+
+Run these commands from this directory after installing `@ccdd/core` and `@ccdd/project`. Submit the Human verdict explicitly through the monitor. Scenario files, the manifest and the shared script determine input identity. Output belongs in `context.outputDir`, outside the supplied workspace. Parameter combinations that generate Artifact declarations are not supported in version 4.

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.1",
+  "version": "4.1.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/"