@warpgogol/forge 0.3.1

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

@@ -0,0 +1,230 @@
+---
+name: fo-idea-plan
+description: Plan RFC implementation — ensure audit/enhance done, map affected artifacts, draft a step-by-step plan with validation and evidence, and persist it. Use when an RFC needs an implementation plan.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'grilling']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [commands.validateRfc]
+  optional: [paths.invariantsFile, paths.compassDocs]
+triggers: ["plan the implementation for this RFC", "create implementation plan", "map affected artifacts and draft steps"]
+---
+
+# Plan RFC Implementation
+
+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.
+
+Create a structured implementation plan for an accepted (or pilot-approved) RFC. The plan fixes the step sequence, affected artifacts, validation suite, and evidence strategy **before** code changes begin — making implementation predictable, repeatable, and verifiable.
+
+## Process
+
+### 0. Identify the RFC(s) and verify prerequisites
+
+The pipeline is: create → audit → enhance → plan. Audit and enhance are **mandatory** — no RFC may proceed to planning without both being completed. This is critical because enhance can only edit the RFC while it is still `draft` — if the RFC is `reviewing`, enhance will transition it to `draft` first. Once it becomes `accepted`, enhancement is no longer possible in place.
+
+**Do not skip these checks for `accepted` RFCs.** An RFC may have been accepted manually without going through the pipeline. The checks below apply to every RFC regardless of status.
+
+#### 0.1. Identify the RFC(s)
+
+The user may provide:
+
+- **A single RFC**: `RFC-XXXX`, a filename, or a path.
+- **A comma-separated list**: `RFC-XXXX, RFC-XXXX, RFC-XXXX` — process each in order.
+- **A range**: `RFC-XXXX..RFC-XXXX` or `от RFC-XXXX до RFC-XXXX` — discover all RFC files in `docs/rfcs/` whose numeric id falls within the inclusive range, sort ascending, and process each in order.
+- **Nothing**: if an RFC file is open in the IDE, use it. Otherwise, ask.
+
+When multiple RFCs are identified, **loop through each one** and run the full plan (steps 0–7) for each RFC sequentially **without pauses between RFCs**. Do not stop, present a summary, or ask the user between RFCs — once the plan for one RFC is committed (or it is skipped), immediately proceed to the next RFC. **Do not emit transition messages such as "Moving to RFC-XXXX next" or per-RFC status reports during the loop.** Internal status is fine, but nothing is shown to the user until the very end. Only after all RFCs are planned, print a single final batch summary.
+
+#### 0.2. Prerequisite checks (per RFC)
+
+Before running the plan on each RFC, perform these checks **in order**. If any check fails, record the RFC as **skipped** in the batch summary with the reason, and immediately proceed to the next RFC in the batch. Do not stop the entire batch — skip and report.
+
+1. **Prefix check** — if the id starts with `ADR-`, this is not an RFC. Skip with message: `ADR-XXXX is an ADR, not an RFC. ADRs do not have a plan step. The ADR pipeline is: create → implement. Run /fo-idea-implement ADR-XXXX to implement.`
+
+2. **RFC file exists** — look for `docs/rfcs/rfc-XXXX-*.md`. If no file is found, skip with message: `RFC-XXXX not found in docs/rfcs/. Run /fo-idea-create-rfc first.`
+
+3. **Terminal status check** — read the RFC's `status` frontmatter. If the status is `implemented`, `rejected`, or `superseded`, skip with message: `RFC-XXXX is <status> (terminal). Terminal RFCs cannot be planned. To change this decision, create a new RFC with supersedes: [RFC-XXXX] via /fo-idea-create-rfc.`
+
+4. **Audit check** — look for `docs/audits/audit-rfc-XXXX-*.md`. If no audit file exists, skip with message: `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.`
+
+5. **Enhance check** — read the RFC's frontmatter and look for the `enhancedAt` field. If `enhancedAt` is absent, skip with message: `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.`
+
+6. **Accepted status check** — if the status is `accepted` and both audit and enhance are done, prerequisites are met. Proceed to step 1.
+
+If all checks pass, proceed to step 0.3.
+
+#### 0.3. Transition draft → accepted
+
+If the RFC is `draft` or `reviewing` and has `enhancedAt` — the user's instruction to plan IS the architecture acceptance. Transition the RFC to `accepted`:
+
+1. Set `status: accepted`.
+2. Set `reviewers` — if the operator specified a reviewer at invocation, use that. Otherwise, read the default reviewer(s) from the `reviewers` field comment in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+3. Set `updatedAt` to today's date.
+4. Commit:
+
+   ```txt
+   rfc: accept RFC-XXXX <short title>
+
+   Transition RFC-XXXX to accepted status for planning.
+   ```
+
+5. Stage only the RFC file.
+
+Then proceed to step 1.
+
+**Inherited acceptance.** If the RFC has a `specRef` frontmatter field pointing to a spec with `status: accepted`, the acceptance inheritance path applies:
+
+1. Check the audit report for this RFC — if the audit verdict is `approved`, the RFC MAY transition `draft → accepted` without a separate human acceptance ceremony. Record `reviewers` from the spec's `reviewers` field and note `via spec acceptance <spec-id>` in the commit message.
+2. If the audit verdict is `needs-revision` or `rejected`, inheritance is void — a human decision is required. Do not transition; ask the operator.
+3. If the `specRef` points to a spec with `status: vendored` (not yet accepted), the RFC cannot progress past `draft` — V-SPEC-03 blocks it.
+
+### 1. Read the RFC
+
+Read the RFC file at `docs/rfcs/rfc-XXXX-*.md` and extract:
+
+- **Decision** — the single decision being made.
+- **Architectural fit** — which DNA invariants it enforces or protects, which existing building blocks it aligns with.
+- **Design** — CLI surface, TypeScript contracts, file system responsibilities, output format, failure modes.
+- **Rollout** — adoption path, pipeline integration, deprecation path.
+- **Risks** — technical, organizational, agent-facing.
+- **Acceptance criteria** — the checkboxes that gate the `accepted → implemented` transition.
+- **Implementation notes for agents** — behavioral policy, constraints, escalation triggers.
+- **Frontmatter** — `commands.proposed/added/changed/removed`, `appsImpacted`, `packagesImpacted`, `satisfies` (DNA trace, RFC-XXXX), `acceptance` probes.
+
+### 2. Explore the codebase
+
+Verify the RFC's claims about affected artifacts. Check:
+
+- Which `packages/*` export the types/commands that need changing.
+- Which `apps/*` consume them and need migration.
+- Which `services/*` are impacted.
+- Which `docs/*.xml` Compass files need synchronization (per root AGENTS.md Compass document duties).
+- Which `AGENTS.md` files (root, `apps/`, `packages/`, `services/`) need rule updates.
+- Which pipelines (`build.check`, `build.prepare`, `sites-check`, `sites-check-postbuild`) the new commands join.
+- Whether `rfc.supersede.propose` is needed for any invariant conflict discovered during exploration.
+
+### 3. Resolve open questions
+
+After exploring, identify decisions the RFC leaves open — ambiguities, trade-offs, unspecified boundaries, conflicting constraints. These are **decisions**, not facts: if a fact can be found by exploring the codebase, look it up instead of asking.
+
+Walk the user through each question **one at a time**. For each:
+
+1. **Short context** — what the question is, why the plan needs it resolved, what changes depending on the answer.
+2. **Options** — list 2-4 concrete options, **recommended option first**. Mark it with "(recommended)". Each option is a short label plus one line explaining the trade-off.
+3. **Wait** — present the question and stop. Do not batch multiple questions; asking several at once is bewildering.
+
+Use the `ask_user_question` tool when available, with the recommended option as the first entry. Otherwise, present the question inline and wait for the answer.
+
+Typical questions that arise:
+
+- **Scope boundary** — the RFC names several packages; which are in-scope for this plan vs. deferred to a follow-up?
+- **Migration strategy** — fail-hard from day one, warn-first with a grace period, or opt-in with a flag?
+- **Pipeline placement** — does the new check join `build.check` (blocking) or `sites-check-postbuild` (advisory)?
+- **Backward compatibility** — forward-only break, or expand-then-contract migration?
+- **Test seam** — unit test at the handler level, integration test through the CLI, or both?
+- **Compass sync** — which `docs/*.xml` files need updates, and is this a structural change or a content-only refresh?
+
+If exploration surfaces no open questions, skip this step and proceed directly to drafting.
+
+### 4. Draft the plan
+
+Copy `docs/plans/plan-0000-template.md` and fill it, incorporating the user's answers from step 3. Each step must have a **completion criterion** — a checkable condition that tells the agent the step is done.
+
+Step ordering follows the contract-first pattern:
+
+1. **Contracts** — types, schemas, frontmatter fields, ontology catalogs.
+2. **Commands** — Site OS command handlers, registry, pipeline wiring.
+3. **Documentation** — `AGENTS.md`, Compass XML (`ref(forge.yaml bindings.paths.compassDocs)`), `ref(forge.yaml bindings.paths.invariantsFile)` (if new DNA invariant).
+4. **Tests** — unit tests, fixture files, test matrix.
+5. **Validation** — run `rfc.validate`, `build:check`, acceptance probes.
+6. **Evidence** — run `rfc.verification.emit`, commit evidence file.
+7. **Review & Fix** — `fo-review` on all session code changes, `fo-fix` if findings (MANDATORY — do not omit from the plan).
+
+Mark **human review points** on steps that:
+
+- Change or establish a DNA invariant (requires a new RFC, not an implementation step).
+- Change an external contract (Stripe, Supabase, Cloudflare, UChat, Matomo).
+- Change security or privacy policy.
+- Change the RFC governance process itself.
+
+### 5. Grill the plan
+
+Invoke the `/grilling` skill to stress-test the draft plan before persisting. This is **mandatory**, not optional — every plan goes through grilling.
+
+The grilling checks:
+
+- Are the objectives concrete enough to verify?
+- Does the step ordering have hidden dependencies?
+- Are completion criteria actually checkable, not vague?
+- Are human review points placed where they should be?
+- Does the validation suite cover the acceptance criteria?
+- Are risks mapped to specific mitigating steps, not just listed?
+- Could an agent following this plan get stuck or confused?
+
+Address every concern the grilling raises by revising the draft. Do not persist until the grilling is satisfied.
+
+### 6. Persist the plan
+
+Name the plan file by mirroring the RFC filename with a `plan-` prefix:
+
+```txt
+docs/rfcs/rfc-0001-introduce-rfc-governance-process.md
+  → docs/plans/plan-rfc-0001-introduce-rfc-governance-process.md
+```
+
+Do **not** modify the RFC file itself — the plan references the RFC by `rfcId`, not the other way around.
+
+### 7. Commit
+
+Commit the plan file. This is **mandatory** — the plan must be committed, not left in the working tree.
+
+Commit message format:
+
+```txt
+plan: RFC-XXXX <short description>
+
+Add implementation plan for RFC-XXXX (<title>).
+```
+
+Reference the RFC ID in the commit subject. Stage only the plan file — do not stage unrelated changes.
+
+### 8. Final batch summary
+
+This step runs only once, after every RFC in the batch has been planned through steps 0–7. Do not run this step after each individual RFC.
+
+If only one RFC was requested, confirm briefly:
+
+```
+Plan created: docs/plans/plan-rfc-XXXX-*.md
+```
+
+If multiple RFCs were processed, present a single batch summary in `aiLanguage`. **Translate all labels, headings, and column names to `aiLanguage`** — the template below is structural only.
+
+```
+## <Batch Plan Summary in aiLanguage>
+
+### RFCs planned: <N>
+### RFCs skipped/errored: <list with reason>
+
+| RFC | Plan path | Status |
+| --- | --- | --- |
+| RFC-XXXX | docs/plans/... | created |
+| RFC-XXXX | docs/plans/... | created |
+...
+```
+
+Do not output per-RFC summaries or "Moving to RFC-XXXX next" messages during the loop; they belong here, at the very end.
+
+## Constraints
+
+- **Commit only your own files.** Stage only the files this skill produces or modifies — the plan file and the RFC file (for status transitions). Do not stage unrelated changes. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+- **Audit and enhance are mandatory.** No RFC may proceed to planning without both an audit file in `docs/audits/` and `enhancedAt` in the RFC frontmatter. This applies regardless of RFC status — an `accepted` RFC may have been accepted manually without the pipeline. Never skip these checks. If either is missing, skip the RFC with a clear message directing the user to the missing step.
+- The agent MAY transition `draft`/`reviewing` → `accepted` in this skill (step 0.3) after enhance is complete. This is the only RFC file modification permitted — the plan itself references the RFC by `rfcId`.
+- The plan describes steps but does NOT authorize execution — use `/fo-idea-implement` to execute.
+- The plan MUST NOT propose changing DNA invariants without a new superseding RFC.
+- The plan MUST respect RFC-XXXX: only `accepted → implemented` is agent-permitted; all other status transitions are human-only. The `draft → accepted` transition in step 0.3 is an exception authorized by the user's explicit instruction to plan the RFC.
+- The plan MUST reference the RFC's acceptance criteria as the source of truth for completion.
+- **Default reviewer source.** When transitioning `draft → accepted` and the operator has not specified a reviewer, read the default reviewer(s) from the `reviewers` field comment in `os/rfc/rfc-0000-template.md` inside `@warpgogol/forge` (currently `human:andrii-syrokomskyi`). Set all listed default reviewers.
+- **No pauses for recoverable tool errors.** If a tool call fails with a recoverable error — e.g. `write_to_file` content too long, JSON truncation, line count/character limit exceeded, or similar — do not stop and ask the user. Recover autonomously: split the content into smaller writes, use `edit`/`multi_edit`, decompose oversized files, and retry immediately. The operator's default answer to "Shall I proceed?" is always "yes".

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

