@open-agent-toolkit/cli 0.2.29 → 0.2.31

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.29"
+  "oatVersion": "0.2.31"
 }

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

@@ -138,6 +138,7 @@ plumbing uses `explainers.*`; project lifecycle preferences use
 | `explainers.publish.publicBaseUrl`     | HTTPS URL                    | shared              | unset           |
 | `explainers.publish.awsRegion`         | non-empty string             | shared              | unset           |
 | `explainers.publish.awsProfile`        | non-empty string             | local, user         | unset           |
+| `explainers.publish.publicAccess`      | `public\|protected`          | shared              | `public`        |
 | `workflow.explainers.projectExplainer` | `always\|ask\|never`         | local, shared, user | `ask`           |
 | `workflow.explainers.projectRecap`     | `always\|ask\|never`         | local, shared, user | `ask`           |
 
@@ -172,6 +173,46 @@ chain applies. Config never starts publishing by itself: lifecycle callers must
 still select publish durability explicitly, and publishing remains
 human-gated. Raw AWS credentials are not config keys.
 
+`publicAccess` declares whether published objects are expected to be reachable
+anonymously; it does not authorize publication and it does not change any
+bucket policy. It selects how publication is verified. The default `public`
+fetches every uploaded object over HTTPS and compares the returned bytes
+against the manifest hash. `protected` skips those anonymous fetches, verifies
+each object through authenticated S3 hashing instead, and records
+`skipped-protected` in the publish receipt. Because no anonymous fetch happens
+under `protected`, a mistyped `publicBaseUrl` is not detected at publish time:
+the advertised URLs are still written into the initiative catalog and receipt,
+and the catalog records `publicVerification: "skipped-by-policy"` so consumers
+can see the URLs were never exercised.
+
+### Explainer publication environment variables
+
+Two escape hatches are read from the process environment rather than from
+config, because both are machine-local operational overrides rather than
+project settings. Neither has a config key.
+
+| Variable                                         | Effect                                                                      | Default |
+| ------------------------------------------------ | --------------------------------------------------------------------------- | ------- |
+| `EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT`        | Permits a loopback, link-local, unique-local or RFC 1918 `publicBaseUrl`    | off     |
+| `EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` | Silences the advisory warning when the S3 key prefix and public path differ | off     |
+
+Both accept `1`, `true` or `on`.
+
+`EXPLAINER_KIT_ALLOW_PRIVATE_PUBLIC_ROOT` disables an anti-SSRF control. Public
+verification issues an outbound GET against whatever `publicBaseUrl` names, so
+by default the connector refuses internal addresses — including the
+`169.254.169.254` instance-metadata endpoint. Enable it only for a genuinely
+internal mirror. When it is set and the root is in fact non-public, the run
+records `publicRootPolicy: "private-allowed"` in the publish receipt, so a
+publication made with the control disabled is distinguishable in durable
+evidence from one made without it. The policy is address-literal only: a
+hostname that resolves inward is not detected either way.
+
+`EXPLAINER_KIT_SUPPRESS_ROOT_DIVERGENCE_WARNING` only affects an advisory
+message. Divergent roots are never a publication failure — a CloudFront Origin
+Path deployment legitimately maps a bucket prefix to the distribution root — so
+this changes no validation outcome.
+
 See [Explainer Kit](../workflows/skills/explainer-kit.md) for recipes, artifact
 locations, lifecycle behavior, and durability.
 
