@open-agent-toolkit/cli 0.2.25 → 0.2.27

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

@@ -35,20 +35,111 @@ callback; a run without one fails `E_AUTHOR_REQUIRED`. An in-process caller
 supplies `options.author(request)`; a JSON-only CLI caller uses
 `--author-module author.mjs`. The core invokes it once per resolved artifact
 with an `explainer-kit.author-request/v2` payload containing the artifact
-identity and type, the artifact's authoring path, the inlined brief, the
-reconciled fact base, the resolved theme, the shell source for artistic
-artifacts, the required narrative sections for narrative floor artifacts, and
-bounded-discovery context. It must return an `explainer-kit.author-result/v2`
-carrying exactly one of `content.markdown` or `content.html`, matching the
-artifact's declared authoring path, plus non-secret provenance. A floor result
-may also carry `proposedArtifacts` of `{id, profileId, rationale}`; the
-referenced expansion profile supplies the type, authoring path, brief, and
-shell. The executable callback is never persisted in `run-request.json`.
-
-Unknown profile IDs and unsafe, duplicate, or floor-colliding artifact IDs are
-hard errors. Proposals beyond a profile's `maxCount` or the recipe's
-`expansion.limits.maxArtifacts` are rejected with a warning and the run
-continues.
+identity and type, the artifact's authoring path, the inlined brief, the bundled
+`visualAuthoringGuidance`, the reconciled fact base, the resolved theme, the
+shell source for artistic artifacts, the required narrative sections for
+narrative floor artifacts, and bounded-discovery context. The guidance is
+loaded only from the installed skill's `references/visual-authoring.md`; no
+ambient or home-directory file is consulted. The callback must return an
+`explainer-kit.author-result/v2` carrying exactly one of `content.markdown` or
+`content.html`, matching the artifact's declared authoring path, plus non-secret
+provenance. The executable callback is never persisted in `run-request.json`.
+
+Project recap requests have an explicit `recapMode`. Omitting it selects and
+persists `artistic`, which keeps the recipe's rich HTML floor. Selecting
+`deterministic-markdown` before the run applies the recipe-owned fallback to
+the complete planned portfolio, including optional expansions, while retaining
+the same adaptive hub, architecture, and deck identities. The resulting
+Markdown author records and `source/content/*.md` paths remain distinct in the
+manifest and immutable rebuild package. An artistic author failure fails the
+run; the core never silently retries or downgrades it as Markdown.
+
+Before artifact authoring, a caller supplies one provider-neutral `planSet`
+callback. It receives the reconciled fact base and recipe policy and returns
+`explainer-kit.set-plan/v1`:
+
+```json
+{
+  "schemaVersion": "explainer-kit.set-plan/v1",
+  "planId": "project-recap-set",
+  "recipe": { "id": "project-recap", "version": "1" },
+  "sourceIds": ["plan"],
+  "ledger": {
+    "terminology": [],
+    "statuses": [],
+    "numbers": []
+  },
+  "portfolio": [
+    {
+      "artifactId": "project-recap",
+      "artifactType": "hub",
+      "profileId": "recap-hub",
+      "required": true,
+      "sourceIds": ["plan"],
+      "draft": "Lead with the validated outcome.",
+      "visualIntent": "Orient the reader in the first viewport."
+    }
+  ]
+}
+```
+
+The set plan owns the shared terminology/status/number ledger, source coverage,
+adaptive portfolio, per-artifact draft, and visual intent. Optional entries add
+a source-backed `justification`; undeclared sources, conflicting ledger values,
+duplicate artifact IDs, and unjustified optional entries are invalid. Each
+`author-request/v2` carries the complete immutable `setContext` plus the exact
+matching `plannedArtifact`. The planner finalizes floor and expansion entries
+before authoring; author results cannot add, remove, or replace artifacts.
+When a planner draft contains a supported non-linear graph, the request also
+carries its closed `graphSemantics` (direction, nodes, edges, and topology).
+Artistic HTML must expose one exact `data-direction`. Each planned node requires
+one observation carrying `data-node`, `data-node-label`, `data-node-shape`, and
+`data-node-explicit`; each planned edge requires one observation carrying
+`data-from`, `data-to`, `data-edge-kind`, and `data-edge-label`. Values must
+match the complete frozen planner tuples exactly, including canonical HTML
+attribute escaping and explicit empty edge labels. Missing, extra, duplicate,
+malformed, noncanonical, rewired, or semantically drifting observations fail
+with `E_DIAGRAM_TOPOLOGY` before browser or visual-critic review.
+
+Visual review uses provider-neutral
+`explainer-kit.visual-review-request/v1` and
+`explainer-kit.visual-review-result/v1` envelopes. The request combines the
+shared plan with rendered artifact paths and viewport evidence, binds every
+rendered file, screenshot, and metrics file by raw-byte SHA-256 hash, and
+binds the launched Chromium name, version, and stable capture identity from
+`explainer-kit.browser-evidence/v2`. It derives a deterministic `requestId` and
+canonical `requestHash`. The critic
+receives a confined reader for those snapshotted paths and cannot read
+unlisted evidence. Core revalidates the bytes after the callback returns.
+Before snapshotting, each screenshot must fully decode as a bounded,
+CRC-verified, non-interlaced 8-bit RGB or RGBA PNG with exact zlib consumption
+and viewport-matched dimensions. The pixel hash established during QA must
+match the later visual-review snapshot.
+The result must echo the exact request identity and hash, name the complete
+artifact set, include artifact-scoped rubric findings, and select exactly one
+`pass`, `correct`, or `fail` disposition. Application validation must pass the
+reviewed request as `visualReviewRequest` context when validating the result.
+Request artifacts must exactly equal the planned portfolio, result artifact IDs
+must exactly equal that reviewed set, and every finding must name one of those
+artifacts. `pass` permits no findings; `correct` and `fail` require at least one
+correction finding. Provider, model, command, credential, and dispatch fields
+are not part of any core contract.
+
+Unattended project recaps require retained browser evidence at every required
+viewport from a branded session returned by `createBrowserProbeSession()` and a
+final visual-critic `pass`. The core derives `runtime.name` and
+`runtime.version` from the launched browser instance; caller assertions cannot
+replace that identity. Deterministic fixture sessions are explicit and may be
+used only in bounded non-production tests. A fixture session, missing trusted
+session, visual-critic failure, terminal `fail`, or second `correct` after the
+one allowed correction pass closes the QA gate with `built-needs-review`. That
+terminal outcome preserves rendered artifacts and all available review
+evidence while skipping durability and publish callbacks.
+
+The canonical immutable evidence consumer contract is
+`explainer-kit.package-coverage/v2`. It requires one matching launched-Chromium
+runtime and capture identity across browser metrics, review requests, retained
+attempt copies, manifest hashes, finalization, and archive validation.
 
 ## Explicit source forms
 
