@warpgogol/forge 2.9.1 → 2.9.4

package/os/rfc/handlers/implement-stamp.ts

@@ -485,6 +485,12 @@ export async function runRfcImplementStamp(
       },
       exitCode: 0,
       summary: `rfc.implement.stamp: ${targetId} stamped as implemented`,
+      nextSteps: [
+        {
+          action: `Commit the stamp: pnpm exec forge run ecosystem.commit`,
+          kind: "optional",
+        },
+      ],
     };
   } finally {
     await releaseRfcLock(lockPath);

package/os/rfc/handlers/list-create.ts

@@ -131,6 +131,15 @@ export async function runRfcList(
       entries,
     },
     summary: `${entries.length} RFC(s) found`,
+    nextSteps:
+      entries.length === 0
+        ? [
+            {
+              action: `Create a new RFC: pnpm exec forge run rfc.create --title "..."`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }
 
@@ -253,6 +262,12 @@ export async function runRfcCreate(
       consultedDecisions,
     },
     summary: `Created ${nextId}: ${title}`,
+    nextSteps: [
+      {
+        action: `Validate the RFC: pnpm exec forge run rfc.validate --file ${relativeFile}`,
+        kind: "optional",
+      },
+    ],
   };
 }
 
@@ -292,5 +307,11 @@ export async function runRfcNextId(
       scannedFiles: files.length,
     },
     summary: `Next RFC number: ${nextId}`,
+    nextSteps: [
+      {
+        action: `Create the RFC: pnpm exec forge run rfc.create --title "..."`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/rfc/handlers/validate.ts

@@ -162,5 +162,13 @@ export async function runRfcValidate(
     summary: hasErrors
       ? `${violations.filter((v) => v.severity === "error").length} error(s) found`
       : `All ${filesToValidate.length} RFC(s) passed validation`,
+    nextSteps: hasErrors
+      ? [
+          {
+            action: `Fix the ${violations.filter((v) => v.severity === "error").length} error(s) above, then re-run: pnpm exec forge run rfc.validate`,
+            kind: "required",
+          },
+        ]
+      : undefined,
   };
 }

package/os/session/handlers/validate.ts

@@ -246,5 +246,13 @@ export async function runSessionValidate(
     summary: hasErrors
       ? `${violations.filter((v) => v.severity === "error").length} error(s) found`
       : `All ${filesToValidate.length} session file(s) passed validation`,
+    nextSteps: hasErrors
+      ? [
+          {
+            action: `Fix the ${violations.filter((v) => v.severity === "error").length} error(s) above, then re-run: pnpm exec forge run session.validate`,
+            kind: "required",
+          },
+        ]
+      : undefined,
   };
 }

package/os/spec/live-spec-list.ts

@@ -74,5 +74,13 @@ export async function runSpecLiveList(
     data: result,
     exitCode: 0,
     summary: `spec.live.list: ${entries.length} living spec(s)`,
+    nextSteps: entries.length > 0
+      ? [
+          {
+            action: `Validate living specs: pnpm exec forge run spec.live.validate`,
+            kind: "optional",
+          },
+        ]
+      : undefined,
   };
 }

package/os/spec/live-spec-merge.ts

@@ -323,7 +323,7 @@ export async function runSpecLiveMerge(
       );
     }
 
-    return { data: result, exitCode: 0, summary: `spec.live.merge: created ${domain} from ${rfcId}` };
+    return { data: result, exitCode: 0, summary: `spec.live.merge: created ${domain} from ${rfcId}`, nextSteps: [{ action: `Validate the living spec: pnpm exec forge run spec.live.validate`, kind: "optional" }] };
   }
 
   for (const heading of rfcHeadings) {
@@ -409,5 +409,5 @@ export async function runSpecLiveMerge(
     );
   }
 
-  return { data: result, exitCode: 0, summary: `spec.live.merge: modified ${domain} from ${rfcId}` };
+  return { data: result, exitCode: 0, summary: `spec.live.merge: modified ${domain} from ${rfcId}`, nextSteps: [{ action: `Validate the living spec: pnpm exec forge run spec.live.validate`, kind: "optional" }] };
 }

package/os/spec/live-spec-show.ts