@@ -568,7 +609,11 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.hillCheckpointDefault` — `every` or `final`. Default HiLL checkpoint behavior in `oat-project-implement`: pause after every phase or only after the last phase. When unset, the skill prompts.
 - `workflow.archiveOnComplete` — boolean. Skip the "Archive after completion?" prompt in `oat-project-complete`. When unset, the skill prompts.
 - `workflow.createPrOnComplete` — boolean. Skip the "Open a PR?" prompt in `oat-project-complete`; when true, completion auto-triggers PR creation. When unset, the skill prompts.
-- `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings; structured arrays contain ordered, globally unique `summary`, `document`, and `pr` steps. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
+- `workflow.postImplementSequence` — legacy `wait`, `summary`, `pr`, or `docs-pr`, or `{ "preApproval": [...], "postApproval": [...] }`. Legacy values remain strings and keep their existing mappings. Structured arrays contain ordered, globally unique `summary`, `document`, `pr`, and `retro` steps. `retro` is post-approval only: a structured value containing it in `preApproval` is rejected. Pre-approval steps run after final review and before final HiLL approval; post-approval steps run only after that approval. Plain retrieval keeps legacy strings and prints structured values as compact JSON; `--json` returns the raw value.
+- `workflow.retro.filing.repo` — `issues`, `backlog`, or `none`; unset by default. Selects the repo-lane filing destination.
+- `workflow.retro.filing.upstream` — `issues` or `none`; unset by default. Selects the upstream-lane filing destination.
+- `workflow.retro.apply` — `auto` or `ask`; defaults to `ask` behavior when unset. `auto` authorizes bounded promotion application in non-interactive runs; `ask` is propose-only when no interaction is possible.
+- `workflow.retro.upstreamRepo` — `owner/repo`; unset in CLI configuration. Retro guidance defaults it to `voxmedia/open-agent-toolkit`.
 - `workflow.reviewExecutionModel` — `subagent`, `inline`, or `fresh-session`. Default final-review execution model in `oat-project-implement`. `subagent` and `inline` run automatically. `fresh-session` is a soft preference: the skill prints guidance to run the review in another session but still offers escape hatches to `subagent` or `inline` if you change your mind. When unset, the skill prompts.
 - `workflow.autoReviewAtHillCheckpoints` — boolean. Automatically run the extra lifecycle review when a HiLL checkpoint is reached. This does not control Tier 1 per-phase `oat-reviewer` gates, which run after each phase in Tier 1 regardless of this setting. When unset, the skill prompts.
 - `workflow.autoNarrowReReviewScope` — boolean, default `true`. Re-reviews automatically use the guarded range after the prior matching review's recorded head. Unset and `true` enable narrowing without a prompt; set `false` to opt out and use the nominal full scope.
@@ -585,6 +630,12 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — validated default gate-review budgets in milliseconds. Both resolve through `local > shared > user`.
 
+Explicit `workflow.retro.apply: auto` or `workflow.retro.filing.*`
+configuration counts as consent for the corresponding non-interactive action.
+Without those settings, non-interactive retro generation records proposals but
+does not apply or file them. Interactive runs still present the applicable
+promotion and filing choices before side effects.
+
 The two project-log keys use the standard workflow precedence:
 `local > shared > user > default`.
 

package/assets/docs/contributing/code.md

@@ -41,18 +41,30 @@ OAT is organized as a pnpm workspace with Turborepo orchestration.
 
 ## Quality Gates
 
-Run the workspace checks that match your change surface:
+Every change runs the ordered Definition of Done from the root `AGENTS.md`,
+which mirrors CI's gate steps exactly so a locally green run implies CI green:
 
 ```bash
-pnpm test
-pnpm lint
-pnpm format
+pnpm check
 pnpm type-check
-pnpm build          # excludes docs for speed
-pnpm build:docs     # builds docs site and its dependencies
+pnpm test
+pnpm build                    # excludes docs for speed
+pnpm run check:skill-bumps    # changed .agents/skills/*/SKILL.md must bump version
+pnpm release:check-versions   # lockstep public package version bumps
+pnpm release:validate
+pnpm build:docs               # builds docs site and its dependencies
 ```
 