@@ -66,6 +157,15 @@ continues.
   documents. The core validates these bindings before loading facts, then
   reconciles the loaded claims and invokes the critic exactly once.
 
+Reviewed GitHub provenance is one indivisible tuple: `repository`, full
+lowercase 40-character `revision`, repository-relative `path`, inclusive
+`lineRange`, and its exact canonical `url`. Every declared source or citation
+backlink must include the complete tuple. The URL authority is
+`scripts/lib/source-backlinks.mjs`; it rejects moving refs, dot or empty path
+segments, decoded separators, noncanonical percent encoding, credentials,
+queries, and tuple/URL mismatches. Adapters must bind facts and hashes to the
+exact reviewed Git blob bytes, not mutable working-tree content.
+
 An unattended request asserts that its explicit source artifacts are already
 approved. It does not prompt, and it fails before narrative serialization when
 the author is absent, returns an invalid result, or copies excessive verbatim
@@ -78,16 +178,48 @@ The core executes:
 
 1. validate request and recipe
 2. reconcile or check the fact base
-3. apply bounded discovery
+3. apply bounded discovery and produce one validated set plan
 4. resolve one theme
-5. author each floor artifact against its brief, evaluate expansion proposals,
-   and author each accepted expansion artifact
+5. author every planned artifact against the same set context
 6. render typed artifacts through the narrative renderer or validate
    agent-composed HTML, per each artifact's declared authoring path
-7. run structural, guideline, and optional browser QA
-8. resolve content approval — the interactive gate pauses here, after render and
+7. run structural and guideline QA, plus required browser and independent
+   visual review for unattended project recaps
+8. close any unresolved recap review gate before external persistence
+9. resolve content approval — the interactive gate pauses here, after render and
    QA and before anything is published or persisted externally
