feat(lessons): record failed-run lessons

README.md

@@ -45,6 +45,10 @@ GitHub Projects deployments can optionally auto-promote validated PRs from `Huma
 [elixir/README.md](elixir/README.md#auto-promote-from-human-review) for the opt-in config and
 rollout controls.
 
+The Elixir implementation can optionally keep repository-local lessons from failed runs in
+`.symphony/lessons.md`. When enabled in `WORKFLOW.md`, Symphony recalls recent entries into future
+agent prompts, but it never auto-commits the file.
+
 ---
 
 ## License

SPEC.md

@@ -612,6 +612,11 @@ not require recognizing or validating extension fields unless that extension is
 - `agent.auto_promote.quiet_seconds`: integer, default `600`
 - `agent.auto_promote.optout_label`: string, default `requires-human-review`
 - `agent.auto_promote.allowed_issue_labels`: list of strings, default `[]`
+- `agent.lessons.enabled`: boolean, default `false`
+- `agent.lessons.path`: repo-relative markdown path, default `.symphony/lessons.md`
+- `agent.lessons.max_entries`: positive integer, default `50`
+- `agent.lessons.recall_n`: non-negative integer, default `10`
+- `agent.lessons.postmortem_max_tokens`: positive integer, default `1024`
 - `codex.command`: shell command string, default `codex app-server`
 - `codex.approval_policy`: Codex `AskForApproval` value, default implementation-defined
 - `codex.thread_sandbox`: Codex `SandboxMode` value, default implementation-defined
@@ -694,6 +699,8 @@ Distinct terminal reasons are important because retry logic and logs differ.
     before accepting the successful exit.
   - If the workspace HEAD is unchanged or cannot be read, keep the issue in an active review state,
     write an operator-visible comment, and do not schedule the normal success continuation.
+  - If lessons are enabled and the workspace HEAD is unchanged, write a repository-local lesson
+    entry before ending the worker session.
   - If no claim-time workspace HEAD SHA was captured, fail open and continue the normal success path.
   - Schedule continuation retry (attempt `1`) after the worker exhausts or finishes its in-process
     turn loop.
@@ -1171,10 +1178,14 @@ The `Agent Runner` wraps workspace + prompt + app-server client.
 Behavior:
 
 1. Create/reuse workspace for issue.
-2. Build prompt from workflow template.
+2. Build prompt from workflow template, appending recent lessons from `agent.lessons.path` when
+   lessons are enabled.
 3. Start app-server session.
 4. Forward app-server events to orchestrator.
-5. On any error, fail the worker attempt (the orchestrator will retry).
+5. On a HEAD-unchanged failure with lessons enabled, ask the coding agent for a bounded
+   post-mortem and append a markdown entry under the configured lessons path. If the post-mortem
+   fails, append the entry with unavailable hypothesis and hint fields.
+6. On any error, fail the worker attempt (the orchestrator will retry).
 
 Note:
 

elixir/README.md

@@ -463,6 +463,12 @@ hooks:
 agent:
   max_concurrent_agents: 10
   max_turns: 20
+  lessons:
+    enabled: false
+    path: ".symphony/lessons.md"
+    max_entries: 50
+    recall_n: 10
+    postmortem_max_tokens: 1024
 codex:
   command: codex app-server
 ---
@@ -536,6 +542,12 @@ agent:
 - `agent.auto_promote` controls the optional GitHub-only `Human Review` promotion rule. It is
   disabled by default; when enabled, use `allowed_issue_labels` for a conservative rollout and
   `optout_label` for per-issue human-review overrides.
+- `agent.lessons.enabled` defaults to `false`. When enabled, a run whose workspace HEAD does not
+  advance writes a short markdown entry to `agent.lessons.path` inside the issue workspace, capped
+  to the newest `agent.lessons.max_entries` entries. Future dispatches append the newest
+  `agent.lessons.recall_n` entries to the Codex prompt under `## Lessons from prior runs`.
+  Symphony does not auto-commit this file; maintainers decide whether to keep, edit, prune, or
+  commit `.symphony/lessons.md`.
 - If the Markdown body is blank, Symphony uses a default prompt template that includes the issue
   identifier, title, and body.
 - Use `hooks.after_create` to bootstrap a fresh workspace. For a Git-backed repo, you can run

elixir/WORKFLOW.github.example.md

@@ -118,6 +118,12 @@ agent:
     quiet_seconds: 600
     optout_label: "requires-human-review"
     allowed_issue_labels: []
+  lessons:
+    enabled: false
+    path: ".symphony/lessons.md"
+    max_entries: 50
+    recall_n: 10
+    postmortem_max_tokens: 1024
 
 codex:
   command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-5.5"' --config model_reasoning_effort=xhigh app-server

elixir/WORKFLOW.md

@@ -38,6 +38,12 @@ agent:
     quiet_seconds: 600
     optout_label: "requires-human-review"
     allowed_issue_labels: []
+  lessons:
+    enabled: false
+    path: ".symphony/lessons.md"
+    max_entries: 50
+    recall_n: 10
+    postmortem_max_tokens: 1024
 codex:
   command: codex --config shell_environment_policy.inherit=all --config 'model="gpt-5.5"' --config model_reasoning_effort=xhigh app-server
   approval_policy: never