-For narrower changes, use package-specific checks when possible, but do not merge without passing the relevant workspace gates.
+`pnpm test` is composite: it runs the workspace vitest suites, then
+`test:smoke` (`tools/smoke`), `test:skills` (`.agents/skills/*/tests`), and
+the named-file `test:release` set. Steps 5 and 6 are the version-lockstep
+gates; they are in the local list because they previously ran only in CI and
+version-bump drift twice reached review with no local gate to surface it.
+
+CI runs neither `pnpm lint` nor `pnpm format` — run both whenever a change
+touches `tools/smoke` or `.agents/skills`, since nothing else covers them.
+For narrower changes, use package-specific checks when possible, but do not
+merge without passing the relevant workspace gates.
 
 ### TypeScript and type-aware linting
 

package/assets/docs/contributing/explainer-kit-verification.md

@@ -62,6 +62,11 @@ The suite recomputes semantic-input hashes, grounds every claim in retained
 source evidence, and evaluates the shared rubric against live runtime output.
 A prose claim or status label without runtime proof does not pass.
 
+The existing three-case, 27-capture golden suite is intentionally unchanged by
+the prose-led visual-review work. Simplifying it is a separate follow-up: first
+audit each case's unique coverage, runtime cost, and flakiness, then remove or
+replace fixtures only with evidence that the same behavior remains protected.
+
 ## Inspect generated evidence
 
 The suite materializes each case's runtime package under its temporary working
@@ -114,9 +119,12 @@ pnpm check
 pnpm type-check
 pnpm test
 pnpm build
+pnpm run check:skill-bumps
+pnpm release:check-versions
+pnpm release:validate
+pnpm build:docs
 pnpm lint
 pnpm format
