npm - @open-agent-toolkit/cli - Versions diffs - 0.2.19 → 0.2.21 - Mend

@open-agent-toolkit/cli 0.2.19 → 0.2.21

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (66) hide show

package/assets/skills/explainer-kit/templates/deck-shell.html CHANGED Viewed

@@ -24,6 +24,7 @@
         --sans: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
         --serif: ui-serif, Georgia, serif;
         --mono: ui-monospace, SFMono-Regular, Consolas, monospace;
+        /* AUTHOR EXTENSION REGION: resolved theme tokens */
         {{THEME_CSS}}
       }
       * {
@@ -39,6 +40,9 @@
         color: var(--ink);
         font-family: var(--sans);
       }
+      noscript p {
+        color: var(--muted);
+      }
       .deck {
         display: flex;
         width: 100%;
@@ -197,16 +201,28 @@
       }
     </style>
   </head>
-  <body>
+  <body data-explainer-shell="deck-shell">
     <noscript>
       <p>This deck remains available below as a readable vertical document.</p>
     </noscript>
-    <main class="deck" aria-label="{{TITLE}}">{{SLIDES}}</main>
-    <nav class="deck-controls" aria-label="Slide navigation">
+    <main class="deck" data-shell-anchor="deck" aria-label="{{TITLE}}">
+      <!-- AUTHOR EXTENSION REGION: semantic section.slide frames -->
+      {{SLIDES}}
+      <!-- END AUTHOR EXTENSION REGION -->
+    </main>
+    <nav
+      class="deck-controls"
+      data-shell-anchor="deck-controls"
+      aria-label="Slide navigation"
+    >
       <button type="button" data-direction="-1" aria-label="Previous slide">
         ←
       </button>
-      <span id="deck-counter" aria-live="polite"></span>
+      <span
+        id="deck-counter"
+        data-shell-anchor="deck-counter"
+        aria-live="polite"
+      ></span>
       <button type="button" data-direction="1" aria-label="Next slide">
         →
       </button>
@@ -214,11 +230,15 @@
     <div
       class="deck-progress"
       id="deck-progress"
+      data-shell-anchor="deck-progress"
       role="progressbar"
       aria-label="Slide progress"
       aria-valuemin="1"
     >
-      <span class="deck-progress__bar"></span>
+      <span
+        class="deck-progress__bar"
+        data-shell-anchor="deck-progress-bar"
+      ></span>
     </div>
     <script>
       (() => {

package/assets/skills/explainer-kit/templates/diagram-shell.html CHANGED Viewed

@@ -20,6 +20,7 @@
         --accent: hsl(215 28% 32%);
         --sans: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
         --mono: ui-monospace, SFMono-Regular, Consolas, monospace;
+        /* AUTHOR EXTENSION REGION: resolved theme tokens */
         {{THEME_CSS}}
       }
       * {
@@ -125,35 +126,56 @@
       }
     </style>
   </head>
-  <body>
+  <body data-explainer-shell="diagram-shell">
     <main>
       <header>
-        <h1 id="diagram-title">{{TITLE}}</h1>
-        <p id="diagram-description">{{DESCRIPTION}}</p>
+        <h1 id="diagram-title" data-shell-anchor="diagram-title">{{TITLE}}</h1>
+        <p id="diagram-description" data-shell-anchor="diagram-description">
+          {{DESCRIPTION}}
+        </p>
       </header>
-      <section class="diagram-shell" aria-labelledby="diagram-title">
+      <section
+        class="diagram-shell"
+        data-shell-anchor="diagram-shell"
+        aria-labelledby="diagram-title"
+      >
         <p class="diagram-hint">
           Use the controls or Ctrl/Command + wheel to zoom; drag to pan.
         </p>
-        <div class="zoom-controls" aria-label="Diagram zoom">
+        <div
+          class="zoom-controls"
+          data-shell-anchor="zoom-controls"
+          aria-label="Diagram zoom"
+        >
           <button type="button" data-zoom="in" aria-label="Zoom in">+</button>
           <button type="button" data-zoom="out" aria-label="Zoom out">−</button>
           <button type="button" data-zoom="reset" aria-label="Reset zoom">
             ↺
           </button>
         </div>
-        <div class="diagram-viewport">
+        <div class="diagram-viewport" data-shell-anchor="diagram-viewport">
           <svg
             class="diagram-canvas"
+            data-shell-anchor="diagram-canvas"
             viewBox="0 0 1200 720"
             role="img"
             aria-labelledby="diagram-title diagram-description"
             xmlns="http://www.w3.org/2000/svg"
           >
+            <!-- AUTHOR EXTENSION REGION: accessible inline SVG diagram -->
             {{DIAGRAM}}
+            <!-- END AUTHOR EXTENSION REGION -->
           </svg>
         </div>
-        <div class="legend" aria-label="Diagram legend">{{LEGEND}}</div>
+        <div
+          class="legend"
+          data-shell-anchor="diagram-legend"
+          aria-label="Diagram legend"
+        >
+          <!-- AUTHOR EXTENSION REGION: optional visual legend -->
+          {{LEGEND}}
+          <!-- END AUTHOR EXTENSION REGION -->
+        </div>
       </section>
     </main>
     <script>

package/assets/skills/explainer-kit/templates/engineer-tour.html CHANGED Viewed

@@ -24,6 +24,7 @@
         --sans: system-ui, -apple-system, BlinkMacSystemFont, sans-serif;
         --serif: ui-serif, Georgia, serif;
         --mono: ui-monospace, SFMono-Regular, Consolas, monospace;
+        /* AUTHOR EXTENSION REGION: resolved theme tokens */
         {{THEME_CSS}}
       }
       * {
@@ -56,8 +57,7 @@
         padding-block: 2.5rem;
       }
       .toc-brand,
