@open-agent-toolkit/cli 0.3.21 → 0.3.22

package/assets/docs/workflows/projects/execution/project-log.md

@@ -11,16 +11,20 @@ would otherwise remain in agent transcripts, then roll that evidence into
 tracked project and repository references before archiving the project.
 
 The command group is the only supported writer for the artifact. Do not edit
-entries or the synthesis section by hand.
+entries or the synthesis section by hand. A new log starts with a two-line
+header that links to this page; the entry contract lives here and in
+`oat project log append --help` rather than in every log.
 
 ## Configure project logs
 
-Two workflow keys control the feature:
+Four workflow keys control the feature:
 
-| Key                             | Values                   | Default                                       |
-| ------------------------------- | ------------------------ | --------------------------------------------- |
-| `workflow.projectLog`           | `auto`, `true`, `false`  | `auto`                                        |
-| `workflow.projectLogLedgerPath` | repository-relative path | `.oat/repo/reference/project-observations.md` |
+| Key                                    | Values                   | Default                                       |
+| -------------------------------------- | ------------------------ | --------------------------------------------- |
+| `workflow.projectLog`                  | `auto`, `true`, `false`  | `auto`                                        |
+| `workflow.projectLogLedgerPath`        | repository-relative path | `.oat/repo/reference/project-observations.md` |
+| `workflow.projectLogDigest.maxEntries` | positive integer         | `12`                                          |
+| `workflow.projectLogDigest.maxLines`   | positive integer         | `60`                                          |
 
 ```bash
 oat config set workflow.projectLog auto --shared
@@ -35,6 +39,12 @@ current config value.
 For one scaffold operation, `oat project new --with-project-log` forces
 creation and `--no-project-log` suppresses it.
 
+The two `workflow.projectLogDigest` keys bound the Workflow Observations digest
+that roll-up writes into `summary.md` (see
+[Promote and roll up observations](#promote-and-roll-up-observations)). They
+are siblings of `workflow.projectLog`, resolve independently of it, and accept
+only positive integers.
+
 ## Append entries
 
 Judgment entries capture evidence about the project or reusable workflow:
@@ -57,6 +67,48 @@ Judgment flags:
 - `--version-note <text>` — adds an `observed on` clause
 - `--project <path>` — optional when an active project resolves
 
+### Learning entries
+
+A judgment entry can carry a learning category and a stable source identity.
+Autonomous, cloud and goal runs record their learnings this way, so the log is
+the one place learnings live; summary and retro read these entries first and a
+legacy `oat-execution-learnings.md` second.
+
+```bash
+oat project log append \
+  --project .oat/projects/shared/example \
+  --type friction --scope project --area "cloud cache misses" \
+  --category environment-limited \
+  --source obs-2026-10-11-cache \
+  --origin oat-project-autonomous \
+  --idempotency-key obs-2026-10-11-cache \
+  --body "Observation: the runner cache missed on every run. Impact: builds doubled. Recommendation: warm the cache in setup."
+```
+
+- `--category <category>` — one of `gotcha`, `efficiency`,
+  `documentation-gap`, `candidate-skill-content`, `decision`, or
+  `environment-limited`, carried verbatim. Any other value is refused, and
+  `--category` without `--source` is refused.
+- `--source <id>` — the stable per-observation source id, one word. Pass the
+  same id as `--idempotency-key` and a retried write appends nothing; the key
+  is found in the `**Source:**` line, so the body need not repeat it.
+- `--origin <producer>` — the producer that recorded the learning.
+
+These flags write a body head above the body:
+
+```text
+**Category:** environment-limited
+**Source:** obs-2026-10-11-cache
+**Origin:** oat-project-autonomous
+**Recorded:** 2026-10-11T14:03:22Z
+```
+
+The heading grammar and the four judgment types are unchanged, and an entry
+written without these flags is stored exactly as before. The flags are refused
+on structural entries.
+
+### Structural entries
+
 Structural entries record lifecycle events without duplicating larger
 artifacts:
 
@@ -185,7 +237,10 @@ oat project log check --project .oat/projects/shared/example --json
 
 `check` reports whether the log is absent, ready, or still awaiting synthesis;
 entry counts by class, type, and scope; the last entry date; and invalid
-hand-written headings. It reads only `project-log.md`.
+hand-written headings. It reads `project-log.md` and checks only for the
+presence of the legacy learnings file: `learnings` is `legacy` when the project
+still has `oat-execution-learnings.md` (summary and retro read it after the
+log) and `none` otherwise, in every status including `absent`.
 
 It also reports whether the log carries a completion seal:
 
@@ -253,16 +308,50 @@ oat project log rollup \
   --json
 ```
 