@@ -0,0 +1,103 @@
+---
+name: fo-idea-status
+description: Show a concise table of RFCs and ADRs filtered by status or mentioned in the current session. Use when the operator wants a quick status overview.
+invocation: user
+category: fo
+concerns: read-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: []
+  optional: [commands.validateRfc, commands.validateAdr]
+triggers: ["show RFC and ADR status", "what is the status of this RFC", "list RFCs by status"]
+---
+
+# RFC and ADR Status
+
+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.
+
+## What this skill does
+
+Lists RFCs and ADRs via site-kernel commands (or by scanning frontmatter as fallback), collects statuses, and presents a concise table. If the operator specifies statuses, filter to those. If the operator mentions RFC/ADR ids in the invocation, include those regardless of status. When a single status has more than 12 documents, show only the count instead of listing each one.
+
+## Process
+
+### 1. Determine the filter
+
+Check the operator's input for:
+
+- **Status names** — `draft`, `accepted`, `implemented`, `reviewing`, `rejected`, `superseded`, `retired`. If provided, filter to those statuses only.
+- **No filter** — if no statuses are specified, show all statuses that have at least one document.
+- **Session mentions** — if the operator included `RFC-XXXX` or `ADR-XXXX` ids in the current invocation, always include those documents in the output, even if their status was not requested.
+
+### 2. Collect documents
+
+**Always** make a single call to `rfc.list --json` (no `--status` flag) and a single call to `adr.list --json`. Filter by status in memory from the returned `entries` array. Never make per-status calls.
+
+```sh
+ref(forge.yaml bindings.commands.validateRfc) --list --json
+ref(forge.yaml bindings.commands.validateAdr) --list --json
+```
+
+If `adr.list` is not available, fall back to scanning `docs/adrs/adr-*.md` frontmatter.
+
+Read the JSON output and extract `id`, `title`, `status`, `createdAt`, and `updatedAt` from each entry.
+
+### 3. Build the table
+
+Sort entries by `updatedAt` descending (newest first). If `updatedAt` is missing or equal, fall back to `createdAt` descending.
+
+Group documents by type (RFC, ADR) and then by status. **Translate all headings and column names to `aiLanguage`** — the templates below are structural only. For each group:
+
+- If the group has **≤12 documents**, list each one: `| ID | Title | Status |`
+- If the group has **>12 documents**, show only the count
+
+For counts-only groups:
+
+```
+## RFC Status
+
+| Status | Count |
+| --- | --- |
+| implemented | 328 |
+| draft | 7 |
+
+(Showing counts for implemented; listing draft individually.)
+```
+
+If all requested groups are small enough, use the detailed table per type:
+
+```
+## RFC Status
+
+| ID | Title | Status |
+| --- | --- | --- |
+| RFC-XXXX | ... | draft |
+...
+```
+
+### 4. Session mentions
+
+If the operator mentioned specific RFC/ADR ids in the invocation, add a section after the tables:
+
+```
+### Mentioned in this session
+
+| ID | Title | Status |
+| --- | --- | --- |
+| RFC-XXXX | ... | draft |
+```
+
+### 5. Stop
+
+Present the table and stop. This skill is read-only — it does not modify any file.
+
+## Constraints
+
+- **Read-only.** This skill does not modify any file.
+- **Concise output.** Use the >12 threshold to keep output manageable. Show counts, not individual listings, for large groups.
+- **Include session mentions.** Always include documents the operator mentioned in the invocation, regardless of the status filter.
+- **Prefer OS commands.** Use `rfc.list`/`adr.list` instead of scanning the file system.
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.

