@warpgogol/forge 0.22.0 → 0.23.0

package/skills/fo/fo-design-summit/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: fo-design-summit
+description: Simulate a multi-persona design discussion for complex RFCs. Each persona reviews from its professional perspective and raises concerns. Optional, invoked for high-risk architectural RFCs.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'fo-idea-audit']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [paths.invariantsFile]
+  optional: []
+triggers: ["design summit", "multi-persona review", "party mode"]
+---
+
+# Design Summit
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+See `_shared/fo-pipeline-conventions.md` §Language policy.
+
+A multi-persona design review for complex RFCs. The summit simulates five professional perspectives — Architect, Security Engineer, QA Engineer, Product Manager, and Developer Advocate — to surface issues that a single-perspective review misses. Each persona reviews the RFC from its professional lens and raises concerns. The operator sees all perspectives and makes the final decision.
+
+The summit is **optional** — invoked manually by the operator or suggested by `fo-idea-plan` for RFCs that meet complexity criteria. It is not part of the default pipeline.
+
+The summit is `concern: document-only` — it writes a summit report to `docs/summits/` and does not modify the RFC or any source code.
+
+## Process
+
+### 1. Identify the RFC
+
+The user may provide:
+
+- **A single RFC**: `RFC-XXXX`, a filename, or a path.
+- **Nothing**: if an RFC file is open in the IDE, use it. Otherwise, ask.
+
+### 2. Prerequisite checks
+
+Before running the summit, perform these checks **in order**:
+
+1. **Prefix check** — if the id starts with `ADR-`, stop with message: `ADR-XXXX is an ADR. Design summits are for RFCs only. ADRs use the accepted-decision fast path.`
+2. **RFC file exists** — look for `docs/rfcs/rfc-XXXX-*.md`. If no file is found, stop with message: `RFC-XXXX not found in docs/rfcs/.`
+3. **Terminal status check** — read the RFC's `status` frontmatter. If the status is `implemented`, `rejected`, or `superseded`, stop with message: `RFC-XXXX is <status> (terminal). Terminal RFCs cannot be reviewed in a summit.`
+
+If all checks pass, proceed to step 3.
+
+### 3. Read the RFC and related context
+
+Read the target RFC file and its related context:
+
+- `ref(forge.yaml bindings.paths.invariantsFile)` — all DNA invariants referenced in the RFC's `satisfies[]` or `related[]`.
+- Each RFC listed in `amends[]`, `supersedes[]`, `related[]` — read enough to understand what this RFC builds on or changes.
+- The closest `AGENTS.md` for the RFC's scope.
+
+### 4. Read the audit report (if available)
+
+Look for `docs/audits/audit-rfc-XXXX-*.md`. If an audit report exists, read it to avoid duplicating findings. The summit complements the audit — it does not repeat it.
+
+If no audit report exists, proceed without it. Note this in the summit report: persona findings may overlap with future audit findings.
+
+### 5. Run each persona
+
+For each of the five personas, the agent:
+
+1. Adopts the persona's perspective and review focus.
+2. Reads the RFC from that perspective.
+3. Produces a persona report with findings (concerns, questions, recommendations).
+
+#### Persona: Architect
+
+**Focus:** Structural integrity, DNA alignment, coupling.
+
+**Key questions:**
+
+- Does this create hidden dependencies between packages or services?
+- Which DNA invariants are affected? Does the RFC explain how it enforces or protects each one?
+- Will this decision be reversible? If not, is the irreversibility justified?
+- Does the RFC propose a new package, command, or lifecycle that could be a flag on an existing one?
+
+#### Persona: Security Engineer
+
+**Focus:** Attack surface, data exposure, trust boundaries.
+
+**Key questions:**
+
+- What new trust boundaries does this create?
+- Are there unauthenticated paths to sensitive data?
+- Does this leak sensitive data in logs, error messages, or generated artifacts?
+- If the RFC touches persistence, does it introduce cookies or client-side storage outside the established policy?
+
+#### Persona: QA Engineer
+
+**Focus:** Testability, failure modes, edge cases.
+
+**Key questions:**
+
+- How do we test this? What is the test seam — unit, integration, or both?
+- What are the failure modes? What happens under partial failure?
+- Does the RFC consider empty states (new app with no content, package with no manifests)?
+- Are acceptance criteria checkable by an agent or human?
+
+#### Persona: Product Manager
+
+**Focus:** User impact, rollout risk, scope.
+
+**Key questions:**
+
+- Does this solve the stated problem? Is the problem statement grounded in a real user need?
+- What is the rollout impact on existing users? Is there a migration path?
+- Is the scope right — too broad, too narrow, or correctly bounded?
+- Are `nonGoals` explicit and meaningful?
+
+#### Persona: Developer Advocate
+
+**Focus:** Agent clarity, onboarding, documentation.
+
+**Key questions:**
+
+- Can a new agent understand and implement this RFC without external context?
+- Is the RFC self-contained, or does it reference implicit assumptions?
+- Are there terms or concepts that need a glossary entry?
+- Does the RFC's `Implementation notes for agents` section provide explicit behavioral rules?
+
+### 6. Synthesize
+
+Present all persona reports in a single summit document, highlighting:
+
+- **Consensus findings** — concerns raised by 2+ personas (high priority).
+- **Unique findings** — concerns raised by a single persona (medium priority).
+- **No concerns** — personas that found no issues (confidence signal).
+
+Deduplicate overlapping concerns. When two personas raise the same issue from different angles, merge them into a consensus finding.
+
+### 7. Persist the summit report
+
+Write `docs/summits/summit-<rfc-id>.md` with the full discussion.
+
+#### Summit report format
+
+```markdown
+---
+rfc: RFC-XXXX
+createdAt: YYYY-MM-DD
+personas: [architect, security, qa, pm, dev-advocate]
+consensusFindings: <count>
+uniqueFindings: <count>
+---
+
+# Design Summit: RFC-XXXX
+
+## Architect
+
+### Findings
+- **A1 (concern):** <finding text>
+- **A2 (question):** <finding text>
+
+### No concerns
+- <what the architect found well-designed>
+
+## Security Engineer
+
+### Findings
+- **S1 (concern):** <finding text>
+
+## QA Engineer
+
+### Findings
+- **Q1 (concern):** <finding text>
+
+## Product Manager
+
+### Findings
+- **P1 (concern):** <finding text>
+
+## Developer Advocate
+
+### Findings
+- **D1 (question):** <finding text>
+
+## Consensus findings
+
+- **A1 + D1 (2 personas):** <merged finding and recommendation>
+
+## Recommendation
+
+<proceed to acceptance | revise the RFC | run fo-explore for unresolved questions>
+```
+
+The report must include the disclaimer: "No findings does not mean no issues — it means no issues were found from these five perspectives."
+
+### 8. Suggest actions
+
+Recommend whether to:
+
+- **Proceed to acceptance** — if no consensus findings and unique findings are minor.
+- **Revise the RFC** — if consensus findings or significant unique findings exist. Route through `fo-idea-enhance` as audit-style findings.
+- **Run `fo-explore`** — if unresolved questions require deeper exploration before revision.
+
+### 9. Commit
+
+Commit the summit report. This is **mandatory** — the report must be committed, not left in the working tree.
+
+Commit message format:
+
+```txt
+summit: RFC-XXXX <short description>
+
+Multi-persona design summit for RFC-XXXX (<title>). <count> consensus findings, <count> unique findings.
+```
+
+Stage only the summit report file — do not stage unrelated changes.
+
+### 10. Stop
+
+Do not modify the RFC or any other file. Do not run `/fo-idea-enhance` or `/fo-idea-plan` — those are separate skills. Present the summit report and stop. If the user asks to fix findings, suggest running `/fo-idea-enhance`.
+
+## Invocation criteria
+
+`fo-design-summit` is invoked explicitly by the operator or suggested by `fo-idea-plan` when the RFC meets **any** of these criteria:
+
+- `kind: architecture` AND `scope: workspace`
+- `satisfies[]` includes 2+ DNA invariants
+- The RFC introduces a new package, new command family, or new lifecycle
+- The RFC supersedes an implemented RFC
+- The operator explicitly requests it
+
+## Failure modes
+
+- **RFC not found:** The skill errors if the target RFC does not exist.
+- **Audit not run yet:** The skill proceeds without the audit report — persona findings may overlap with future audit findings. The skill notes this in the report.
+- **RFC is too small for a summit:** If the RFC body is less than 500 words, the skill warns that a summit may be overkill and proceeds only if the operator confirms.
+- **Persona findings overlap:** Multiple personas may raise the same concern. The synthesis step deduplicates and marks consensus findings.
+
+## Constraints
+
+- The summit is `concern: document-only` — it must not modify the RFC, source code, or any file except the summit report in `docs/summits/`.
+- **Commit only your own files.** Stage only the summit report. Do not stage unrelated changes. `git add -A` or `git add .` is forbidden.
+- Personas are **simulated** by a single agent in one session. This is not multi-agent infrastructure. Each persona is a perspective shift, not a separate process.
+- The summit report is an informational artifact, not a governance document. It does not block RFC acceptance — the operator decides whether to act on its findings.
+- Summit findings that warrant RFC changes should be routed through `fo-idea-enhance` as audit-style findings, not applied directly by the summit skill.
+- **No pauses for recoverable tool errors.** If a tool call fails with a recoverable error, recover autonomously: split content into smaller writes, use `edit`/`multi_edit`, and retry immediately.

