@open-agent-toolkit/cli 0.2.10 → 0.2.12

package/assets/docs/cli-utilities/configuration.md

@@ -106,18 +106,19 @@ The `oat-explainer-kit` adapter owns two typed config groups. Build and publish
 plumbing uses `explainers.*`; project lifecycle preferences use
 `workflow.explainers.*`.
 
-| Key                                    | Type                 | Stored scopes       | Default   |
-| -------------------------------------- | -------------------- | ------------------- | --------- |
-| `explainers.defaults.palette`          | non-empty string     | local, shared, user | `neutral` |
-| `explainers.defaults.visualProfile`    | non-empty string     | local, shared, user | `clean`   |
-| `explainers.defaults.themeBundlePath`  | path                 | local, shared       | unset     |
-| `explainers.publish.provider`          | `s3-static`          | shared              | unset     |
-| `explainers.publish.s3Uri`             | `s3://` URI          | shared              | unset     |
-| `explainers.publish.publicBaseUrl`     | HTTPS URL            | shared              | unset     |
-| `explainers.publish.awsRegion`         | non-empty string     | shared              | unset     |
-| `explainers.publish.awsProfile`        | non-empty string     | local, user         | unset     |
-| `workflow.explainers.projectExplainer` | `always\|ask\|never` | local, shared, user | `ask`     |
-| `workflow.explainers.projectRecap`     | `always\|ask\|never` | local, shared, user | `ask`     |
+| Key                                    | Type                         | Stored scopes       | Default         |
+| -------------------------------------- | ---------------------------- | ------------------- | --------------- |
+| `explainers.defaults.style`            | curated style name           | local, shared, user | `clean-neutral` |
+| `explainers.defaults.palette`          | nullable string (deprecated) | local, shared, user | `null`          |
+| `explainers.defaults.visualProfile`    | nullable string (deprecated) | local, shared, user | `null`          |
+| `explainers.defaults.themeBundlePath`  | path                         | local, shared       | unset           |
+| `explainers.publish.provider`          | `s3-static`                  | shared              | unset           |
+| `explainers.publish.s3Uri`             | `s3://` URI                  | shared              | unset           |
+| `explainers.publish.publicBaseUrl`     | HTTPS URL                    | shared              | unset           |
+| `explainers.publish.awsRegion`         | non-empty string             | shared              | unset           |
+| `explainers.publish.awsProfile`        | non-empty string             | local, user         | unset           |
+| `workflow.explainers.projectExplainer` | `always\|ask\|never`         | local, shared, user | `ask`           |
+| `workflow.explainers.projectRecap`     | `always\|ask\|never`         | local, shared, user | `ask`           |
 
 Stored values resolve `local > shared > user > default` where the key permits
 each scope. Explicit runtime inputs take precedence for one invocation without
@@ -125,10 +126,23 @@ mutating stored config. Use `oat config get <key> --json` to inspect both the
 resolved value and its source, and `oat config describe <key>` for its exact
 scope and type contract.
 
+For example:
+
+```bash
+oat config set explainers.defaults.style navy-ocean --shared
+oat config get explainers.defaults.style --json
+oat config describe explainers.defaults.style
+```
+
 Shared theme-bundle paths must be repository-relative. Local paths may be
 repository-relative or absolute; user config cannot set a theme-bundle path.
-A supplied bundle takes precedence over named palette and profile defaults and
-produces a warning.
+A supplied bundle takes precedence over all named selections. Otherwise choose
+one of `clean-neutral`, `business-corporate`, `navy-ocean`, or `dark-edgy` with
+`explainers.defaults.style`. An explicit style takes precedence over legacy
+`palette` and `visualProfile` values. Those matrix fields remain available for
+advanced compatibility but emit deprecation warnings. When no source explicitly
+selects a theme, the core uses `clean-neutral` and records a visible fallback
+warning.
 
 Publishing remains build-only when `explainers.publish.provider` is unset.
 When it is `s3-static`, `s3Uri`, `publicBaseUrl`, and `awsRegion` are all

package/assets/docs/reference/cli-reference.md

@@ -64,7 +64,7 @@ Notable commands introduced in the current CLI surface:
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
-- `oat project archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
+- `oat project archive [project-path] [--project-recap-run <project-relative-path>]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).

package/assets/docs/workflows/projects/artifacts.md