-`rollup` writes or updates `## Workflow Observations` in `summary.md` and
-appends `general` judgments to `workflow.projectLogLedgerPath`. Ledger entries
+`rollup` writes a bounded observations digest into `summary.md` and appends
+`general` judgments to `workflow.projectLogLedgerPath`. Ledger entries
 deduplicate by date and area. The command is idempotent.
 
+The digest is a projection, not a copy:
+
+- Only judgment entries qualify. Structural entries are provenance and stay in
+  the log; they are counted, never rendered.
+- Entries are ordered newest first, then `decision` and `gotcha` categories
+  ahead of the rest, then by heading text, and taken while both bounds hold:
+  at most `workflow.projectLogDigest.maxEntries` items and at most
+  `workflow.projectLogDigest.maxLines` lines for the whole section. Entries
+  beyond the bound are counted in a one-line trailer, never copied.
+- Each item is concise: a line with date, type, area, scope, category and the
+  entry's source locator, then the first observation sentence and any
+  limitation or uncertainty line. A recommendation is rendered only for an
+  uncategorized entry; a categorized learning's recommendation belongs to the
+  summary's Autonomous Execution Learnings section, and the digest adds a
+  one-line cross-reference to it.
+- The locator is a plain token, never a link:
+  `oat-project:<slug>#<entry-id>`, where the entry id is
+  `<date>-<type>-<area slug>-<n>` and `n` counts entries sharing that date,
+  type and area slug in log order. Archive export finalizes the token to the
+  archive identity.
+- Live `.oat/projects/<scope>/<slug>/…` paths in rendered text are replaced by
+  a `(project file …)` label that keeps the project-relative remainder.
+- When no judgment entry qualifies, the section is omitted: an existing
+  Workflow Observations section is removed and none is created.
+
+The digest never feeds the ledger. Ledger graduation reads the complete
+judgment set, so a `general` lesson the digest bound left out still graduates.
+
 The structured result contains:
 
 - `status`: `ok`, `failed`, or `ambiguous`
-- `summarySection`: `written` or `updated`
+- `summarySection`: `written`, `updated`, or `omitted`
 - `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
-- `entriesRolledUp`: number of log entries written to the summary section
+- `entriesRolledUp`: number of log entries read, structural and judgment
+- `digest`: the bounds used (`maxEntries`, `maxLines`), the `rendered` count,
+  `omitted` counts (`overBound`, `structural`, and `malformed` for a heading
+  that matches neither grammar and was skipped individually),
+  `omittedEntries` (the locator tokens of over-bound entries, no bodies), and
+  `byProducer` rendered/omitted counts keyed by a judgment's `**Origin:**` (or
+  `unattributed`) or a structural entry's producer
 
 An `ambiguous` result carries only `status` and an `ambiguity` reason, and exits
 1: the log's structure has two readings, so no count would mean anything and

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

@@ -66,7 +66,7 @@ Implementation closeout has one authoritative order:
 4. Run the configured pre-approval sequence.
 5. Record final HiLL approval when the final phase is a checkpoint.
 6. Run the configured post-approval sequence.
-7. Mark implementation complete and emit the implementation success output.
+7. Check the journal (`oat project journal check --at implement-preflight`), then mark implementation complete and emit the implementation success output.
 
 The configured exit gate is independent from the mandatory lifecycle review,
 root-owned phase reviews, and optional `oat_phase_review_gate`. It must reach an
@@ -91,7 +91,7 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - After revision tasks complete, state returns to `pr_open`
-5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override; see the [CLI reference](../../reference/cli-reference.md).
+5. **Complete** (`oat-project-complete`) — accepts `pr_open` or `complete` (an `in_progress` project is routed back to `oat-project-implement`, because the journal and `state.md` must agree at completion), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override for that invariant. Completion then refreshes the journal's Final Summary and `summary.md` prose from observed facts, runs the summary staged, and validates the journal with `oat project journal check --at completion` before any roll-up, seal, archive or lifecycle write; a refusal stops completion with the reason, line and owner, and `complete-state` rechecks the same evaluator before its write. A journal-only override line under `## Deviations from Plan / Design` can cover an authorized gap such as lost commit evidence, never the closeout invariant; see the [CLI reference](../../reference/cli-reference.md) and [Project Artifacts](../../reference/project-artifacts.md#the-implementation-journal).
 
 ### Project-recap gate (non-lite)
 