package/skills/fo/fo-memory-sync/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: fo-memory-sync
+description: Sync memory and recent sessions from external AI coding tools (Codex CLI, Claude Code) into the current project. Cross-platform, local-only.
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+knowledge:
+  - qa-log.md
+  - fix-patterns.md
+  - learned-principles.md
+triggers: ["sync memory from codex", "import external agent knowledge", "recall sessions from other tools", "sync memory from claude code"]
+---
+
+# fo-memory-sync
+
+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 `my-preferences` skill semantics.
+
+Sync memory and recent sessions from external AI coding tools into the current project so that a fresh agent can pick up knowledge left by other agents who worked on the same project. Runs locally — no network calls, no data exfiltration. Cross-platform: Linux, WSL, Windows.
+
+## Knowledge layers
+
+The skill maintains three knowledge files alongside `SKILL.md`:
+
+- **`fix-patterns.md`** (L1) — baseline patterns for filtering, deduplication, and import decisions. Grown by AI per operator direction.
+- **`learned-principles.md`** (L2) — distilled concrete principles extracted from past runs, with `confirmations: N` counter. At N≥3 the skill auto-applies without asking.
+- **`qa-log.md`** (L0) — append-only raw Q&A pairs from each run. Used for meta-analysis and prioritizing suggestions.
+
+Read L1 and L2 at the start of each run. Append to L0 during the run. Distill L2 from L0 at the end.
+
+## Source locations
+
+The skill reads from two external tool families. All paths are resolved relative to the home directory.
+
+### Codex CLI
+
+| Platform    | Memory                           | Sessions                         |
+| ----------- | -------------------------------- | -------------------------------- |
+| Linux / WSL | `~/.codex/memories/`             | `~/.codex/sessions/`             |
+| Windows     | `%USERPROFILE%\.codex\memories\` | `%USERPROFILE%\.codex\sessions\` |
+
+Memory files are typically Markdown or plain text. Session files may be JSON, JSONL, or Markdown — read whatever format exists.
+
+### Claude Code
+
+| Platform | Global instructions | Global settings | Project instructions |
+| --- | --- | --- | --- |
+| Linux / WSL | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` | `<repo>/CLAUDE.md` or `<repo>/.claude/CLAUDE.md` |
+| Windows | `%USERPROFILE%\.claude\CLAUDE.md` | `%USERPROFILE%\.claude\settings.json` | `<repo>\CLAUDE.md` or `<repo>\.claude\CLAUDE.md` |
+
+Claude Code does not store session history in a standard filesystem location readable by external tools. For Claude Code, the skill reads global and project-level instructions only.
+
+## Process
+
+### 1. Detect platform and resolve paths
+
+Detect the operating system via `process.platform` or equivalent. Resolve the home directory:
+
+- Linux / WSL: `os.homedir()` → typically `/home/<user>`
+- Windows: `os.homedir()` → typically `C:\Users\<user>`
+
+Build the full path table for both Codex and Claude Code. Check which paths exist. Skip any source that does not exist — do not error.
+
+### 2. Read knowledge files
+
+Read `fix-patterns.md` and `learned-principles.md` for accumulated filtering and import patterns from previous runs across all projects.
+
+### 3. Discover external memory and sessions
+
+#### 3a. Codex memories
+
+List all files in `~/.codex/memories/` (or Windows equivalent). Sort by modification time, newest first. Read each file. For each memory file:
+
+1. **Check L2** — is there a learned principle matching this memory's topic + project context? If yes and confirmations ≥3, auto-decide (import or skip) without asking.
+2. **Check L1** — is there a baseline pattern matching this memory type? If yes, apply the pattern's filter/import rule.
+3. **No match** — ask the operator with 2-3 options. Record the Q&A pair in L0.
+
+#### 3b. Codex sessions
+
+List all files in `~/.codex/sessions/` (or Windows equivalent). Sort by modification time, newest first. Apply the session limit (default: 20, configurable via operator input). For each session file:
+
+1. Read the file. Detect format (JSON, JSONL, Markdown, plain text).
+2. Extract: date, session name or ID, first lines of context, project path if present.
+3. **Filter by project** — if the session references a project path, check whether it matches the current project root (by path or git remote). If it does not match and the operator did not request all projects, skip it.
+4. **Filter by date** — if the operator specified a date range, apply it.
+5. **Filter by name** — if the operator specified a session name filter, apply it.
+
+#### 3c. Claude Code instructions
+
+Read `~/.claude/CLAUDE.md` (global instructions) and `<repo>/CLAUDE.md` or `<repo>/.claude/CLAUDE.md` (project instructions). These are instruction files, not session logs — treat them as persistent knowledge that may contain project-relevant conventions.
+
+### 4. Filter and deduplicate
+
+For each discovered item (memory, session, instruction):
+
+1. **Relevance filter** — does the item reference the current project, its file paths, its technologies, or its domain? Score relevance as high / medium / low / irrelevant.
+2. **Deduplication** — check whether the knowledge is already present in the project. Search:
+   - `AGENTS.md` files at all levels
+   - `docs/architecture-dna.md`
+   - `docs/rfcs/` and `docs/adrs/`
+   - Existing `docs/sessions/` files
+   - Memory DB (if accessible)
+3. **Staleness check** — is the item older than the last sync? Check L0 for the last sync timestamp for this project.
+
+Items that are irrelevant, duplicated, or stale are listed in the report but not imported.
+
+### 5. Present findings to operator
+
+Present a structured summary in `aiLanguage`. **Translate all labels, headings, and column names to `aiLanguage`** — the template below is structural only.
+
+```
+# <fo-memory-sync report in aiLanguage>
+
+## Sources scanned
+- Codex memories: N files found (M relevant)
+- Codex sessions: N files found (M relevant, K within date range)
+- Claude Code instructions: found / not found
+
+## Relevant items
+| # | Source | Type | Date | Relevance | Summary | Action |
+| --- | --- | --- | --- | --- | --- | --- |
+| 1 | Codex memory | memory | 2026-07-20 | high | <one-line summary> | import |
+| 2 | Codex session | session | 2026-07-22 | medium | <one-line summary> | import |
+| 3 | Claude CLAUDE.md | instruction | — | high | <one-line summary> | already present |
+
+## Filtered out
+| # | Source | Reason |
+| --- | --- | --- |
+| 4 | Codex memory | irrelevant — references different project |
+| 5 | Codex session | duplicate — knowledge already in AGENTS.md |
+```
+
+Ask the operator to confirm which items to import. Use `ask_user_question` with the relevant items as options.
+
+### 6. Import confirmed items
+
+For each confirmed item, route the knowledge to the appropriate destination:
+
+| Knowledge type | Destination | Mechanism |
+| --- | --- | --- |
+| Project convention or rule | Nearest applicable `AGENTS.md` | Direct edit |
+| Architectural decision | `docs/adrs/` | Delegate to `fo-idea-create-adr` |
+| Cross-workspace invariant | `ref(forge.yaml bindings.paths.invariantsFile)` | Delegate to `fo-extract-dna` |
+| Session context | `docs/sessions/` | Create session file |
+| Operator preference | `.agents/operator-profile.md` | Direct edit |
+| Ephemeral context | Memory DB | `create_memory` tool |
+
+Do not duplicate knowledge already present in the target. Read the target file before editing. Add knowledge in the most concise actionable form.
+
+### 7. Update knowledge files
+
+After the run:
+
+1. Append new Q&A pairs to `qa-log.md` (L0).
+2. If new filtering or import patterns emerged, propose them to the operator and append approved patterns to `fix-patterns.md` (L1).
+3. If recurring decisions were confirmed, distill principles and append to `learned-principles.md` (L2) with `confirmations: 1`. Increment existing principles if the same decision was made again.
+4. Commit knowledge file updates: `git add packages/forge/skills/fo/fo-memory-sync/ && git commit -m "chore: update fo-memory-sync knowledge from run"`.
+
+### 8. Final report
+
+Output a structured summary:
+
+```
+# fo-memory-sync summary
+
+## Sync completed
+- Project: <project root>
+- Date: <YYYY-MM-DD>
+- Sources: Codex (memories: N, sessions: M), Claude Code (instructions: found)
+
+## Imported
+- AGENTS.md rules: N
+- ADRs: N (delegated to fo-idea-create-adr)
+- DNA invariants: N (delegated to fo-extract-dna)
+- Session files: N
+- Memory DB entries: N
+- Operator profile entries: N
+
+## Filtered out
+- Irrelevant: N
+- Duplicate: N
+- Stale: N
+
+## Knowledge files updated
+- qa-log.md: N new entries
+- fix-patterns.md: N new patterns
+- learned-principles.md: N new/updated principles
+
+## Next sync
+- Suggested: <YYYY-MM-DD> (weekly)
+```
+
+## Constraints
+
+- **Local-only.** No network calls, no API requests, no data exfiltration. All reading is from the local filesystem.
+- **Read-only on external sources.** Never modify files in `~/.codex/`, `~/.claude/`, or any external tool directory. The skill only reads from those locations.
+- **Cross-platform.** Must work on Linux, WSL, and Windows. Use `os.homedir()` and `path.join()` — never hardcode path separators.
+- **Operator confirmation mandatory for imports.** Do not import any knowledge without explicit confirmation. Present findings, let the operator choose.
+- **No duplication.** Always check whether knowledge is already present in the project before importing. Read target files before editing.
+- **Dedup across projects.** Knowledge files (L0/L1/L2) are shared across all projects. Use project path or git remote as the dedup key in `qa-log.md` entries.
+- **Commit knowledge files.** After each run, commit updated knowledge files to the forge repo. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **Session limit.** Default 20 sessions. Prevents reading hundreds of old session files.
+- **Sensitive information.** Redact API keys, passwords, and PII from any imported knowledge. Same redaction pattern as `fo-handoff`.