-9. write the manifest and build record
+10. write the manifest and build record
+
+An incomplete interactive result includes
+`approval.resumeToken: "ekrt2:<64 lowercase hex characters>"`. The token is an
+opaque v2 digest over the run ID, original canonical absolute output root, the
+raw-byte SHA-256 hash of `run-request.json`, and raw-byte SHA-256 hashes of the
+five retained `source/set-plan/*.json` records. It is generated from trusted
+in-memory run identity before the interactive pause. The external caller must
+retain it outside the run root and echo it unchanged as
+`reviewedSource.resumeToken` with the later approval decision.
+
+Resume validates the fixed-length token with a timing-safe comparison before
+parsing retained request fields or hydrating set-plan, author, or content
+state. Missing, malformed, mismatched, relocated-root, or byte-drifted tokens
+fail `E_APPROVAL_RESUME` before planner, author, durability, or publish
+callbacks. Only the fixed-format authenticated `ekrt2` token is accepted.
+Every `ekrt1` token is rejected, including a correctly derived legacy digest.
+Legacy paused runs must restart to obtain an authenticated token; a retained
+relative `outputRoot` or any other mutable package state cannot opt into legacy
+resume behavior. The token is not written into the run request, content
+approval, build record, set-plan projections, manifest, or immutable-hash
+inventory.
+
+After authenticating the retained bytes, resume applies initialization's same
+canonical privacy-safe request projection to the current request, including the
+canonical output root and default render strategy, and requires an exact match
+with `run-request.json` before installing current request state or hydrating any
+package content. This binds recipe and recap mode, fact-base input, complete
+theme and render policy, privacy, public base URL, durability, publish
+destination, and run mode. Raw art direction may differ only when
+`privacy.retainRawArtDirection` is not `true`, because that deliberately
+redacted input is non-semantic after the rendered package has paused.
 
 The run package retains the privacy-safe `run-request.json`,
 `source/content-approval.json`, `source/fact-base.json`,
@@ -98,6 +230,15 @@ The run package retains the privacy-safe `run-request.json`,
 structured error and recovery action without deleting earlier outputs. Raw art
 direction is omitted unless the request explicitly opts in.
 
+`scripts/lib/package-coverage.mjs` is the versioned pure-ESM authority for
+required immutable paths. Successful unattended recaps require complete
+attempt-1 evidence. Successful interactive recaps require no review paths when
+none are retained, but any retained review material requires a complete
+attempt. Failed and incomplete packages follow the same no-evidence/complete-
+evidence split. Only `built-needs-review` may retain a deliberately partial
+chain. Outside that handoff, any attempt-2 material requires complete attempt
+1, the revision record, and complete attempt 2.
+
 Build-record stages are terminal once `passed` or `warned`. A rejected run that
 is later approved reopens the render and QA stages through a narrowly guarded
 record-level reset so the corrected sources are re-rendered and re-validated,
@@ -111,6 +252,10 @@ empty rounds and always stops at the recipe's `maxRounds`.
 
 Durability and publishing are never implicit.
 
+`built-needs-review` is not durability-eligible. The core skips both callbacks
+for that outcome, and downstream finalizers, exporters, and archive pushers
+must reject it rather than converting it to success.
+
 - `durability.strategy: none` invokes neither seam.
 - `durability.strategy: commit` invokes the explicit `durability` callback.
   Caller-created commit evidence is subsequently verified with
@@ -139,6 +284,8 @@ marking rides in the result and the approval record only; `manifest/v1` stays
 frozen and carries no marking field. Input validation and unsupported
 recipes reject before output mutation. Failures after initialization return a
 `failed` result with paths to the retained record and intermediates.
+`built-needs-review` is a distinct terminal review-gate result, not a synonym
+for `built-not-durable`.
 
 V1 readers reject unknown schema majors and unknown contract fields. Relative
 record paths are run-root confined, hashes use `sha256:<hex>`, and command

package/assets/skills/explainer-kit/references/golden-conformance.md

