@open-agent-toolkit/cli 0.2.29 → 0.2.31

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

@@ -20,19 +20,19 @@ OAT lifecycle callers use the adapter.
 
 ## Recipes
 
-The core ships four versioned recipes on the `explainer-kit.recipe/v2` file
-schema. Each recipe's own `version` selector remains `"1"`, so `{id, version}`
-callers and manifest cross-checks are unaffected by the schema move.
+The core ships four recipe families on the `explainer-kit.recipe/v2` file
+schema. Most recipe selectors remain at version `"1"`. New project recaps use
+immutable `project-recap@2`, while `project-recap@1` remains readable for replay.
 
 A v2 recipe declares a **floor** — the artifacts every run must produce — plus
 a licensed **expansion** set. Most recipes retain one floor artifact.
-Unattended `project-recap` is the exception: it plans and composes an adaptive
-minimum set before any artifact author runs.
+`project-recap@2` requires one complete navigational hub and plans any additional
+artifact before an author runs.
 
 | Recipe              | Use                                                    | Required floor                                                                                                    |
 | ------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
 | `project-explainer` | Working explanation after project planning             | one Markdown `hub` covering architecture, decisions, risks, phases, and validation                                |
-| `project-recap`     | Final record after implementation and final review     | HTML visual hub, architecture/system diagram, and deck governed by one set plan                                   |
+| `project-recap`     | Final record after implementation and final review     | one HTML navigational hub; diagrams, decks, and deep dives are adaptive expansions                                |
 | `program-recap`     | Bird's-eye record of a multi-wave delivery program     | one Markdown `hub` covering the wave map, outcomes, convention evolution, aggregate numbers, and follow-up ledger |
 | `engineer-tour`     | Engineer-facing orientation to a codebase and its flow | one HTML-composed `explainer` covering orientation, architecture, execution flow, key code, and validation        |
 
@@ -46,8 +46,8 @@ adding an OAT dependency.
 ### Project recap modes
 
 Project recaps default to `recapMode: artistic`. This mode uses the shared set
-plan and provider-neutral author seam to compose the required HTML hub,
-architecture view, and deck.
+plan and provider-neutral author seam to compose the required HTML hub plus any
+source-backed expansion that answers a distinct reader question.
 
 `recapMode: deterministic-markdown` is an explicit fallback for callers that
 need deterministic output. It preserves the same planned artifact portfolio and
@@ -63,16 +63,16 @@ artifact `type`, authoring path, brief, optional shell, and a mandatory
 `maxCount`. Every recipe also carries a mandatory `expansion.limits.maxArtifacts`
 that caps the whole expansion set; floor artifacts do not count against it.
 
-| Recipe              | Profiles (max per profile)                       | `maxArtifacts` |
-| ------------------- | ------------------------------------------------ | -------------- |
-| `project-recap`     | `status-view` 1, `rollout-view` 1, `deep-dive` 3 | 5              |
-| `program-recap`     | `supporting-diagram` 3, `project-page` 12        | 12             |
-| `project-explainer` | `supporting-diagram` 4                           | 4              |
-| `engineer-tour`     | `supporting-diagram` 4                           | 4              |
+| Recipe              | Profiles (max per profile)                                  | `maxArtifacts` |
+| ------------------- | ----------------------------------------------------------- | -------------- |
+| `project-recap@2`   | `supporting-diagram` 1, `walkthrough-deck` 1, `deep-dive` 3 | 5              |
+| `program-recap`     | `supporting-diagram` 3, `project-page` 12                   | 12             |
+| `project-explainer` | `supporting-diagram` 4                                      | 4              |
+| `engineer-tour`     | `supporting-diagram` 4                                      | 4              |
 
-For project recaps, optional status and rollout views require matching
-source-backed justifications, while `deep-dive` remains a Markdown
-`explainer`. Other recipes retain their recipe-owned diagram and project-page
+For project recaps, every optional diagram, deck, or deep dive needs a distinct
+reader question, supporting source evidence, and rationale for choosing that
+medium. Other recipes retain their recipe-owned diagram and project-page
 profiles. Every declared type stays inside the frozen `manifest/v1` enum.
 
 ## Content authoring and review
@@ -116,6 +116,11 @@ author request, so an unattended author receives everything it needs in one
 payload. Changing a brief changes output expectations with no contract
 migration.
 