-      .eyebrow,
-      .section-number {
+      .eyebrow {
         color: var(--muted);
         font: 0.7rem/1.4 var(--mono);
         letter-spacing: 0.12em;
@@ -116,12 +116,105 @@
         max-width: 100%;
         margin: 0;
         overflow-x: auto;
+        border: 0;
+        border-radius: 0;
+        background: transparent;
         padding: 1rem;
         font-family: var(--mono);
       }
       .snippet:not(.open) pre {
         display: none;
       }
+      .diagram-scroll {
+        max-width: 100%;
+        overflow-x: auto;
+      }
+      .diagram-scroll > svg {
+        display: block;
+      }
+      /* Narrative renderer block output. The renderer emits these for any
+         markdown artifact, so the shell must style them or the structure
+         renders as unformatted text. */
+      .callout {
+        min-width: 0;
+        border: 1px solid var(--border);
+        border-inline-start: 0.25rem solid var(--accent);
+        border-radius: 0.6rem;
+        background: var(--panel);
+        padding: 1rem;
+        overflow-wrap: anywhere;
+      }
+      .callout--important {
+        border-inline-start-color: var(--success, var(--accent));
+      }
+      .callout--warning {
+        border-inline-start-color: var(--warning);
+      }
+      .callout--caution {
+        border-inline-start-color: var(--danger, var(--warning));
+      }
+      .callout__label {
+        color: var(--muted);
+        font: 0.72rem/1.4 var(--mono);
+        font-weight: 700;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+      .timeline {
+        display: grid;
+        gap: 0.8rem;
+        padding-inline-start: 0;
+        list-style: none;
+      }
+      .timeline li {
+        display: grid;
+        grid-template-columns: minmax(7rem, 0.25fr) 1fr;
+        gap: 1rem;
+        border-inline-start: 0.2rem solid var(--accent);
+        padding-inline-start: 1rem;
+      }
+      .timeline time {
+        color: var(--muted);
+        font-family: var(--mono);
+      }
+      .table-scroll,
+      pre {
+        max-width: 100%;
+        overflow-x: auto;
+      }
+      table {
+        width: 100%;
+        border-collapse: collapse;
+      }
+      th,
+      td {
+        border-block-end: 1px solid var(--border);
+        padding: 0.6rem;
+        text-align: start;
+      }
+      pre {
+        border: 1px solid var(--border);
+        border-radius: 0.6rem;
+        background: var(--panel);
+        padding: 1rem;
+        font-family: var(--mono);
+      }
+      code {
+        font-family: var(--mono);
+      }
+      blockquote {
+        margin-inline: 0;
+        border-inline-start: 0.2rem solid var(--border);
+        color: var(--muted);
+        padding-inline-start: 1rem;
+      }
+      figure {
+        margin-inline: 0;
+      }
+      figcaption {
+        color: var(--muted);
+        font: 0.8rem/1.5 var(--mono);
+      }
       .diagram-rail {
         position: sticky;
         top: 0;
@@ -140,6 +233,19 @@
         width: 100%;
         height: auto;
       }
+      .diagram-card .node rect {
+        fill: var(--panel-muted);
+        stroke: var(--accent);
+        stroke-width: 1.5;
+      }
+      .diagram-card .edge {
+        fill: none;
+        stroke: var(--muted);
+      }
+      .diagram-card text {
+        fill: var(--ink);
+        font: 0.85rem var(--sans);
+      }
       .diagram-card .node,
       .diagram-card .edge {
         transition: opacity 180ms ease, stroke 180ms ease, fill 180ms ease;
@@ -199,25 +305,43 @@
       }
     </style>
   </head>
-  <body>
-    <div class="layout">
-      <nav class="toc" aria-label="Tour sections">
+  <body data-explainer-shell="engineer-tour">
+    <div class="layout" data-shell-anchor="tour-layout">
+      <nav
+        class="toc"
+        data-shell-anchor="tour-navigation"
+        aria-label="Tour sections"
+      >
         <div class="toc-brand">{{EYEBROW}}</div>
+        <!-- AUTHOR EXTENSION REGION: section navigation -->
         {{NAVIGATION}}
+        <!-- END AUTHOR EXTENSION REGION -->
       </nav>
-      <main class="tour-body">
+      <main class="tour-body" data-shell-anchor="tour-body">
         <header>
           <div class="eyebrow">{{EYEBROW}}</div>
           <h1>{{TITLE}}</h1>
           <p>{{DESCRIPTION}}</p>
         </header>
+        <!-- AUTHOR EXTENSION REGION: narrative tour sections -->
         {{CONTENT}}
-        <footer>{{FOOTER}}</footer>
+        <!-- END AUTHOR EXTENSION REGION -->
+        <footer>
+          <!-- AUTHOR EXTENSION REGION: supporting references and next steps -->
+          {{FOOTER}}
+          <!-- END AUTHOR EXTENSION REGION -->
+        </footer>
       </main>
-      <aside class="diagram-rail" aria-label="System diagram">
-        <div class="diagram-card">
+      <aside
+        class="diagram-rail"
+        data-shell-anchor="diagram-rail"
+        aria-label="System diagram"
+      >
+        <div class="diagram-card" data-shell-anchor="diagram-card">
           <svg viewBox="0 0 360 540" role="img" aria-label="{{TITLE}}">
+            <!-- AUTHOR EXTENSION REGION: synchronized system diagram -->
             {{DIAGRAM}}
+            <!-- END AUTHOR EXTENSION REGION -->
           </svg>
         </div>
       </aside>

package/assets/skills/explainer-kit/templates/house-style.html CHANGED Viewed

@@ -118,11 +118,76 @@
       .callout {
         border-inline-start: 0.25rem solid var(--accent);
       }
+      .callout--tip,
+      .callout--note {
+        border-inline-start-color: var(--accent);
+      }
+      .callout--important {
+        border-inline-start-color: var(--success);
+      }
+      .callout--warning {
+        border-inline-start-color: var(--warning);
+      }
+      .callout--caution {
+        border-inline-start-color: var(--danger);
+      }
+      .callout__label {
+        color: var(--muted);
+        font: 0.72rem/1.4 var(--mono);
+        font-weight: 700;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+      }
+      blockquote {
+        margin-inline: 0;
+        border-inline-start: 0.2rem solid var(--border);
+        padding-inline-start: 1rem;
+        color: var(--muted);
+      }
+      .task-list {
+        padding-inline-start: 0;
+        list-style: none;
+      }
+      .task-list li {
+        display: flex;
+        align-items: baseline;
+        gap: 0.5rem;
+      }
+      .task-list li > p {
+        margin-block: 0.2rem;
+      }
+      .timeline {
+        display: grid;
+        gap: 0.8rem;
+        padding-inline-start: 0;
+        list-style: none;
+      }
+      .timeline li {
+        display: grid;
+        grid-template-columns: minmax(7rem, 0.25fr) 1fr;
+        gap: 1rem;
+        border-inline-start: 0.2rem solid var(--accent);
+        padding-inline-start: 1rem;
+      }
+      .timeline time {
+        color: var(--muted);
+        font-family: var(--mono);
+      }
       .table-scroll,
+      .diagram-scroll,
       pre {
         max-width: 100%;
         overflow-x: auto;
       }
+      .diagram-scroll > svg {
+        display: block;
+      }
+      pre {
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        background: var(--panel-muted);
+        padding: 1rem;
+      }
       table {
         width: 100%;
         border-collapse: collapse;
@@ -137,6 +202,23 @@
       pre {
         font-family: var(--mono);
       }
+      :not(pre) > code {
+        border-radius: calc(var(--radius) / 2);
+        background: var(--panel-muted);
+        padding: 0.1em 0.3em;
+      }
+      figure {
+        margin-inline: 0;
+        border: 1px solid var(--border);
+        border-radius: var(--radius);
+        background: var(--panel);
+        padding: 1rem;
+      }
+      figcaption {
+        margin-block-start: 0.5rem;
+        color: var(--muted);
+        font-size: 0.9rem;
+      }
       footer {
         border-block-start: 1px solid var(--border);
         color: var(--muted);

package/assets/skills/oat-explainer-kit/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: oat-explainer-kit
-version: 1.0.1
+version: 1.0.2
 description: Use when building project explainers or recaps from OAT configuration, state, and lifecycle artifacts.
 disable-model-invocation: false
 user-invocable: true
@@ -19,6 +19,7 @@ Adapt OAT project context into the versioned request consumed by the canonical
 - Derive canonical project or repository output roots.
 - Bind OAT lifecycle artifacts to generic recipe source roles.
 - Resolve project explainer and recap intent before invoking the core.
+- Require lifecycle callers to construct a brief-aware author seam.
 ## Dependency Direction
@@ -33,7 +34,7 @@ rollback, and operator-owned real-wrapper gate, use `references/migration.md`.
 Before reading OAT config or invoking the core, call
 `scripts/check-core.mjs#checkCoreCompatibility` with this installed skill
-directory and minimum core version `1.0.0`. Continue only when it returns
+directory and minimum core version `2.0.0`. Continue only when it returns
 `ok: true`.
 - Missing core: stop and show
@@ -54,7 +55,7 @@ Call `scripts/run.mjs#runOatExplainer` with the repository root, project
 invocation, active project path, recipe, slug, lifecycle mode, and any explicit
 runtime overrides. The adapter:
-1. checks the user-scoped installed core at minimum version `1.0.0`;
+1. checks the user-scoped installed core at minimum version `2.0.0`;
 2. resolves only the public `explainers.*` and `workflow.explainers.*` keys;
 3. derives the canonical project output root;
 4. binds approved OAT artifacts to the recipe's single `project` source set;
@@ -68,13 +69,19 @@ Missing optional artifacts are omitted, but at least one approved lifecycle
 artifact is required. An explicit supplied fact-base path bypasses artifact
 federation and is passed through as `factBase.mode: supplied`.
+Before invocation, read `references/author-callback.md` and construct exactly
+one provider-neutral author seam in both modes: in-process callers supply
+`author`, while JSON/CLI callers supply `authorModulePath` naming a module with
+an `author` function export. The callback consumes `author-request/v2` with the
+recipe brief and fact base inlined, plus theme and any recipe-selected artistic
+shell. It may propose expansion only through recipe profile IDs. The adapter
+validates and resolves that executable input before passing it to
+`core.runExplainer`; callbacks and module paths never enter the persisted run
+request.
 Unattended project runs pass `approved-oat-artifacts` provenance to the core's
-content-approval seam and never prompt. Every unattended run also requires
-exactly one provider-neutral author seam: in-process callers supply `author`,
-while JSON/CLI callers supply `authorModulePath` naming a module with an
-`author` function export. The adapter validates and resolves that executable
-input before passing it to `core.runExplainer`; callbacks and module paths never
-enter the persisted run request.
+content-approval seam and never prompt. Automated completion and
+implementation-tail recaps always use `mode: unattended`.
 Federated runs still require an explicit provider-neutral critic callback.
 In-process callers may supply `critic` (or `coreOptions.critic` for

package/assets/skills/oat-explainer-kit/references/author-callback.md ADDED Viewed

@@ -0,0 +1,51 @@
+# Author callback contract
+Lifecycle callers own the executable author seam; the explainer core owns
+construction of each author request. In-process callers pass an `author`
+callback to `runOatExplainer`. JSON-only and official CLI callers pass
+`authorModulePath`, which must name a module with an `author` function export.
+Provide exactly one of those inputs in both interactive and unattended modes.
+The callback or module may use any provider, but its request and result remain
+provider-neutral.
+## Request handling
+The callback receives one `explainer-kit.author-request/v2` per artifact. The
+core constructs that request from recipe-owned policy:
+- `brief` contains the prose loaded from the floor entry or expansion profile's
+  `briefRef`; the author must treat the inlined brief as its editorial contract.
+- `factBase` contains the reconciled evidence for the run. Ground claims in that
+  fact base and do not replace it with ambient project context.
+- `authoring` selects the output path. Return Markdown for `markdown` and a
+  complete HTML document for `html`.
+- `theme` is attached to every request. HTML requests also carry the
+  recipe-selected `shell`; use it as the starting canvas while following the
+  brief's license to elaborate.
+- A floor request may include `floor.requiredNarrative`, which identifies the
+  narrative coverage checked later as non-blocking guidelines.
+Return one matching `explainer-kit.author-result/v2`: preserve `artifactId`,
+set exactly one of `content.markdown` or `content.html`, and include
+`provenance`. Do not persist provider credentials or callback configuration in
+the result.
+## Expansion
+Only a floor result may propose expansion. Put each proposal in
+`proposedArtifacts` as `{id, profileId, rationale}`. Do not choose an artifact
+type, authoring mode, brief, or shell in the proposal; the referenced recipe
+profile, selected by `profileId`, owns those values.
+The core validates proposal IDs, profile membership, collisions, and finite
+caps. It rejects malformed proposals, records over-limit proposals as warnings,
+and issues a new author request for every accepted artifact. Handle each
+follow-up request independently and do not recursively propose more artifacts.
+## Lifecycle invocation
+Automated project-completion and implementation-tail recaps always call
+`runOatExplainer` with `mode: unattended`. They construct the author seam before
+invocation and supply it alongside the existing provider-neutral `critic` or
+validated `criticModulePath`. Interactive invocations use the same author
+contract; only the later approval behavior differs.

package/assets/skills/oat-explainer-kit/references/lifecycle-contract.md CHANGED Viewed

@@ -71,18 +71,20 @@ On a stale-write conflict, the caller must re-read state, resolve precedence
 again, and decide whether a write is still required. It must not retry the old
 record blindly.
-## Unattended author execution
+## Author execution
-Every unattended adapter run must provide exactly one provider-neutral author
-seam. In-process callers pass `author`; JSON-only and official CLI callers put
-`authorModulePath` in the adapter context, naming a module whose `author` export
-is a function. Missing module files, invalid exports, and direct-plus-module
-conflicts fail at the adapter boundary.
+Every adapter run in both interactive and unattended modes must provide exactly
+one provider-neutral author seam. In-process callers pass `author`; JSON-only
+and official CLI callers put `authorModulePath` in the adapter context, naming
+a module whose `author` export is a function. Missing module files, invalid
+exports, and direct-plus-module conflicts fail at the adapter boundary. See
+`author-callback.md` for brief, fact-base, shell, theme, result, and expansion
+handling.
 The resolved callback is passed only as the `author` option to
 `core.runExplainer`. It is never copied into `ExplainerRunRequestV1`,
-`run-request.json`, or another retained data contract. Interactive runs may
-omit an author and retain their existing reviewed-source path.
+`run-request.json`, or another retained data contract. Interactive runs use the
+same author contract and differ only at the later approval gate.
 ## Tracked-run finalization

package/assets/skills/oat-explainer-kit/scripts/resolve-intent.mjs CHANGED Viewed

@@ -130,6 +130,20 @@ export function validateIntentRecord(product, record) {
   return record;
 }
+export function explainerModeForIntent(intent) {
+  if (
+    !intent ||
+    typeof intent !== 'object' ||
+    intent.product !== 'projectRecap' ||
+    intent.decision !== 'generate'
+  ) {
+    throw new Error(
+      'Only a generated projectRecap intent can select completion-chain explainer mode.',
+    );
+  }
+  return 'unattended';
+}
 function resolveAutonomous({
   product,
   state,

package/assets/skills/oat-explainer-kit/scripts/run.mjs CHANGED Viewed

@@ -12,7 +12,7 @@ import {
 } from './resolve-config.mjs';
 import { resolveExplainerOutputRoot } from './resolve-paths.mjs';
-const MINIMUM_CORE_VERSION = '1.0.0';
+const MINIMUM_CORE_VERSION = '2.0.0';
 const ADAPTER_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export async function runOatExplainer({
@@ -114,7 +114,6 @@ export async function runOatExplainer({
     author,
     authorModulePath,
     coreOptions,
-    mode: request.mode,
   });
   const lifecycleCritic = await resolveLifecycleCritic({
     critic,
@@ -141,6 +140,7 @@ export async function runOatExplainer({
     request,
     manifest,
     result,
+    marking: result.marking ?? null,
     outputRoot,
   };
 }
@@ -149,7 +149,6 @@ async function resolveLifecycleAuthor({
   author,
   authorModulePath,
   coreOptions,
-  mode,
 }) {
   if (coreOptions?.author !== undefined) {
     throw new TypeError(
@@ -166,14 +165,11 @@ async function resolveLifecycleAuthor({
   }
   if (author === undefined && authorModulePath === undefined) {
-    if (mode === 'unattended') {
-      const error = new Error(
-        'Unattended OAT explainer runs require exactly one provider-neutral author callback or author module entry point.',
-      );
-      error.code = 'E_AUTHOR_REQUIRED';
-      throw error;
-    }
-    return null;
+    const error = new Error(
+      'Unattended and interactive OAT explainer runs require exactly one provider-neutral author callback or author module entry point.',
+    );
+    error.code = 'E_AUTHOR_REQUIRED';
+    throw error;
   }
   if (authorModulePath === undefined) {
     return author;

package/assets/skills/oat-project-complete/SKILL.md CHANGED Viewed

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.5.4
+version: 1.6.0
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -282,7 +282,23 @@ When `SHOULD_GENERATE_RECAP="true"`, inspect manifests under
 `{PROJECT_PATH}/explainers/` before generating. A fresh `project-recap` manifest for the current completed implementation is reused without invoking the adapter again. Fresh means the manifest identifies recipe `project-recap`, belongs to this project, has a terminal outcome, and its recorded source hashes match the current approved implementation inputs, including the refreshed summary when present.
 If no fresh recap exists, invoke `scripts/run.mjs#runOatExplainer` exactly once with recipe `project-recap`, project invocation, the active project, and unattended lifecycle mode so approved OAT artifacts do not trigger a second content prompt. A failed adapter run warns but does not block completion. Use a returned valid terminal `project-recap` manifest as the selected run; do not rerun to improve its outcome.
-Supply the provider-neutral critic callback (or validated critic module entry point for JSON/CLI invocation) on every federated adapter run.
+Before that invocation, construct exactly one brief-aware, provider-neutral
+author seam as documented by
+`oat-explainer-kit/references/author-callback.md`. In-process callers pass
+`author`; JSON/CLI callers pass a validated `authorModulePath`. Supply it
+alongside the existing `critic` callback (or validated
+`criticModulePath`), and invoke the recap with `mode: unattended`.
+The author seam is the recap's quality mechanism, so derive its output from the
+request rather than from ambient context or a stock recap shape. Cover every
+`floor.requiredNarrative` section, ground each claim in the supplied `factBase`,
+and follow the inlined `brief` for structure — evidence tables for the
+implementation and validation sections, at least one high-level architecture
+diagram, and lists where material is enumerable. A recap whose warnings include
+`guideline-narrative-coverage-missing`, `guideline-structured-depth-missing`, or
+`guideline-architecture-diagram-missing` is thin: it still completes, but treat
+those warnings as the signal that the authored content did not use the evidence
+it was given.
 Set `SELECTED_PROJECT_RECAP_RUN` only to the final selected `project-recap` run. The value must be project-relative in the form `explainers/<run-slug>` so it can be passed safely to the archive CLI. An incomplete, stale, wrong-project, or `project-explainer` manifest is never selected as the final recap.