@@ -0,0 +1,80 @@
+# Golden conformance contract
+
+Golden conformance runs the unattended project-recap workflow from portable
+semantic inputs and validates its live output in real Chromium. It is a
+behavioral oracle, not a pixel snapshot: output may change markup, spacing, or
+composition when it clears the same quality bar.
+
+## Cases
+
+Each case directory under `tests/fixtures/golden/` contains:
+
+- `simple` checks viewport-sized lead evidence and a cohesive baseline recap.
+- `non-linear` checks branch, fan-in, and cycle preservation.
+- `explainer-authoring-redesign` checks an archive-only rebuild from a dense
+  completed project record.
+
+| Path                          | Contract                                                        |
+| ----------------------------- | --------------------------------------------------------------- |
+| `descriptor.json`             | Case identity plus paths and SHA-256 hashes for semantic inputs |
+| `source-input.json`           | Source-grounded claims, topology, and reader questions          |
+| `evidence/source-record.json` | Retained source claims, upstream repository hash, and topology  |
+
+All cases share `tests/fixtures/golden/rubric.json`. Generated HTML, browser
+captures, measurements, manifests, catalogs, and review records are temporary
+test output and must not be committed.
+
+The descriptor's retained-file set is case-relative and content addressed. The
+loader recomputes each hash, resolves source records, and rejects missing,
+changed, duplicate, non-portable, or ungrounded input.
+`sharedRubricPath` resolves from `tests/fixtures/golden/`, and
+`sharedRubricSha256` content-addresses that common contract.
+
+## Required rubric
+
+The shared `explainer-kit.golden-rubric/v1` `checks` object has exactly these
+required fields:
+
+1. `adaptiveMinimumSet`
+2. `firstViewport`
+3. `hierarchy`
+4. `representationChoice`
+5. `legibility`
+6. `cohesion`
+7. `sourceCoverage`
+8. `interactions`
+9. `topologyPreservation`
+10. `catalogParity`
+11. `boundedCorrection`
+
+The benchmark enforces every field against live runtime evidence. A passing set
+contains exactly the project recap, architecture, and deck; preserves source
+meaning and topology; has catalog-to-manifest parity; includes real browser
+captures and measurements; and reaches a passing terminal review without a
+correction. Integration suites separately exercise the one-correction ceiling.
+
+## Runtime evidence
+
+The suite generates one complete recap package per case in a temporary
+directory. It validates artifact membership, claim markers, exact topology,
+catalog parity, independent visual review, real Chromium identity, viewport
+dimensions, lead-content presence, heading order, capture identity, overflow,
+keyboard and deck-arrow behavior, and bounded review. The temporary package is
+removed when the test completes.
+
+Claims are accepted only when their source ID exists and their text exactly
+matches a claim in the retained source record. Repository-backed records also
+pin the upstream repository file and prove every retained claim occurs there.
+Runtime tests must not load an operator plugin, home directory, active project,
+or moving branch.
+
+## Portability rules
+
+- Retained descriptor paths are relative to their case and cannot escape it;
+  the shared rubric path is relative to the golden fixture root.
+- POSIX roots, Windows drive paths, UNC paths, home-relative paths, and
+  `file://` locators are rejected wherever they occur in committed inputs.
+- Repository-relative paths and supported `https://` source URLs are allowed.
+- Every claim, topology node, and topology edge resolves to retained,
+  hash-verified source input, so later runs do not need the original
+  workstation.

package/assets/skills/explainer-kit/references/visual-authoring.md