@@ -157,7 +157,7 @@ On completion, OAT treats archive handling as an explicit closeout choice:
 - If `.oat/config.json` sets `archive.awsProfile` and/or `archive.awsRegion`, those values are forwarded to every `aws` invocation triggered by completion (preflight checks + `aws s3 sync`) and override any ambient shell `AWS_PROFILE` / `AWS_DEFAULT_PROFILE` / `AWS_REGION` / `AWS_DEFAULT_REGION` values. The repo's archive-scoped credentials are treated as deliberate intent so users don't have to unset shell env vars before running completion. See [`config-and-local-state.md`](../../reference/config-and-local-state.md) for the full precedence chain.
 - If `.oat/config.json` sets `archive.summaryExportPath`, completion copies `summary.md` to `<archive.summaryExportPath>/20260401-<project>.md`.
 - Missing or unusable AWS CLI configuration blocks synced terminal cleanup when S3 durability is configured; when S3 sync is not configured, it is not part of the durability requirement.
-- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3; it selects the latest dated remote snapshot and materializes it into the local bare archive tree.
+- `oat repo archive sync` can later sync all archived projects, or one named archived project, back down from S3, materializing each snapshot into the local bare archive tree under its full local name (generation 2 of `<project>` restores to `<project>-g2`, never over generation 1). Archive names follow one contract, `<project>[-gN][-<scope>]` locally and `<YYYYMMDD>-<project>[-gN][-<scope>]` in S3, where `-<scope>` appears only when another scope's archive already held the unqualified name. An unnamed sync restores the latest dated snapshot of every local archive. A named sync takes an exact snapshot name first, then a full generation name such as `<project>-g2` or `<project>-g2-local`, then a generation family: `<project>-<scope>` restores that scope's latest generation, and the base `<project>` restores every family of the project (the unqualified one and each scope-qualified one) at its latest generation, then latest date. A project whose own name ends in `-gN` or `-<scope>` reads as that generation or qualifier, so its name can resolve to the same archive directory as a shorter-named project's; sync it by exact snapshot name to remove the ambiguity.
 - Persisted archive metadata binds the snapshot to the source-ref SHA, allowing
   an interrupted closeout or legacy complete record to resume without
   rematerializing an active project. Dashboard and list surfaces omit fully

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

@@ -259,6 +259,24 @@ Final review `passed` gate requires:
 A goal milestone delivery is gated by its passed, fresh integrated review and
 exit carrier rather than by a `final` row.
 