package/skills/fo/fo-explore/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: fo-explore
+description: Explore an idea in the codebase without creating an RFC or ADR. Produces a markdown exploration note in docs/explorations/. Use when weighing options before committing to a specification.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [paths.invariantsFile]
+  optional: []
+triggers: ["explore this idea", "let me think about this", "what are the options for", "what if we"]
+---
+
+# Explore an idea before specification
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+> **This is a document-only skill.** It produces exploration notes in `docs/explorations/` — nothing else. It must never modify, create, or delete source code files. It must not run build commands, tests, or validation suites. Exploration notes are not governance documents — they have no status transitions, no validation, and no acceptance step. They are informational artifacts that may precede an RFC or ADR.
+
+## Process
+
+### 1. Read the idea
+
+The operator describes what they want to explore. Identify:
+
+- **What is being explored** — the core question or idea.
+- **Why exploration is needed** — is the operator unsure about approach, feasibility, or scope?
+- **What constraints are known** — packages, DNA invariants, existing RFCs, timeline.
+
+### 2. Explore the codebase
+
+Search for relevant code, existing patterns, constraints, and dependencies. This is interactive — ask clarifying questions if the idea is vague. Use `code_search`, `grep_search`, and `read_file` to understand the current state of the codebase.
+
+If the codebase is empty or inaccessible, document the constraint and focus on option analysis without codebase findings.
+
+### 3. Weigh options
+
+Present 2–5 options with trade-offs. For each option:
+
+- **Approach** — a brief description of how the idea would be implemented.
+- **Trade-offs** — pros and cons.
+- **DNA alignment** — which invariants from `ref(forge.yaml bindings.paths.invariantsFile)` are relevant.
+- **Blockers** — what needs to be resolved first (missing schema, missing command, conflicting RFC).
+- **Estimated effort** — small / medium / large.
+
+### 4. Assess feasibility
+
+For each option, identify:
+
+- **Blockers** — missing infrastructure, conflicting decisions, missing RFCs.
+- **Required RFCs** — does this option need a new RFC or ADR before implementation?
+- **Estimated effort** — small / medium / large.
+
+### 5. Persist the exploration note
+
+Write `docs/explorations/<slug>.md` using the exploration note format below. The slug must be kebab-case, lowercase, latin-only (matching the project naming convention).
+
+If the file already exists, append a new exploration section with a timestamp header instead of overwriting.
+
+After persisting, transition the note's `status` from `open` to `explored` by editing the frontmatter directly. This skill is `concern: document-only` and may edit `.md` files — no separate command is needed for this transition.
+
+### 6. Suggest next steps
+
+Recommend whether to:
+
+- **Create an RFC** — the exploration identified a cross-workspace change that needs governance.
+- **Create an ADR** — the exploration identified a local decision that needs recording.
+- **Shelve the idea** — the exploration revealed blockers or insufficient value.
+- **Explore further** — the exploration raised more questions than it answered.
+
+## Exploration note format
+
+```markdown
+---
+id: <slug>
+title: "<exploration title>"
+createdAt: YYYY-MM-DD
+status: open
+related: []
+---
+
+# Exploration: <title>
+
+## Idea
+
+<operator's description>
+
+## Codebase findings
+
+<what the agent found in the codebase — relevant files, existing patterns, constraints>
+
+## Options
+
+### Option 1: <name>
+- **Approach:** <description>
+- **Trade-offs:** <pros/cons>
+- **DNA alignment:** <which invariants are relevant>
+- **Blockers:** <what needs to be resolved first>
+- **Estimated effort:** <small/medium/large>
+
+### Option 2: <name>
+...
+
+## Recommendation
+
+<agent's recommendation with rationale>
+
+## Open questions
+
+- <unresolved questions for the operator>
+```
+
+## Frontmatter fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | string | Kebab-case slug, matches filename |
+| `title` | string | Human-readable title |
+| `createdAt` | date | Creation date |
+| `status` | enum | `open` (exploration in progress), `explored` (exploration complete, awaiting decision), `archived` (superseded by RFC or shelved) |
+| `related` | string[] | RFC/ADR ids that materialized from this exploration |
+
+## File system responsibilities
+
+| Path                          | Role                                     |
+| ----------------------------- | ---------------------------------------- |
+| `docs/explorations/<slug>.md` | Exploration note (created by this skill) |
+| `docs/explorations/`          | Directory for all exploration notes      |
+
+## Failure modes
+
+- **Exploration note already exists:** Append a new exploration section with a timestamp header instead of overwriting.
+- **Invalid slug:** Slugs must be kebab-case, lowercase, latin-only. Invalid slugs are rejected by `exploration.archive` — exit code 1.
+- **No codebase access:** Document the constraint and focus on option analysis without codebase findings.
+- **Slug not found:** `exploration.show` and `exploration.archive` return exit code 1 if the slug does not exist.
+- **Already archived:** `exploration.archive` is idempotent — if the note is already `archived`, it returns exit code 0 with `previousStatus: "archived"` (no-op).
+- **Empty directory:** `exploration.list` returns `{ explorations: [] }` with exit code 0 when `docs/explorations/` is empty or does not exist.
+
+## Constraints
+
+- **No source code changes.** This skill is `concern: document-only`. It may only create and edit `.md` files in `docs/explorations/`.
+- **No governance authority.** Exploration notes are not RFCs or ADRs. They do not define contracts, policies, or decisions. They are informational artifacts.
+- **No pipeline integration.** Exploration notes are not part of any build or validation pipeline. They are discoverable via `exploration.list` and by browsing `docs/explorations/`.
+- **Bindings compliance.** Use `ref(forge.yaml bindings.*)` references for paths and commands — no hardcoded project literals in skill instruction lines.

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