@@ -0,0 +1,92 @@
+# Visual authoring guidance
+
+Use this reference with the reconciled fact base, shared set plan, selected
+theme, and the artifact-specific brief. It is sufficient for an unattended
+author. An optional installed visual-explainer capability may improve the
+composition, but the run must not depend on it.
+
+## Choose the representation
+
+Choose the visual form that makes the reader's question easiest to answer:
+
+- Use a hub for orientation, current state, key decisions, and links into the
+  rest of the set.
+- Use a system visual for boundaries, relationships, direction, ownership, or
+  flow. Preserve branches, fan-in, and cycles; reject or reroute a topology the
+  selected renderer cannot represent.
+- Use a deck for a paced beginning-to-end narrative with one idea per frame.
+- Use a table for repeated facts with comparable columns, not for prose.
+- Use cards for independent summaries and lanes for parallel work.
+
+Do not turn every fact into a chart. Prefer structured text when shape or
+position adds no meaning.
+
+## Establish hierarchy
+
+Make the first viewport answer what this is, why it matters, and where the work
+stands. Use one dominant title, a short framing statement, and the most useful
+visual or status summary before secondary detail. Keep headings descriptive,
+group related items, and use size, spacing, and contrast consistently.
+
+Use the shared terminology, status labels, and numbers exactly. Never create a
+shorter synonym that changes meaning. Keep source-backed uncertainty visible as
+`needs confirmation`.
+
+## Hubs and responsive navigation
+
+- Lead with the project outcome and current state, then expose architecture,
+  decisions, validation, and next steps.
+- Link every artifact in the planned set using descriptive labels.
+- Keep navigation compact and keyboard reachable. On narrow screens, collapse
+  a side rail into horizontal, wrapping, or disclosure navigation.
+- Avoid fixed widths. Let text wrap, put wide tables and diagrams in bounded
+  scroll containers, and ensure the document itself does not overflow.
+- Keep the primary reading order useful without JavaScript.
+
+## Diagrams and system visuals
+
+- Encode relationships with position and connectors, not color alone.
+- Label nodes with concrete nouns and edges with actions or data movement.
+- Make direction explicit and include a legend only when the encoding needs it.
+- Preserve graph semantics. Never serialize branches, fan-in, or cycles into a
+  false linear sequence.
+- For each non-linear `graphSemantics` input, emit one element with the exact
+  `data-direction`. Emit every node exactly once with `data-node`,
+  `data-node-label`, `data-node-shape`, and `data-node-explicit`; emit every
+  edge exactly once with `data-from`, `data-to`, `data-edge-kind`, and
+  `data-edge-label`. Use the frozen tuple values verbatim with canonical HTML
+  attribute escaping, including `data-edge-label=""` for an unlabeled edge.
+- Give the canvas an accessible name and description. Keep labels readable at
+  the required viewport widths and provide bounded pan or zoom for large maps.
+- Use the same component names and status vocabulary as the hub and deck.
+
+## Decks
+
+- Give each slide one claim, decision, or transition.
+- Open with the outcome and audience question; close with current state and next
+  action.
+- Prefer short headings, diagrams, lists, and comparisons over paragraphs.
+- Keep critical content inside one viewport, with overflow available as a
+  safety valve rather than the default reading experience.
+- Support keyboard controls, visible position, reduced motion, print, and a
+  readable no-script flow.
+
+## Tables
+
+- Use a clear header row and comparable values in each column.
+- Put units in headings, align numbers consistently, and preserve exact values
+  from the shared ledger.
+- Keep cells concise. Move explanations below the table or into a linked deep
+  dive.
+- Wrap or scroll wide tables without clipping their final column.
+
+## Composition check before return
+
+Confirm the artifact:
+
+1. answers its planned reader question in the first viewport;
+2. uses the planned medium and visual intent;
+3. follows the shared ledger without terminology, status, or number drift;
+4. includes only source-grounded claims and planned links;
+5. remains legible and navigable on desktop, tablet, and mobile; and
+6. returns complete content for the recipe-selected authoring path.

package/assets/skills/explainer-kit/references/visual-review.md

@@ -0,0 +1,57 @@
+# Visual review guidance
+
+Review the rendered artifact set against its reconciled fact base, shared
+ledger, set plan, and browser evidence. This rubric is independent of authoring
+guidance: it tells a critic what to assess, not how an author should compose.
+An optional installed visual-explainer capability may assist, but review must
+remain possible from bundled evidence and rules alone.
+
+## Review the whole set
+
+Inspect the complete set before assigning artifact findings. Verify:
+
+- **First viewport:** each artifact establishes purpose, project state, and the
+  primary reader question without scrolling.
+- **Hierarchy:** the most important outcome or relationship is dominant, with
+  secondary detail grouped and ordered consistently.
+- **Representation choice:** the selected medium makes the evidence easier to
+  understand than plain prose would.
+- **Legibility:** text, labels, status cues, tables, and connectors remain
+  readable at every required viewport.
+- **Medium fit:** the hub orients and links, the system visual preserves
+  relationships, the deck paces a narrative, and optional artifacts add a
+  distinct source-backed perspective.
+- **Cohesion:** terminology, status labels, numbers, color meaning, and visual
+  language match the shared ledger and one another.
+- **Coverage and redundancy:** planned sources and reader questions are covered
+  once at the right depth; optional artifacts do not repeat the hub or deck
+  without a justified purpose.
+- **Interaction:** navigation, links, keyboard controls, reduced motion, table
+  overflow, and diagram pan or zoom work without hiding content.
+
+## Artifact-scoped findings
+
+Every finding identifies an artifact ID, the failed rubric area, evidence, and
+a concrete correction. Distinguish factual or ledger conflicts from visual
+judgment. Never infer a fact that is absent from the retained sources.
+
+Use severity proportionally:
+
+- Critical: unsafe, fabricated, or materially false output.
+- Important: the artifact cannot answer its primary question or loses required
+  topology, content, or legibility.
+- Medium: meaningful visual or cohesion weakness that does not invalidate the
+  set.
+- Minor: localized polish issue.
+
+## Disposition
+
+Return exactly one provider-neutral disposition:
+
+- `pass` when the full set clears the rubric with no required correction.
+- `correct` when bounded artifact-scoped changes can clear the rubric.
+- `fail` when evidence is missing, the plan or ledger is internally invalid, or
+  correction would require unsupported facts or a different artifact set.
+
+Do not award `pass` from source code inspection alone. Base visual findings on
+the retained browser evidence available to the review request.

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