package/skills/fo/fo-memory-sync/fix-patterns.md

@@ -0,0 +1,24 @@
+<!-- L1: Baseline fix patterns for filtering, deduplication, and import decisions.
+     Grown by AI per operator direction. Each pattern describes a recurring situation
+     and the action to take. -->
+# Fix Patterns
+
+## Pattern A: Skip non-project sessions
+
+**Situation:** Codex session references a project path that does not match the current project root or git remote.
+**Action:** Skip. List in the "Filtered out" section of the report with reason "irrelevant — references different project".
+
+## Pattern B: Skip duplicate knowledge
+
+**Situation:** Memory or session content is already present in `AGENTS.md`, `docs/architecture-dna.md`, or existing `docs/sessions/` files.
+**Action:** Skip import. List in the "Filtered out" section with reason "duplicate — knowledge already in <location>".
+
+## Pattern C: Import project convention
+
+**Situation:** Memory or instruction contains a convention or rule directly applicable to the current project.
+**Action:** Route to the nearest applicable `AGENTS.md`. Read the file before editing. Add in concise actionable form.
+
+## Pattern D: Redact sensitive information
+
+**Situation:** Memory or session content contains API keys, passwords, or PII.
+**Action:** Redact before importing. Replace with `<redacted>` placeholder. Never import raw secrets.

package/skills/fo/fo-memory-sync/learned-principles.md

@@ -0,0 +1,6 @@
+<!-- L2: Concrete principles distilled from past runs, with confirmations counter.
+     At confirmations >= 3, the skill auto-applies the principle without asking.
+     Rejecting a recommended answer resets confirmations to 0. -->
+# Learned Principles
+
+<!-- Format: - principle: <text> | confirmations: N | project: <path-or-remote-or-all> -->

package/skills/fo/fo-memory-sync/qa-log.md

@@ -0,0 +1,5 @@
+<!-- L0: Append-only Q&A log. Each entry records a question asked and the operator's answer.
+     Format: [YYYY-MM-DD] project:<path-or-remote> Q: <question> A: <answer> -->
+# Q&A Log
+
+<!-- Entries are appended by the skill during runs. Do not hand-edit. -->