@@ -39,6 +39,16 @@ Read the operator's description and identify:
 
 Default to document creation. Only route to implementation if the operator explicitly says "implement" or "don't create a document, just do it".
 
+### 1b. Explore suggestion
+
+If the operator's description is ambiguous, exploratory, or contains phrases like "what are the options", "let me think about", "explore", or "what if we", suggest using `fo-explore` before creating an RFC. Use `ask_user_question`:
+
+> "This sounds like an exploration rather than a settled decision. Should I explore the codebase first, or create an RFC/ADR draft directly?"
+>
+> Recommended option: "Explore first" — because exploration is low-commitment and the results inform a better RFC.
+
+If the operator chooses "Explore first", invoke `/fo-explore` inline. Do not proceed to classification or document creation in this invocation — `fo-explore` will produce an exploration note and suggest next steps, which may include creating an RFC or ADR in a separate invocation.
+
 ### 1a. Accepted-decision fast path
 
 When the operator signals that a decision is **already made** and provides justification, the skill must take a fast path. Recognition signals include:

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

@@ -125,6 +125,7 @@ This ecosystem is forward-only — no backward compatibility layers, no expand-t
 - **Implementation notes** reference the correct governance rules: RFC-XXXX (accepted→implemented transition), RFC-XXXX (if touching agent surface), RFC-XXXX (supersede escalation on invariant conflict), RFC-XXXX (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`.
+- **NEEDS CLARIFICATION markers**: List all unresolved `NEEDS CLARIFICATION` markers with line numbers. If none are found, state "No unresolved markers." Markers in `draft` status are informational; markers in `reviewing`+ status are a blocking finding.
 
 #### Axis F — Pragmatism
 

package/skills/fo/fo-idea-create-rfc/SKILL.md

@@ -49,6 +49,7 @@ Ask the user for, or infer from context:
 - **owners** — default `architecture`; confirm before using a different owner.
 - **commands.proposed / changed / removed** — any new, modified, or removed Site OS commands.
 - **packagesImpacted / appsImpacted** — concrete workspace names.
+- **liveSpec** — for feature-level RFCs (not governance/policy), suggest `liveSpec: true` to auto-derive a living spec domain from `packagesImpacted[0]`, or `liveSpec: <domain>` for an explicit domain. This enables automatic delta-merge into `docs/specs/live/<domain>.md` when the RFC is implemented.
 - **satisfies** — for `architecture` or `contract` RFCs, at least one `DNA-NN` invariant from `ref(forge.yaml bindings.paths.invariantsFile)`.
 - **related** — relevant RFCs, DNA ids, anti-patterns, specs.
 - **reviewer** — if the caller specifies a reviewer identity, use it. If not, default to `human:andrii-syrokomskyi` (matching the default in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge`) **only when the skill is also responsible for moving the RFC out of draft**. For a pure draft scaffold, leave `reviewers: []`.