+## Receipts in the journal
+
+`oat-project-review-receive` writes one receipt per received review: a
+phase-scoped receipt in that phase's section of `implementation.md`, a final,
+multi-phase, milestone or remote (PR) receipt under `## Reviews and Gates`,
+never after `## References`. Each receipt lists every finding's identity and
+substance, its disposition and rationale, the fix task or approved deferral it
+links to, and the final outcome; approved deferrals are also lines under
+`## Deferred Findings`. The review file path is a local-only citation: reviews
+are not archived, so the journal and plan must stand without it, and an
+unresolved review path is never a completion defect.
+
+Code reviews run `oat project journal check --at review --scope <phases>`
+first; its reasons reach the reviewer in the Review Scope. A finding that a
+mechanical pointer or projection refresh resolves (stale overview totals, a
+run line to re-render, a lagging resume pointer) is refresh-only and belongs to
+closeout's refresh, never a fix task.
+
 ## Complexity review at budget exhaustion
 
 When a review or gate budget runs out, another round of the same review is

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.21",
-  "docs-config": "0.3.21",
-  "docs-theme": "0.3.21",
-  "docs-transforms": "0.3.21"
+  "cli": "0.3.22",
+  "docs-config": "0.3.22",
+  "docs-theme": "0.3.22",
+  "docs-transforms": "0.3.22"
 }

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.1.3
+  version: 1.1.4
 ---
 
 # OAT in Cursor Cloud
@@ -33,7 +33,8 @@ end-to-end requests route to `oat-project-autonomous` after orientation.
 
 - A shell and Node/npm are available.
 - Read `references/cursor-cloud-mechanics.md` only when model-family identity,
-  dispatch-surface catalogs, or degraded review evidence is needed.
+  dispatch-surface catalogs, degraded review evidence, or a learning write is
+  needed.
 
 ## Mode Assertion
 
@@ -62,7 +63,7 @@ context without taking ownership of a lifecycle phase.
 - Verifying or installing the supported OAT CLI.
 - Comparing skill versions as a freshness check.
 - Loading Cursor mechanics and org-layer context skills when relevant.
-- Recording environment anomalies and degraded routes in project learnings.
+- Recording environment anomalies and degraded routes as project-log learnings.
 
 **Self-Correction Protocol:**
 
@@ -243,9 +244,10 @@ user version >= repo version
 It never chooses the source:
 
 - user version equal to or higher than repo → read the user copy;
-- repo version higher than user → still read the user copy, append an anomaly
-  to `oat-execution-learnings.md`, and flag the user tier for refresh with
-  `oat tools update` or an environment rebuild;
+- repo version higher than user → still read the user copy, record the anomaly
+  as a learning through the project-log learning write in
+  `references/cursor-cloud-mechanics.md` (Learning Write), and flag the user
+  tier for refresh with `oat tools update` or an environment rebuild;
 - if freshness is safety-critical, refresh and re-verify before continuing;
   stop if the user tier cannot be refreshed safely.
 
@@ -283,8 +285,10 @@ the provider dispatch algorithm.
   environment when integrated systems require them. Do not hard-depend on,
   name, or emulate an absent org layer.
 - When an expected skill, MCP server, CLI surface, or credential is absent,
-  record the gap in the active project's `oat-execution-learnings.md`. Continue
-  only through a documented integrity-preserving route.
+  record the gap as a learning in the active project's `project-log.md` through
+  the Learning Write in `references/cursor-cloud-mechanics.md`; with the
+  project log disabled it warns once and records nothing. Continue only through
+  a documented integrity-preserving route.
 
 Return an orientation summary:
 

package/assets/skills/oat-cursor-cloud-projects/references/cursor-cloud-mechanics.md

@@ -92,10 +92,71 @@ That provider reference owns Cursor launch, acceptance, continuation, retry,
 and recovery mechanics. `oat-project-dispatch-subagents` owns lifecycle scope
 and policy adaptation. Do not duplicate those contracts here.
 