+The bundled authoring prose covers typographic roles, hierarchy, composition,
+density, medium leverage, template repetition, diagram semantics, and
+cross-artifact cohesion. These remain editorial judgments rather than numeric
+scores or deterministic layout checks.
+
 ### The planning and author seams
 
 Before authoring, one provider-neutral `planSet` callback produces the complete
@@ -125,15 +130,17 @@ portfolio. Every run also requires one provider-neutral author callback, in
 without one fails with `E_AUTHOR_REQUIRED`.
 
 The core invokes the author once per planned artifact with an
-`explainer-kit.author-request/v2` payload carrying the artifact identity and
+`explainer-kit.author-request/v3` payload carrying the artifact identity and
 type, its authoring path, the inlined brief, the reconciled fact base, the
 resolved theme, the shell source for artistic artifacts, the immutable set
-context, the matching planned artifact, and bundled medium-specific authoring
-guidance. The installed skill is the complete unattended baseline; optional
+context, the matching planned artifact, canonical artifact links, and bundled
+medium-specific authoring guidance. Version 2 requests remain readable for
+replay. The installed skill is the complete unattended baseline; optional
 provider capabilities can enhance composition but are not required. The core
-accepts only a schema-valid `explainer-kit.author-result/v2` containing exactly one of
-`content.markdown` or `content.html` plus non-secret provenance. Authored
-content is still checked for excessive verbatim overlap with the fact base.
+accepts only a schema-valid `explainer-kit.author-result/v2` containing exactly
+one of `content.markdown` or `content.html` plus non-secret provenance.
+Authored content is still checked for excessive verbatim overlap with the fact
+base.
 
 Direct callbacks and module entry points are first-class but transient: they
 never enter retained request contracts. See
@@ -143,9 +150,10 @@ planner, author, browser-session, and visual-critic boundaries.
 ### Planner-owned adaptive sets
 
 The set planner finalizes required and optional artifacts before authoring.
-Project recaps always contain a hub, architecture/system diagram, and deck;
-the planner may add only recipe-licensed optional views with a source-backed
-justification. Recipe and per-profile limits still bound the portfolio.
+New project recaps always contain a navigational hub. The planner may add only
+recipe-licensed optional diagrams, decks, or deep dives with a distinct reader
+question, source evidence, and medium rationale. Recipe and per-profile limits
+still bound the portfolio.
 Undeclared sources, conflicting ledger values, duplicate IDs, and unjustified
 optionals fail validation. Author results cannot add, remove, or replace
 artifacts.
@@ -188,11 +196,21 @@ evidence to an independent critic. Fixture sessions are test-only and are
 rejected in unattended production.
 
 A `correct` disposition permits one bounded correction and exactly one final
-review; there is no second correction or third review. Missing, forged,
+review; there is no second correction or third review. The correction budget is
+shared with the internal-link gate described below, so a `correct` disposition
+is refused outright with `E_VISUAL_CORRECTION` when link validation already
+spent the single bounded correction on this run. Missing, forged,
 cross-record-mismatched, or invalid evidence, a failed critic, or an unresolved
 correction ends as `built-needs-review`. Such output is retained for diagnosis
 but cannot become durable, finalized, archived, or published.
 
+The critic reviews the whole set for typography, hierarchy, composition,
+density, medium leverage, template repetition, diagram semantics, and
+cross-artifact cohesion. It returns the existing provider-neutral result:
+`pass` when no required correction remains or `correct` with concrete,
+artifact-scoped actions for the bounded correction round. No numeric design
+threshold is part of the contract.
+
 The approval record is also the durable source of truth for the resolved
 artifact set. It records every floor and accepted expansion artifact for all
 approval states, including pending and rejected, so a paused expanded run
@@ -221,6 +239,26 @@ Every legacy `ekrt1` token is rejected. A paused run created with the legacy
 format must restart to receive an authenticated token; editing retained package
 state cannot opt it into compatibility.
 
