@open-agent-toolkit/cli 0.2.28 → 0.2.30

package/assets/skills/oat-project-retro/SKILL.md

@@ -0,0 +1,310 @@
+---
+name: oat-project-retro
+version: 1.0.2
+description: Use when the user requests or confirms a project retrospective — e.g. "run the project retro", "write project-retro.md", "retrospective this project", or confirms a previously offered retro. Do NOT auto-invoke merely because implementation or summary completed. Produces references/project-retro.md from project logs, execution learnings, and session/transcript evidence, with repo improvements and OAT upstream feedback.
+disable-model-invocation: false
+user-invocable: true
+allowed-tools: Read, Write, Bash(git:*), Bash(pnpm:*), Bash(oat config:*), Bash(oat decision:*), Bash(oat project log:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion
+---
+
+# Project Retrospective
+
+Generate an evidence-grounded project retrospective or apply approved
+repo-improvement items from an existing retrospective.
+
+## Mode Resolution
+
+Resolve exactly one mode before reading evidence:
+
+- **Generate:** an explicit retro/retrospective request, a configured
+  post-approval `retro` sequence step, or confirmation of a retro offer.
+- **Apply:** an explicit apply flag or wording such as "apply the retro
+  findings." Apply mode requires an existing artifact and never regenerates it.
+- Explicit flags or wording beat inference. If the request remains ambiguous,
+  ask once.
+
+Do not auto-invoke merely because implementation, summary, or completion work
+finished. A configured sequence step or direct confirmation is explicit
+consent to generate.
+
+For apply mode, follow
+[references/apply-procedure.md](references/apply-procedure.md) and skip the
+generation process below.
+
+Apply mode treats a docs item as an append-only project-log correction only
+when its safe normalized target canonical path has the exact final path
+component `project-log.md`; use `oat project log append` and never directly edit
+the log.
+Fail closed on absolute, traversing, or otherwise ambiguous targets. The
+proposal must identify the prior heading or event being corrected and preserve
+the original entry. Follow the reference's judgment flags, stable correction
+identity, correction-commit, and later retro-writeback transitions. Perform
+semantic post-side-effect recovery before appending again. Record `Applied-ref`
+only after the correction and retro writeback are durably committed.
+
+## Progress Indicators
+
+Print one banner and concise step indicators:
+
+```text
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+OAT ▸ PROJECT RETRO
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Use `[1/6] Resolving project and mode…` through `[6/6] Formatting and
+committing…`. Name evidence inventory, synthesis, disposition, and project-log
+steps as they begin.
+
+## Artifact Hygiene
+
+Before finishing or committing, format every created or edited file with the
+repository's documented write/fix formatter, preferably file-scoped. Run the
+checks relevant to those files after formatting. Never leave a partial retro:
+complete it fully or delete the newly created partial file.
+
+## Generate Process
+
+### Step 1: Resolve the Active Project
+
+Use an explicit project path when supplied. Otherwise resolve:
+
+```bash
+PROJECT_PATH=$(oat config get activeProject 2>/dev/null || true)
+```
+
+If it is absent or invalid, ask for the project and resolve it beneath the
+configured projects root. Derive `PROJECT_NAME` from the directory name.
+Confirm the target before expensive transcript retrieval.
+
+The output is always:
+
+```text
+{PROJECT_PATH}/references/project-retro.md
+```
+
+### Step 2: Inventory Evidence Honestly
+
+Follow the reading order and environment detection in
+[references/evidence-and-lanes.md](references/evidence-and-lanes.md).
+
+Create an inventory before synthesis. Record every source in
+`oat_retro_evidence_sources` with `status: used | unavailable`; name unavailable
+sources in `## Evidence and Review Method`. Do not invent session-only claims.
+When an evidence family is partial, split it into truthful source entries, for
+example `archived-review-markdown: unavailable` and `gate-receipts: used`
+instead of `review-artifacts: unavailable`. Do not add a `partial` evidence
+status. Derivative current-run reconnaissance transcripts are not original
+project-run evidence.
+
+Use optional bounded, read-only reconnaissance lanes only when project size
+justifies them. Root synthesis remains with the invoking agent.
+
+### Step 3: Render the Artifact
+
+Copy `.oat/templates/project-retro.md` to the output path and render it against
+[references/retro-quality-bar.md](references/retro-quality-bar.md).
+
+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. This evidence-scaled depth adds no new
+consent-bearing config surface.
+
+Each material incident must stand alone: a reader can understand it 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.
+
+Give each narrative section one job:
+
+- `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.
+
+Required contracts:
+
+1. Keep all core sections and only evidence-supported conditional sections.
+2. Render `## Current State` from register fields and frontmatter rollups. This
+   is the only freeform live-status surface that apply/file writeback refreshes.
+3. Phrase status elsewhere as generation-time evidence, not as live status.
+4. Separate the Repo Improvements and OAT Upstream Feedback lanes.
+5. Use stable `RP-NN` and `UP-NN` item IDs.
+6. Give every RP item a `Type`, authoritative `Disposition: apply | file`, and
+   fields/status matching that disposition.
+7. Give every register item a mutable `Disposition-note` initialized to `—`.
+8. Start every actionable item at `Status: proposed`.
+9. Keep the upstream section and its explicit empty-state line when no item is
+   warranted.
+10. Derive `oat_retro_promotions` from RP apply-items and `oat_retro_filing`
+    from UP items plus RP file-items.
+
+Narrative outside `## Current State` is immutable historical analysis after
+generation. It may describe an item's generation-time status when explicitly
+qualified, but it must not claim a register item "remains" or "is currently"
+in a mutable state. Proposal bodies remain immutable.
+
+Before the artifact can be considered complete:
+
+- set `oat_retro_project` to the non-null project slug;
+- set `oat_retro_generated` to a non-null UTC generation timestamp in
+  `YYYY-MM-DDTHH:MM:SSZ` form;
+- reject all unreplaced scaffold item examples and placeholders, including
+  example `RP-01`/`RP-02`/`UP-01` headings, brace-delimited instructional text,
+  and template-only empty item blocks;
+- set `oat_generated: true` and `oat_template: false`; and
+- remove `oat_template_name` entirely.
+
+A rendered artifact must never retain scaffold-only template markers or null
+provenance.
+
+### Step 4: Resolve Post-Generation Consent
+
+Read effective `workflow.retro.apply` and `workflow.retro.filing` configuration.
+
+**Interactive run:**
+
+1. Present the generated register summary.
+2. Ask whether to apply eligible RP apply-items now.
+3. If unfiled UP or RP file-items exist, offer the `oat-project-retro-file`
+   skill.
+
+**Non-interactive run:**
+
+- Apply only when `workflow.retro.apply` is `auto`.
+- `ask` or absent means propose-only.
+- Chain to `oat-project-retro-file` only when at least one
+  `workflow.retro.filing` destination is explicitly configured.
+- Without filing config, file nothing and report that proposals remain.
+
+All applications follow the apply procedure. Filing remains owned by
+`oat-project-retro-file`; generate/apply mode does not file tracker items.
+
+### Step 5: Record the Run
+
+Append a structural project-log entry with `oat project log append` when the
+project log exists. Never hand-edit the project log. Use this exact one-line
+receipt shape, with every key present exactly once:
+
+```text
+retro artifact=<path> evidence_used=<csv> evidence_unavailable=<csv> promotions=<number> upstream=<number> apply=<performed|declined|skipped|deferred> filing=<performed|declined|skipped|deferred>
+```
+
+`artifact` is the repo-relative retro path. `evidence_used` and
+`evidence_unavailable` are deterministic source lists. Source identifiers are
+deduplicated, sorted in bytewise ascending order, and serialized as
+comma-separated values with no spaces; an empty list is `none`. Reject an
+identifier unless it matches `[a-z0-9][a-z0-9._:-]*`; this excludes commas and
+whitespace. `promotions` is the RP register count and `upstream` is the UP
+register count. `apply` is the apply action outcome and `filing` is the filing
+action outcome. Counts describe artifact contents; outcomes describe actions.
+Never reuse a count key for an outcome or encode a count in `filing`.
+
+Capture one immutable pre-action eligibility snapshot for each action after the
+registers are rendered and before any apply consent decision or filing
+dispatch. The apply snapshot contains the stable IDs of unsettled RP
+`Disposition: apply` items. The filing snapshot contains the stable IDs and
+lanes of unsettled UP items plus RP `Disposition: file` items. Never recompute
+initial eligibility from post-action register state.
+
+For each snapshot, record:
+
+- `INITIAL_ELIGIBLE`: the number of members in that pre-action snapshot;
+- `DECISION`: `not-applicable | declined | deferred | entered`;
+- `COMPLETION`: `not-started | normal | failed`; and
+- `REMAINING_INITIAL`: how many members of that same snapshot remain unsettled
+  after the action. Ignore newly created eligible work until the next run.
+
+Validate `0 <= REMAINING_INITIAL <= INITIAL_ELIGIBLE`, then derive the outcome
+with this total precedence function:
+
+```text
+if INITIAL_ELIGIBLE == 0                         => skipped
+else if DECISION == declined                     => declined
+else if DECISION != entered                      => deferred
+else if COMPLETION != normal                     => deferred
+else if REMAINING_INITIAL > 0                    => deferred
+else                                             => performed
+```
+
+This samples initial eligibility exactly once. A successful action that settles
+every snapshot member is `performed`, never `skipped` because the post-action
+set became empty. Exact recovered no-ops count as normal completion when they
+settle the snapshot member. Item-level rejection is settled work; action-level
+rejection before entry is `declined`.
+
+For filing, use one lane-tagged union snapshot and one outcome. If any initially
+eligible repo or upstream lane remains unsettled because its destination is
+absent or configured `none`, the mixed action is `deferred` even when another
+lane completed normally. It is `performed` only when normal completion settles
+all initially eligible lanes.
+
+| Scenario                              | Initial eligible | Decision       | Completion  | Remaining initial | Outcome   |
+| ------------------------------------- | ---------------- | -------------- | ----------- | ----------------- | --------- |
+| Initially empty                       | 0                | not-applicable | not-started | 0                 | skipped   |
+| Interactive action rejection          | 2                | declined       | not-started | 2                 | declined  |
+| Absent non-interactive consent        | 2                | deferred       | not-started | 2                 | deferred  |
+| Configured apply deferral             | 2                | deferred       | not-started | 2                 | deferred  |
+| Action failure                        | 2                | entered        | failed      | 1                 | deferred  |
+| Normal completion with remaining work | 2                | entered        | normal      | 1                 | deferred  |
+| All settled successfully              | 2                | entered        | normal      | 0                 | performed |
+| Mixed filing lanes partly deferred    | 3                | entered        | normal      | 1                 | deferred  |
+| Mixed filing lanes all settled        | 3                | entered        | normal      | 0                 | performed |
+
+Build the one-line body in `RECEIPT_BODY`, then use this complete invocation.
+The producer and ref are stable literals:
+
+```bash
+oat project log append --project "$PROJECT_PATH" --structural \
+  --producer oat-project-retro \
+  --ref project-retro \
+  --body "$RECEIPT_BODY"
+```
+
+Do not append if body validation fails. After the command succeeds, verify the
+generated structural heading uses producer `oat-project-retro` and ref
+`project-retro`, and verify the appended body exactly equals `RECEIPT_BODY`.
+
+### Step 6: Format, Verify, and Commit
+
+Format the retro, any approved promotion targets, and any decision records.
+Verify:
+
+- required core sections exist;
+- evidence availability is explicit;
+- every RP item has a valid disposition and matching fields/status;
+- every register item has a `Disposition-note`;
+- rollups are derivable from register fields;
+- `Current State` is derived from register fields and frontmatter rollups and
+  contains no contradictory status claim;
+- `oat_retro_project` is a non-null project slug;
+- `oat_retro_generated` is a valid UTC generation timestamp;
+- no unreplaced scaffold item examples, placeholders, or brace-delimited
+  instructions remain;
+- rendered template metadata is retired; and
+- final verification confirms the structural receipt has all required keys
+  exactly once, both register counts are numeric, and count keys are never
+  reused for action outcomes; and
+- no unrelated implementation file changed.
+
+Commit the artifact, project-log append, and any approved apply outputs. Use
+one reviewed batch when items are tightly coupled; otherwise use one commit per
+item as described in the apply procedure. Never stage unrelated changes.
+
+## Success Criteria
+
+- The resolved mode matches explicit user/config intent.
+- `references/project-retro.md` is complete, evidence-grounded, and not marked
+  as a template.
+- Missing evidence is named; hypotheses remain hypotheses.
+- Both feedback lanes are explicit and machine-scannable.
+- Register statuses and frontmatter rollups agree.
+- `Current State` agrees with the registers and rollups; immutable historical
+  narrative does not masquerade as live status.
+- No promotion is applied or item filed without interactive approval or
+  explicit non-interactive configuration.
+- The project log and commit preserve the outcome without unrelated changes.

package/assets/skills/oat-project-retro/references/apply-procedure.md

@@ -0,0 +1,212 @@
+# Retro Promotion Apply Procedure
+
+Use this procedure only for `RP-NN` items whose authoritative field is
+`Disposition: apply`. Never mutate RP file-items or any UP item; those belong
+to `oat-project-retro-file`.
+
+## Classification and Routing
+
+| Type                 | Default disposition | Apply behavior                                        |
+| -------------------- | ------------------- | ----------------------------------------------------- |
+| `docs`               | `apply`             | Edit canonical repository documentation               |
+| `agents-instruction` | `apply`             | Edit the narrowest existing agent instruction surface |
+| `rule`               | `apply`             | Edit the canonical scoped rule                        |
+| `decision`           | `apply`             | Create a durable record with `oat decision new`       |
+| `code-follow-up`     | `file`              | Leave for the filing skill                            |
+
+`Disposition` is authoritative when it differs from the default. Apply mode
+processes only apply-items with `Status: proposed | approved`. It skips
+`applied` and `rejected` items, so interrupted or repeated runs resume
+idempotently.
+
+## Consent
+
+- Interactive runs present each proposed item, target, rationale, and concrete
+  edit. Apply only approved items.
+- Non-interactive runs apply only when `workflow.retro.apply: auto`.
+- A configured `auto` value authorizes the bounded register changes, not
+  architecture, security, product-scope, credential, or destructive changes.
+  Stop for explicit direction at those boundaries.
+
+When approval occurs before editing, set `Status: approved`. If execution
+continues immediately, this can be written back together with the final
+`applied` state.
+
+## Application by Type
+
+1. **Docs:** update the canonical existing page. Avoid duplicate documents.
+   Route a docs item to the append-only correction special case only when its
+   target canonical path passes this matcher:
+   1. Parse the `Target` field value, removing at most one matching pair of
+      Markdown backticks.
+   2. Reject an empty value, NUL, an absolute POSIX path, a Windows drive or UNC
+      path, a trailing separator, or any unresolved `..` segment.
+   3. Convert `\` separators to `/`, remove leading `./`, remove interior `.`
+      segments, and collapse repeated separators.
+   4. Route only when the normalized target's exact, case-sensitive final path
+      component is `project-log.md`. A lookalike is an ordinary docs target,
+      not a correction. Any ambiguous normalization stops with no write.
+
+   | Scenario            | Target                                     | Disposition   |
+   | ------------------- | ------------------------------------------ | ------------- |
+   | Repo-relative POSIX | `.oat/projects/shared/demo/project-log.md` | route         |
+   | Windows separators  | `.oat\projects\shared\demo\project-log.md` | route         |
+   | Exact basename      | `project-log.md`                           | route         |
+   | Lookalike suffix    | `project-log.md.bak`                       | ordinary-docs |
+   | Prefixed basename   | `my-project-log.md`                        | ordinary-docs |
+   | Nested child        | `project-log.md/child`                     | ordinary-docs |
+   | Ambiguous traversal | `.oat/projects/../demo/project-log.md`     | stop          |
+   | Absolute path       | `/tmp/project-log.md`                      | stop          |
+
+   For a routed item:
+   - Use `oat project log append`; never directly edit `project-log.md`.
+   - Require the immutable proposal body to identify the prior heading or
+     event being corrected, preserve the original entry, and supply a stable
+     `ORIGINAL_ENTRY_ANCHOR`. Set `RP_ID` to the item's stable `RP-NN` ID.
+   - Construct `CORRECTION_BODY` with the exact stable identity first line
+     `Retro correction id=$RP_ID original=$ORIGINAL_ENTRY_ANCHOR`, followed by
+     the immutable correction text. The ID, anchor, and correction text must
+     match exactly during recovery.
+   - Perform semantic post-side-effect recovery before appending: search the
+     project log and Git state for the exact identity first line. Zero matches
+     permits one append. Exactly one match permits recovery only when the
+     original-entry anchor and full correction body are semantically exact; do
+     not append again. Multiple, partial, or divergent matches stop for
+     direction without appending.
+   - Only when recovery finds zero matches, run the complete judgment append
+     invocation exactly once:
+
+     ```bash
+     oat project log append --project "$PROJECT_PATH" \
+       --type feedback \
+       --scope project \
+       --area "retro correction $RP_ID" \
+       --body "$CORRECTION_BODY"
+     ```
+
+   - Commit the project-log append without retro writeback. Verify the commit
+     contains the normalized project-log path and exact correction body.
+     Capture its full 40-character SHA and exact generated heading.
+   - In a later retro-only writeback commit, set the RP status and
+     `Applied-ref`. The reference names the full 40-character correction commit
+     plus the exact generated heading, serialized as
+     `<40-character-sha> :: <exact-generated-heading>`. Consider `Applied-ref`
+     recorded only after that writeback commit succeeds; at that point the
+     correction and retro writeback are durably committed.
+
+   The transition table is authoritative:
+
+   | Scenario                  | Starting state                                    | Required transition                                                                              |
+   | ------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+   | Fresh                     | No exact correction                               | Append once; commit project log; write back retro in a later commit                              |
+   | Uncommitted append        | One exact uncommitted correction                  | Do not append; commit the recovered project-log mutation; then write back                        |
+   | Committed append          | One exact committed correction and RP not applied | Do not append; verify full commit, path, and body; then write back                               |
+   | Append failure            | Command fails                                     | No correction commit or writeback; retain prior RP status                                        |
+   | Correction commit failure | Append exists but commit fails                    | No writeback; retain prior RP status; recover exact append on retry                              |
+   | Writeback commit failure  | Correction commit succeeds but retro commit fails | Preserve correction commit; restore non-applied artifact; retry writeback from recovered receipt |
+   | Ambiguous recovery        | Multiple or divergent matches                     | Stop with no append, commit, or writeback                                                        |
+
+   This special case is limited to normalized `project-log.md` targets and does
+   not add or change the public RP type vocabulary. All other docs items
+   continue to update the canonical existing page under the normal docs apply
+   contract.
+
+2. **Agent instruction:** choose the narrowest existing applicable
+   `AGENTS.md`, skill, or provider-neutral instruction. Do not create nested
+   instruction files solely for discoverability.
+3. **Rule:** update the canonical rule whose scope matches the finding. Preserve
+   provider-neutral guidance and existing precedence.
+4. **Decision:** ensure the decision scaffold exists, then run:
+
+   ```bash
+   oat decision new "<title>" --status accepted --context "<context>" --decision "<decision>" --consequences "<consequences>"
+   ```
+
+   Before creating it, compute the slug with the CLI's lowercase,
+   ASCII-folded, hyphen-collapsed, 30-character whole-word rule (including
+   trailing stop-word trimming). Perform a **date-independent exact-slug**
+   lookup for `DR-<6 digits>-<slug>.md`; never use a loose suffix glob.
+
+   Use the granted `Glob` tool, rooted at the repository, with this pattern
+   after substituting the computed slug:
+
+   ```text
+   .oat/repo/reference/decisions/DR-??????-<slug>.md
+   ```
+
+   The six `?` characters anchor the date segment to exactly six characters,
+   and the remaining slug must match exactly. Handle the returned paths
+   deterministically:
+   - **Zero matches:** create the record with `oat decision new`, capture its
+     reported ID/path, and verify it represents the current proposal before
+     writeback.
+   - **Exactly one match:** read it and verify its normalized title, context,
+     decision, and consequences represent the current proposal. On a match,
+     treat this as interrupted post-side-effect recovery: do not create a
+     duplicate, and recover `Applied-ref` from that record's ID/path. On a
+     proposal mismatch, stop for direction and perform no write.
+   - **Multiple matches:** stop with an ambiguity error and perform no write;
+     never choose a record by date, ordering, or convenience.
+
+   Use only the generated or verified record and managed index. Never
+   hand-author a decision ID or edit the managed index.
+
+5. **Code follow-up:** do not implement it here, even when technically small.
+   A code follow-up defaults to `Disposition: file`.
+
+## Per-Item Writeback
+
+After a successful application:
+
+- set `Status: applied`;
+- set `Applied-ref` to the resulting commit/path reference; and
+- clear `Disposition-note` to `—`; and
+- recompute `oat_retro_promotions` from all RP apply-items; and
+- refresh the bounded `## Current State` contents from register fields and
+  frontmatter rollups.
+
+On explicit rejection, set `Status: rejected` and write the reason to the
+mutable `Disposition-note` field. On transient failure, leave
+`Status: proposed` (or `approved` when approval remains valid), record bounded
+execution context in `Disposition-note`, report the failure, and continue only
+when safe.
+
+Apply mode may mutate only `Status`, `Applied-ref`, `Disposition-note`, and the
+promotions rollup inside the artifact, plus the contents of `## Current State`.
+It must not alter file-items, UP items, `oat_retro_filing`, item IDs,
+dispositions, proposal bodies, or any other narrative. Refresh `Current State`
+without rewriting proposal bodies. Proposal bodies are stable and immutable
+after generation.
+
+Compute `oat_retro_promotions` exactly:
+
+- `none` when no apply items exist;
+- `proposed` when apply items exist and none are settled;
+- `partial` for a mix of settled and unsettled apply items; and
+- `complete` when all apply items are settled.
+
+`proposed` and `approved` are unsettled; `applied` and `rejected` are settled.
+
+## Commit and Resume Strategy
+
+- Use one commit per item when targets are independent, review boundaries
+  differ, or one item may fail without invalidating the rest.
+- Use one reviewed batch when the items are inseparable edits to the same
+  canonical surface.
+- Include the target edit and its artifact status writeback in the same commit
+  whenever possible. The project-log correction route is the explicit
+  exception: its correction commit must precede the later retro-only writeback
+  commit so `Applied-ref` can name an already durable correction.
+- Before each commit, format touched files, run surface-relevant checks, and
+  verify the item still has the expected pre-apply status.
+- On re-run, rescan the artifact and process only remaining
+  `proposed | approved` apply-items. Never repeat an `applied` item.
+
+For **every apply type**, perform post-side-effect recovery before repeating an
+eligible item: inspect the declared target for the exact proposed semantic
+change, verify the existing result represents the current proposal, and
+recover `Applied-ref` when it does. This includes docs, agent-instruction,
+rule, and decision items. A matching side effect plus missing writeback is an
+interrupted success, not permission to apply twice. A partial, divergent, or
+unverifiable target requires direction; never overwrite or claim it
+automatically.

package/assets/skills/oat-project-retro/references/evidence-and-lanes.md

@@ -0,0 +1,91 @@
+# Retro Evidence and Reconnaissance
+
+## Required Reading Order
+
+Inventory and read available evidence in this order:
+
+1. `project-log.md` — always check first; use its append-only entries as
+   workflow evidence.
+2. `oat-execution-learnings.md` — when present, extract observations, impact,
+   and recommendations without treating them as already proven.
+3. Lifecycle artifacts — at minimum `implementation.md`, `state.md`, and
+   `plan.md`; also read load-bearing `discovery.md`, `design.md`, `spec.md`,
+   reviews, references, and evidence ledgers when present.
+4. Session/run evidence — use the environment-appropriate route below.
+
+Implementation outcomes and committed evidence outrank planned behavior.
+Record each source as `used` or `unavailable` in retro frontmatter.
+When an evidence family is partial, split it into truthful source entries, for
+example `archived-review-markdown: unavailable` and `gate-receipts: used`
+instead of `review-artifacts: unavailable`. Do not add a `partial` evidence
+status. Derivative current-run reconnaissance transcripts are not original
+project-run evidence.
+
+Return and preserve stable evidence anchors for load-bearing claims: prefer
+project-log event IDs, artifact headings, review paths, decision IDs, and
+commit IDs over line numbers. Anchors supplement but never replace explanation;
+the rendered incident narrative must remain understandable without opening the
+referenced source.
+
+## Environment Detection
+
+### Cloud tooling available
+
+Use the host's cloud run-info, events, and transcript/detail tooling. Fetch
+relevant first-class child runs when their identifiers matter. Prefer bounded
+reconnaissance over loading a giant transcript into root context.
+
+### Local transcript access
+
+Use the current host's local agent session transcript/history. Keep the search
+bound to the current project/run and avoid quoting secrets or irrelevant user
+history.
+
+### No session access
+
+State that session evidence is unavailable and continue from durable
+artifacts. Do not infer tool output, operator corrections, or chronology that
+exists only in a missing transcript.
+
+## Transcript Caveat
+
+Cloud or local transcript exports may omit terminal tool-result bodies. When
+they do, committed ledgers, reviews, implementation notes, and project-log
+entries are authoritative for runtime detail. A command mention is not proof
+of its result. Mark an unresolved mechanism as inconclusive.
+
+## Reconnaissance Lanes
+
+Recon lanes are optional and read-only. Scale them to evidence volume:
+
+- **Small project:** root reads evidence directly; no dispatch required.
+- **Medium project:** two or three lanes, usually durable artifacts,
+  transcript chronology, and dual-feedback classification.
+- **Large or long-running project:** add focused lanes for implementation
+  decisions, orchestration/liveness, failure taxonomy, and durable-guidance
+  gaps.
+
+Every lane returns compact conclusions with stable evidence anchors, uncertainty
+labels, repo-improvement candidates, and OAT-upstream candidates. Lanes do not
+write the retro or apply changes. Root synthesis verifies each load-bearing
+anchor against committed artifacts before preserving it in the retro.
+
+Minimum conceptual coverage, whether dispatched or performed directly:
+
+1. durable project outcomes and decisions;
+2. session chronology and operator corrections when available; and
+3. explicit classification into repo feedback versus OAT upstream feedback.
+
+## Evidence Labels
+
+Use these labels consistently in synthesis:
+
+- **Confirmed:** directly supported by durable evidence or matching independent
+  sources.
+- **Hypothesis:** plausible mechanism with incomplete proof; name what would
+  confirm it.
+- **Inconclusive:** evidence rules out some explanations but cannot establish
+  the mechanism.
+
+Prefer classification over blame. Do not convert a later successful run into
+proof of an earlier failure's cause.