+## Learning Write
+
+Cloud learnings — environment anomalies, setup gaps, degraded checks, freshness
+anomalies and missing skills, MCP servers, CLI surfaces or credentials — are
+category-bearing judgment entries in the active project's `project-log.md`,
+written only through `oat project log append`. Never create or append to
+`oat-execution-learnings.md`.
+
+Give each observation a stable, whitespace-free source id unique to this run
+and observation (for example `cloud-<run id>-<NN>`) and retain it for retries;
+it is both `--source` and `--idempotency-key`, so a replay appends nothing.
+Write the learning title as `--area` and the body as `Observation:`,
+`Impact:`, `Recommendation:` and, when it applies, `Uncertainty:` lines.
+
+```bash
+# Learning write (shared by oat-project-autonomous, oat-cursor-cloud-projects
+# and oat-project-goal): oat_record_learning <category> <source-id> <title> <body>
+oat_record_learning() {
+  local category="$1" source="$2" title="$3" body="$4" type result
+  case "$category" in
+    gotcha | environment-limited) type=friction ;;
+    efficiency | candidate-skill-content) type=worked-well ;;
+    documentation-gap | decision) type=feedback ;;
+    *)
+      echo "oat: unknown learning category '$category'" >&2
+      return 1
+      ;;
+  esac
+  result=$(oat project log append --json --project "$PROJECT_PATH" \
+    --type "$type" --scope project --area "$title" \
+    --category "$category" \
+    --source "$source" \
+    --origin "${LEARNING_ORIGIN:?set to the producer skill name}" \
+    --idempotency-key "$source" \
+    --body "$body") || {
+    printf '%s\n' "$result" >&2
+    return 1
+  }
+  if printf '%s' "$result" | grep -Eq '"status": *"skipped"'; then
+    echo "oat: warning: project log disabled (workflow.projectLog=false); learning $source not recorded" >&2
+  fi
+}
+```
+
+Set `LEARNING_ORIGIN=oat-cursor-cloud-projects`. Use the six categories
+verbatim; an environment anomaly or a missing surface is usually
+`environment-limited`, a stale user tier `gotcha`. The write maps the category
+to the judgment type (`gotcha`, `environment-limited` → `friction`;
+`efficiency`, `candidate-skill-content` → `worked-well`; `documentation-gap`,
+`decision` → `feedback`).
+
+Call it unconditionally; do not read `workflow.projectLog` yourself. The
+append consults that flag only while `project-log.md` does not exist: with the
+log disabled and absent it creates nothing and reports `status: skipped`, the
+write prints one warning line, records nothing, and orientation continues. An
+existing `project-log.md` keeps accepting categorized learnings whatever the
+flag says (`DR-260718-automatic-create-on-first`). Commit `project-log.md`, when it
+exists, with the next bookkeeping commit for the project (a synced project uses
+`oat project push`).
+
 ## Degraded Route Evidence
 
 Degradation is a pre-launch selection outcome, not a post-accept fallback.
-Record it in the canonical dispatch record plus project learnings.
+Record it in the canonical dispatch record plus one learning (see Learning
+Write).
 
 Use this shape for the Cursor-specific evidence supplied to the generic record:
 
@@ -149,7 +210,7 @@ independence:
 degradation:
   present: true
   reason: catalog-contained-one-dispatchable-family