+### Internal-link validation
+
+Every internal reference in the rendered set must resolve to a
+manifest-declared target before the run can reach browser review. The gate runs
+after render and uses a bounded tokenizer rather than a general HTML parser.
+Relative references resolve from the current explicit file and must bind
+exactly to the manifest/site tree, and a referenced fragment must resolve to
+exactly one ID in its target document. Directory references, path traversal,
+missing targets, missing fragments, ambiguous fragments, and unsafe schemes all
+fail with `E_INTERNAL_REFERENCE`.
+
+A failure gets one bounded correction round, re-rendered and revalidated. That
+round is the same single budget the visual-review `correct` disposition uses —
+whichever gate reaches it first consumes it. Once it is exhausted the run fails
+hard: the QA stage is recorded `failed` with code-only evidence and the scrubbed
+message `The qa stage failed.`, and the run is neither durability- nor
+publication-eligible. No finding is retained, so nothing in the durable record
+names the broken reference; the failure is attributed to the `link-validation`
+evidence stage.
+
 ## Warnings and QA severity
 
 QA findings are split by severity, and the split is what lets thin content ship
@@ -296,9 +334,17 @@ Reviewed source and citation backlinks are absolute canonical GitHub blob URLs
 pinned to the exact 40-character commit revision and line range, so they
 survive project archival without resolving through a mutable branch or local
 checkout. Each recap also emits
-`site/initiatives/<slug>/catalog.json` from the finalized manifest. Its
-artifact IDs, types, paths, URLs, and source backlinks must remain in exact
-manifest parity; authors do not hand-maintain the catalog.
+`site/initiatives/<slug>/catalog.json` from the finalized manifest, versioned
+as `explainer-kit.initiative-catalog/v2`. Its artifact IDs, types, paths,
+URLs, and source backlinks must remain in exact manifest parity; authors do
+not hand-maintain the catalog. The catalog's `publicVerification` field is a
+**policy marker, never an outcome**: `required` when the run's public access
+policy calls for anonymous URL verification, `skipped-by-policy` for
+protected destinations. It records what the publication policy was — the
+per-artifact verification outcomes live in `publish-receipt.json`.
+Compatibility is regenerate-only: consumers parse the declared version, and
+no v1 read path exists because no released consumer could verify v1 catalog
+evidence.
 
 `manifest.immutableHashes` covers the exact retained bytes for
 `run-request.json`, content approval, fact-base JSON and Markdown, declared
@@ -322,12 +368,25 @@ Build success and durability are separate:
 
 The core verifies caller-supplied commit or publish evidence; it never creates
 Git commits. Publishing is always explicitly requested and human-gated. The