-pnpm build:docs
 git diff --check
 ```
 

package/assets/docs/contributing/skills.md

@@ -43,6 +43,15 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - `allowed-tools`
 - `oat_gateable`
 
+### The `version` field is gated
+
+Changing any canonical skill's `SKILL.md` requires bumping its frontmatter
+`version` in the same PR — one bump per changed skill in the final PR diff,
+even if the skill was edited multiple times on the branch. The rule is
+enforced by `pnpm run check:skill-bumps`, which runs locally (root `AGENTS.md`
+Definition of Done) and in CI; a changed skill whose version matches
+`origin/main` fails the gate.
+
 ## Practical Authoring Flow
 
 1. Decide whether you are adding a general reusable skill or an OAT-specific lifecycle skill.

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

@@ -30,6 +30,11 @@ Mode-sensitive notes:
 - `pr/*.md`: generated PR descriptions
 - `references/imported-plan.md`: preserved source plan for import mode
 - `references/split-plan.json`: persisted split plan for a coordination parent, used as the durable resume source when `oat-project-split` is interrupted
+- `references/project-retro.md`: optional post-approval retrospective with
+  machine-scannable repo-improvement (`RP-NN`) and upstream-feedback (`UP-NN`)
+  registers. Promotion and filing rollups let the retro skills resume approved
+  applications and tracker filing without repeating settled work. See
+  [Project Retrospectives](retro.md).
 
 ### Explainer artifacts
 

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

@@ -12,6 +12,7 @@ Projects are where the workflow layer becomes concrete: lifecycle phases, `state
 ## Contents
 
 - [Lifecycle](lifecycle.md) - End-to-end flow from discovery through completion.
+- [Project Retrospectives](retro.md) - Generate evidence-grounded retros, apply repo improvements, and file tracker feedback.
 - [Autonomous Project Execution](autonomy.md) - Session-scoped autonomy signals, gate boundaries, review requirements, and execution learnings.
 - [OAT in Cursor Cloud](cursor-cloud.md) - Project-home, provisioning, asset-precedence, and execution-surface guidance for cloud agents.
 - [Design Modes](design-modes.md) - How full design balances collaborative, selective collaborative, and draft-and-review interaction.

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

@@ -110,12 +110,35 @@ approval, and only then runs post-approval steps. The snapshot is restart-safe:
 an incomplete sequence routes back to implementation and resumes from its first
 incomplete step.
 
+Structured sequences accept `summary`, `document`, `pr`, and `retro`.
+`retro` is post-approval only: placing it in `preApproval` invalidates the
+structured value. This placement lets the retrospective include the final
+approval and feedback tail while still running before project completion
+freezes lifecycle artifacts. The legacy string mappings are unchanged and do
+not add a retro step.
+
+When a pending post-approval `retro` step runs, OAT dispatches
+`oat-project-retro` in generate mode. Applying repo improvements and filing
+tracker items remain separately consented through interactive confirmation or
+`workflow.retro.*` configuration.
+
 `oat-project-next` checks `oat_implement_exit_gate` before every normal
 post-implementation route. Missing, pending, blocked, malformed, or stale state
 routes back to `oat-project-implement` even when `oat_phase_status` is
 `complete` or `pr_open`. Only an allowed, fresh disposition can continue to
 summary, documentation, PR, or project completion.
 
+### Retrospective completion safety net
+
+Before an interactive completion archives the project,
+`oat-project-complete` checks for
+`{PROJECT_PATH}/references/project-retro.md`. If the artifact is missing, it
+offers to generate one before completion. If the artifact exists, completion
+does not offer another retro; it may note unsettled promotion or filing
+registers. Non-interactive completion skips this offer, so autonomous
+generation occurs only through an explicitly configured post-approval `retro`
+step.
+
 When `workflow.autoReviewAtHillCheckpoints` is enabled or `plan.md` frontmatter sets `oat_auto_review_at_hill_checkpoints`, completing a HiLL checkpoint automatically runs the extra lifecycle review scoped to every implementation phase not already covered by a passed whole-phase code review, through the just-completed checkpoint. Mid-implementation multi-phase reviews use inclusive phase-range scopes such as `p02-p03`; the final implementation checkpoint uses `code final`. The review uses auto-disposition mode (minors auto-converted to fix tasks, no user prompts). Disabled by default. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks. This does not control Tier 1 per-phase `oat-reviewer` gates.
 
 ### Phase-review setup during planning

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

@@ -0,0 +1,261 @@
+---
+title: Project Retrospectives
+description: Generate evidence-grounded project retrospectives, apply repo improvements, and file tracker feedback.
+---
+
+# Project Retrospectives
+
+OAT project retrospectives capture how an implementation run went and route
+what should change next. The workflow uses two skills:
+
+- `oat-project-retro` generates
+  `{PROJECT_PATH}/references/project-retro.md` and applies approved repo
+  improvements.
+- `oat-project-retro-file` files tracker-bound feedback into repository or
+  upstream GitHub issues and OAT backlog items.
+
+A configured `retro` post-approval sequence step can generate the artifact
+after final feedback exists and before project completion freezes lifecycle
+artifacts. Interactive completion also offers generation when the artifact is
+missing. Neither path applies or files findings without separate consent.
+
+## Generate a retrospective
+
+Ask to run the project retro, or configure `retro` in
+`workflow.postImplementSequence.postApproval`. Generate mode resolves the active
+project, inventories evidence, renders the retro artifact, and records the run
+in the project log when that log exists.
+
+Evidence is read in this order:
+
+1. `project-log.md`
+2. `oat-execution-learnings.md`, when present
+3. Lifecycle artifacts such as `implementation.md`, `state.md`, `plan.md`,
+   design and discovery artifacts, reviews, and evidence ledgers
+4. The current session or run transcript when the environment makes it
+   available
+
+The artifact identifies every used or unavailable source. Missing transcript
+access is recorded rather than hidden, and runtime claims fall back to durable
+ledgers when transcript output is incomplete. Findings distinguish confirmed
+causes, hypotheses, and inconclusive mechanisms.
+
+Evidence status remains `used | unavailable`. When an evidence family is
+partial, split it into truthful source entries, such as
+`archived-review-markdown: unavailable` and `gate-receipts: used`, rather than
+recording `review-artifacts: unavailable`. Do not add a `partial` evidence
+status. Derivative current-run reconnaissance transcripts are not original
+project-run evidence.
+
+### Scale depth to the evidence
+
+Keep output concise by default. Every section must add distinct information.
+Prefer references to evidence over repeated chronology. For a small project,
+keep core sections brief. Use subsections and tables only for evidence-rich
+projects where they improve decisions. The required core and register
+contracts stay intact; evidence volume controls depth, not a new configuration
+or consent setting.
+
+Each material incident remains understandable without opening another
+artifact. Use stable evidence anchors such as project-log event IDs, artifact
+headings, review paths, decision IDs, and commit IDs. Anchors supplement but
+never replace explanation.
+
+Narrative sections have distinct ownership:
+
+- `Challenges and Struggles` owns the complete incident narrative: what
+  happened, impact, response, and result.
+- `Where We Changed Course` records only the trigger, changed direction, and
+  outcome.
+- `Domain Learnings` abstracts reusable lessons without replaying chronology.
+- `Gotchas for Humans` and `Gotchas for Autonomous Agents` contain
+  future-facing instructions rather than incident summaries.
+
+Every retro contains two machine-scannable registers:
+
+- **Repo Improvements (`RP-NN`)** route each item through
+  `Disposition: apply` for a bounded repo edit or `Disposition: file` for a
+  tracker follow-up.
+- **OAT Upstream Feedback (`UP-NN`)** contains sanitized, tracker-ready
+  suggestions for toolkit improvements. The section remains present with an
+  explicit empty state when no upstream item is warranted.
+
+Per-item statuses and frontmatter rollups make interrupted and repeated runs
+resumable. The promotions rollup covers RP apply-items; the filing rollup covers
+UP items plus RP file-items.
+
+### Project-log receipt
+
+When a project log exists, generate mode appends this one-line structural
+receipt:
+
+```text
+retro artifact=<path> evidence_used=<csv> evidence_unavailable=<csv> promotions=<number> upstream=<number> apply=<performed|declined|skipped|deferred> filing=<performed|declined|skipped|deferred>
+```
+
+Source identifiers are validated, deduplicated, sorted bytewise ascending, and
+joined with commas and no spaces; an empty source list is `none`. Counts
+describe the generated registers.
+
+Before any apply decision or filing dispatch, capture one immutable eligibility
+snapshot for that action. Apply snapshots contain unsettled RP apply-items;
+filing snapshots contain the lane-tagged union of unsettled UP items and RP
+file-items. Do not recompute initial eligibility after an action changes the
+registers.
+
+Derive each outcome from that snapshot with this precedence:
+
+1. An initially empty snapshot is `skipped`.
+2. An action-level interactive rejection before entry is `declined`.
+3. Non-entry, failure, or any snapshot member still unsettled is `deferred`.
+4. An entered action that completes normally with no snapshot member remaining
+   is `performed`.
+
+This makes an all-settled successful action `performed`, even though its
+post-action eligible set is empty. For mixed filing lanes, any initially
+eligible lane left unsettled by absent or `none` routing makes the single filing
+outcome `deferred`; normal completion that settles every initial lane is
+`performed`.
+
+The append uses stable structural identity and the exact rendered body:
+
+```bash
+oat project log append --project "$PROJECT_PATH" --structural \
+  --producer oat-project-retro \
+  --ref project-retro \
+  --body "$RECEIPT_BODY"
+```
+
+## Apply repo improvements
+
+Invoke apply mode directly with wording such as "apply the retro findings."
+Apply mode requires an existing retro and never regenerates it. It processes
+only RP items whose authoritative disposition is `apply` and whose status is
+`proposed` or `approved`.
+
+Interactive runs present each item, target, rationale, and concrete edit before
+approval. Non-interactive runs apply items only when
+`workflow.retro.apply: auto`; an absent value or `ask` leaves proposals
+untouched when no interaction is possible.
+
+Application follows the item type:
+
+- documentation updates the canonical existing page;
+- agent instructions update the narrowest existing instruction surface;
+- rules update the canonical scoped rule;
+- decisions use `oat decision new` after an exact duplicate check; and
+- code follow-ups default to `Disposition: file` and remain outside apply mode.
+
+After a successful application, the skill records `Status: applied` and an
+`Applied-ref`. Re-runs skip settled items and recover an exact prior side effect
+instead of applying it twice.
+
+For a docs item whose safely normalized target canonical path has the exact,
+case-sensitive final component `project-log.md`, apply mode uses
+`oat project log append` and never directly edits the log. Absolute paths,
+traversal, and ambiguous normalization fail closed; suffixes and prefixed
+lookalikes remain ordinary docs targets.
+
+The proposal must identify the prior heading or event being corrected and
+preserve the original entry. The appended judgment uses `--type feedback`,
+`--scope project`, `--area "retro correction $RP_ID"`, and a body whose stable
+identity includes both the RP ID and original-entry anchor. Before appending,
+perform semantic post-side-effect recovery. The skill recovers an exact
+uncommitted or committed correction and stops on partial, divergent, or
+multiple matches before it appends.
+
+The correction is committed first without retro writeback. A later retro-only
+writeback records `Status: applied` and an `Applied-ref` naming the full
+correction commit plus exact generated heading. `Applied-ref` is considered
+recorded only after the correction and retro writeback are durably committed.
+Append failure creates neither commit; correction-commit failure leaves the RP
+unsettled for exact recovery; writeback failure preserves the correction commit
+and retries only the writeback. This remains a bounded docs special case; it
+adds no RP type and does not weaken the normal docs apply contract.
+
+## File tracker feedback
+
+Run `oat-project-retro-file` against the active project's retro or an explicit
+artifact path. It extracts every UP item and each RP item with
+`Disposition: file`; it never mutates apply-items.
+
+Before item approval, the skill reports a lane-by-destination capability
+matrix:
+
+| Lane     | Destination | Preflight                                             |
+| -------- | ----------- | ----------------------------------------------------- |
+| Repo     | Issues      | GitHub issues enabled and `gh` authenticated          |
+| Repo     | Backlog     | Canonical OAT backlog initialized and writable        |
+| Upstream | Issues      | Upstream issues enabled and creation authorized       |
+| Either   | None        | Intentionally disabled; no external capability needed |
+
+Interactive runs confirm or override configured lane defaults and choose a
+disposition for each suspected duplicate:
+
+1. **Strengthen** the existing issue or backlog item with new evidence.
+2. **File as new** despite the candidate.
+3. **Skip** without filing.
+4. **Link existing** without adding content.
+
+Strengthening is the default when applicable, but it is still an external
+write. Non-interactive configuration does not authorize modifying an existing
+destination; an unambiguous duplicate may be linked without an external write,
+while ambiguous candidates remain unsettled for interactive review.
+
+### Local receipts and reruns
+
+Before skipping an already-filed item, the filing skill runs a pre-selection
+integrity pass. A local backlog destination is complete only when its path
+exists, its current contents still represent the retro proposal, its full
+`Destination-receipt` names the latest exact-path commit containing that path,
+and `Remote-visibility` is `pushed` or `unpushed`. A valid exact recovery may
+retain `filed` without mutating the destination. A missing or invalid local
+receipt that cannot be recovered cannot remain `filed`.
+
+New and strengthened local destinations use destination-first ordering: commit
+the destination mutation alone, verify that commit contains the backlog path
+and excludes retro writeback, then record its receipt in a later retro
+writeback commit. A failed destination commit never produces `filed`. A local
+link performs no destination mutation, but must recover and validate the latest
+exact-path commit before it can be filed.
+
+Remote visibility is independent of local durability. No configured upstream
+means `unpushed`; the skill never pushes without separate authorization.
+GitHub destinations use a validated issue URL and explicitly leave
+`Destination-receipt` and `Remote-visibility` as `—`.
+
+Public destinations receive a sanitization check when the source repository is
+private. Filing records the confirmed URL or backlog path in `Destination` and
+updates the filing rollup. Unavailable lanes and missing backlog metadata are
+reported rather than silently rerouted or invented.
+
+## Configure non-interactive consent
+
+The `workflow.retro` namespace controls non-interactive actions:
+
+| Key                              | Values                      | Unset behavior                              |
+| -------------------------------- | --------------------------- | ------------------------------------------- |
+| `workflow.retro.apply`           | `auto`, `ask`               | Propose only                                |
+| `workflow.retro.filing.repo`     | `issues`, `backlog`, `none` | No repo-lane filing                         |
+| `workflow.retro.filing.upstream` | `issues`, `none`            | No upstream-lane filing                     |
+| `workflow.retro.upstreamRepo`    | `owner/repo`                | Guidance uses `voxmedia/open-agent-toolkit` |
+
+Explicit `auto` or filing destinations count as consent only for their bounded
+action. Architecture, security, product-scope, credential, destructive, and
+duplicate-mutation boundaries still require direction. See
+[Configuration](../../cli-utilities/configuration.md#workflow-preferences-workflow)
+for the full key reference.
+
+## Summary versus retrospective
+
+|                       | Summary                       | Retrospective                                    |
+| --------------------- | ----------------------------- | ------------------------------------------------ |
+| Primary question      | What did we build and decide? | How did the run go, and what should change next? |
+| Session transcript    | Optional                      | Required when available                          |
+| OAT upstream feedback | Rare                          | Required section or explicit empty lane          |
+| Tone                  | Institutional memory          | Reflective and operational                       |
+| Default path          | `summary.md`                  | `references/project-retro.md`                    |
+
+Use the summary to preserve the delivered system and its decisions. Use the
+retro to preserve execution lessons, course changes, repo improvements, and
+upstream toolkit feedback.

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

@@ -38,9 +38,11 @@ The provider-neutral `planSet` callback runs once after fact reconciliation and
 before any author callback. It returns the complete portfolio and one shared
 claim ledger.
 
-For a project recap, the portfolio must contain the required hub, architecture
-view, and deck. Optional entries must use a recipe-licensed profile, remain
-inside recipe and per-profile limits, and carry source-backed justification.
+For a new project recap, the portfolio must contain the required navigational
+hub. A diagram, deck, or deep dive is optional and must use a recipe-licensed
+profile, remain inside recipe and per-profile limits, and answer a distinct
+reader question with source evidence and a medium rationale. Version 1 recap
+plans remain readable for replay with their historical three-artifact floor.
 Duplicate identities, undeclared sources, conflicting shared terms, and
 unjustified optionals fail validation.
 
@@ -50,14 +52,16 @@ artifact. Authors cannot add, remove, replace, or rename portfolio entries.
 ## Artifact author
 
 The core invokes `author` once per planned artifact with
-`explainer-kit.author-request/v2`. The request contains:
+`explainer-kit.author-request/v3`. Version 2 requests remain readable for
+replay. The current request contains:
 
 - artifact identity, type, and authoring path;
 - the versioned brief and bundled medium-specific guidance;
 - reconciled facts and the shared set context;
 - the matching planned artifact;
 - the resolved theme; and
-- the bundled shell for artistic HTML.
+- the bundled shell for artistic HTML; and
+- canonical artifact links ending in explicit `index.html` paths.
 
 Return `explainer-kit.author-result/v2` with exactly one of
 `content.markdown` or `content.html` and non-secret provenance. The core
@@ -128,6 +132,13 @@ all reviewed artifact IDs, structured findings, and one disposition:
 - `correct` requests one bounded correction and one final review; or
 - `fail` terminates the gate.
 
+Judge typography, hierarchy, composition, density, medium leverage, template
+repetition, diagram semantics, and cross-artifact cohesion from the bound
+browser evidence. `pass` means no required correction remains. `correct`
+findings name concrete artifact-scoped actions that can be completed in the
+single bounded correction round. Keep this judgment in prose; do not invent
+numeric scores or geometry thresholds.
+
 The critic must not mutate rendered files or evidence. The core revalidates all
 bound bytes after each callback.