feat: add loop FSM transitions, plan amendments, and audit rewind (#72)

* feat: add loop FSM transitions, plan amendments, and audit rewind

* refactor: consolidate loop transition logging and persist final_audit_fix phase

- Renumber migrations 138-140 to 141-143 to avoid collision with feat/loop-metrics
- Extract transitionSectionIndex and recordTerminalTransition single-source helpers
- Dedupe loops-repo bind params and unify setState/restoreState via persistState
- Persist final_audit_fix as a real phase; restart resumes the final-audit fix prompt
- Move plan-adjust guards into adjustRemainingSections under immediateTransaction
- Cache dashboard repos and strip amendment section content from poll payload

* fix: render dashboard machine graph SVG elements in correct namespace

* style: improve dashboard edge label contrast with yellow fill and stroke outline

---------

Co-authored-by: Forge <forge@example.com>

Author: chriswritescode-dev

README.md

@@ -369,7 +369,7 @@ Model and variant selection follows this priority order:
 
 ## Loop
 
-The loop is an iterative development system with four phases, ending with an optional post-completion action:
+The loop is an iterative development system with five persisted phases (`coding`, `auditing`, `final_auditing`, `final_audit_fix`, `post_action`), ending with an optional post-completion action:
 
 1. **Coding phase** — A Code session works on the task
 2. **Auditing phase** — The Auditor agent reviews changes against project conventions and stored review findings

docs/api/README.md

@@ -371,7 +371,7 @@ Model and variant selection follows this priority order:
 
 ## Loop
 
-The loop is an iterative development system with four phases, ending with an optional post-completion action:
+The loop is an iterative development system with five persisted phases (`coding`, `auditing`, `final_auditing`, `final_audit_fix`, `post_action`), ending with an optional post-completion action:
 
 1. **Coding phase** — A Code session works on the task
 2. **Auditing phase** — The Auditor agent reviews changes against project conventions and stored review findings

docs/api/_media/architecture.md

@@ -167,7 +167,7 @@ OpenCode Forge uses `bun:sqlite` for all data persistence. The storage layer is
 - `initializeDatabase(dataDir, options)` - Creates SQLite DB in the data directory
 - `closeDatabase()` - Closes database connections on shutdown
 - `resolveDataDir()` - Resolves platform-appropriate data directory (`~/.local/share/opencode/forge`)
-- Migrations are sequential SQL files (numbered 100-131) tracked in a `migrations` table
+- Migrations are registered explicitly in execution order (ids 100-143; not every id ships a SQL file) and tracked in a `migrations` table
 
 ### Repository Pattern
 
@@ -179,6 +179,8 @@ All data access goes through typed repository interfaces created via factory fun
 | `PlansRepo` | CRUD for plans | `PlanRow`, `PlansRepo` |
 | `ReviewFindingsRepo` | CRUD for review findings | `ReviewFindingRow`, `ReviewFindingsRepo` |
 | `SectionPlansRepo` | CRUD for milestone (section) plans used in decomposed loops | `SectionPlanRow`, `SectionPlansRepo` |
+| `LoopTransitionsRepo` | Append-only loop phase-transition log | `LoopTransitionRow` |
+| `PlanAmendmentsRepo` | Append-only audit trail of mid-loop plan amendments | `PlanAmendmentRow` |
 | `LoopSessionUsageRepo` | Per-session token/cost usage across rotated loop sessions | `LoopSessionUsageRow`, `LoopUsageAggregate` |
 | `TuiPrefsRepo` | TUI preferences persistence | `TuiPrefsRepo` |
 

docs/api/_media/loop-system.md

@@ -40,13 +40,15 @@ stateDiagram-v2
     Auditing --> Auditing: next section
     Auditing --> FinalAuditing: last section clean
     Auditing --> [*]: audit clear
-    FinalAuditing --> Coding: final audit dirty (fix mode)
-    Coding --> FinalAuditing: final-audit fix complete
+    FinalAuditing --> FinalAuditFix: final audit dirty
+    FinalAuditFix --> FinalAuditing: fix pass idle complete
+    FinalAuditing --> Auditing: plan amendment appended sections
     FinalAuditing --> PostAction: final audit clean
     note right of PostAction: Only when loop.postAction.enabled
     PostAction --> [*]: post-action complete
     Coding --> [*]: max iterations / retry limit / stall timeout / cancellation
     Auditing --> [*]: max iterations / retry limit / stall timeout / cancellation
+    FinalAuditFix --> [*]: max iterations / retry limit / stall timeout / cancellation
     FinalAuditing --> [*]: final audit clean (no post-action)
 ```
 
@@ -66,7 +68,7 @@ interface LoopState {
   maxIterations: number              // Maximum iterations (0 = unlimited)
   startedAt: string                  // ISO timestamp
   prompt?: string                    // Original task prompt
-  phase: 'coding' | 'auditing' | 'final_auditing' | 'post_action'
+  phase: 'coding' | 'auditing' | 'final_auditing' | 'final_audit_fix' | 'post_action'
   lastAuditResult?: string           // Last audit output
   errorCount: number                 // Consecutive error count
   auditCount: number                 // Number of audits completed
@@ -187,7 +189,7 @@ graph TD
     G --> H[Branch preserved]
 ```
 
-When a workspace carries a SHA pin (`extra.startRef`, set by remote loop launches), the new branch is created from that exact commit instead of the clone's current `HEAD`. If the commit is not present locally, the adapter fetches the sync ref (`extra.syncRef`, default `refs/forge/<loopName>`) from the configured git remote first, and fails with a descriptive error when the SHA still cannot be resolved. Existing branches always win — the pin is ignored when the loop branch already exists. On final teardown the sync ref is deleted from the shared git remote. See [Configuration → Remotes](configuration.md#remotes).
+When a workspace carries a SHA pin (`extra.startRef`, set by remote loop launches), the new branch is created from that exact commit instead of the clone's current `HEAD`. If the commit is not present locally, the adapter fetches the sync ref (`extra.syncRef`, default `refs/forge/<loopName>`) from the configured git remote first, and fails with a descriptive error when the SHA still cannot be resolved. If the loop branch already exists, its tip must match the pinned SHA — a leftover same-named branch at a different commit fails creation with an actionable error instead of silently running old code (unpinned workspaces still reuse existing branches). On final teardown the sync ref is deleted from the shared git remote. See [Configuration → Remotes](configuration.md#remotes).
 
 Benefits of worktree isolation:
 - Isolation from ongoing development
@@ -215,7 +217,15 @@ In user-facing language, a plan is decomposed into **milestones** — ordered un
 - `<!-- forge-section -->` markers in the architect plan output
 - `section-read` tool reads the current or specified milestone
 
-Decomposition is a one-shot preprocessing step at loop start (`services/deterministic-decomposer.ts`), not a runtime loop phase. Once milestones exist, the loop advances through them via `advance-section` transitions inside the `auditing` phase. When the `final_auditing` phase reports outstanding bug findings, the loop rotates to a coding session in "final-audit fix" mode — the code agent fixes the reported findings without rewinding to a specific section, and on idle the loop transitions straight back to `final_auditing` for re-verification.
+Decomposition is a one-shot preprocessing step at loop start (`services/deterministic-decomposer.ts`), not a runtime loop phase. Once milestones exist, the loop advances through them via `advance-section` transitions inside the `auditing` phase. When the `final_auditing` phase reports outstanding bug findings, the loop rotates to a coding session in the persisted `final_audit_fix` phase — the code agent fixes the reported findings without rewinding to a specific section, and on idle the loop transitions straight back to `final_auditing` for re-verification. A loop stopped mid-fix restarts as a coding pass that re-sends the final-audit fix prompt (rebuilt from the persisted `lastAuditResult`).
+
+### Plan Amendments
+
+After decomposition, the *remaining* (not yet started) milestones can still be amended mid-loop: during a section audit, the auditor may call the `plan-adjust` tool to replace the pending section suffix when completed work makes the remaining sections unable to achieve the plan objective as written. The objective and verification criteria are immutable, completed/current sections cannot be changed, goal loops are excluded, and the resulting total is capped at 24 sections. Every amendment is recorded in the `plan_amendments` table with before/after snapshots and a rationale. If an amendment appends sections while the loop is already in `final_auditing`, the loop reverts to `auditing` to execute them.
+
+### Transition Log
+
+Every persisted phase change appends exactly one row to the `loop_transitions` table (event type, transition kind, from/to phase, iteration, section index, and terminal status/reason for terminate rows). The dashboard renders this log as a live state-machine graph with per-edge traversal counts. Transition history survives loop restarts (loop rows are restored in place, never delete+reinserted) but is removed with the loop row by the terminal-loop sweep.
 
 ## Completion Conditions
 
@@ -224,7 +234,7 @@ A loop completes when the active phase emits a clean audit result (optionally fo
 - Non-sectioned loops complete on `audit-clear`.
 - Sectioned loops advance through clean section audits, then complete on `final-audit-clean`.
 - Dirty section audits rotate back to coding for the same section so findings can be addressed.
-- Dirty final audits rotate to coding in "final-audit fix" mode (no section rewind); when the fix coding pass goes idle, the loop returns straight to `final_auditing`.
+- Dirty final audits rotate to a coding session in the `final_audit_fix` phase (no section rewind); when the fix coding pass goes idle, the loop returns straight to `final_auditing`.
 - After a clean final audit, if `loop.postAction.enabled` is `true` and specifies a `skill` or `prompt`, the loop enters a `post_action` phase that runs inside the worktree before teardown. Completion occurs when the post-action session goes idle (`post-action-complete` event).
 
 ## Post-Completion Action Phase

docs/api/_media/tools.md

@@ -10,6 +10,7 @@ See also: [Agents and Slash Commands](agents-and-commands.md), [Configuration](c
 |---|---|---|
 | `plan-read` | Read the current session or loop plan, or list/search recent project plans. | [`src/tools/plan-kv.ts`](../src/tools/plan-kv.ts) |
 | `section-read` | Read a section plan and status for the active loop session. | [`src/tools/section-read.ts`](../src/tools/section-read.ts) |
+| `plan-adjust` | Replace the remaining (not yet started) sections of the active loop plan; auditor-only, logged as a plan amendment. | [`src/tools/plan-adjust.ts`](../src/tools/plan-adjust.ts) |
 | `review-write` | Store a review finding. | [`src/tools/review.ts`](../src/tools/review.ts) |
 | `review-read` | Read review findings. | [`src/tools/review.ts`](../src/tools/review.ts) |
 | `review-delete` | Delete a review finding. | [`src/tools/review.ts`](../src/tools/review.ts) |
@@ -46,6 +47,17 @@ Arguments:
 |---|---|
 | `section_index` | Optional 0-based section index. If omitted, returns the lowest-index incomplete section. |
 
+### `plan-adjust`
+
+Only callable by the current auditor session of a sectioned plan loop during the `auditing` phase (rejected in goal loops and during the final audit). Replaces the pending section suffix (from the current section + 1 onward); the plan objective and verification are immutable. The resulting total may not exceed 24 sections. Every adjustment is recorded in the `plan_amendments` table with before/after snapshots.
+
+Arguments:
+
+| Argument | Description |
+|---|---|
+| `sections` | Replacement list of `{ title, content }` for the remaining sections. An empty list removes the entire pending suffix. |
+| `rationale` | Why the plan needs adjustment. |
+
 ## Review Tools
 
 Review findings are scoped to the current loop when invoked from a loop session. Sectioned loops automatically scope findings to the current section unless overridden.

docs/api/functions/createForgePlugin.md

@@ -8,7 +8,7 @@
 
 > **createForgePlugin**(`config`): `Plugin`
 
-Defined in: [index.ts:199](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L199)
+Defined in: [index.ts:199](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L199)
 
 Creates an OpenCode plugin instance with loop management and sandboxing.
 

docs/api/functions/createParentSessionLookup.md

@@ -8,7 +8,7 @@
 
 > **createParentSessionLookup**(`__namedParameters`): (`sessionId`) => `Promise`\<`string` \| `null`\>
 
-Defined in: [index.ts:53](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L53)
+Defined in: [index.ts:53](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L53)
 
 ## Parameters
 

docs/api/functions/createSessionDirectoryLookup.md

@@ -8,7 +8,7 @@
 
 > **createSessionDirectoryLookup**(`__namedParameters`): (`sessionId`) => `Promise`\<`string` \| `null`\>
 
-Defined in: [index.ts:134](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L134)
+Defined in: [index.ts:134](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L134)
 
 ## Parameters
 

docs/api/interfaces/CompactionConfig.md

@@ -6,7 +6,7 @@
 
 # Interface: CompactionConfig
 
-Defined in: [types.ts:152](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/types.ts#L152)
+Defined in: [types.ts:152](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/types.ts#L152)
 
 Configuration for session compaction behavior.
 
@@ -16,7 +16,7 @@ Configuration for session compaction behavior.
 
 > `optional` **customPrompt?**: `boolean`
 
-Defined in: [types.ts:154](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/types.ts#L154)
+Defined in: [types.ts:154](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/types.ts#L154)
 
 Use a custom compaction prompt.
 
@@ -26,6 +26,6 @@ Use a custom compaction prompt.
 
 > `optional` **maxContextTokens?**: `number`
 
-Defined in: [types.ts:156](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/types.ts#L156)
+Defined in: [types.ts:156](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/types.ts#L156)
 
 Maximum context tokens for compaction.

docs/api/interfaces/CreateParentSessionLookupOptions.md

@@ -6,31 +6,31 @@
 
 # Interface: CreateParentSessionLookupOptions
 
-Defined in: [index.ts:43](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L43)
+Defined in: [index.ts:43](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L43)
 
 ## Properties
 
 ### client
 
 > **client**: `ForgeClient`
 
-Defined in: [index.ts:44](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L44)
+Defined in: [index.ts:44](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L44)
 
 ***
 
 ### directory
 
 > **directory**: `string`
 
-Defined in: [index.ts:45](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L45)
+Defined in: [index.ts:45](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L45)
 
 ***
 
 ### logger
 
 > **logger**: `object`
 
-Defined in: [index.ts:47](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L47)
+Defined in: [index.ts:47](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L47)
 
 #### debug
 
@@ -92,12 +92,12 @@ Defined in: [index.ts:47](https://github.com/chriswritescode-dev/opencode-forge/
 
 > **loop**: `Loop`
 
-Defined in: [index.ts:46](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L46)
+Defined in: [index.ts:46](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L46)
 
 ***
 
 ### negativeTtlMs?
 
 > `optional` **negativeTtlMs?**: `number`
 
-Defined in: [index.ts:48](https://github.com/chriswritescode-dev/opencode-forge/blob/f95e7c2c73f775c4d7d3d5c8c63957e7a3039691/src/index.ts#L48)
+Defined in: [index.ts:48](https://github.com/chriswritescode-dev/opencode-forge/blob/a221960b2db97da192fa8ae878f660ac7cfa0d90/src/index.ts#L48)