-public `s3-static` connector validates corresponding S3 and HTTPS roots with a
-run-unique sentinel, uploads only manifest-declared `site/` files, verifies the
-content type and SHA-256 response bytes at public URLs, and writes
-`publish-receipt.json`. Public roots cannot contain credentials, queries, or
-fragments. Publishing is additive and does not run a root-wide destructive
-sync.
+public `s3-static` connector validates each S3 and HTTPS root independently and
+proves the destination with a run-unique sentinel, uploads only
+manifest-declared `site/` files, and writes `publish-receipt.json`.
+Verification depends on the declared `publicAccess` policy: in `public` mode
+the connector anonymously fetches each published URL and compares content
+type and SHA-256 response bytes; in `protected` mode it verifies object
+integrity through authenticated S3 hashing instead, and every receipt entry
+records `publicVerification: skipped-protected` so the skipped anonymous
+check is visible rather than implied.
+
+Root screening is strict on both roots: no credentials, queries, or
+fragments; no whitespace, C0/C1 control characters, or backslashes; and the
+gate applies to every publish-request and publish-receipt contract version
+rather than being pinned to one version string. Public roots must be HTTPS
+and must not address loopback, link-local, or private networks, and
+verification fetches refuse redirects (`redirect: 'error'`) — see the
+[publication environment variables](/docs/cli-utilities/configuration#explainer-publication-environment-variables)
+for the explicit private-root opt-in and its durable receipt trace.
+Publishing is additive and does not run a root-wide destructive sync.
 
 Release validation drives the bounded curated-style/template matrix in a real
 installed Chromium browser and retains machine-readable viewport, clipping,
@@ -375,8 +434,9 @@ typed adapter settings.
 Private integrations use the core boundary directly: resolve private inputs
 before the run, construct one versioned request, invoke the core once, then
 publish or link the versioned manifest after the run. Wrapper acceptance reads
-the complete post-run `PublishReceiptV1`, verifies every manifest artifact and
-the core run ID, and rejects foreign or stale receipts. Presets, private source
+the complete post-run `publish-receipt/v2`, verifies every manifest artifact
+and the core run ID, and rejects foreign or stale receipts; `publish-receipt/v1`
+remains readable for replay of older runs only. Presets, private source
 systems, external-document synchronization, and personal destinations remain
 wrapper-owned.
 

package/assets/docs/workflows/skills/index.md

@@ -24,6 +24,10 @@ Use this section when you want to choose the right OAT skill for a task. If you
 - Split a broad discovery or brainstorm into child projects: `oat-project-split`
 - Retroactively capture existing work: `oat-project-capture`
 - Run or receive reviews: `oat-project-review-provide`, `oat-project-review-receive`, or the non-project review variants
+- Generate an evidence-grounded project retrospective, apply approved repo
+  improvements, or file tracker feedback: `oat-project-retro` and
+  `oat-project-retro-file`. See
+  [Project Retrospectives](../projects/retro.md).
 - Capture a scoped, shippable backlog item: `oat-pjm-add-backlog-item` directly when the work is already scoped, or `oat-brainstorm` when the thought hasn't converged yet — the brainstorm dispatcher's "scoped backlog item" destination pre-fills the title / description / acceptance criteria / scope estimate / priority from the conversation and then runs `oat-pjm-add-backlog-item` with confirmed inputs
 - Manage the repo backlog and reference docs: `oat-pjm-update-repo-reference`, `oat-pjm-review-backlog`
 - Turn a repo audit, maintainability review, backlog review, backlog directory, or backlog item into standalone external implementation plans: `oat-repo-improve`. Plans land under `.oat/repo/reference/external-plans/`; execute them directly or optionally pass one to `oat-project-import-plan` for tracked OAT execution.
@@ -74,6 +78,8 @@ Use this section when you want to choose the right OAT skill for a task. If you
     - `oat-project-pr-progress`
     - `oat-project-pr-final`
     - `oat-project-document`
+    - `oat-project-retro`
+    - `oat-project-retro-file`
     - `oat-explainer-kit`
     - `oat-wrap-up`
     - `oat-project-complete`

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.2.29",
-  "docs-config": "0.2.29",
-  "docs-theme": "0.2.29",
-  "docs-transforms": "0.2.29"
+  "cli": "0.2.31",
+  "docs-config": "0.2.31",
+  "docs-theme": "0.2.31",
+  "docs-transforms": "0.2.31"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: explainer-kit
-version: 2.0.3
+version: 2.1.0
 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__*
@@ -74,11 +74,13 @@ request.
 The recipe — never the author — selects each artifact's authoring path. Floor
 entries and expansion profiles declare `authoring: markdown` for the narrative
 path or `authoring: html` for the artistic path. The core invokes the author
-once per artifact with an `explainer-kit.author-request/v2` payload carrying the
+once per artifact with an `explainer-kit.author-request/v3` payload carrying the
 artifact identity and type, its authoring path, the inlined brief from
 `briefs/`, the reconciled fact base, the resolved theme, the shell source for
-artistic artifacts, and the required narrative sections for narrative floor
-artifacts. It accepts only a schema-valid
+artistic artifacts, the required narrative sections for narrative floor
+artifacts, and canonical `artifactLinks` with explicit `index.html` site paths
+and receiver-relative hrefs. Version 2 requests remain readable for replay. It
+accepts only a schema-valid
 `explainer-kit.author-result/v2` with exactly one of `content.markdown` or
 `content.html` plus non-secret provenance, rejects excessive verbatim source
 overlap, retains each validated result under `source/author/` and its content
@@ -107,11 +109,28 @@ continues. Accepted expansion artifacts render to
 `site/{directory}/{slug}/{artifactId}/index.html` and are linked from the floor
 hub; floor artifacts keep their existing paths.
 
+`project-recap@2` requires one complete navigational hub and makes diagrams,
+decks, and deep dives adaptive expansions. The planner proposes one only when
+it can name a distinct reader question, the supporting source evidence, and why
+that medium improves on adding more hub prose. The prose brief governs
+typographic roles, hierarchy, slide archetypes, diagram semantics,
+fit-to-content composition, density, repetition, and medium choice. These are
+editorial judgments, not new request fields or renderer rules.
+`project-recap@1` remains readable for replay with its historical three-artifact
+floor.
+
 ## Review, Approval, and Warnings
 
-Approval runs after theme, render, safety validation, the guideline checker, and
-render QA, immediately before publish and durability — so a reviewer approves
-rendered artifacts and the complete warning set, not raw prose.
+Approval runs after theme, render, hard internal-reference validation, safety
+validation, the guideline checker, and render QA, immediately before publish and
+durability — so a reviewer approves rendered artifacts and the complete warning
+set, not raw prose. The reference gate resolves `href`, `src`, `srcset`,
+fragments, and safe embedded references against explicit manifest/site-tree
+files. It may invoke the existing correction author once, then rerenders and
+revalidates before any browser or visual review. A later visual correction also
+rerenders and passes through the validation-only reference gate without
+receiving another correction attempt. An exhausted `E_INTERNAL_REFERENCE`
+finding fails closed and cannot reach durability.
 
 Interactive runs stop with an `incomplete` outcome once artifacts are built and
 checked. Review the rendered `site/` tree, the sources under `source/content/`,
@@ -144,7 +163,13 @@ succeed.
 
 Visual critics use the independent whole-set rubric in
 `references/visual-review.md`, which separates review judgment from
-medium-specific authoring rules.
+medium-specific authoring rules. They assess typography, hierarchy,
+composition, density, medium leverage, template repetition, diagram semantics,
+and cross-artifact cohesion from rendered browser evidence. The rubric keeps
+the existing provider-neutral result contract: `pass` means no required
+correction remains, while `correct` carries concrete artifact-scoped actions
+into the one bounded correction round. It does not assign design scores or
+encode geometry thresholds.
 
 Render QA is opt-in. It runs only against an injected `browserProbe`, and the
 core never launches a browser of its own — reviewing the rendered output in a

package/assets/skills/explainer-kit/briefs/project-recap.md

@@ -34,14 +34,32 @@ Use the same terms, statuses, and numbers throughout.
 
 ## Floor
 
-Produce one rich narrative hub covering all six sections above. It must contain
-at least one high-level architecture diagram, structured lists where useful,
-and evidence tables for implementation and validation. The page should remain
-useful without any expansion artifact.
+Produce one rich navigational hub covering all six sections above. It must
+orient the reader, expose the project state and outcome in the first viewport,
+and link every selected artifact with descriptive labels. The hub should remain
+complete and useful without an expansion artifact.
+
+Establish deliberate typographic roles for the title, framing statement,
+section headings, labels, body text, and evidence annotations. Build hierarchy
+through scale, spacing, contrast, and grouping instead of applying one repeated
+card or section treatment everywhere. Keep density fit to the material: shorten
+or restructure crowded passages, but do not pad sparse evidence with decorative
+filler. Choose tables, lists, diagrams, and prose only when each medium makes
+the evidence easier to understand.
 
 ## Expansion license
 
-Propose additional diagrams, a deep-dive, or a walkthrough deck when complexity
-earns it. Expansion should clarify a real boundary, flow, trade-off, or
-operational handoff that would overload the hub. Do not expand to repeat the
+Propose a supporting diagram, walkthrough deck, or deep-dive only when it
+answers a distinct reader question that the hub cannot answer cleanly. For
+every proposal, identify the reader question, the source evidence that supports
+it, and the rationale for choosing that medium. Do not expand to repeat the
 same story in another format.
+
+Use a diagram when topology, direction, ownership, or flow carries meaning.
+Preserve branches, fan-in, cycles, labels, and explicit relationships, and fit
+the frame to the content rather than leaving a tiny graph in a large canvas.
+Use a deck only when pacing adds value; choose slide archetypes to match the
+story, such as an outcome opener, comparison, system view, decision, evidence,
+or next-action frame. Vary composition to fit each claim instead of repeating
+one template. Use a deep-dive when source-backed mechanics or trade-offs need
+more room than the hub can give them.

package/assets/skills/explainer-kit/recipes/project-recap.v2.json

@@ -0,0 +1,72 @@
+{
+  "schemaVersion": "explainer-kit.recipe/v2",
+  "id": "project-recap",
+  "version": "2",
+  "sourceRoles": [
+    {
+      "role": "project",
+      "required": true,
+      "accepts": ["file", "directory", "git", "github"],
+      "minBindings": 1,
+      "maxBindings": 1
+    }
+  ],
+  "floor": [
+    {
+      "id": "project-recap",
+      "type": "hub",
+      "authoring": "html",
+      "template": "house-style",
+      "required": true,
+      "briefRef": "briefs/project-recap.md",
+      "requiredNarrative": [
+        "original-request",
+        "key-agent-decisions",
+        "as-built-architecture",
+        "implementation-record",
+        "validation-evidence",
+        "outcome"
+      ]
+    }
+  ],
+  "expansion": {
+    "profiles": [
+      {
+        "profileId": "supporting-diagram",
+        "type": "diagram",
+        "authoring": "html",
+        "briefRef": "briefs/supporting-diagram.md",
+        "shell": "diagram-shell",
+        "maxCount": 1
+      },
+      {
+        "profileId": "walkthrough-deck",
+        "type": "deck",
+        "authoring": "html",
+        "briefRef": "briefs/walkthrough-deck.md",
+        "shell": "deck-shell",
+        "maxCount": 1
+      },
+      {
+        "profileId": "deep-dive",
+        "type": "explainer",
+        "authoring": "markdown",
+        "briefRef": "briefs/deep-dive.md",
+        "maxCount": 3
+      }
+    ],
+    "limits": {
+      "maxArtifacts": 5
+    }
+  },
+  "fallback": {
+    "mode": "deterministic-markdown",
+    "selection": "explicit",
+    "authoring": "markdown",
+    "scope": "portfolio"
+  },
+  "discoveryLimits": {
+    "consecutiveNoNewFindingsRounds": 2,
+    "maxRounds": 8
+  }
+}

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

@@ -34,25 +34,34 @@ Every run, interactive or unattended, also requires a provider-neutral author
 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
+with an `explainer-kit.author-request/v3` payload containing the artifact
 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
+narrative floor artifacts, bounded-discovery context, and `artifactLinks`.
+Each canonical link entry names the planned artifact, its explicit site-relative
+path ending in `index.html`, and the relative `href` from the receiving
+artifact's own location. 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.
+New project recap producers select immutable `project-recap@2`. Its
+navigational hub is the only mandatory artifact. A diagram, deck, or deep dive
+is an optional expansion only when its justification states a distinct reader
+question, supporting source evidence, and the rationale for using that medium.
+Project recap requests also 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 — the hub plus any accepted expansions — without
+changing its artifact 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. `project-recap@1` is immutable
+replay guidance only: retained v1 requests remain readable, but current
+producers do not select it.
 
 Before artifact authoring, a caller supplies one provider-neutral `planSet`
 callback. It receives the reconciled fact base and recipe policy and returns
@@ -62,7 +71,7 @@ callback. It receives the reconciled fact base and recipe policy and returns
 {
   "schemaVersion": "explainer-kit.set-plan/v1",
   "planId": "project-recap-set",
-  "recipe": { "id": "project-recap", "version": "1" },
+  "recipe": { "id": "project-recap", "version": "2" },
   "sourceIds": ["plan"],
   "ledger": {
     "terminology": [],
@@ -87,9 +96,11 @@ 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
+`author-request/v3` 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.
+Version 2 requests remain valid for deterministic replay; new runs emit only
+the complete v3 request.
 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
@@ -183,12 +194,33 @@ The core executes:
 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 and guideline QA, plus required browser and independent
+7. validate every post-render `href`, `src`, `srcset`, and embedded reference
+   against the manifest paths and generated site tree; reject directory links,
+   escapes, missing files or fragments, malformed references, and unsafe
+   embedded resources
+8. optionally apply one bounded author correction, then rerender and revalidate
+   the complete site before any browser callback
+9. 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
-10. write the manifest and build record
+10. close any unresolved recap review gate before external persistence
+11. resolve content approval — the interactive gate pauses here, after render and
+    QA and before anything is published or persisted externally
+12. write the manifest and build record
+
+The internal-reference gate uses a bounded tokenizer/classifier rather than a
+general HTML parser. Relative references resolve from the current explicit file
+with an isolated HTTPS base, then must bind exactly to the manifest/site tree.
+Referenced fragments must resolve to exactly one ID in the target document;
+unused duplicate renderer-generated IDs do not fail indexing. Safe base64 image
+data references and same-document fragments are classified separately. A
+malformed, unresolved, or ambiguous reference fails `E_INTERNAL_REFERENCE`.
+Once the one correction is exhausted, including after visual correction, the run
+fails hard: the QA stage is recorded `failed` with code-only evidence and the
+scrubbed message `The qa stage failed.`, and the run is not durability- or
+publication-eligible. No finding is retained and nothing names the broken
+reference — terminal evidence is code-only by design, and the failure is
+attributed to the `link-validation` evidence stage rather than to
+`browser-review`.
 
 An incomplete interactive result includes
 `approval.resumeToken: "ekrt2:<64 lowercase hex characters>"`. The token is an