@ccdd/core 6.5.0 → 6.6.0

package/README.md

@@ -85,6 +85,7 @@ Reviews run in the workspace you supply. Keep it unchanged until completion, inc
 - [Register optional text, image and desktop tools](packages/default-tools/README.md).
 - [Compose folders and mounts](examples/artifact-folders/README.md), including coding-style and blind image comparison Critics.
 - [Compute views on demand](examples/computed-views/README.md) from scenario material.
+- [Declare an Artifact family](examples/artifact-families/README.md): many Artifacts sharing one folder, script and Critic.
 - [Design reviewer tools](docs/reviewer-tools.md) that return only what the reviewer requests.
 - [Configure Agent and Human reviewers](docs/reviewers.md).
 - [Try Why → Spec → Tests → Implementation](docs/demo.md).
@@ -105,7 +106,7 @@ See [Contributing](CONTRIBUTING.md), [the context map](CONTEXT-MAP.md), [detaile
 
 [MIT](LICENSE).
 
-**CCDD 6.5.0:** opt-in review budgets (`maxToolCalls`, `maxTokens`) and a bounded tool-call record for reviews that end in ERROR; existing review identities are unchanged unless a profile sets a budget. See the [release notes](docs/releases/v6.5.0.md).
+**CCDD 6.6.0:** Artifact families declare many Artifacts that share one folder, view scripts and Critics through a static instance list, with per-instance identities so siblings never invalidate each other. Pi is updated to 1.0.0; existing review identities are unchanged. See the [release notes](docs/releases/v6.6.0.md).
 
 
 ### Existing Pi AI API

package/dist/src/artifact-scope.js

@@ -21,6 +21,12 @@ export function resolveScopePath(scope, artifactId, path = '') {
             remaining = remaining.slice(child.length).replace(/^\//, '');
             continue;
         }
+        // A family folder belongs to its instances, not to the parent: address it as <folder>/<instance>/<path>.
+        for (const [name, id] of Object.entries(entry.children)) {
+            const folder = name.slice(0, -id.length - 1);
+            if (scope[id]?.family && name.endsWith(`/${id}`) && (remaining === folder || remaining.startsWith(`${folder}/`)))
+                throw new Error(`Artifact path is inside the folder of Artifact family ${scope[id].family.name}; address one of its instances as ${folder}/<instance>/<path>.`);
+        }
         return { artifactId: current, path: remaining };
     }
 }

package/dist/src/artifact-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-scope.js","sourceRoot":"","sources":["../../src/artifact-scope.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,UAAkB,EAAE,IAAI,GAAG,EAAE;IAClF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC7Q,IAAI,OAAO,GAAG,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC;QACR,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACnG,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QACxG,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;QAC/G,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAAC,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACrI,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;AACH,CAAC"}
+{"version":3,"file":"artifact-scope.js","sourceRoot":"","sources":["../../src/artifact-scope.ts"],"names":[],"mappings":"AAEA,sFAAsF;AACtF,MAAM,UAAU,gBAAgB,CAAC,KAAoB,EAAE,UAAkB,EAAE,IAAI,GAAG,EAAE;IAClF,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,KAAK,EAAE,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IAC7Q,IAAI,OAAO,GAAG,UAAU,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3C,SAAS,CAAC;QACR,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,OAAO,EAAE,CAAC,CAAC;QACnG,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;QAC7B,IAAI,CAAC,SAAS;YAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC;QACzD,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;YACvC,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QACxG,CAAC;QACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC;QAC/G,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YAAC,OAAO,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAAC,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAAC,SAAS;QAAC,CAAC;QACrI,yGAAyG;QACzG,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;YACxD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,MAAM,IAAI,SAAS,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,yDAAyD,KAAK,CAAC,EAAE,CAAC,CAAC,MAAO,CAAC,IAAI,qCAAqC,MAAM,qBAAqB,CAAC,CAAC;QACrR,CAAC;QACD,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAClD,CAAC;AACH,CAAC"}

package/dist/src/definitions.d.ts

@@ -54,6 +54,21 @@ export interface ReviewPolicy {
     dependencyGates?: 'green' | 'ignore';
     maxConcurrentExecutors?: number;
 }