@@ -90,6 +91,8 @@ Read the generated file and the full template (`os/rfc/rfc-0000-template.md` ins
 - **Acceptance criteria** — ≥3 checkable checkboxes mapped to implementation artifacts.
 - **Implementation notes for agents** — explicit MAY/MUST NOT rules, status-gate reminders, escalation triggers.
 
+When a section cannot be filled with confidence, insert `> NEEDS CLARIFICATION: <question>` instead of guessing. Do not leave sections empty or fill them with speculative content. Markers are resolved during the enhance step.
+
 ### 6. Validate and report
 
 Run:

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

@@ -73,9 +73,9 @@ Read the RFC's `status` frontmatter:
   rfc: revert RFC-XXXX to draft for enhancement
 
   Transition RFC-XXXX from reviewing to draft before enhance.
-  ```
+```
 
-  Stage only the RFC file. Then proceed with enhancement.
+Stage only the RFC file. Then proceed with enhancement.
 
 **No RFC may begin enhancement in any status other than `draft`.** The transition to `draft` is mandatory and must be committed before proceeding to step 4. (Terminal and accepted statuses are already filtered out in step 1.5.)
 
@@ -86,6 +86,7 @@ Read every finding from the audit report. For each, classify it as one of:
 - **Direct fix** — the RFC text can be edited to address it: fill a placeholder section, add a missing edge case, fix a DNA reference, tighten a contract, add a failure mode, etc.
 - **New RFC** — the finding reveals a topic that is too large or too distinct for this RFC. Examples: a new package, a new DNA invariant, a new governance policy, a new external contract. Splitting it out keeps the RFC focused and follows the ecosystem's one-decision-per-RFC principle.
 - **Out of scope** — the finding is valid but belongs to a different RFC or a future effort. Add it to this RFC's `nonGoals` with a brief explanation and, if applicable, a `related` reference to where it will be addressed.
+- **NC (Needs Clarification)** — Unresolved `NEEDS CLARIFICATION` markers in the RFC body. Resolution: ask the operator the question, replace the marker line with the operator's answer in the RFC body. If the operator defers, the marker remains and the RFC cannot transition to `reviewing`.
 
 Record the classification for every finding — the summary in step 8 reports it.
 

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

@@ -79,9 +79,9 @@ Execute the plan's step sequence in order. For each step:
    implement: RFC-XXXX step N — <step title>
 
    <one-line description of what was done in this step>.
-   ```
+```
 
-   Stage only the files touched by this step. Do not stage unrelated changes — another agent may be working in a different session.
+Stage only the files touched by this step. Do not stage unrelated changes — another agent may be working in a different session.
 
 **Implementation principles:**
 
@@ -151,6 +151,7 @@ Read the RFC's `## Acceptance criteria` section. For each checkbox:
 3. **If a criterion is not met**, implement the missing work, commit it, and re-verify.
 4. **Annotate every `[x]` with inline evidence** — add `(evidence: <file-path:line>, <test-or-command>)` to each checked criterion. This is enforced by V-27.
 5. **If a criterion cannot be met** (e.g., requires an external dependency not yet available, requires a pilot that is not registered), do NOT mark it `[x]` and do NOT stamp `implemented`. Instead, split the deferred work into a follow-up RFC via `rfc.supersede.propose`. An RFC with unchecked `[ ]` criteria cannot transition to `implemented` — this is enforced by V-26.
+6. **Ensure `reviewers` is non-empty** — `rfc.validate` enforces V-25: implemented RFCs with an empty `reviewers` field fail validation. Add at least one reviewer (e.g. `human:<name>`) before stamping `implemented`.
 
 Do not proceed to step 3.7 until every acceptance criterion checkbox is checked with evidence.
 
@@ -168,6 +169,8 @@ If the RFC was created on or after 2026-07-07 and has acceptance probes:
 ref(forge.yaml bindings.commands.validateRfc) --verification.emit --id RFC-XXXX
 ```
 
+**Note:** If acceptance probes are commented out (`# acceptance:`) in the RFC frontmatter, `rfc.verification.emit` silently skips creating an evidence file (`filesModified: []`, zero errors). This is expected behavior — RFCs with commented-out probes get no evidence file, and `rfc.implement.stamp` still works without it.
+
 Commit the evidence file:
 
 ```txt
@@ -183,7 +186,7 @@ Stage `docs/rfcs/verification/rfc-xxxx.generated.json`.
 Transition the RFC to `implemented` using the `rfc.implement.stamp` command. Direct edits to `status`, `implementedAt`, and `updatedAt` are prohibited for all actors.
 
 1. Ensure the working tree is clean (all implementation changes committed).
-2. Identify the implementation commit SHA — the commit that contains the core implementation work and references the RFC id in its message or changed files.
+2. Identify the implementation commit SHA — use the **first** `implement:` commit (the commit where implementation began), not the latest fix or documentation commit. Find it via `git log --oneline` and locate the first commit with an `implement:` prefix after the `plan:` or `rfc: accept` commit.
 3. Run the stamp command:
 
    ```sh
@@ -192,6 +195,8 @@ Transition the RFC to `implemented` using the `rfc.implement.stamp` command. Dir
 
    The command atomically validates all preconditions (accepted status, checked+evidenced criteria, clean tree, reachable RFC-referencing commit, passing probe evidence) and sets `status: implemented`, `implementedAt`, and `updatedAt` in one atomic write.
 
+   **Troubleshooting:** If the stamp fails with `Could not parse target RFC` (RFC-IMP-01), the RFC frontmatter has a YAML syntax error — not a missing file. Check for unquoted backtick values in `successSignals`, `nonGoals`, or other list items. YAML plain scalars starting with a backtick must be double-quoted.
+
 4. Commit the stamped RFC file:
 
    ```txt
@@ -314,7 +319,7 @@ 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:
+Read the `## Decision` section and implement it in code. **For each decision point, verify whether the code already exists** — ADRs may declare fields or extensions that related RFCs did not fully implement. Do not assume associated RFCs covered everything; check each decision against the actual codebase and implement any gaps. 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.

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

@@ -168,6 +168,16 @@ The grilling checks:
 
 Address every concern the grilling raises by revising the draft. Do not persist until the grilling is satisfied.
 
+### 5b. Summit suggestion
+
+If the RFC meets summit criteria (any of: `kind: architecture` AND `scope: workspace`, `satisfies[]` includes 2+ DNA invariants, introduces a new package/command/lifecycle, supersedes an implemented RFC), suggest using `fo-design-summit` before acceptance. Use `ask_user_question`:
+
+> "This RFC is complex (architecture, workspace scope, 2+ DNA invariants). Should I run a multi-persona design summit before acceptance?"
+
+Recommended option: "Run summit" — because complex RFCs benefit from multi-perspective review.
+
+If the operator declines, proceed to step 6. If the operator accepts, invoke `fo-design-summit` via the `skill` tool, wait for it to complete, then proceed to step 6.
+
 ### 6. Persist the plan
 
 Name the plan file by mirroring the RFC filename with a `plan-` prefix:

package/skills/fo/fo-session-retro/SKILL.md

@@ -126,12 +126,14 @@ rtk git status --porcelain
 for d in missions/*/workpiece; do [ -d "$d/.git" ] && echo "=== $d ===" && rtk git -C "$d" status --porcelain; done
 ```
 
-**3b. Classify each dirty file as "ours" or "theirs":**
+**3b. Classify each dirty file as "ours" or "unattributed":**
 
-- A file is "ours" if EITHER:
+- A file is "ours" if ANY of:
   - You directly modified it via `edit`, `write_to_file`, `multi_edit`, or `edit_notebook` tools.
   - You indirectly modified it by running a command (`run_command`) that generates or updates it (e.g. codegen pipelines, build commands, etc.).
-- A file is "theirs" if it appears dirty but you have no record of touching it in this session. This means another parallel agent modified it. Do NOT commit, stash, or revert these files.
+  - It was produced by a session-end pipeline step in THIS session: session transcripts (`docs/sessions/*.md`), review reports (`docs/reviews/**/*.md`), or `docs.archive` moves.
+  - It was created by a skill you invoked in this session (e.g. `fo-review` creating a review report, `fo-doc-audit` editing AGENTS.md, `fo-idea-create-adr` creating an ADR).
+- A file is "unattributed" if it appears dirty but you have no record of touching it in this session. Do NOT assume it belongs to a parallel agent — it may be an orphan from a previous session that was not committed. The previous session-end protocol should have caught it, but if it didn't, this session must not propagate the problem further.
 
 **3c. Commit our changes:**
 
@@ -139,9 +141,12 @@ for d in missions/*/workpiece; do [ -d "$d/.git" ] && echo "=== $d ===" && rtk g
 - If there are "our" dirty files in a workpiece: `git -C missions/<missionId>/workpiece add <files>` and `git -C missions/<missionId>/workpiece commit -m "<descriptive message>"`.
 - Use descriptive commit messages that explain what the changes are, not just "session cleanup".
 
-**3d. Report remaining dirty files:**
+**3d. Handle unattributed dirty files (NON-NEGOTIABLE):**
 
-- If any dirty files remain after committing ours, report them to the operator: "The following files were modified by another agent and left untouched: <list>". Then proceed.
+- If any unattributed dirty files remain after committing ours, present them to the operator via `ask_user_question` (in `aiLanguage`) and ask whether to commit or leave each one untouched. Do NOT silently proceed — unattributed files are often orphans from previous sessions that must be resolved, not propagated.
+- For each unattributed file, the operator can choose:
+  - **Commit** — the agent stages and commits the file with a descriptive message.
+  - **Leave untouched** — the operator explicitly acknowledges the file should remain dirty (e.g. it belongs to a parallel agent still running).
 - If the tree is now clean (or was clean from the start), proceed silently.
 
 ### Step 4: RFC implementation verification (NON-NEGOTIABLE)