@@ -10,8 +10,11 @@
     "artifactType",
     "authoring",
     "brief",
+    "visualAuthoringGuidance",
     "factBase",
-    "theme"
+    "theme",
+    "setContext",
+    "plannedArtifact"
   ],
   "properties": {
     "schemaVersion": { "const": "explainer-kit.author-request/v2" },
@@ -21,9 +24,17 @@
     },
     "authoring": { "enum": ["markdown", "html"] },
     "brief": { "type": "string", "minLength": 1 },
+    "visualAuthoringGuidance": { "type": "string", "minLength": 1 },
     "factBase": { "$ref": "explainer-kit.fact-base/v1" },
     "shell": { "type": "string", "minLength": 1 },
     "theme": { "$ref": "explainer-kit.theme/v1" },
+    "setContext": { "$ref": "explainer-kit.set-plan/v1" },
+    "plannedArtifact": { "$ref": "#/$defs/plannedArtifact" },
+    "graphSemantics": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/graphSemantics" },
+      "minItems": 1
+    },
     "floor": {
       "type": "object",
       "additionalProperties": false,
@@ -37,5 +48,165 @@
         }
       }
     }
+  },
+  "$defs": {
+    "graphSemantics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["direction", "nodes", "edges", "topology"],
+      "properties": {
+        "direction": { "enum": ["TD", "LR"] },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "label", "shape", "explicit"],
+            "properties": {
+              "id": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*$" },
+              "label": { "type": "string", "minLength": 1 },
+              "shape": { "enum": ["rectangle", "rounded", "diamond"] },
+              "explicit": { "type": "boolean" }
+            }
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["from", "to", "kind", "label"],
+            "properties": {
+              "from": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "to": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_-]*$" },
+              "kind": { "enum": ["arrow", "line"] },
+              "label": { "type": "string" }
+            }
+          },
+          "minItems": 1
+        },
+        "topology": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "kind",
+            "features",
+            "branchNodes",
+            "fanInNodes",
+            "cycle",
+            "order"
+          ],
+          "properties": {
+            "kind": { "const": "non-linear" },
+            "features": {
+              "type": "array",
+              "items": {
+                "enum": [
+                  "branch",
+                  "fan-in",
+                  "cycle",
+                  "disconnected",
+                  "non-linear"
+                ]
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "branchNodes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "uniqueItems": true
+            },
+            "fanInNodes": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "uniqueItems": true
+            },
+            "cycle": { "type": "boolean" },
+            "order": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[A-Za-z][A-Za-z0-9_-]*$"
+              },
+              "maxItems": 0
+            }
+          }
+        }
+      }
+    },
+    "plannedArtifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "artifactId",
+        "artifactType",
+        "profileId",
+        "required",
+        "sourceIds",
+        "draft",
+        "visualIntent"
+      ],
+      "properties": {
+        "artifactId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+        },
+        "artifactType": {
+          "enum": ["hub", "diagram", "explainer", "deck", "catalog"]
+        },
+        "profileId": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+        },
+        "required": { "type": "boolean" },
+        "sourceIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+          },
+          "minItems": 1,
+          "uniqueItems": true
+        },
+        "draft": { "type": "string", "minLength": 1 },
+        "visualIntent": { "type": "string", "minLength": 1 },
+        "justification": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "sourceIds", "rationale"],
+          "properties": {
+            "kind": {
+              "enum": [
+                "status-change",
+                "rollout-complexity",
+                "source-backed-detail"
+              ]
+            },
+            "sourceIds": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$"
+              },
+              "minItems": 1,
+              "uniqueItems": true
+            },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    }
   }
 }