-learnings_entry: oat-execution-learnings.md#<entry>
+learnings_entry: <learning source id>
 ```
 
 Include the exact configured invocation evidence required by the generic record

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.21
+  version: 1.0.22
 ---
 
 # Autonomous OAT Project
@@ -99,7 +99,7 @@ If you catch yourself:
 **Recovery:**
 
 1. Persist only safe, owned bookkeeping.
-2. Record the deviation or inventory gap in the learnings log.
+2. Record the deviation or inventory gap as a learning (Step 4).
 3. Return to the earliest incomplete canonical lifecycle step, or stop with the
    structured blocker report.
 
@@ -117,7 +117,7 @@ Print each indicator only when its step begins:
 - `[2/9] Detecting persisted lifecycle state…`
 - `[3/9] Selecting workflow review density…`
 - `[4/9] Gathering external-integration evidence…`
-- `[5/9] Initializing execution learnings…`
+- `[5/9] Preparing the project-log learning write…`
 - `[6/9] Running lifecycle phases and independent reviews…`
 - `[7/9] Completing implementation closeout…`
 - `[8/9] Committing and pushing the phase boundary…`
@@ -388,18 +388,12 @@ continue with checked-out sources when that preserves integrity. Missing
 evidence that would force material product or safety assumptions is a boundary,
 not permission to guess.
 
-### Step 4: Create and Maintain the Learnings Log
+### Step 4: Record Learnings in the Project Log
 
-At run start, create `"$PROJECT_PATH/oat-execution-learnings.md"` when absent
-with `oat_generated: false` and append-only intent. Append UTC-dated entries:
-
-```markdown
-## {timestamp} - {category} - {title}
-
-**Observation:** ...
-**Impact:** ...
-**Recommendation:** ...
-```
+Learnings are category-bearing judgment entries in `project-log.md`, written
+only through `oat project log append`. Never create or append to
+`oat-execution-learnings.md`; summary and retro still read an existing legacy
+file second.
 
 Use only these categories: `gotcha`, `efficiency`, `documentation-gap`,
 `candidate-skill-content`, `decision`, and `environment-limited`. Record
@@ -407,22 +401,89 @@ degraded routes, inventory gaps, unavailable verification, and reusable
 improvements. Never record secrets, token values, signed URLs, or active
 autonomy signals.
 
-After creating the log and after every later append, persist that write before
-continuing:
+Give every observation a stable source id: one whitespace-free word that is
+unique to this run and observation, for example
+`autonomous-<run id>-<NN>`. Retain it for retries: the id is both `--source`
+and `--idempotency-key`, so a replayed write reports `already-appended` and
+appends nothing. Write the learning title as `--area`, and the body as
+`Observation:`, `Impact:`, `Recommendation:` and, when it applies,
+`Uncertainty:` lines. Define the write once and call it for every learning:
 
 ```bash
-PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
-  echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2
-  exit 1
+# Learning write (shared by oat-project-autonomous, oat-cursor-cloud-projects
+# and oat-project-goal): oat_record_learning <category> <source-id> <title> <body>
+oat_record_learning() {
+  local category="$1" source="$2" title="$3" body="$4" type result
+  case "$category" in
+    gotcha | environment-limited) type=friction ;;
+    efficiency | candidate-skill-content) type=worked-well ;;
+    documentation-gap | decision) type=feedback ;;
+    *)
+      echo "oat: unknown learning category '$category'" >&2
+      return 1
+      ;;
+  esac
+  result=$(oat project log append --json --project "$PROJECT_PATH" \
+    --type "$type" --scope project --area "$title" \
+    --category "$category" \
+    --source "$source" \
+    --origin "${LEARNING_ORIGIN:?set to the producer skill name}" \
+    --idempotency-key "$source" \
+    --body "$body") || {
+    printf '%s\n' "$result" >&2
+    return 1
+  }
+  if printf '%s' "$result" | grep -Eq '"status": *"skipped"'; then
+    echo "oat: warning: project log disabled (workflow.projectLog=false); learning $source not recorded" >&2
+  fi
 }