@@ -44,13 +44,25 @@ different retention contracts:
 - A selected final `project-recap` is a durable completion record. Before a
   shared project is removed, archive copies the complete selected run to
   `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies its
-  manifest artifact hashes, and reports that tracked export path. Summary and
-  PR links use this export, never the gitignored local archive.
+  immutable package hashes, and reports that tracked export path. Summary and
+  PR links use this export, never the gitignored local archive. Lifecycle
+  callers identify the selected project-relative run with:
+
+  ```bash
+  oat project archive <project-path> \
+    --project-recap-run explainers/<recap-slug>
+  ```
 
 The archive exports at most one selected recap package. It preserves structured
 failure outcomes and successful intermediates, rejects an existing dated
-destination, and fails before deleting the active project if copy or hash
-verification fails.
+destination, and requires the selected path to stay under the project's
+`explainers/` directory with a `project-recap` manifest. Verification covers
+the exact retained bytes for the privacy-safe request, content approval, fact
+base JSON and Markdown, declared author results, authored Markdown, resolved
+theme, and every built artifact. Canonical fact-base and theme hashes remain
+normalized-object identities; `manifest.immutableHashes` independently covers
+serialized file bytes. Missing, stale, or tampered coverage fails before the
+active project is deleted.
 
 Local-scope projects are not archived through this export path. Their explainer
 packages inherit the local project's untracked posture and remain

package/assets/docs/workflows/skills/explainer-kit.md

@@ -20,38 +20,81 @@ OAT lifecycle callers use the adapter.
 
 ## Recipes
 
-The v1 project recipes serve different lifecycle jobs:
-
-| Recipe              | Lifecycle use                                      | Required narrative                                                                                                    |
-| ------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `project-explainer` | Working explanation after project planning         | planned architecture, decisions, risks, phases, and validation approach                                               |
-| `project-recap`     | Final record after implementation and final review | original request, key agent decisions, as-built architecture, implementation record, validation evidence, and outcome |
-
-Both recipes bind one project source set. The adapter binds `plan.md`,
-`design.md`, and `spec.md` for a project explainer; a project recap can also
-include `implementation.md` and `summary.md`.
-
-## Themes
-
-Every artifact set uses one resolved theme. The bundled defaults are the
-`neutral` palette and `clean` visual profile. The core also ships the `ocean`,
-`ember`, `forest`, and `violet` palettes plus `editorial` and `technical`
-profiles.
-
-A caller may select named palette/profile values, supply a validated theme
-bundle, or provide per-run art direction. A supplied bundle takes precedence
-over named selections. The resolved concrete bundle is retained with the run;
-raw art-direction text is not retained by default. Themes contain validated
-light and dark modes, while the render strategy chooses either the default mode
-or a user-switchable result.
+The core ships four versioned recipes:
+
+| Recipe              | Use                                                    | Required narrative                                                                                                    |
+| ------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `project-explainer` | Working explanation after project planning             | planned architecture, decisions, risks, phases, and validation approach                                               |
+| `project-recap`     | Final record after implementation and final review     | original request, key agent decisions, as-built architecture, implementation record, validation evidence, and outcome |
+| `program-recap`     | Bird's-eye record of a multi-wave delivery program     | program overview, wave map and outcomes, convention evolution, aggregate numbers, and follow-up ledger                |
+| `engineer-tour`     | Engineer-facing orientation to a codebase and its flow | orientation, architecture, execution flow, key code, and validation                                                   |
+
+The OAT project lifecycle owns `project-explainer` and `project-recap`. Both
+bind one project source set. The adapter binds `plan.md`, `design.md`, and
+`spec.md` for a project explainer; a project recap can also include
+`implementation.md` and `summary.md`. Wave callers supply the program source
+set for `program-recap`; direct core callers can use `engineer-tour` without
+adding an OAT dependency.
+
+## Content authoring and review
+
+Every unattended run requires one provider-neutral author. The core invokes
+the author once per recipe artifact with the exact narrative outline,
+reconciled fact base, and bounded-discovery context. It accepts only a
+schema-valid result with the required section IDs, substantive prose, and
+non-secret provenance. Each section is checked independently for excessive
+verbatim overlap with the fact base so one copied section cannot be hidden by
+otherwise original prose.
+
+In-process core callers supply `options.author`; core CLI callers use
+`--author-module`. The OAT adapter accepts either an in-process `author` or an
+`authorModulePath` and rejects zero or two seams for unattended runs before it
+invokes the core. Callback and module paths are transient. Validated results
+are retained under `source/author/` and covered by the run's immutable hashes.
+
+Interactive runs may omit an author. They pause after writing
+`source/content/*.md`, require an explicit content-review decision, and resume
+the same run only after approval. Content approval never authorizes publishing.
+
+## Curated styles and themes
+
+Every artifact set uses one resolved theme. The primary selection surface is
+one of four complete curated styles:
+
+- `clean-neutral` — restrained neutral default
+- `business-corporate` — structured corporate presentation
+- `navy-ocean` — navy-led technical and operational presentation
+- `dark-edgy` — solid dark canvas with high-contrast editorial accents
+
+A caller may select a style, supply a validated theme bundle, or provide
+per-run art direction. A supplied bundle takes precedence over a style. Legacy
+`palette` and `visualProfile` inputs remain nullable compatibility fields, but
+an explicit style wins and legacy use emits a deprecation warning. When no
+selection is explicit, the core uses `clean-neutral` and records the fallback.
+
+The resolved concrete bundle is retained with the run; raw art-direction text
+is not retained by default. Every bundle contains validated light and dark
+modes. The render strategy chooses either the default mode or a user-switchable
+result without changing the bundle identity.
 
 ## Build, durability, and publish
 
 Missing publish configuration means build-only. A completed build writes the
-source package, resolved theme, `manifest.json`, `build-record.json`, and the
-rendered `site/` tree. Rendering or publishing failures preserve successful
+privacy-safe request, content approval, fact base, author results, authored
+content, resolved theme, `manifest.json`, `build-record.json`, and the rendered
+`site/` tree. Rendering or publishing failures preserve successful
 intermediates and recovery information.
 
+`manifest.immutableHashes` covers the exact retained bytes for
+`run-request.json`, content approval, fact-base JSON and Markdown, declared
+author results, authored Markdown, the resolved theme, and every built
+artifact. Canonical fact-base and theme hashes identify normalized objects;
+they are intentionally distinct from serialized file-byte hashes. The mutable
+manifest and build record are excluded from their own durability evidence and
+are committed separately after verification. Older v1 manifests without
+complete coverage fail with a legacy-manifest diagnostic and must be
+regenerated.
+
 Build success and durability are separate:
 
 - `built-not-durable` means artifacts exist but verified commit or publish
@@ -69,7 +112,7 @@ content type and SHA-256 response bytes at public URLs, and writes
 fragments. Publishing is additive and does not run a root-wide destructive
 sync.
 
-Release validation drives the bounded palette/profile/template matrix in a real
+Release validation drives the bounded curated-style/template matrix in a real
 installed Chromium browser and retains machine-readable viewport, clipping,
 motion, keyboard, no-JavaScript, and print measurements. The gate fails closed
 when no supported browser executable is available.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.10",
-  "docs-config": "0.2.10",
-  "docs-theme": "0.2.10",
-  "docs-transforms": "0.2.10"
+  "cli": "0.2.12",
+  "docs-config": "0.2.12",
+  "docs-theme": "0.2.12",
+  "docs-transforms": "0.2.12"
 }

package/assets/skills/explainer-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 1.0.1
+version: 1.0.2
 description: Use when building destination-neutral visual explainer artifacts from explicit, versioned inputs.
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Grep, Glob, Agent, mcp__*
@@ -58,8 +58,14 @@ require a provider-neutral critic callback and invoke it exactly once.
 Optional claim `sections` tags route facts to matching recipe narrative
 sections; untagged claims remain shared context for every required section.
 
-Unattended calls use explicit, already-approved source artifacts, persist their
-review provenance in `source/content-approval.json`, and never prompt.
+Unattended calls use explicit, already-approved source artifacts and require a
+provider-neutral author callback once per recipe artifact. In-process callers
+supply `options.author`; JSON-only CLI callers supply `--author-module`. The
+core validates exact narrative sections and non-secret author provenance,
+rejects excessive verbatim source overlap, retains each validated result under
+`source/author/`, persists review provenance in
+`source/content-approval.json`, and never prompts. Keep executable callback
+references out of the persisted run request.
 
 Interactive runs stop with an `incomplete` outcome after writing
 `source/content/*.md`. Review and correct that Markdown, then provide an

package/assets/skills/explainer-kit/references/contracts.md

@@ -30,6 +30,14 @@ claims, sources, overrides, and the freshness policy. It returns:
 No provider name, command, credential, or dispatch protocol is part of this
 contract.
 
+Every unattended run also requires a provider-neutral author callback. An
+in-process caller supplies `options.author(request)`; a JSON-only CLI caller
+uses `--author-module author.mjs`. The core invokes it once per recipe artifact
+with an `AuthorRequestV1` containing the exact narrative outline, reconciled
+fact base, and bounded-discovery context. It must return an `AuthorResultV1`
+with every required section in order, non-empty prose, and non-secret
+provenance. The executable callback is never persisted in `run-request.json`.
+
 ## Explicit source forms
 
 - `factBase.mode: supplied` points to a valid `FactBaseV1` JSON file. The core
@@ -47,8 +55,9 @@ contract.
   reconciles the loaded claims and invokes the critic exactly once.
 
 An unattended request asserts that its explicit source artifacts are already
-approved. It does not prompt. Interactive review and same-run approval/resume
-are introduced separately and are not part of this contract.
+approved. It does not prompt, and it fails before narrative serialization when
+the author is absent, returns an invalid result, or copies excessive verbatim
+source text. Interactive review and same-run approval/resume remain unchanged.
 
 ## Pipeline and retained package
 
@@ -56,14 +65,16 @@ The core executes:
 
 1. validate request and recipe
 2. reconcile or check the fact base
-3. apply bounded discovery and create recipe content
+3. apply bounded discovery and obtain or create recipe content
 4. resolve one theme
 5. render typed artifacts
 6. run structural and optional browser QA
 7. write the manifest and build record
 
-The run package retains `source/fact-base.json`, `source/fact-base.md`,
-`source/content/*.md`, `theme.resolved.json`, rendered `site/` files,
+The run package retains the privacy-safe `run-request.json`,
+`source/content-approval.json`, `source/fact-base.json`,
+`source/fact-base.md`, `source/content/*.md`, optional structured
+`source/author/*.json` results, `theme.resolved.json`, rendered `site/` files,
 `manifest.json`, and `build-record.json` as far as each stage succeeds. A stage
 failure records a structured error and recovery action without deleting earlier
 outputs. Raw art direction is omitted unless the request explicitly opts in.
@@ -81,9 +92,13 @@ Durability and publishing are never implicit.
   Caller-created commit evidence is subsequently verified with
   `record-durability.mjs`; the core never creates commits. The first evidence
   commit must contain every path and byte hash in `manifest.immutableHashes`:
-  fact-base JSON and Markdown, all content Markdown, the resolved theme, and
-  every built artifact retained in the package. Mutable `manifest.json` and
+  the privacy-safe request, content approval, fact-base JSON and Markdown,
+  declared author results, all content Markdown, the resolved theme, and every
+  built artifact retained in the package. Mutable `manifest.json` and
   `build-record.json` remain excluded for the separate evidence update.
+  Schema-v1 manifests created before complete-package coverage are rejected
+  with a legacy-manifest diagnostic and must be regenerated; validators never
+  invent missing hashes.
 - `durability.strategy: publish` invokes the explicit `publish` callback with
   the complete publish request. A verified receipt is subsequently recorded as
   durability evidence.

package/assets/skills/explainer-kit/schemas/author-request.schema.json

@@ -0,0 +1,85 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.author-request/v1",
+  "title": "AuthorRequestV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "run",
+    "recipe",
+    "artifact",
+    "narrativeOutline",
+    "factBase",
+    "discovery"
+  ],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.author-request/v1" },
+    "run": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["runId", "slug"],
+      "properties": {
+        "runId": { "type": "string", "minLength": 1 },
+        "slug": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+        }
+      }
+    },
+    "recipe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "version", "requiredNarrative"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "requiredNarrative": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "enum": ["hub", "diagram", "explainer", "deck", "catalog"] }
+      }
+    },
+    "narrativeOutline": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "title"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 }
+        }
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "factBase": { "$ref": "explainer-kit.fact-base/v1" },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["rounds", "findings", "reason"],
+      "properties": {
+        "rounds": { "type": "integer", "minimum": 0 },
+        "findings": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "reason": {
+          "enum": ["not-requested", "two-empty-rounds", "hard-maximum"]
+        }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/author-result.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "explainer-kit.author-result/v1",
+  "title": "AuthorResultV1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "artifactId", "content", "provenance"],
+  "properties": {
+    "schemaVersion": { "const": "explainer-kit.author-result/v1" },
+    "artifactId": { "type": "string", "minLength": 1 },
+    "content": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title", "description", "sections"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "description": { "type": "string", "minLength": 1 },
+        "eyebrow": { "type": "string", "minLength": 1 },
+        "footer": { "type": "string", "minLength": 1 },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "title", "prose"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "title": { "type": "string", "minLength": 1 },
+              "prose": { "type": "string", "minLength": 1 }
+            }
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "artifactLinks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "type", "label"],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "type": {
+                "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+              },
+              "label": { "type": "string", "minLength": 1 }
+            }
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "provenance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authorId", "generatedAt"],
+      "properties": {
+        "authorId": { "type": "string", "minLength": 1 },
+        "generatedAt": { "type": "string", "format": "date-time" },
+        "method": { "type": "string", "minLength": 1 },
+        "model": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/assets/skills/explainer-kit/schemas/manifest.schema.json

@@ -43,7 +43,13 @@
         "factBasePath": { "$ref": "#/$defs/safeRelativePath" },
         "factBaseHash": { "$ref": "#/$defs/hash" },
         "sourceRevision": { "type": "string", "minLength": 1 },
-        "inputHashes": { "$ref": "#/$defs/hashMap" }
+        "inputHashes": { "$ref": "#/$defs/hashMap" },
+        "authorResultPaths": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/safeRelativePath" },
+          "minItems": 1,
+          "uniqueItems": true
+        }
       }
     },
     "theme": {

package/assets/skills/explainer-kit/schemas/run-request.schema.json

@@ -115,6 +115,14 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "style": {
+          "enum": [
+            "clean-neutral",
+            "business-corporate",
+            "navy-ocean",
+            "dark-edgy"
+          ]
+        },
         "palette": { "type": "string", "minLength": 1 },
         "visualProfile": { "type": "string", "minLength": 1 },
         "suppliedBundlePath": {

package/assets/skills/explainer-kit/schemas/theme.schema.json

@@ -178,6 +178,14 @@
       "additionalProperties": false,
       "required": ["derived"],
       "properties": {
+        "style": {
+          "enum": [
+            "clean-neutral",
+            "business-corporate",
+            "navy-ocean",
+            "dark-edgy"
+          ]
+        },
         "palette": { "type": "string", "minLength": 1 },
         "visualProfile": { "type": "string", "minLength": 1 },
         "derived": { "type": "boolean" },

package/assets/skills/explainer-kit/scripts/lib/content-approval.mjs

@@ -12,7 +12,12 @@ const DECISIONS = new Map([
   ['rejected', 'rejected'],
 ]);
 
-export async function resolveContentApproval(run, mode, reviewedSource) {
+export async function resolveContentApproval(
+  run,
+  mode,
+  reviewedSource,
+  authorResultPaths,
+) {
   assertRun(run);
   if (!MODES.has(mode)) {
     throw new Error('Content approval mode must be interactive or unattended.');
@@ -21,6 +26,7 @@ export async function resolveContentApproval(run, mode, reviewedSource) {
   const previous = await readPrevious(run);
   let record;
   if (mode === 'unattended') {
+    assertAuthorResultPaths(authorResultPaths);
     const provenance =
       reviewedSource ?? approvedSourceProvenance(run.request.factBase);
     assertProvenance(provenance);
@@ -30,6 +36,7 @@ export async function resolveContentApproval(run, mode, reviewedSource) {
       mode,
       status: 'approved',
       reviewedSource: structuredClone(provenance),
+      authorResultPaths: [...authorResultPaths],
       attempts: previous?.attempts ?? [],
     };
   } else if (reviewedSource === undefined) {
@@ -164,6 +171,24 @@ function assertProvenance(value) {
   }
 }
 
+function assertAuthorResultPaths(value) {
+  if (
+    !Array.isArray(value) ||
+    value.length === 0 ||
+    new Set(value).size !== value.length ||
+    value.some(
+      (path) =>
+        typeof path !== 'string' ||
+        !/^source\/author\/[^/]+\.json$/.test(path) ||
+        path.includes('..'),
+    )
+  ) {
+    throw new Error(
+      'Unattended content approval requires unique source/author result paths.',
+    );
+  }
+}
+
 function assertRun(run) {
   if (
     !isObject(run) ||