+/**
+ * One statically listed member of an Artifact family. Its params, merged shallowly over the family
+ * defaults and its named variant, fill `{"$param": "/pointer"}` values in the shared views and Critics.
+ */
+export interface ArtifactInstanceDeclaration {
+    variant?: string;
+    params?: Record<string, unknown>;
+    material?: string[];
+}
+/** Instances are listed inline or in an owner-relative JSON file; discovery reads them and executes nothing. */
+export interface ArtifactFamilyDeclaration {
+    instances: string | Record<string, ArtifactInstanceDeclaration>;
+    params?: Record<string, unknown>;
+    variants?: Record<string, Record<string, unknown>>;
+}
 export interface ArtifactManifest {
     name: string;
     critics?: CriticDefinition[];
@@ -63,18 +78,31 @@ export interface ArtifactManifest {
     basis?: boolean;
     stale?: StaleStrategy;
     envRequirements?: Record<string, EnvironmentRequirement>;
+    /** Declares several Artifacts that share this folder, its views and its Critics. `name` then names the family. */
+    family?: ArtifactFamilyDeclaration;
+}
+/** How an instance Artifact belongs to its family. Paths are relative to the shared family folder. */
+export interface ArtifactFamilyMembership {
+    name: string;
+    /** The static instance list file, when the list is not inline. */
+    instances?: string;
+    /** Material that only this instance's identity covers; other instances exclude it. */
+    material: string[];
+    /** Hash of this instance's static entry: its params and material list. */
+    entry: string;
 }
 export interface ArtifactDefinition {
     name: string;
     path: string;
     views: ArtifactViews;
     mounts: Record<string, string>;
-    /** Nearest marked descendants, indexed by their physical relative paths. */
+    /** Nearest marked descendants, indexed by their physical relative paths; a family instance is keyed `<family folder>/<instance>`. */
     children: Record<string, string>;
     reviewPolicy?: ReviewPolicy;
     basis?: boolean;
     stale?: StaleStrategy;
     envRequirements?: Record<string, EnvironmentRequirement>;
+    family?: ArtifactFamilyMembership;
 }
 export interface ResolvedCriticDefinition extends CriticDefinition {
     localId: string;
@@ -94,5 +122,9 @@ export interface ArtifactScopeEntry {
     path: string;
     children: Record<string, string>;
     mounts: Record<string, string>;
+    family?: {
+        name: string;
+        material: string[];
+    };
 }
 export type ArtifactScope = Record<string, ArtifactScopeEntry>;

package/examples/artifact-families/README.md

@@ -0,0 +1,22 @@
+# Artifact families
+
+`scenarios/ccdd.json` declares the family `scenarios`: one folder, one view script and one Critic shared by the Artifacts listed in `scenarios/instances.json`. Each listed name, `checkout` and `search`, is an ordinary Artifact with its own Critic `checkout/review` or `search/review`, its own evidence and its own place in the graph.
+
+An instance entry has two optional parts:
+
+- `params` fill every `{"$param": "/json/pointer"}` value in the shared views and Critics. Here each instance gets its own `detail` input enum and its own instruction. Parameters are copied as JSON; nothing is evaluated.
+  Values shared by many instances can live in `family.params` (defaults) or `family.variants` (named sets an entry selects with `"variant"`); an entry's own `params` win, key by key.
+- `material` lists the files that belong to that instance alone; they must exist. The view script finds them in `context.scope[context.artifactId].family.material`.
+
+Editing `checkout.json` or the `checkout` entry invalidates only `checkout`'s review. Adding a new instance with its own material leaves existing reviews current. Editing the shared `ccdd.json`, `view.mjs` or any unlisted file invalidates every instance. Discovery only reads `instances.json`; an authoring tool may write that file, but CCDD never runs code to produce it.
+
+Run these commands from this directory after installing `@ccdd/ccdd`:
+
+```sh
+ccdd-project config check
+ccdd-project tools check --artifact checkout --for agent --tool detail --execute --args '{"id":"summary"}'
+ccdd-project verify --all --human-inbox
+ccdd-project monitor
+```
+
+The monitor shows the family as one node; select it to list its instances and their Critics, or expand it into instance nodes. Submit the Human verdicts explicitly through the monitor. See [the Artifact family contract](../../docs/contracts.md#artifact-families).

package/examples/artifact-families/scenarios/ccdd.json

@@ -0,0 +1,66 @@
+{
+  "name": "scenarios",
+  "family": {
+    "instances": "instances.json"
+  },
+  "views": {
+    "agentTools": {
+      "overview": {
+        "metadata": {
+          "description": "Read the objective, criteria and detail IDs of {artifactName}.",
+          "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
+          "resultKinds": ["json"],
+          "observation": "content"
+        },
+        "script": { "command": "node", "args": ["view.mjs", "overview"] }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Read one observed detail of {artifactName}.",
+          "inputSchema": {
+            "type": "object",
+            "properties": { "id": { "type": "string", "enum": { "$param": "/detailIds" } } },
+            "required": ["id"],
+            "additionalProperties": false
+          },
+          "resultKinds": ["json"],
+          "observation": "content"
+        },
+        "script": { "command": "node", "args": ["view.mjs", "detail"] }
+      }
+    },
+    "humanTools": {
+      "overview": {
+        "metadata": {
+          "description": "Read the objective, criteria and detail IDs of {artifactName}.",
+          "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false },
+          "resultKinds": ["json"],
+          "observation": "content"
+        },
+        "script": { "command": "node", "args": ["view.mjs", "overview"] }
+      },
+      "detail": {
+        "metadata": {
+          "description": "Read one observed detail of {artifactName}.",
+          "inputSchema": {
+            "type": "object",
+            "properties": { "id": { "type": "string", "enum": { "$param": "/detailIds" } } },
+            "required": ["id"],
+            "additionalProperties": false
+          },
+          "resultKinds": ["json"],
+          "observation": "content"
+        },
+        "script": { "command": "node", "args": ["view.mjs", "detail"] }
+      }
+    }
+  },
+  "critics": [
+    {
+      "id": "review",
+      "title": "Review the scenario",
+      "profile": { "kind": "human" },
+      "payload": { "instruction": { "$param": "/instruction" } }
+    }
+  ]
+}

package/examples/artifact-families/scenarios/checkout.json

@@ -0,0 +1,12 @@
+{
+  "name": "Guest checkout",
+  "objective": "A guest can review the total before placing an order.",
+  "criteria": [
+    "The order summary shows both shipping and the final total.",
+    "The guest can return to the cart before placing the order."
+  ],
+  "details": [
+    { "id": "summary", "observation": "The summary shows items at $20, shipping at $5, and a final total of $25." },
+    { "id": "navigation", "observation": "A Back to cart link appears beside the Place order button." }
+  ]
+}

package/examples/artifact-families/scenarios/instances.json

@@ -0,0 +1,16 @@
+{
+  "checkout": {
+    "params": {
+      "detailIds": ["summary", "navigation"],
+      "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."
+    },
+    "material": ["checkout.json"]
+  },
+  "search": {
+    "params": {
+      "detailIds": ["message", "query"],
+      "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."
+    },
+    "material": ["search.json"]
+  }
+}

package/examples/artifact-families/scenarios/search.json

@@ -0,0 +1,12 @@
+{
+  "name": "Empty search results",
+  "objective": "A user can recover from a search that finds no items.",
+  "criteria": [
+    "The result view states that no items match the search.",
+    "The user can change the query without leaving the result view."
+  ],
+  "details": [
+    { "id": "message", "observation": "The result heading reads No matching items." },
+    { "id": "query", "observation": "The original query remains in an editable search field above the heading." }
+  ]
+}

package/examples/artifact-families/scenarios/view.mjs

@@ -0,0 +1,16 @@
+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.');
+// Every instance shares this folder and script; each one names its own material.
+const [file] = context.scope[context.artifactId].family?.material ?? [];
+if (!file) throw new Error('This view serves Artifact family instances.');
+const scenario = JSON.parse(await readFile(join(context.artifactPath, file), '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/computed-views/README.md

@@ -9,4 +9,4 @@ ccdd-project verify checkout --human-inbox
 ccdd-project monitor
 ```
 
-Run these commands from this directory after installing `@ccdd/ccdd`. 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.
+Run these commands from this directory after installing `@ccdd/ccdd`. 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. When many scenarios share one script and Critic, the [Artifact family example](../artifact-families/README.md) declares them once with a static instance list instead of one folder each.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ccdd/core",
-  "version": "6.5.0",
+  "version": "6.6.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -55,8 +55,8 @@
     "examples/"
   ],
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.99.1",
-    "@earendil-works/pi-ai": "0.99.1",
+    "@earendil-works/pi-agent-core": "1.0.0",
+    "@earendil-works/pi-ai": "1.0.0",
     "@lucide/vue": "1.41.0",
     "@vue-flow/background": "1.3.2",
     "@vue-flow/core": "1.48.2",