-if [ "$PROJECT_SCOPE" = "synced" ]; then
-  oat project push "$PROJECT_PATH" --message "chore(oat): update autonomous execution learnings" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
-else
-  OWNED_COMMIT_PATHS=("$PROJECT_PATH/oat-execution-learnings.md")
-  oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-autonomous:2" --message "chore(oat): update autonomous execution learnings" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
+```
+
+Set `LEARNING_ORIGIN=oat-project-autonomous`. The category is preserved
+verbatim in the entry's `**Category:**` head and maps to the judgment type:
+`gotcha` and `environment-limited` → `friction`; `efficiency` and
+`candidate-skill-content` → `worked-well`; `documentation-gap` and `decision`
+→ `feedback`.
+
+Call the write unconditionally; do not read `workflow.projectLog` yourself.
+The append consults that flag only while `project-log.md` does not exist: with
+the log disabled (`workflow.projectLog: false`) and absent, it creates nothing
+and reports `status: skipped` (`reason: projectLog=false`), the write prints
+its one warning line, records nothing, and the run continues. An existing
+`project-log.md` keeps accepting categorized learnings whatever the flag says
+(`DR-260718-automatic-create-on-first`). Disabling the log stops its creation;
+do not persist the learning anywhere else.
+
+Assign the source id before each write and pass that variable, so the commit
+below carries the id just written (`$RUN_ID` is this run's id; `NN` numbers the
+observation and is retained for retries):
+
+```bash
+LEARNING_SOURCE="autonomous-$RUN_ID-NN"
+oat_record_learning <category> "$LEARNING_SOURCE" "<title>" "<body>"
+```
+
+After every write, persist the log before continuing:
+
+```bash
+if [ -f "$PROJECT_PATH/project-log.md" ]; then
+  PROJECT_SCOPE=$(oat project scope "$PROJECT_PATH" --format value) || {
+    echo "oat: cannot resolve project scope for $PROJECT_PATH; refusing to commit artifacts" >&2
+    exit 1
+  }
+  if [ "$PROJECT_SCOPE" = "synced" ]; then
+    oat project push "$PROJECT_PATH" --message "chore(oat): record autonomous execution learning" || { echo "oat: project push failed; run oat project pull, resolve the reported state, and retry" >&2; exit 1; }
+  else
+    OWNED_COMMIT_PATHS=("$PROJECT_PATH/project-log.md")
+    oat internal commit-paths --identity "${COMMIT_IDENTITY:?set once and retain for retries}:oat-project-autonomous:learning:${LEARNING_SOURCE:?set to the source id just written}" --message "chore(oat): record autonomous execution learning" -- "${OWNED_COMMIT_PATHS[@]}" || exit 1
+  fi
 fi
 ```
 
+`LEARNING_SOURCE` is the source id just written, so each learning commits
+under its own operation identity; an unset id stops the commit rather than
+sharing one identity across learnings.
+
 ### Step 5: Invoke Lifecycle Skills and Reviews
 
 Invoke each lifecycle skill by name and let it own its complete workflow,
@@ -582,7 +643,7 @@ Take this goal from discovery to PR with OAT autonomy: add resumable exports.
 Do not create or normalize project artifacts by hand.
 
 **A lifecycle skill asks an unmapped question:** Treat it as an
-`inventory-gap` boundary, record the exact site in the learnings log, and stop
+`inventory-gap` boundary, record the exact site as a learning (Step 4), and stop
 resumably.
 
 **A review launch fails after acceptance:** Continue or retry only through the
@@ -607,4 +668,5 @@ reconciliation path. Do not guess or overwrite the tracker.
   resumable boundary.
 - ✅ Phase-boundary commits and non-force pushes are recorded.
 - ✅ The run ended with a final PR report or a structured blocker report.
-- ✅ The learnings log contains reusable, secret-free entries.
+- ✅ Learnings are reusable, secret-free, category-bearing project-log entries,
+  or the run reported that the disabled, absent log recorded none.

package/assets/skills/oat-project-autonomous/references/gate-inventory.md

@@ -324,7 +324,7 @@ remains immutable baseline evidence for the original p01-t01 verification.
 | `oat-project-summary/SKILL.md`                                             | `68c197c44c18 -> NG`; `a8983fec040c -> NG`; `a167d03559fa -> NG`; `cf317c17c586 -> SUMMARY-01`; `f3e49b727752 -> NG`; `f979b2342d28 -> NG`; `803bf40ec423 -> NG`; `c8fced47ef8e -> NG`; `d7ea1e2a4f5f -> NG`; `5f315ab87cb1 -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `oat-project-pr-final/SKILL.md`                                            | `601ac2b890f2 -> NG`; `c264a64398f0 -> NG`; `9efcbcee42ea -> NG`; `655d61df0a8f -> NG`; `cf317c17c586 -> PRFINAL-01`; `2de348a391c0 -> PRFINAL-03`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `oat-project-pr-final/references/docs/autonomy-contract.md`                | `* -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `oat-project-complete/SKILL.md`                                            | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `7bcbf58b54e9 -> NG`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG`; `8c5e599f6bac -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `oat-project-complete/SKILL.md`                                            | `6ed459f9e462 -> NG`; `a167d03559fa -> NG`; `79c2eeed668c -> COMPLETE-01`; `2c1514b9d9af -> COMPLETE-01`; `31c750b4fea7 -> COMPLETE-01`; `cfba413b1293 -> COMPLETE-01`; `7fcfce0423ac -> COMPLETE-01`; `4c7f88a7f942 -> COMPLETE-02`; `6a1a95acc8cc -> COMPLETE-02`; `3b559956b3eb -> COMPLETE-03`; `14d161cdf99b -> COMPLETE-03`; `fffe5eea5ebd -> NG`; `e7dc6fdc4eb3 -> COMPLETE-01`; `e5460e437299 -> NG`; `882b61c9096c -> NG`; `9ffa1c752505 -> NG`; `8c5e599f6bac -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `oat-project-review-provide/SKILL.md`                                      | `1f4b981cac8b -> NG`; `adaeca152bb2 -> NG`; `2f7c201c3c06 -> NG`; `88f79700afdc -> NG`; `655d61df0a8f -> NG`; `efafde9ef5a0 -> NG`; `d2a3861d6323 -> REVIEWPROVIDE-02`; `65f5b9cf49cd -> REVIEWPROVIDE-04`; `962cb38d246a -> REVIEWPROVIDE-04`; `1a568483ba0b -> REVIEWPROVIDE-04`; `610e27edfe85 -> REVIEWPROVIDE-04`; `bb0096e95c47 -> REVIEWPROVIDE-06`; `55f6357a987d -> REVIEWPROVIDE-06`; `e3c08ecdab17 -> REVIEWPROVIDE-06`; `1bee61f8531c -> REVIEWPROVIDE-07`; `3d35091607a1 -> REVIEWPROVIDE-08`; `fb40c4341c4c -> NG`; `b22d16885150 -> NG`; `d2b25906242e -> REVIEWPROVIDE-08`; `fd8ebf72b3c4 -> NG`; `79c8103e8656 -> NG`; `4fbd78337e33 -> NG`; `c3d50ea7cf69 -> NG`; `09b1b8dd445c -> NG`; `7acc8f3718d2 -> REVIEWPROVIDE-09`; `b2fa883fc4a2 -> NG`; `fe4421531b4c -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `oat-project-review-receive/SKILL.md`                                      | `9b8a3743d626 -> NG`; `49ed2780983b -> NG`; `4ee8730382d3 -> NG`; `655d61df0a8f -> NG`; `765f897d67ac -> NG`; `53b58d16dd32 -> NG`; `fb8755a3bdf4 -> NG`; `1d710fb4cc66 -> NG`; `1f7dd98dff2f -> NG`; `56f78c6740e6 -> NG`; `76f5fb5a88cd -> NG`; `085abfa3599f -> REVIEWRECEIVE-01`; `92578f7df686 -> NG`; `a7d114059bb6 -> NG`; `ac88cfaa83d9 -> NG`; `594bbf70346c -> REVIEWRECEIVE-08`; `f31f07284718 -> REVIEWRECEIVE-02`; `e4c0625439f8 -> REVIEWRECEIVE-04`; `505ad8389c0a -> REVIEWRECEIVE-05`; `20e05e1a4381 -> REVIEWRECEIVE-06`; `e30e06f39281 -> REVIEWRECEIVE-07`; `f8fd58180ecf -> NG`; `c3abcdc02d9f -> NG`; `f2ebdd6abb9b -> NG`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `oat-project-review-provide/SKILL.md`                                      | `2e794bf4fc4a -> REVIEWPROVIDE-08`; `5441ab977b46 -> REVIEWPROVIDE-08`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

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

@@ -7,7 +7,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.0.2
+  version: 1.0.3
 ---
 
 # Brief Project