@open-agent-toolkit/cli 0.3.21 → 0.3.23

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

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(jq:*), Bash(oat config:*), Bash(oat decision:*), Bash(oat pjm:*), Bash(oat project log:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat template:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.5.10
+  version: 1.5.11
 ---
 
 # Project Summary
@@ -88,6 +88,31 @@ writing prose artifacts does not imply unrelated full test suites.
 
 ## Process
 
+### Staged Invocation
+
+Staged invocation: the caller states `staged: true`; the summary skill completes Steps 0–5, writes frontmatter, and stops; the caller later states `resume: roll-up` to run Step 6 onward; standalone invocations run straight through.
+
+In a staged run:
+
+- Step 2.5 performs only the read-only `oat project log check` and identifies
+  promotion candidates. Offer them and record the selection under the same
+  promotion consent rule as a standalone run, but append nothing yet.
+- Before suspending, write only `summary.md` sections and their freshness
+  frontmatter: no project-log append, roll-up, ledger write, decision
+  promotion or commit. Suspend with a report that names each selected
+  promotion by the original entry's exact heading.
+- The caller sends `resume: roll-up` only after its final journal validation
+  succeeds. On resume, first perform the deferred `project` → `general`
+  appends exactly as Step 2.5 describes (setting
+  `PROJECT_LOG_PROMOTION_APPENDED`), then run Step 6 onward, so the roll-up's
+  ledger graduation reads the complete judgment set including the promotions.
+- A staged run that is never resumed has written nothing beyond `summary.md`.
+
+Standalone behavior, the seal and ambiguity routing in Step 2.5 and the
+promotion consent rule are unchanged. An inline fallback that follows this
+skill without loading it (`oat-project-complete` Step 3.5) stops at the same
+suspension point.
+
 ### Step 0: Resolve Active Project
 
 OAT stores active project context in `.oat/config.local.json` (`activeProject`, local-only).
@@ -167,14 +192,17 @@ For every other workflow mode, read all available artifacts for synthesis:
 - `"$PROJECT_PATH/implementation.md"` — task outcomes, deviations, challenges, review notes
 - `"$PROJECT_PATH/state.md"` — associated issues, workflow mode
 - `"$PROJECT_PATH/project-log.md"` — optional append-only workflow
-  observations; never hand-edit
-- `"$PROJECT_PATH/oat-execution-learnings.md"` — optional append-only
-  autonomous-run observations and recommendations
+  observations; never hand-edit. Judgment entries whose body opens with a
+  `**Category:**` head are the project's learnings; read them first
+- `"$PROJECT_PATH/oat-execution-learnings.md"` — optional legacy learnings
+  file written before the log carried categories; read it second and never
+  write it
 
 **Priority for content:** Implementation.md outcomes take precedence over design.md plans. Summary should reflect what actually happened, not what was planned.
 
-If `oat-execution-learnings.md` is absent, do not infer autonomous learnings
-from other artifacts and do not add an Autonomous Execution Learnings section.
+If the project log has no category-bearing judgment entry and
+`oat-execution-learnings.md` is absent, do not infer autonomous learnings from
+other artifacts and do not add an Autonomous Execution Learnings section.
 
 ### Step 2.5: Check Project Log and Offer Ledger Graduation
 
@@ -244,16 +272,56 @@ test -f "$PROJECT_PATH/summary.md"
    ```
 
 3. Determine update scope:
-   - If `oat-execution-learnings.md` exists, compare its dated entry
-     identifiers (timestamp, category, and title) with the source pointers in
-     the existing `## Autonomous Execution Learnings` section. Treat missing,
-     added, or changed recommendations as `learnings_changed`.
-   - If `oat_summary_last_task == current_last_task` AND `oat_summary_revision_count == current_rev_count` AND learnings are absent or unchanged AND the project-log check reports `status: "ok"` with no entries: **No changes detected. Skip update.** Report: "Summary is current. No updates needed."
+   - Compute `CURRENT_LEARNINGS_FINGERPRINT` with the function below and
+     compare it with `oat_summary_learnings_fingerprint`. When they differ,
+     the learning sources are `learnings_changed`: a new or changed learning
+     source identity, or a changed recommendation in a legacy entry, requires
+     a refresh on its own, whatever the task, revision or phase tracking says.
+     A missing field compares as `none`.
+   - If `oat_summary_last_task == current_last_task` AND `oat_summary_revision_count == current_rev_count` AND learnings are not `learnings_changed` AND the project-log check reports `status: "ok"` with no entries: **No changes detected. Skip update.** Report: "Summary is current. No updates needed."
    - If `current_rev_count > oat_summary_revision_count`: New revision phases exist. Update: Revision History, What Was Implemented, Follow-up Items.
    - If `current_last_task > oat_summary_last_task`: New tasks completed. Update: What Was Implemented, Notable Challenges, Tradeoffs Made.
    - If `learnings_changed`: update Autonomous Execution Learnings even when
      task and revision tracking fields are unchanged.
 
+The learnings fingerprint hashes every category-bearing judgment entry of the
+project log (heading and body) and the whole legacy file, and is `none` when
+neither exists. Uncategorized and structural entries do not move it; they
+reach the summary through the project-log check above and the roll-up.
+
+```bash
+summary_learnings_fingerprint() {
+  local sources
+  sources=$(
+    if [ -f "$PROJECT_PATH/project-log.md" ]; then
+      awk '
+        function flush() { if (heading != "" && categorized) printf "log %s\n%s", heading, body; heading = "" }
+        { sub(/\r$/, "") }
+        /^## / { flush(); in_entries = ($0 == "## Entries"); next }
+        !in_entries { next }
+        /^### / { flush(); heading = $0; body = ""; categorized = 0; head = 1; next }
+        heading == "" { next }
+        head && /^\*\*Category:\*\* / { categorized = 1 }
+        head && !/^\*\*(Category|Source|Origin|Recorded):\*\* / && !/^[ \t]*$/ { head = 0 }
+        { body = body $0 "\n" }
+        END { flush() }
+      ' "$PROJECT_PATH/project-log.md"
+    fi
+    if [ -f "$PROJECT_PATH/oat-execution-learnings.md" ]; then
+      printf 'legacy\n'
+      cat "$PROJECT_PATH/oat-execution-learnings.md"
+    fi
+  )
+  if [ -z "$sources" ]; then
+    echo none
+    return
+  fi
+  printf '%s' "$sources" | { command -v sha256sum >/dev/null 2>&1 && sha256sum || shasum -a 256; } | cut -d' ' -f1
+}
+
+CURRENT_LEARNINGS_FINGERPRINT=$(summary_learnings_fingerprint)
+```
+
 **If does not exist (first run):**
 
 Copy template: `oat template resolve summary --output "$PROJECT_PATH/summary.md"`
@@ -396,7 +464,7 @@ spec, or design artifacts.
 | Follow-up Items                | implementation.md deferred findings, plan.md deferred items                    |
 | Associated Issues              | state.md `associated_issues` field                                             |
 | Workflow Observations          | project-log.md via `oat project log rollup` only                               |
-| Autonomous Execution Learnings | oat-execution-learnings.md dated entries                                       |
+| Autonomous Execution Learnings | project-log.md category-bearing judgments, then legacy learnings entries       |
 | Explainer Outcome              | project-recap `manifest.json` and `qa/result.json`, or the recorded recap skip |
 | Exit-Gate Waivers              | state.md `oat_implement_exit_gate.waivers`                                     |
 
@@ -455,7 +523,8 @@ only when the list is absent or empty.
 
 **Autonomous Execution Learnings (conditional):**
 
-When `"$PROJECT_PATH/oat-execution-learnings.md"` exists, synthesize
+When the project log has category-bearing judgment entries or the legacy
+`"$PROJECT_PATH/oat-execution-learnings.md"` exists, synthesize
 `## Autonomous Execution Learnings` as actionable recommendations grouped
 under exactly these categories:
 
@@ -468,6 +537,47 @@ under exactly these categories:
 - **Workflow issues** — lifecycle, gate, review, dispatch, or orchestration
   process changes.
 
+Read learning sources in this order and deduplicate them by source identity:
+
+1. **Unified log entries** — judgment entries of `project-log.md` whose body
+   opens with a `**Category:**` head. Read the observation, impact,
+   recommendation and uncertainty from the body below the head. The source
+   identity is the export-safe token `oat-project:<slug>#<entry-id>`, where
+   `<slug>` is the project directory name and `<entry-id>` is the id
+   `oat project log rollup` assigns and prints in its digest:
+   `<date>-<type>-<area slug>-<n>`. Derive it with `project_log_entry_ids`
+   below; never construct a different id.
+2. **Legacy entries** — the `## {timestamp} - {category} - {title}` sections of
+   `oat-execution-learnings.md`. The source identity is that exact
+   `{timestamp} — {category} — {title}` triple.
+
+A legacy entry is a proven twin of a unified entry only when the unified
+entry's `**Recorded:**` value equals the timestamp, its `**Category:**` equals
+the category and its heading area equals the title, each exactly. Use a proven
+twin once, under its unified token. Keep every other entry, including a
+distinct lesson that only shares a title.
+
+```bash
+project_log_entry_ids() {
+  awk '
+    { sub(/\r$/, "") }
+    /^## / { in_entries = ($0 == "## Entries"); next }
+    !in_entries { next }
+    /^### [0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] · (project|general) · (bug|friction|worked-well|feedback) · / {
+      split($0, field, " · ")
+      date = substr(field[1], 5); type = field[3]; area = field[4]
+      sub(/[ \t]+$/, "", area)
+      slug = tolower(area); gsub(/[^a-z0-9]+/, "-", slug); gsub(/^-+|-+$/, "", slug)
+      if (slug == "") slug = "entry"
+      stem = date "-" type "-" slug
+      print stem "-" (++seen[stem]) "\t" $0
+    }
+  ' "$PROJECT_PATH/project-log.md"
+}
+```
+
+Each output line is `<entry-id>`, a tab, then the entry's heading.
+
 For each source entry:
 
 1. Use its `Observation`, `Impact`, and `Recommendation` fields to decide
@@ -479,28 +589,35 @@ For each source entry:
    not a one-to-one output mapping.
 3. Write a concise action plus one-line rationale. Preserve uncertainty and
    environment-limited status; do not claim an unverified fix.
-4. End the item with a relative link to `oat-execution-learnings.md` and the
-   exact source entry identifier (`timestamp — category — title`). Link to the
-   entry heading anchor when one exists; otherwise link to the file and include
-   the identifier in the link text so the entry remains traceable.
+4. End the item with the source identity of every supporting entry as plain
+   text, never a Markdown link: the `oat-project:<slug>#<entry-id>` token for a
+   unified entry, and `legacy learning {timestamp} — {category} — {title}` for
+   a legacy entry. The summary is exported into the tracked repository while
+   the log and the legacy file stay with the archived project, so never
+   present either as a retrievable path; the archive export finalizes the
+   tokens.
 5. Deduplicate recommendations that describe the same action, while retaining
-   pointers to every supporting source entry.
+   every distinct supporting source identity; a merged recommendation lists
+   each token and legacy triple once.
 
-Omit empty category subheadings. If the learnings file contains no actionable
-entries, omit the entire section. If the file is absent, this behavior is inert:
-remove the template placeholder during a first render and make no
+Omit empty category subheadings. If no source contains an actionable entry,
+omit the entire section. With no learning source at all this behavior is
+inert: remove the template placeholder during a first render and make no
 learnings-driven update on a re-run.
 
 **Workflow Observations coexistence contract:**
 
 Keep `## Workflow Observations` and `## Autonomous Execution Learnings` as
 distinct summary sections. Author the autonomous-execution section first, then
-perform the project-log roll-up in Step 6. Because the roll-up command writes
-every project-log entry, keep the project-log observation in Workflow
-Observations and represent any overlap from Autonomous Execution Learnings with
-a one-line cross-reference instead of copying it there. The roll-up command
-remains the only writer of Workflow Observations—never hand-implement its
-section or ledger writes.
+perform the project-log roll-up in Step 6. The roll-up writes a bounded digest
+of judgment entries (structural entries stay in the log): one observation line
+per selected entry, with a recommendation only for an uncategorized entry. A
+categorized learning's synthesized recommendation therefore appears once, in
+Autonomous Execution Learnings, while the digest keeps its observation line and
+adds a one-line cross-reference to that section; never restate the digest's
+observations here or a recommendation there. The roll-up command remains the
+only writer of Workflow Observations—never hand-implement its section or
+ledger writes.
 
 **For incremental updates (re-run):**
 
@@ -520,9 +637,12 @@ oat_generated: true
 oat_summary_last_task: { highest completed task ID }
 oat_summary_revision_count: { count of p-revN phases }
 oat_summary_includes_revisions: [{ list of p-revN IDs reflected }]
+oat_summary_learnings_fingerprint: { CURRENT_LEARNINGS_FINGERPRINT }
 ---
 ```
 
+`oat_summary_learnings_fingerprint` is written in every workflow mode (Step 3).
+
 In brief and goal modes write `oat_summary_phase_fingerprint: {CURRENT_PHASE_FINGERPRINT}`
 (Step 3) and omit `oat_summary_last_task`; keep `oat_summary_revision_count`
 and `oat_summary_includes_revisions` as informational fields.
@@ -530,8 +650,9 @@ and `oat_summary_includes_revisions` as informational fields.
 ### Step 6: Roll Up Project Observations and Offer Backlog Graduation
 
 Run this step after `summary.md` has been authored or refreshed, including the
-distinct `## Autonomous Execution Learnings` section when its source artifact
-exists.
+distinct `## Autonomous Execution Learnings` section when a learning source
+exists. In a staged invocation this step runs only after `resume: roll-up`,
+once the deferred Step 2.5 promotions are appended.
 
 **Goal terminal deferral.** When `oat_workflow_mode` is `goal`, this run
 comes before `pr` in the post-implement sequence (`oat_post_implement_sequence`
@@ -606,9 +727,12 @@ Route only on the structured `ProjectLogRollupResult`:
 - `status: "failed"` or `ledgerOutcome: "failed"`: surface the failure to the
   user and stop before commit. Do not describe the summary as fully rolled up.
 
-The command mechanically writes or updates `## Workflow Observations` and
-appends/deduplicates eligible `general` judgments in the configured ledger. Do
-not reproduce either write by hand.
+The command mechanically writes, updates or omits the bounded
+`## Workflow Observations` digest (`summarySection: "written" | "updated" |
+"omitted"`; `omitted` means no judgment entry qualified and the section is
+absent) and appends/deduplicates every eligible `general` judgment in the
+configured ledger, whether or not the digest bound selected it. Do not
+reproduce either write by hand.
 
 Separately inspect follow-up-marked project-log entries and offer backlog
 graduation through `oat-pjm-add-backlog-item`. Backlog graduation creates a
@@ -819,11 +943,16 @@ Summary tracks: last task {task_id}, {N} revision phases
 - Summary is under 200 lines for typical projects
 - Re-run after revisions updates only affected sections
 - Re-run with no changes produces no modifications
-- When `oat-execution-learnings.md` exists, actionable recommendations are
-  grouped under Agent-instruction updates, Cloud-environment improvements, Code
-  follow-ups, and Workflow issues with source-entry pointers
-- When `oat-execution-learnings.md` is absent, no Autonomous Execution
-  Learnings section is rendered and normal summary behavior is unchanged
+- When learning sources exist (category-bearing log entries first, the legacy
+  `oat-execution-learnings.md` second), actionable recommendations are grouped
+  under Agent-instruction updates, Cloud-environment improvements, Code
+  follow-ups, and Workflow issues, each with plain-text source identities and
+  each proven twin counted once
+- With no learning source, no Autonomous Execution Learnings section is
+  rendered and normal summary behavior is unchanged
+- A new or changed learning source makes the summary stale on its own
+- A staged invocation writes only summary sections and frontmatter before
+  `resume: roll-up`
 - Project-log ledger graduation appends a new referencing `general` judgment
   before roll-up and never mutates the original `project` judgment
 - `oat project log rollup --json` owns the distinct Workflow Observations

package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: false
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.6.3
+  version: 1.6.4
 ---
 
 # Autonomous Worktree Bootstrap
@@ -487,7 +487,7 @@ for smoke mode and `false` for normal mode.
 
 When baseline failures occur under `allow-failing` policy and an active project exists:
 
-Append to `implementation.md` under `## Implementation Log`:
+Append to `implementation.md` under `## Deviations from Plan / Design`, after that section's existing content and before the next `##` heading:
 
 ```markdown
 ### {YYYY-MM-DD} — Baseline Warning (autonomous bootstrap)
@@ -500,7 +500,7 @@ Append to `implementation.md` under `## Implementation Log`:
 - {check_name}: {failure summary}
 ```
 
-When a base mismatch is detected (Step 2.7) and an active project exists, append a distinct entry regardless of baseline policy so post-mortems can find it:
+When a base mismatch is detected (Step 2.7) and an active project exists, append a distinct entry in the same section regardless of baseline policy so post-mortems can find it:
 
 ```markdown
 ### {YYYY-MM-DD} — Base Mismatch (autonomous bootstrap)

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -65,6 +65,12 @@ Built-in FlexSearch-powered static search for discovering content without browsi
 
 Theme toggle is included in the layout. Mermaid diagrams re-render on mode switch.
 
+## Generated files
+
+The app-root `index.md` is the generated manifest, rebuilt from `docs/` on every `predev` and `prebuild` by `oat docs generate-index`. Edit the authored `docs/index.md` and its `## Contents`, then regenerate the manifest; do not hand-edit it.
+
+The `docs/**/meta.json` sidebar files are committed derived navigation. After changing authored `## Contents`, run `oat docs nav sync --target-dir "{{APP_DIR}}"` from the repository root to update them. They are separate from the generated app-root manifest.
+
 ## Agent guidance
 
 See `AGENTS.md` in this directory for how agents should work inside this docs app. This `contributing.md` covers human authoring conventions; `AGENTS.md` covers agent runtime discipline (adding pages, restructuring nav, audit/apply, three agent-instruction surfaces). Keeping those concerns separate keeps each file useful to its audience.

package/assets/templates/docs-app-fuma/docs/getting-started.md

@@ -9,7 +9,7 @@ Use this guide to set up your local environment and preview {{SITE_NAME}}.
 
 ## Prerequisites
 
-- Node.js 20+ (or whatever your repo's `.nvmrc` / `package.json` `engines.node` pins — match that)
+- Node.js {{NODE_REQUIREMENT}}
 - pnpm 10+ (or npm/yarn)
 
 ## Install dependencies

package/assets/templates/docs-app-fuma/next.config.js

@@ -1,5 +1,9 @@
+// {{TURBOPACK_ROOT_IMPORTS}}
 import { createDocsConfig } from '@open-agent-toolkit/docs-config';
 
 const basePath = process.env.NEXT_PUBLIC_BASE_PATH || undefined;
 
-export default createDocsConfig(basePath ? { basePath } : {});
+export default createDocsConfig({
+  ...(basePath ? { basePath } : {}),
+  // {{TURBOPACK_ROOT_OPTION}}
+});

package/assets/templates/implementation-brief.md

@@ -80,50 +80,19 @@ Intent, files, proof command, result.
 
 ## Orchestration Runs
 
-_Each run from `oat-project-implement` appends an entry below with:_
-_- Run header (number, timestamp, branch, tier, policy, phase counts)_
-_- Phase Outcomes table_
-_- Parallel Groups list_
-_- Outstanding Items_
+<!-- One line per dispatch request id, rendered by `oat project dispatch record --format line` and written as a list item. Update that line in place with the terminal outcome; never paste the record or event JSON. -->
 
 <!-- orchestration-runs-start -->
 
-_Orchestration runs from `oat-project-implement` are appended here, most-recent-first within the file but append-only at the bottom of the log._
-
 <!-- orchestration-runs-end -->
 
----
-
-## Implementation Log
-
-Chronological log of implementation progress.
-
-### YYYY-MM-DD
-
-**Session Start:** [time]
-
-- [x] p01: [Phase name] - [head SHA]
-- [ ] p02: [Phase name] - in progress
-
-**What changed (high level):**
+## Reviews and Gates
 
-- [short bullets suitable for PR/docs]
+<!-- Receipts for final, milestone and multi-phase reviews (a phase review receipt may stay in its phase) and one terminal line per gate run. state.md owns gate transitions; this slot keeps the outcome, waivers and operator choices. -->
 
-**Decisions:**
+## Deferred Findings
 
-- [Decision made and rationale]
-
-**Follow-ups / TODO:**
-
-- [anything discovered during implementation that should be captured for later]
-
-**Blockers:**
-
-- [Blocker description] - [status: resolved/pending]
-
-**Session End:** [time]
-
----
+<!-- One line per approved deferral (finding, rationale, approval, follow-up trigger), plus excluded parallel phases and unmerged worktrees. -->
 
 ## Deviations from Plan / Design
 

package/assets/templates/implementation.md

@@ -14,15 +14,7 @@ oat_template_name: implementation
 **Started:** YYYY-MM-DD
 **Last Updated:** YYYY-MM-DD
 
-> This document is used to resume interrupted implementation sessions.
->
-> Conventions:
->
-> - `oat_current_task_id` always points at the **next plan task to do** (not the last completed task).
-> - When all plan tasks are complete, set `oat_current_task_id: null`.
-> - Reviews are **not** plan tasks. Track review status in `plan.md` under `## Reviews` (e.g., `| final | code | passed | ... |`).
-> - Keep phase/task statuses consistent with the Progress Overview table so restarts resume correctly.
-> - Before running the `oat-project-pr-final` skill, fill the Final Summary (for PR/docs) section below with what was actually implemented.
+This journal resumes interrupted implementation sessions. Every plan task has one block in its phase; `oat project journal check` validates it.
 
 ## Progress Overview
 
@@ -31,7 +23,7 @@ oat_template_name: implementation
 | Phase 1 | in_progress | N     | 0/N       |
 | Phase 2 | pending     | N     | 0/N       |
 
-**Total:** 0/{N} tasks completed
+**Total:** 0/N tasks completed
 
 ---
 
@@ -50,10 +42,7 @@ oat_template_name: implementation
 
 - `{path}` - {why}
 
-**Verification:**
-
-- Run: `{command(s)}`
-- Result: {pass/fail + notes}
+**Verification:** {command(s) run for the phase and the result}
 
 **Notes / Decisions:**
 
@@ -61,8 +50,8 @@ oat_template_name: implementation
 
 ### Task p01-t01: {Task Name}
 
-**Status:** completed / in_progress / pending / blocked
-**Commit:** {sha} (if completed)
+**Status:** pending
+**Commit:** -
 
 **Outcome (required when completed):**
 
@@ -72,19 +61,12 @@ oat_template_name: implementation
 
 - `{path}` - {why}
 
-**Verification:**
-
-- Run: `{command(s)}`
-- Result: {pass/fail + notes}
+**Verification:** {command(s) and result}
 
 **Notes / Decisions:**
 
 - {gotchas, trade-offs, design deltas, important context for future sessions}
 
-**Issues Encountered:**
-
-- {Issue and resolution}
-
 ---
 
 ### Task p01-t02: {Task Name}
@@ -92,10 +74,6 @@ oat_template_name: implementation
 **Status:** pending
 **Commit:** -
 
-**Notes:**
-
-- {Notes will be added during implementation}
-
 ---
 
 ## Phase 2: {Phase Name}
@@ -112,58 +90,19 @@ oat_template_name: implementation
 
 ## Orchestration Runs
 
-_Each run from `oat-project-implement` appends an entry below with:_
-_- Run header (number, timestamp, branch, tier, policy, phase counts)_
-_- Phase Outcomes table_
-_- Parallel Groups list_
-_- Outstanding Items_
+<!-- One line per dispatch request id, rendered by `oat project dispatch record --format line` and written as a list item. Update that line in place with the terminal outcome; never paste the record or event JSON. -->
 
 <!-- orchestration-runs-start -->
 
-_Orchestration runs from `oat-project-implement` are appended here, most-recent-first within the file but append-only at the bottom of the log._
-
 <!-- orchestration-runs-end -->
 
----
-
-## Implementation Log
-
-Chronological log of implementation progress.
-
-### YYYY-MM-DD
-
-**Session Start:** {time}
-
-- [x] p01-t01: {Task name} - {commit sha}
-- [ ] p01-t02: {Task name} - in progress
-
-**What changed (high level):**
+## Reviews and Gates
 
-- {short bullets suitable for PR/docs}
+<!-- Receipts for final and multi-phase reviews (a phase review receipt may stay in its phase) and one terminal line per gate run. state.md owns gate transitions; this slot keeps the outcome, waivers and operator choices. -->
 
-**Decisions:**
+## Deferred Findings
 
-- {Decision made and rationale}
-
-**Follow-ups / TODO:**
-
-- {anything discovered during implementation that should be captured for later}
-
-**Blockers:**
-
-- {Blocker description} - {status: resolved/pending}
-
-**Session End:** {time}
-
----
-
-### YYYY-MM-DD
-
-**Session Start:** {time}
-
-{Continue log...}
-
----
+<!-- One line per approved deferral (finding, rationale, approval, follow-up trigger), plus excluded parallel phases and unmerged worktrees. -->
 
 ## Deviations from Plan / Design
 
@@ -173,15 +112,6 @@ Document any intentional deviations from the original plan, spec, or design. Inc
 | ------------- | --------------- | -------------------- | ----------------- | ------ | --------------- | --------- |
 | -             | -               | -                    | -                 | -      | -               | -         |
 
-## Test Results
-
-Track test execution during implementation.
-
-| Phase | Tests Run | Passed | Failed | Coverage |
-| ----- | --------- | ------ | ------ | -------- |
-| 1     | -         | -      | -      | -        |
-| 2     | -         | -      | -      | -        |
-
 ## Final Summary (for PR/docs)
 
 **What shipped:**

package/assets/templates/project-log.md

@@ -8,40 +8,11 @@ oat_last_updated: YYYY-MM-DD
 
 # Project Log: {Project Name}
 
-This append-only log serves two audiences: the project team learning from this project's execution, and maintainers improving the general OAT workflow and tooling.
-
-## Logging contract
-
-Append when something breaks, surprises you, requires a workaround, or works notably well enough to preserve as do-not-regress evidence. Record evidence, not a running narrative. Prior entries are never edited or struck through; append corrections as a new judgment entry that references the original entry and explains the correction. Add a version note to tool-related observations. Create entries only with `oat project log append`; run `oat project log append --help` for the complete entry contract. Reference supporting artifacts by path instead of inlining them. Never record secret values such as tokens, keys, signed URLs, or credentials because this log rolls up into tracked surfaces; reference secrets by name or source, never by value.
-
-Judgment entries default to 1–3 sentences covering what happened, the impact or workaround, and any follow-up. High-value entries may instead use this structured body:
-
-```text
-Observation: What happened and the supporting evidence.
-Impact: Why it mattered or what workaround was required.
-Recommendation: What should change or be preserved.
-```
-
-Shared tracked surfaces must be written only from the root checkout, never from parallel worktrees.
-
-## Entry format
-
-Judgment entries:
-
-```text
-### YYYY-MM-DD · <project|general> · <bug|friction|worked-well|feedback> · <area>
-```
-
-Structural entries:
-
-```text
-### YYYY-MM-DD · structural · <producer> · <ref>
-```
+Append-only evidence of what broke, surprised, or worked: write entries only with `oat project log append` (see its `--help`), never edit a prior entry, and never record secret values.
+Contract, entry grammar and roll-up: https://voxmedia.github.io/open-agent-toolkit/workflows/projects/execution/project-log
 
 ## Entries
 
-Entries are chronological and append-only.
-
 ## End-of-run synthesis (pending — do not skip at project completion)
 
 Summarize the overall verdict, adopted adjustments, and entries graduated to the repo ledger or backlog. Roll up durable observations into tracked surfaces before archiving this project log.

package/assets/templates/project-retro.md

@@ -22,7 +22,10 @@ oat_template_name: project-retro
 <!-- Rendered artifacts must replace oat_retro_project with a non-null project
      slug and oat_retro_generated with a UTC YYYY-MM-DDTHH:MM:SSZ timestamp,
      set oat_template: false, and remove oat_template_name. Record every
-     inspected evidence source above with status: used | unavailable. When an
+     inspected evidence source above with status: used | unavailable.
+     project-log covers the unified learnings (category-bearing judgment
+     entries) and is read first; oat-execution-learnings is the legacy file,
+     read second and recorded unavailable when absent. When an
      evidence family is partial, split it into truthful source entries, such as
      archived-review-markdown: unavailable and gate-receipts: used. Do not add
      a `partial` evidence status. Derivative current-run reconnaissance