@@ -113,5 +113,11 @@ export async function runSpecLiveShow(
     data: result,
     exitCode: 0,
     summary: `spec.live.show: ${domain}`,
+    nextSteps: [
+      {
+        action: `Validate the living spec: pnpm exec forge run spec.live.validate`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/spec/spec-materialize.ts

@@ -386,5 +386,11 @@ export async function runSpecMaterialize(
     },
     exitCode: 0,
     summary: `spec.materialize: created ${created.length} RFC(s) from spec '${specId}'`,
+    nextSteps: [
+      {
+        action: `Validate the created RFCs: pnpm exec forge run rfc.validate`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/spec/spec-status.ts

@@ -280,5 +280,11 @@ export async function runSpecStatus(
     },
     exitCode: 0,
     summary: `spec.status: ${results.length} spec(s)`,
+    nextSteps: [
+      {
+        action: `Validate specs: pnpm exec forge run spec.validate`,
+        kind: "optional",
+      },
+    ],
   };
 }

package/os/werkstatt/handlers/werkstatt-lock-recover.ts

@@ -168,6 +168,15 @@ export async function runWerkstattLockRecover(
     return {
       data: { recovered, failed },
       summary: `[werkstatt.lock.recover] ${recovered.length} artifact${recovered.length === 1 ? "" : "s"} recovered, ${failed.length} failure${failed.length === 1 ? "" : "s"}`,
+      nextSteps:
+        failed.length > 0
+          ? [
+              {
+                action: `Investigate the ${failed.length} failed recovery item(s) above and retry manually`,
+                kind: "required",
+              },
+            ]
+          : undefined,
     };
   } finally {
     await releaseLock(workspaceRoot, "werkstatt-recovery");

package/os/werkstatt/handlers/werkstatt-lock-status.ts

@@ -69,5 +69,14 @@ export async function runWerkstattLockStatus(
       staleCount,
     },
     summary: `[werkstatt.lock.status] ${locks.length} lock${locks.length === 1 ? "" : "s"}, ${staleCount} stale`,
+    nextSteps:
+      staleCount > 0
+        ? [
+            {
+              action: `Recover stale locks: pnpm exec forge run werkstatt.lock.recover`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }

package/os/workflow/handlers.ts

@@ -203,6 +203,15 @@ export async function runWorkflowList(
     data: { command: "workflow.list", workflows: entries },
     exitCode: 0,
     summary: `workflow.list: ${entries.length} workflow file(s) found`,
+    nextSteps:
+      entries.length === 0
+        ? [
+            {
+              action: `Create a workflow file in .devin/workflows/ or .windsurf/workflows/`,
+              kind: "optional",
+            },
+          ]
+        : undefined,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warpgogol/forge",
-  "version": "2.9.1",
+  "version": "2.9.4",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",

package/profiles/godot-csharp.yaml

@@ -690,6 +690,9 @@ workspace:
         #!/bin/sh
         # Platform-scope pre-commit guard
         # Runs werkstatt autonomy and plugin validation before commits
+        # Note: compass.validate reads all source files and may add a few seconds
+        # to commit time for large projects. Remove the line below if this is
+        # too slow during iterative development.
         echo "Pre-commit: running platform checks..."
         pnpm exec werkstatt run werkstatt.autonomy.validate || exit 1
         pnpm exec werkstatt run werkstatt.plugin.validate || exit 1

package/profiles/phaser-turborepo.yaml

@@ -293,6 +293,9 @@ workspace:
         #!/bin/sh
         # Platform-scope pre-commit guard
         # Runs werkstatt autonomy and plugin validation before commits
+        # Note: compass.validate reads all source files and may add a few seconds
+        # to commit time for large projects. Remove the line below if this is
+        # too slow during iterative development.
         echo "Pre-commit: running platform checks..."
         pnpm exec werkstatt run werkstatt.autonomy.validate || exit 1
         pnpm exec werkstatt run werkstatt.plugin.validate || exit 1

package/skills/_shared/fo-pipeline-conventions.md

@@ -276,6 +276,45 @@ When a pipeline step fails and cannot be auto-fixed within 2 attempts (per §Com
 
 The error checkpoint doubles as a resume marker: when resuming an interrupted session, scan for the last error checkpoint. If found, resume from the failed step using the partialState and resumePoint fields.
 
+## Pipeline continuation
+
+When a pipeline step completes (audit, enhance, plan), the agent MUST proactively suggest the next step and offer to proceed. This is NOT automatic chaining — the agent asks the operator first. This applies when the operator is manually driving the pipeline step by step.
+
+### After audit completes
+
+The audit report is persisted and committed. The agent MUST:
+
+1. Present the audit summary.
+2. State: "The next pipeline step is `fo-idea-enhance` — it applies the audit findings to the RFC."
+3. Ask: "Proceed to enhance?" using `ask_user_question` with "Yes, enhance" as the recommended option.
+4. If the operator says yes, invoke `fo-idea-enhance` via the `skill` tool.
+
+### After enhance completes
+
+The enhanced RFC is committed. The agent MUST:
+
+1. Present the enhancement summary.
+2. State: "The next pipeline step is `fo-idea-plan` — it transitions the RFC to accepted and creates the implementation plan."
+3. Ask: "Proceed to plan?" using `ask_user_question` with "Yes, plan" as the recommended option.
+4. If the operator says yes, invoke `fo-idea-plan` via the `skill` tool.
+
+### After plan completes
+
+The plan is committed. The agent MUST:
+
+1. Present the plan summary.
+2. State: "The next pipeline step is `fo-idea-implement` — it executes the plan and stamps the RFC as implemented."
+3. Ask: "Proceed to implement?" using `ask_user_question` with "Yes, implement" as the recommended option.
+4. If the operator says yes, invoke `fo-idea-implement` via the `skill` tool.
+
+### Exception: orchestrator skills
+
+When the pipeline is driven by `fo-idea-i-just-want-to-see-the-result` or `fo-idea-i-just-want-to-see-the-plan`, the orchestrator handles chaining automatically. The continuation suggestion is NOT emitted — the orchestrator's "no pauses between pipeline steps" rule applies.
+
+### Exception: operator declines
+
+If the operator declines the continuation suggestion, the agent stops. The operator can invoke the next step manually later. Do not re-ask.
+
 ## Batch plan preview
 
 When the orchestrator skill processes multiple documents (>=2), emit a batch plan preview before starting the first document. The preview is a table showing: processing order, document id, type, complexity estimate, dependencies, and notes.

package/skills/_shared/fo-prerequisites.md

@@ -0,0 +1,81 @@
+# WG Pipeline Prerequisites & Batch Processing
+
+Reference for `fo-idea-audit`, `fo-idea-enhance`, `fo-idea-plan`, `fo-idea-implement`. These skills share identical input parsing, prerequisite checks, and batch loop behavior.
+
+## Input parsing
+
+The operator may provide:
+
+- **A single id**: `RFC-0362`, `ADR-0003`, a filename, or a path.
+- **A comma-separated list**: `RFC-0355, RFC-0356, RFC-0357` — process each in order.
+- **A range**: `RFC-0355..RFC-0360` or `от RFC-0355 до RFC-0360` — discover all files in `docs/rfcs/` whose numeric id falls within the inclusive range, sort ascending, and process each in order. Ranges are only valid within a single document type (RFC or ADR).
+- **Nothing**: if a document file is open in the IDE, use it. Otherwise, ask.
+
+## Common prerequisite checks
+
+Run these **in order** for each document. If any check fails, record the document as **skipped** in the batch summary with the reason, and immediately proceed to the next document. Do not stop the entire batch — skip and report.
+
+1. **Prefix check** — if the id starts with `ADR-` and this skill handles RFCs only, skip with: `ADR-XXXX is an ADR, not an RFC. ADRs do not have <this step>. The ADR pipeline is: create → implement (includes review → fix). Run /fo-idea-implement ADR-XXXX to implement.`
+
+   If the id starts with `RFC-` and this skill handles ADRs only, skip with: `RFC-XXXX is an RFC, not an ADR. Use the RFC pipeline: create → audit → enhance → plan → implement (includes review → fix).`
+
+2. **File exists** — look for `docs/rfcs/rfc-XXXX-*.md` (or `docs/adrs/adr-XXXX-*.md` for ADRs). If no file is found, skip with: `RFC-XXXX not found in docs/rfcs/. Run /fo-idea-create-rfc first.`
+
+3. **Terminal status check** — read the document's `status` frontmatter. If the status is `implemented`, skip with: `RFC-XXXX is already implemented. Nothing to do.` If the status is `rejected` or `superseded`, skip with: `RFC-XXXX is <status> (terminal). Terminal RFCs cannot be <this action>. To change this decision, create a new RFC with supersedes: [RFC-XXXX] via /fo-idea-create-rfc.`
+
+## Skill-specific prerequisite checks
+
+After the common checks, each skill adds its own:
+
+### fo-idea-audit
+
+No additional checks.
+
+### fo-idea-enhance
+
+4. **Accepted status check** — if the status is `accepted`, skip with: `RFC-XXXX is accepted. Accepted RFCs cannot be edited in place. Run /fo-idea-create-rfc with amends: [RFC-XXXX] to create an amending RFC, or supersedes: [RFC-XXXX] to create a superseding RFC.`
+
+### fo-idea-plan
+
+4. **Audit check** — look for `docs/audits/audit-rfc-XXXX-*.md`. If no audit file exists, skip with: `No audit report found for RFC-XXXX in docs/audits/. Run /fo-idea-audit RFC-XXXX first. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+5. **Enhance check** — read the RFC's frontmatter and look for the `enhancedAt` field. If `enhancedAt` is absent, skip with: `RFC-XXXX has not been enhanced (no enhancedAt in frontmatter). Run /fo-idea-enhance RFC-XXXX first. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+6. **Accepted status check** — if the status is `accepted` and both audit and enhance are done, prerequisites are met. If the status is `draft` or `reviewing` and has `enhancedAt`, the user's instruction to plan IS the architecture acceptance — proceed to the draft→accepted transition.
+
+### fo-idea-implement
+
+4. **Audit check** — look for `docs/audits/audit-rfc-XXXX-*.md`. If no audit file exists, skip with: `No audit report found for RFC-XXXX in docs/audits/. Run /fo-idea-audit RFC-XXXX first. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+5. **Enhance check** — read the RFC's frontmatter and look for the `enhancedAt` field. If `enhancedAt` is absent, skip with: `RFC-XXXX has not been enhanced (no enhancedAt in frontmatter). Run /fo-idea-enhance RFC-XXXX first. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+6. **Accepted status check** — if the status is not `accepted` (e.g. `draft` or `reviewing`), skip with: `RFC-XXXX is <status>, not accepted. Run /fo-idea-plan RFC-XXXX first — it will transition the RFC to accepted and create the plan. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+7. **Plan check** — look for `docs/plans/plan-rfc-XXXX-*.md`. If no plan file exists, skip with: `No plan file found for RFC-XXXX in docs/plans/. Run /fo-idea-plan RFC-XXXX first. The pipeline is: create → audit → enhance → plan → implement (includes review → fix).`
+
+## Batch processing
+
+When multiple documents are identified, **loop through each one** and run the full skill process for each sequentially **without pauses between documents**. Do not stop, present a summary, or ask the user between documents — once the work for one document is committed (or it is skipped), immediately proceed to the next document. **Do not emit transition messages such as "Moving to RFC-XXXX next" or per-document status reports during the loop.** Internal status is fine, but nothing is shown to the user until the very end. Only after all documents are processed, print a single final batch summary.
+
+**Exception:** Interactive steps within a skill (grilling, resolving open questions) are inherently interactive — they may require user responses. This is not a "pause between documents" but a required step within one document's processing. Resolve all interactions for the current document before proceeding to the next.
+
+## Batch summary format
+
+After all documents are processed, present a single batch summary:
+
+```
+## Batch <Action> Summary
+
+### Documents requested: <N>
+### Documents processed: <N>
+### Documents skipped: <list with reason>
+
+| ID | Type | Status | <action-specific columns> |
+|---|---|---|---|
+| RFC-0355 | RFC | <result> | ... |
+| ADR-0003 | ADR | <result> | ... |
+
+### Total commits: <count>
+```
+
+Do not output per-document summaries or "Moving to XXXX next" messages during the loop; they belong here, at the very end.

package/skills/fo/fo-idea-audit/AUDIT-AXES.md

@@ -0,0 +1,66 @@
+# Audit Axes
+
+Load this file when running step 4 of `fo-idea-audit`. For each axis, check every item. An item either **passes**, **fails** (specific finding with evidence), or is **not applicable** (state why). Skip N/A items silently — do not pad the report.
+
+## Axis A — Structural completeness
+
+Beyond V-13 (required sections exist) and V-14 (≥3 acceptance items), check that each section contains real content, not template placeholders or empty HTML comments:
+
+- **Decision** is a single decision in present tense ("The kernel gains…"), not a wishlist or "we should".
+- **CLI surface** shows exact `pnpm exec werkstatt run …` invocations with flags and scope.
+- **TypeScript contracts** are minimal type signatures, not full implementations.
+- **File system responsibilities** table names concrete paths the RFC touches.
+- **Output format** documents the `--json` shape.
+- **Failure modes** specifies exit codes and warn-vs-fail behavior.
+- **Rollout** describes default behavior, adoption path for existing apps, and new-app compliance.
+- **Alternatives considered** is honest — at least one real alternative with a rejection reason.
+- **Risks** includes agent misinterpretation risk and false-positive rate for validators.
+- **Acceptance criteria** items are checkable (can an agent or human verify each one?) and sufficient (do they cover the decision's full scope?).
+- **Implementation notes for agents** are explicit behavioral rules, not vague guidance.
+
+## Axis B — DNA alignment
+
+- Each entry in `satisfies[]` is a real DNA invariant in `docs/architecture-dna.md`, and the RFC body explains **how** it enforces, protects, or extends that invariant — not just that it's "related".
+- If the RFC establishes a new DNA invariant (body says "DNA-N established by this RFC"), the audit confirms `docs/architecture-dna.md` will need a new `## DNA-N` entry and the RFC's `satisfies[]` includes it.
+- The RFC does not silently conflict with any existing DNA invariant. If it changes a DNA invariant, it must `supersede` the establishing RFC — not amend it.
+- `related[]` DNA references are relevant and not decorative.
+
+## Axis C — Ecosystem fit
+
+- **Package boundaries**: imports flow `apps/* → packages/*` and `services/* → packages/*`, never `apps/* → apps/*` or `apps/* → services/*` (DNA-1). If the RFC proposes a new package, it belongs in `packages/*`.
+- **Pipeline placement**: the RFC names the correct pipeline for each new check — `build.prepare`, `build.check`, `sites-check`, `sites-check-postbuild` — and the choice is justified (blocking vs. advisory).
+- **Compass sync**: if the RFC changes repository-wide requirements, shared package contracts, or app-package relationships, it identifies which `docs/*.xml` files need synchronization (root AGENTS.md Compass document duties).
+- **AGENTS.md updates**: the RFC identifies which `AGENTS.md` files need rule updates (root, `apps/`, `packages/`, `services/`, or site-specific).
+- **Cosmic naming**: if the RFC touches manifests or component/section/page contracts, it addresses the three-way alignment (manifest `cosmicName` ↔ `PLANET_IMPORT_PATHS`/`MOON_IMPORT_PATHS` ↔ `system.md` pins).
+- **Command lifecycle**: `commands.proposed/added/changed/removed` buckets are internally consistent — proposed commands that the RFC introduces will land in `added` upon implementation; changed commands are existing registered commands; removed commands are explicitly deprecated.
+
+## Axis D — Forward-only compliance
+
+This ecosystem is forward-only — no backward compatibility layers, no expand-then-contract migrations. Check:
+
+- The RFC does not propose a compatibility shim, bridge, or dual-path that keeps legacy behavior alive alongside the new one.
+- Deprecation means removal in the same RFC wave, not an indefinite grace period.
+- If the RFC amends another RFC, it changes the amended RFC's contract directly — it does not add a parallel interpretation.
+- Legacy code paths are deleted, not maintained behind a flag.
+
+## Axis E — Agent-facing policy
+
+- **Status gate**: the RFC does not contain self-authorizing language ("may proceed while draft", "implementation can start before acceptance"). Draft RFCs cannot grant implementation permission.
+- **Implementation notes** reference the correct governance rules: RFC-0224 (accepted→implemented transition), RFC-0230 (if touching agent surface), RFC-0334 (supersede escalation on invariant conflict), RFC-0330 (verification evidence for probe-bearing RFCs).
+- **Anti-fabrication**: if the RFC's acceptance criteria include content authoring (prose, business records, claims), the criteria distinguish between code changes an agent can make and content that requires human authoring. The RFC must not claim content will be "auto-generated" when it requires human authoring.
+- **Storage policy**: if the RFC touches persistence, it does not introduce cookies (`document.cookie`, `Set-Cookie`). Client-side persistence is `localStorage` only; server-side is `unstorage`.
+
+## Axis F — Pragmatism
+
+- **Minimal command surface**: each proposed command earns its existence — no command that could be a flag on an existing command, no command that duplicates an existing command's scope.
+- **Lean contracts**: TypeScript types are the minimum needed to understand the shape — no speculative generality, no unused optional fields, no abstraction for needs the RFC doesn't have.
+- **Existing patterns**: the RFC checks whether an existing command, schema, or pattern can be extended before proposing a new one. If a new one is proposed, the alternatives section explains why extension was insufficient.
+- **Scope discipline**: `appsImpacted` and `packagesImpacted` list only what's actually impacted. `nonGoals` are explicit and meaningful, not boilerplate.
+
+## Axis G — Blind spots
+
+- **Performance**: build-time commands specify their cost (file scan count, regex complexity, I/O patterns). A command that scans all `apps/**` on every `build.check` is a bottleneck.
+- **False positives**: validators estimate their false-positive rate and describe how to suppress noise during migration.
+- **Edge cases**: the RFC considers empty states (new app with no content, package with no manifests), concurrent execution (two builds, two agents), and interrupted operations (crash mid-write).
+- **Migration path**: existing apps' path to compliance is documented — do they pass without changes, or is there a documented migration window?
+- **Security/privacy**: if the RFC touches user data, PII, or external services, it addresses GDPR/privacy implications and secret management (no hardcoded keys, env vars documented in `.env.example` per DNA-40).

package/skills/fo/fo-idea-audit/SKILL.md

@@ -236,9 +236,9 @@ Semantic audit of RFC-XXXX (<title>). Verdict: <approved | needs-revision | reje
 
 Stage only the audit file — do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
 
-### 8. Stop
+### 8. Stop and suggest next step
 
-Do not modify the RFC or any other file. Do not run `/fo-idea-plan` or `/fo-idea-implement` — those are separate skills with different purposes. Present the report and stop. If the user asks to fix the findings, suggest running `/fo-idea-enhance` — it reads the persisted audit and applies the fixes. The full pipeline is: create → audit → enhance → plan → implement.
+Do not modify the RFC or any other file. Present the report. Then follow the pipeline continuation protocol per `_shared/fo-pipeline-conventions.md` §Pipeline continuation — proactively suggest the next step (`fo-idea-enhance`) and offer to proceed via `ask_user_question`. Do not automatically run the next skill — ask the operator first. The full pipeline is: create → audit → enhance → plan → implement.
 
 ## Constraints
 

package/skills/fo/fo-idea-enhance/SKILL.md

@@ -204,9 +204,9 @@ Integrate audit findings into RFC-XXXX (<title>). <count> direct fixes,
 
 Stage only the RFC files and audit files touched by this enhancement — do not stage unrelated changes.
 
-### 11. Stop
+### 11. Stop and suggest next step
 
-Do not run `/fo-idea-plan` — that is a separate skill for accepted RFCs. If the user asks to plan implementation, suggest running `/fo-idea-plan` after the RFC is accepted. If the user asks to implement, suggest running `/fo-idea-implement` — it requires a plan file and will stop if one is missing. The full pipeline is: create → audit → enhance → plan → implement.
+Follow the pipeline continuation protocol per `_shared/fo-pipeline-conventions.md` §Pipeline continuation — proactively suggest the next step (`fo-idea-plan`) and offer to proceed via `ask_user_question`. Do not automatically run the next skill — ask the operator first. The full pipeline is: create → audit → enhance → plan → implement.
 
 ## Constraints
 

package/skills/fo/fo-idea-implement/ADR-FLOW.md

@@ -0,0 +1,179 @@
+# ADR Implementation Flow
+
+Execute this flow when the document is an ADR (prefix `ADR-`, or file in `docs/adrs/`).
+
+## 4.1. Read the ADR
+
+Read the ADR file. Extract:
+
+- **Status** — must be `accepted`, `reviewing`, or `proposed`. If `superseded` or `rejected` (terminal), stop with message: `ADR-XXXX is <status> (terminal). Terminal ADRs cannot be implemented. To change this decision, create a new ADR or RFC that supersedes ADR-XXXX.` If `implemented`, stop with message: `ADR-XXXX is already implemented. Nothing to do.`
+- **Decision** — the core decision from the `## Decision` section.
+- **Context** — the local situation and constraints from `## Context`.
+- **Consequences** — what the decision implies for the codebase.
+- **Related** — any RFCs, ADRs, or DNA invariants referenced.
+
+## 4.2. Transition to accepted (if needed)
+
+If the ADR is `proposed` or `reviewing`, transition it to `accepted`:
+
+1. Set `status: accepted` in the frontmatter.
+2. Set `updatedAt: <today's date>`.
+3. If `reviewers` is empty, read the default reviewer(s) from the `reviewers` field comment in `docs/adrs/adr-0000-template.md` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+4. Commit:
+
+   ```txt
+   adr: accept ADR-XXXX <short title>
+
+   Transition ADR-XXXX to accepted status for implementation.
+   ```
+
+   Stage only the ADR file.
+
+If the ADR is already `accepted`, proceed directly.
+
+## 4.3. Implement the decision
+
+Read the `## Decision` section and implement it in code. Follow the same principles as RFC implementation:
+
+- Make autonomous, ecosystem-aligned decisions.
+- Use `edit`/`multi_edit` for changes to existing files, `write_to_file` for new files.
+- Commit each logical phase of work:
+
+  ```txt
+  implement: ADR-XXXX — <phase description>
+
+  <one-line description of what was done in this phase>.
+  ```
+
+  Stage only the files touched by this phase — see `_shared/fo-pipeline-conventions.md` §Commit discipline.
+
+- Recoverable errors: see `_shared/fo-pipeline-conventions.md` §Recoverable errors.
+
+## 4.4. Run scoped build checks
+
+After implementation is complete, run heavy checks for the impacted workspaces only:
+
+1. ADR validation:
+
+   ```sh
+   pnpm exec werkstatt run adr.validate <adr-id> --json
+   ```
+
+2. Determine impacted packages/apps from the ADR's `scope` and the files touched during implementation. Build only those workspaces:
+
+   ```sh
+   pnpm --filter @gogol/<package> run build:check
+   ```
+
+   Or for apps:
+
+   ```sh
+   pnpm --filter <app-name> run build:check
+   ```
+
+   See `_shared/fo-pipeline-conventions.md` §Build verification discipline.
+
+## 4.5. Fix errors
+
+If any check fails, fix every error:
+
+1. Read the error output.
+2. Identify the root cause.
+3. Fix it.
+4. Re-run the failing check to confirm the fix.
+5. Commit each fix:
+
+   ```txt
+   fix: ADR-XXXX — <error description>
+
+   <one-line description of the root cause and fix>.
+   ```
+
+Continue until all impacted checks pass.
+
+## 4.6. Documentation audit (fo-doc-audit)
+
+After implementation is complete and all checks pass, invoke `fo-doc-audit` via the `skill` tool. It analyzes the session's changes, checks all documentation surfaces, applies needed updates, and commits them separately. Wait for it to complete.
+
+If `fo-doc-audit` reports that no updates are needed, proceed to the next step.
+
+## 4.7. ADR code-trace
+
+Before stamping `implemented`, verify that the ADR is mentioned in the codebase — this leaves a trace linking code back to the decision record, just as RFCs leave traces.
+
+1. **Search for the ADR id** — use `grep_search` to scan `apps/`, `packages/`, and `services/` for the ADR id string (e.g. `ADR-0003`). Check:
+   - **COMPASS block comments** — `MODULE_CONTRACT`, `CHANGE_SUMMARY`, or other Compass scaffolding comments that reference the ADR id.
+   - **Inline code mentions** — comments, docstrings, or annotations in source files that reference the ADR id.
+
+2. **If mentions are found** — the trace exists. Proceed to step 4.8.
+
+3. **If no mentions are found** — attempt to find the most relevant file(s) where the decision was implemented. If the file(s) can be identified:
+   - Add a Compass block comment referencing the ADR id to the file's `MODULE_CONTRACT` or `CHANGE_SUMMARY` section. For example: `<item>ADR-0003: <brief note on what this ADR decided for this module.</item>`
+   - If the file has no Compass scaffolding, add a brief inline comment at the top of the file: `// Implements ADR-XXXX: <one-line decision summary>`
+   - Commit the trace:
+
+     ```txt
+     trace: ADR-XXXX — add code mention
+
+     Add ADR-XXXX reference to <file> to link the decision to the code.
+     ```
+
+   - Proceed to step 4.8.
+
+4. **If the relevant file(s) cannot be identified** — ask the operator: `ADR-XXXX was implemented but no code mention was found. Please point to the file(s) where this ADR's decision was applied so I can add a trace reference.` After the operator provides the file(s), add the trace as described in step 3, commit, and proceed.
+
+**For already-implemented ADRs** (if this step is reached for an ADR that was already `implemented`): this check is informational — attempt to find the trace and add it if missing, but do not block on it.
+
+## 4.8. Stamp implemented
+
+After all checks pass and documentation is updated, transition the ADR to `implemented`:
+
+1. Set `status: implemented` in the frontmatter.
+2. Set `implementedAt: <today's date>`.
+3. Set `updatedAt: <today's date>`.
+4. Commit:
+
+   ```txt
+   adr: implement ADR-XXXX <short title>
+
+   Transition ADR-XXXX to implemented status. Decision is live in code,
+   scoped build passes.
+   ```
+
+   Stage only the ADR file.
+
+## 4.9. Review (fo-review) — MANDATORY GATE
+
+**This step is unconditional.** It MUST be executed after every implementation run — regardless of whether build checks passed, failed, or were fixed. No exceptions. The ADR report (step 4.11) MUST NOT be emitted until this step is complete.
+
+1. **Determine the diff scope** — identify the git fixed point at the start of this implementation session (the commit before the first `implement:` or `adr:` commit). Capture the diff via `git diff <fixed-point>...HEAD`.
+2. **Invoke `fo-review`** — run the review skill inline via the `skill` tool, passing the diff scope. Wait for it to complete (mechanical floor, seven axes, spec compliance, persist report + commit). If the `skill` tool call fails, retry once. If it fails again, proceed to step 4.11 and note the failure in the report.
+3. **Read the review report** — extract the verdict and all findings.
+
+If the review verdict is **Approved** with zero findings, skip step 4.10 and proceed directly to step 4.11 (Report).
+
+## 4.10. Fix findings (fo-fix) — MANDATORY if findings exist
+
+If the review has ANY findings — this step MUST be executed — it is not optional. "Findings" means any issue noted under any review axis (A–G), regardless of severity label ("minor", "cosmetic", "advisory") or the review's overall verdict. An **approved** verdict with minor findings **still requires** `fo-fix` — do not skip because the verdict is "approved" or findings are "minor". The only case where this step is skipped is a review with **zero findings** (every axis says "No issues."):
+
+1. **Re-verify findings** — before fixing, quickly check whether each finding is still relevant: the flagged code may have been changed by a subsequent step. Discard stale findings.
+2. **Invoke `fo-fix`** — run the fix skill inline via the `skill` tool. It reads the persisted review report, applies fixes in priority order, runs scoped typecheck verification, commits, and delegates doc updates to `fo-doc-audit`. Wait for it to complete. If the `skill` tool call fails, retry once. If it fails again, proceed to step 4.11 and note the failure in the report.
+3. **Re-run scoped build checks** if `fo-fix` made code changes — repeat step 4.4 for any workspaces touched by the fixes.
+
+If the review verdict is **Approved** with zero findings, skip this step — no fix is needed.
+
+## 4.11. Report
+
+After implementation, review, and fix are complete, report:
+
+```
+## ADR-XXXX Implementation Summary
+
+### Decision: <one-line summary>
+### Phases implemented: <count>
+### Commits: <count>
+### Scoped build: <Pass | Fail — fixed>
+### Review: <verdict> — <N> findings
+### Fix: <done, <N> findings fixed | skipped, no findings>
+### Status: implemented (<date>)
+```