@warpgogol/forge 0.3.1 → 0.5.0

package/skills/fo/fo-knowledge-distill/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: fo-knowledge-distill
+description: Distill raw knowledge logs (L0) into durable fix patterns (L1) and learned principles (L2), maintain confirmation counters, and migrate legacy sections — with operator approval on every mutation.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'grilling']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: []
+  optional: []
+triggers: ["distill knowledge", "compact skill knowledge", "knowledge lifecycle", "promote fix patterns"]
+---
+
+# Knowledge Distillation
+
+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 skill assists the operator in the knowledge distillation lifecycle: reading raw material (L0), proposing durable patterns (L1) and principles (L2), re-confirming existing entries, migrating legacy sections, and recommending compaction. Every mutation requires explicit operator approval.
+
+## When to invoke
+
+- **After a productive session** — when the session generated raw Q&A pairs or debugging insights that could benefit future agents.
+- **When `forge.skill.knowledge.compact --all-skills --dry-run` reports legacy sections** — this skill performs the actual migration with operator approval.
+- **When a SKILL-21 budget warning appears** — distill to reduce active knowledge volume.
+- **When the operator asks to "distill", "compact", or "maintain" skill knowledge.**
+
+## What this skill is NOT
+
+- It is NOT `forge.skill.knowledge.compact` — that command handles mechanical archival (expiry, supersession, L0 retention, L2 staleness). This skill handles semantic work: grouping, promoting, and migrating.
+- It is NOT `fo-session-retro` — that skill triages session discoveries and routes them. This skill works within a single skill's knowledge files.
+- It is NOT `fo-extract-dna` — that skill extracts architectural invariants. This skill distills operational knowledge (fix patterns, learned principles).
+
+## Process
+
+### Step 1: Scope selection
+
+Ask the operator which skill(s) to distill:
+
+- Use `ask_user_question` to offer: (a) a specific skill by name, or (b) all skills with knowledge files.
+- Parse the selected skill's knowledge files via the structured knowledge parser (in-process import of the forge `src/knowledge/` module or the `forge` package).
+- Report what was found: file names, entry counts, legacy section counts, parse issues.
+
+**Completion criteria:** operator has selected a scope and the skill has parsed all relevant knowledge files without errors.
+
+### Step 2: Read cold material
+
+Read L0 (`qa-log.md`) and, if present, `qa-log.archive.md`. This is the sanctioned wholesale read of the cold layer (hot/warm/cold discipline).
+
+- Also read L1 (`fix-patterns.md`) and L2 (`learned-principles.md`) to understand existing distilled knowledge.
+- Report a summary: how many raw entries, how many existing patterns/principles, what themes recur.
+
+**Completion criteria:** all knowledge files for the selected skill have been read and summarized.
+
+### Step 3: Propose distillations
+
+Group recurring Q&A themes from L0. For each theme, propose either:
+
+- An **L2 principle** (with `confirmations` seeded from observed recurrences) — for cross-cutting insights that apply broadly.
+- An **L1 fix pattern** — for specific, reusable solutions to specific problems.
+
+Present proposals as a table:
+
+| #   | Proposed entry | Layer | Source entries | Rationale |
+| --- | -------------- | ----- | -------------- | --------- |
+
+For each proposal, use `ask_user_question` to let the operator:
+
+- **Confirm** — the entry is written as proposed.
+- **Edit** — the operator provides corrections; the entry is written with edits.
+- **Drop** — the proposal is discarded.
+
+**Completion criteria:** every proposal has been confirmed, edited, or dropped by the operator.
+
+### Step 4: Re-confirmation pass
+
+For existing L2 entries whose themes appear in the new material:
+
+- Propose `confirmations + 1` and `lastConfirmedAt: today`.
+- If the entry is `status: stale`, propose restoring to `status: active`.
+- Present each re-confirmation individually via `ask_user_question`.
+
+**Completion criteria:** every re-confirmation has been approved or declined by the operator.
+
+### Step 5: Legacy migration
+
+For each legacy section (freeform prose that predates structured entries):
+
+- Propose a structured entry: assign an ID, set metadata (layer, created, status), preserve the body verbatim.
+- Use `ask_user_question` for each legacy section — the operator approves the proposed structured entry.
+
+**Completion criteria:** every legacy section has been migrated or explicitly skipped by the operator.
+
+### Step 6: Write
+
+Apply approved mutations via the knowledge serializer (`serializeKnowledgeFile`). Never string-splice markdown. Never touch entries that were not explicitly approved.
+
+- Write files atomically (staging + rename) to prevent corruption on mid-run failure.
+- Commit only the mutated knowledge files (fo-pipeline commit discipline).
+
+**Completion criteria:** all approved mutations are written and committed.
+
+### Step 7: Recommend compact
+
+If retention/expiry candidates remain after distillation:
+
+- Recommend `forge.skill.knowledge.compact --skill <name>` to the operator.
+- Offer to run it via `ask_user_question`.
+- If the operator declines, note it in the session summary.
+
+**Completion criteria:** the operator has been informed of compaction opportunities and has made a decision.
+
+### Step 8: Commit
+
+Commit only the mutated knowledge files. Reference this skill and the knowledge lifecycle in the commit message. Do not stage unrelated changes.
+
+**Completion criteria:** changes are committed with a descriptive message.
+
+## Knowledge file format
+
+All knowledge files use the structured knowledge entry format:
+
+````markdown
+<!-- knowledge-layer: L2 -->
+# learned-principles.md
+
+### K-0001: Short title
+
+```knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+````
+
+Body text describing the principle.
+
+```
+
+See `writing-great-skills` § Cumulative knowledge pattern for the three-layer reference pattern (L0 raw logs, L1 fix patterns, L2 learned principles), entry format, and mutation contract.
+
+## Constraints
+
+- **Operator approval on every mutation.** Never write to a knowledge file without explicit approval for each entry.
+- **Serializer only.** Always use `serializeKnowledgeFile` from the forge knowledge module. Never string-splice markdown.
+- **No semantic logic in command handlers.** The `forge.skill.knowledge.compact` command handles mechanical archival only. Semantic grouping and promotion live in this skill.
+- **No LLM logic in `src/knowledge/`.** Deterministic planning only; meaning work lives here.
+- **Read archives too.** When distilling, read both live and archive files — archived material may still contain themes worth re-distilling.
+
+## Cross-skill promotion
+
+When `forge.doctor` reports `knowledge-duplicate` warnings (cross-skill L2 entries with matching normalized titles), or when the operator identifies a promotion candidate, execute the promotion protocol:
+
+### Promotion protocol
+
+1. **Present the pair** — show both titles, bodies, confirmations, and the proposed merged shared entry (merged body, summed confirmations, `promotedFrom` provenance). The operator approves, edits, or rejects via grilling.
+2. **Write the shared entry** — append to `packages/forge/skills/shared/knowledge/learned-principles.md` with the next `K-NNNN` id, `status: active`, `created: today`, `lastConfirmedAt: today`, `confirmations` (sum of sources), and `promotedFrom: ["<skill>/K-NNNN", ...]`.
+3. **Rewrite local copies** — each skill-local entry keeps its heading and id but its metadata is rewritten: `promotedTo: shared/K-NNNN`, `status: superseded`; body replaced with one line: "Promoted to shared layer as shared/K-NNNN." The next compact run archives these pointer entries out of the hot file.
+4. **Cite, don't copy** — future distill runs in any skill reference the shared id (`shared/K-NNNN`) instead of re-creating the principle locally.
+5. **Commit** — shared file + all touched skill files in one commit.
+
+### Promotion constraints
+
+- **Promotion requires operator approval inside grilling** — detection is deterministic, promotion is human. Never promote without explicit operator approval for each pair.
+- **Never copy shared-layer content into skill-local files** — cite via `shared/K-NNNN`, do not duplicate.
+- **Never promote project-specific knowledge from pack skills into the forge shared layer** — domain-neutrality is checked during grilling. If the principle is project-specific, it stays pack-local.
+- **Portability gate** — grilling must include the question: "Is this principle genuinely cross-skill, or is it specific to one skill's domain?" Only genuinely cross-skill principles promote.
+```

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

@@ -64,7 +64,7 @@ Build the full path table for both Codex and Claude Code. Check which paths exis
 
 ### 2. Read knowledge files
 
-Read `fix-patterns.md` and `learned-principles.md` for accumulated filtering and import patterns from previous runs across all projects.
+Read `fix-patterns.md` and `learned-principles.md` for accumulated filtering and import patterns from previous runs across all projects. Apply only entries with `status: active`; skip entries with `status: stale`, `superseded`, or `archived`.
 
 ### 3. Discover external memory and sessions
 
@@ -142,12 +142,15 @@ For each confirmed item, route the knowledge to the appropriate destination:
 | 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 |
+| Session context (structured record) | `docs/sessions/` | Create session file |
 | Operator preference | `.agents/operator-profile.md` | Direct edit |
-| Ephemeral context | Memory DB | `create_memory` tool |
+| Ephemeral context (import-only) | `.agents/memory/daily/<today>.md` | Append to daily log |
+| Ephemeral context (mirror) | Memory DB | `create_memory` tool (optional mirror) |
 
 Do not duplicate knowledge already present in the target. Read the target file before editing. Add knowledge in the most concise actionable form.
 
+**Boundary between `docs/sessions/` and `.agents/memory/daily/`:** `docs/sessions/` holds structured imported session records (from external tools). `.agents/memory/daily/` holds agent-written Context bullets (append-only, git-ignored). Use `docs/sessions/` for imported external sessions; use `.agents/memory/daily/` for ephemeral context bullets that the agent writes during this session.
+
 ### 7. Update knowledge files
 
 After the run:

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

@@ -1,24 +1,58 @@
 <!-- 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. -->
+<!-- knowledge-layer: L1 -->
+
 # Fix Patterns
 
-## Pattern A: Skip non-project sessions
+### K-0001: Skip non-project sessions
+
+```knowledge-entry
+id: K-0001
+layer: L1
+created: 2026-08-03
+status: active
+```
 
 **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
+### K-0002: Skip duplicate knowledge
+
+```knowledge-entry
+id: K-0002
+layer: L1
+created: 2026-08-03
+status: active
+```
 
 **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
+### K-0003: Import project convention
+
+```knowledge-entry
+id: K-0003
+layer: L1
+created: 2026-08-03
+status: active
+```
 
 **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
+### K-0004: Redact sensitive information
+
+```knowledge-entry
+id: K-0004
+layer: L1
+created: 2026-08-03
+status: active
+```
 
 **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-review/SKILL.md

@@ -230,10 +230,10 @@ Derive the `<module-folder>` from the reviewed files: take the package path with
 Write the report to:
 
 ```txt
-docs/reviews/code/<module-folder>/review-<YYYY-MM-DD>-<HH>-<module-folder>.md
+docs/reviews/code/<module-folder>/review-<YYYY-MM-DD>-<HH-mm>-<module-folder>.md
 ```
 
-For example: `docs/reviews/code/packages-growth/review-2026-07-10-19-packages-growth.md`.
+For example: `docs/reviews/code/packages-growth/review-2026-07-10-19-30-packages-growth.md`.
 
 Create any missing parent directories. The file must begin with a YAML frontmatter block:
 

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

@@ -43,7 +43,7 @@ Each discovered insight is categorized into exactly one of six types. The catego
 | **Invariant** | A cross-workspace architectural rule that warrants DNA status | `ref(forge.yaml bindings.paths.invariantsFile)` | Delegate to `fo-extract-dna` |
 | **Pattern** | A reusable code pattern or abstraction worth porting to forge | `packages/forge/` | Delegate to `fo-harvest` |
 | **Operator** | A preference, communication style, or behavioral insight about the operator | `.agents/operator-profile.md` | Direct edit by this skill |
-| **Context** | Session-local knowledge with no durable home | Memory DB | `create_memory` tool |
+| **Context** | Session-local knowledge with no durable home | `.agents/memory/daily/<today>.md` (default) or `MEMORY.md` (when durable); Memory DB optional mirror | Direct edit (daily log append) or curated edit (MEMORY.md); Memory DB via `create_memory` tool (optional mirror) |
 
 ### Category criteria
 
@@ -106,22 +106,26 @@ For each candidate, ask: "Would another agent working in this area benefit from
 
 ### 3. Categorize and present
 
+**Language requirement (NON-NEGOTIABLE):** The triage table, the `ask_user_question` confirmation prompt, and all inline commentary MUST be written in `PREFERENCES.md` `aiLanguage`. The English template below is structural only — translate ALL headings, column names, labels, and prose to `aiLanguage` before presenting. Only identifiers (file paths, skill names, RFC/ADR ids) stay untranslated. Example: if `aiLanguage` is `ru`, the heading is «Сортировка инсайтов сессии», column headers are «№ | Инсайт | Категория | Назначение | Действие».
+
 Present each insight with a proposed category and routing:
 
 ```
-## Session Insight Triage
+## <Triage heading in aiLanguage>
 
-| # | Insight | Category | Destination | Action |
+| # | <Insight> | <Category> | <Destination> | <Action> |
 | --- | --- | --- | --- | --- |
 | 1 | hydrateFromArtifacts is mandatory when steps write state | Rule | packages/AGENTS.md | Direct edit |
 | 2 | Model registry chosen over hardcoded clients | Decision | docs/adrs/ | Delegate to fo-idea-create-adr |
 | 3 | Gogol ID must not equal phase ID | Invariant | ref(forge.yaml bindings.paths.invariantsFile) | Delegate to fo-extract-dna |
 | 4 | Batch AI calls for large-context models | Pattern | packages/forge/ | Delegate to fo-harvest |
 | 5 | Operator prefers concise responses without code blocks | Operator | .agents/operator-profile.md | Direct edit |
-| 6 | Current pipeline state for mission X | Context | memory DB | create_memory |
+| 6 | Current pipeline state for mission X | Context | `.agents/memory/daily/` or `MEMORY.md` | Direct edit |
 ```
 
-Ask the operator to confirm, adjust categories, or drop items using `ask_user_question`. Do not proceed without explicit confirmation.
+Ask the operator to confirm, adjust categories, or drop items using `ask_user_question` — the question text MUST be in `aiLanguage`. Do not proceed without explicit confirmation.
+
+**Confirmation format (NON-NEGOTIABLE):** Use `allowMultiple: true` and present each insight as a separate option, with the option label matching the insight number from the triage table (e.g. option 1 = "1: <insight summary>"). This ensures the operator's response ("1, 2", "3", etc.) unambiguously refers to insight numbers, not to abstract option ordinals. Never use abstract options like "confirm all", "only rules", "only context" — these create a numbering mismatch between the table and the confirmation prompt.
 
 ### 4. Route each confirmed insight
 
@@ -133,7 +137,7 @@ For each rule insight:
 2. **Read** the target file before editing.
 3. **Add the rule** in a minimal, actionable form: "Always implement `hydrateFromArtifacts` when a step writes state fields. The engine skips `validateBeforeStart` and `run()` when artifacts are valid, so downstream steps receive empty state." Include a code reference if applicable.
 4. **Do not duplicate** rules already present in the target file. If the rule extends an existing section, append to it.
-5. **Do not create `.agents/rules/*.md`** — `.agents/**` is reference/historical only per root AGENTS.md. Rules live in `AGENTS.md` files.
+5. **Do not create `.agents/rules/*.md`** — `.agents/**` is reference/historical only per root AGENTS.md, except `.agents/memory/` (active context store), `.agents/skills/` (synced by forge), and `.agents/operator-profile.md` (written by this skill). Rules live in `AGENTS.md` files.
 
 #### 4b. Decision → ADR
 
@@ -203,9 +207,15 @@ Cumulative knowledge about the operator. This file is gitignored by default to p
 - [YYYY-MM-DD] <insight>
 ```
 
-#### 4f. Context → memory
+#### 4f. Context → memory layer
+
+For each context insight, choose the destination with the operator:
+
+1. **Daily log (default)** — append to `.agents/memory/daily/<today>.md` (create if absent). This is the ephemeral warm store — git-ignored, append-only. Format: `- [HH:MM] <insight>`. Redact API keys, passwords, and PII before appending.
+2. **MEMORY.md (when durable)** — if the insight is useful across sessions (not just today), append to `.agents/memory/MEMORY.md` under the most relevant section (`## Current focus`, `## Decisions in flight`, or `## Environment notes`). This is the curated hot store — versioned, so keep it concise.
+3. **Memory DB (optional mirror)** — use the `create_memory` tool to save the insight with appropriate tags. This is an optional mirror of the file-based layer, not the primary store.
 
-Use the `create_memory` tool to save the insight with appropriate tags. Use a descriptive title and include enough context for the next agent to understand why it matters.
+Both daily-log and MEMORY.md edits require operator confirmation. Files are the source of truth; Memory DB is a mirror.
 
 ### 5. Commit
 
@@ -232,7 +242,7 @@ If any operator insights were routed to `.agents/operator-profile.md`, offer the
 
 ### 7. Report
 
-Present a concise summary in `aiLanguage`. **Translate all labels, headings, and column names to `aiLanguage`** — the template below is structural only. Only identifiers (file paths, skill names, RFC/ADR ids) stay untranslated.
+Present a concise summary in `aiLanguage`. **ALL labels, headings, column names, and prose MUST be translated to `aiLanguage`** — the template below is structural only. Only identifiers (file paths, skill names, RFC/ADR ids, commit hashes) stay untranslated. This is non-negotiable: an English summary when `aiLanguage` is `ru` is a violation of this skill's language contract.
 
 ```
 ## <Session Retro Summary in aiLanguage>
@@ -247,7 +257,7 @@ Present a concise summary in `aiLanguage`. **Translate all labels, headings, and
 | 3 | ... | Invariant | fo-extract-dna | RFC-XXXX drafted |
 | 4 | ... | Pattern | fo-harvest | ported to forge |
 | 5 | ... | Operator | .agents/operator-profile.md | committed |
-| 6 | ... | Context | memory DB | saved |
+| 6 | ... | Context | `.agents/memory/` | saved |
 
 ### <Delegated skills invoked>: <count>
 ### <Direct edits>: <count>
@@ -266,7 +276,7 @@ Recommended session-end sequence: `fo-doc-audit` → `fo-session-retro` → `fo-
 ## Constraints
 
 - **Document-only.** This skill must not modify, create, or delete source code files. The only files it may directly edit are `AGENTS.md` files (for rule insights) and `.agents/operator-profile.md` (for operator insights, RFC-XXXX). All other routing is via delegation to skills that own their output.
-- **No `.agents/rules/` files.** Rules live in `AGENTS.md` files, which are loaded into every agent's system prompt. `.agents/**` is reference/historical only per root AGENTS.md.
+- **No `.agents/rules/` files.** Rules live in `AGENTS.md` files, which are loaded into every agent's system prompt. `.agents/**` is reference/historical only per root AGENTS.md, except `.agents/memory/` (active context store), `.agents/skills/` (synced by forge), and `.agents/operator-profile.md` (written by this skill).
 - **Delegation, not duplication.** For ADR, DNA, and pattern insights, delegate to the appropriate skill. Do not create ADRs, RFCs, or forge packages directly.
 - **Operator confirmation is mandatory.** Do not route any insight without explicit confirmation of category and destination.
 - **Minimal edits.** Add rules in the most concise actionable form. Do not rewrite existing sections.

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

@@ -8,7 +8,7 @@ dependsOn: ['my-preferences']
 languagePolicy: ref(PREFERENCES.md)
 knowledge: [qa-log.md, learned-principles.md, fix-patterns.md]
 bindings:
-  requires: [paths.sessionsDir]
+  requires: [paths.sessionsDir, commands.sessionSave]
   optional: []
 triggers: ["save this session", "enhance session transcript with annotations", "save session with quality checks"]
 ---
@@ -28,15 +28,14 @@ Enhance saved session transcripts with semantic annotations, summaries, and qual
 1. **Read `PREFERENCES.md`** at the repository root. If `saveSessions: false`, exit immediately with "Session saving disabled by operator preference."
 
 2. **Check for raw files** in `docs/sessions/.raw/`. If raw files exist, run `session.save` first to convert them to structured markdown:
-   <!-- skill-lint-disable SKILL-11 -->
 
    ```
-   pnpm exec site-kernel run session.save --json
+   ref(forge.yaml bindings.commands.sessionSave)
    ```
 
 3. **Read the most recently saved session file** from `docs/sessions/`. If no session files exist, exit with "No session files to annotate."
 
-4. **Read knowledge files** (`qa-log.md`, `learned-principles.md`, `fix-patterns.md`) for accumulated knowledge from previous sessions.
+4. **Read knowledge files** (`qa-log.md`, `learned-principles.md`, `fix-patterns.md`) for accumulated knowledge from previous sessions. Apply only entries with `status: active`; skip entries with `status: stale`, `superseded`, or `archived`.
 
 5. **Analyze the transcript semantically:**
    - Generate a 1-3 sentence `summary` of the session's purpose and outcome.

package/skills/fo/fo-session-save/fix-patterns.md

@@ -1,33 +1,57 @@
+<!-- knowledge-layer: L1 -->
+
 # Fix Patterns
 
 Patterns of errors in auto-extracted metadata (by `session.save`) and their fixes (applied by `fo-session-save` skill). Each pattern helps the skill recognize and correct common extraction mistakes.
 
-## Format
-
-Each entry: pattern name, symptom, root cause, fix.
-
----
-
-1. **False-positive RFC-id in comments**
-
-   - **Symptom:** `relatedRfcs` contains an RFC-id that doesn't exist.
-   - **Root cause:** Regex `RFC-\d{4}` matches references in code comments, URLs, or quoted text that aren't actual related RFCs.
-   - **Fix:** Verify each RFC-id exists in `docs/rfcs/` before keeping it in `relatedRfcs`. Remove non-existent ones.
-
-2. **Commit hash matching version numbers**
-
-   - **Symptom:** `commits` array contains strings like `1.0.0` or `12345678`.
-   - **Root cause:** Regex `\b[0-9a-f]{7,40}\b` matches version strings and short numeric sequences.
-   - **Fix:** Filter out strings that look like version numbers (contain dots) or are pure decimal numbers. Verify remaining hashes correspond to actual git commits.
-
-3. **File paths from error messages**
-
-   - **Symptom:** `files` array contains paths from error messages or stack traces that weren't actually edited.
-   - **Root cause:** Regex matches any path starting with `packages/`, `docs/`, etc., including paths in error output.
-   - **Fix:** Cross-reference with `commits` and actual git diff to identify files that were genuinely modified during the session.
-
-4. **Missing session type**
-
-   - **Symptom:** Auto-detected `types` is `["freeform"]` but the session clearly involved implementation or review.
-   - **Root cause:** The type detection patterns didn't match the specific phrasing used in the session.
-   - **Fix:** Semantically analyze the transcript and override `types` with the correct classification.
+### K-0001: False-positive RFC-id in comments
+
+```knowledge-entry
+id: K-0001
+layer: L1
+created: 2026-08-03
+status: active
+```
+
+- **Symptom:** `relatedRfcs` contains an RFC-id that doesn't exist.
+- **Root cause:** Regex `RFC-\d{4}` matches references in code comments, URLs, or quoted text that aren't actual related RFCs.
+- **Fix:** Verify each RFC-id exists in `docs/rfcs/` before keeping it in `relatedRfcs`. Remove non-existent ones.
+
+### K-0002: Commit hash matching version numbers
+
+```knowledge-entry
+id: K-0002
+layer: L1
+created: 2026-08-03
+status: active
+```
+
+- **Symptom:** `commits` array contains strings like `1.0.0` or `12345678`.
+- **Root cause:** Regex `\b[0-9a-f]{7,40}\b` matches version strings and short numeric sequences.
+- **Fix:** Filter out strings that look like version numbers (contain dots) or are pure decimal numbers. Verify remaining hashes correspond to actual git commits.
+
+### K-0003: File paths from error messages
+
+```knowledge-entry
+id: K-0003
+layer: L1
+created: 2026-08-03
+status: active
+```
+
+- **Symptom:** `files` array contains paths from error messages or stack traces that weren't actually edited.
+- **Root cause:** Regex matches any path starting with `packages/`, `docs/`, etc., including paths in error output.
+- **Fix:** Cross-reference with `commits` and actual git diff to identify files that were genuinely modified during the session.
+
+### K-0004: Missing session type
+
+```knowledge-entry
+id: K-0004
+layer: L1
+created: 2026-08-03
+status: active
+```
+
+- **Symptom:** Auto-detected `types` is `["freeform"]` but the session clearly involved implementation or review.
+- **Root cause:** The type detection patterns didn't match the specific phrasing used in the session.
+- **Fix:** Semantically analyze the transcript and override `types` with the correct classification.

package/skills/fo/fo-session-save/learned-principles.md

@@ -1,19 +1,70 @@
+<!-- knowledge-layer: L2 -->
+
 # Learned Principles
 
 Principles learned across sessions by the `fo-session-save` skill. These are accumulated observations about session transcript quality, metadata extraction accuracy, and annotation patterns.
 
-## Format
+### K-0001: Always verify RFC-id exists before listing as related
+
+```knowledge-entry
+id: K-0001
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
+
+The `session.save` command extracts RFC-ids via regex (`RFC-\d{4}`), which can match references in comments, URLs, or quoted text. Before confirming a `relatedRfcs` entry, check that the RFC file exists in `docs/rfcs/`.
+
+### K-0002: Commit hash regex matches version numbers — filter by context
+
+```knowledge-entry
+id: K-0002
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
+
+The regex `\b[0-9a-f]{7,40}\b` can match version strings like `1.0.0`. The `session.save` handler filters pure numeric strings ≤ 8 chars, but the skill should also verify that extracted hashes correspond to actual git commits in the session's work.
+
+### K-0003: Session types are not mutually exclusive
+
+```knowledge-entry
+id: K-0003
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
 
-Each principle: a concise statement, optionally with a rationale.
+A single session can involve grilling followed by implementation. The `types` array should reflect all major activities, not just the dominant one.
 
----
+### K-0004: The `## Transcript` section is deterministic output
 
-1. **Always verify RFC-id exists before listing as related.** The `session.save` command extracts RFC-ids via regex (`RFC-\d{4}`), which can match references in comments, URLs, or quoted text. Before confirming a `relatedRfcs` entry, check that the RFC file exists in `docs/rfcs/`.
+```knowledge-entry
+id: K-0004
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
 
-2. **Commit hash regex matches version numbers — filter by context.** The regex `\b[0-9a-f]{7,40}\b` can match version strings like `1.0.0`. The `session.save` handler filters pure numeric strings ≤ 8 chars, but the skill should also verify that extracted hashes correspond to actual git commits in the session's work.
+Never modify it. Only add `## Session notes` and update frontmatter.
 
-3. **Session types are not mutually exclusive.** A single session can involve grilling followed by implementation. The `types` array should reflect all major activities, not just the dominant one.
+### K-0005: Redact sensitive information before saving
 
-4. **The `## Transcript` section is deterministic output.** Never modify it. Only add `## Session notes` and update frontmatter.
+```knowledge-entry
+id: K-0005
+layer: L2
+created: 2026-08-03
+lastConfirmedAt: 2026-08-03
+confirmations: 1
+status: active
+```
 
-5. **Redact sensitive information before saving.** API keys, passwords, PII must be removed from the transcript. Same redaction pattern as `fo-handoff`.
+API keys, passwords, PII must be removed from the transcript. Same redaction pattern as `fo-handoff`.

package/skills/fo/fo-step-commit/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: fo-step-commit
+description: >-
+  Commit agent file changes after each operator request. Stages only files the
+  agent changed, in both monorepo and mission workpiece. Callable by other skills
+  for intermediate commits.
+invocation: model
+category: fo
+concerns: code-mutation
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+triggers:
+  - "commit after request"
+  - "auto-commit changes"
+  - "step commit"
+---
+
+# Step Commit
+
+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.
+
+Commit file changes after every standalone operator request that produces file changes. This skill runs autonomously — the agent invokes it before sending its response to the operator, without explicit instruction.
+
+## When this skill runs
+
+- **After every standalone operator request** (default behavior): the agent runs this skill before sending its response to the operator, if any files were changed during the request. "Standalone" means the operator's message is not part of a skill pipeline (e.g. not inside another multi-step skill).
+- **Called by other skills**: other skills MAY invoke this skill for intermediate commits during multi-step pipelines. During pipeline execution, only the parent skill's explicit invocations fire — the default "after every request" behavior is suppressed to avoid conflicting with the pipeline's own commit discipline.
+
+## Behavior
+
+After every standalone operator request that produces file changes, perform the following:
+
+1. **Detect changed files.** Run `git status --short` in the monorepo root. If the working tree is clean (no modifications), skip — no commit.
+2. **Verify diff before staging.** Run `git diff` (not just `git diff --cached`) on every file the agent touched in this request. Confirm the changes are the agent's own work and not foreign changes from another session. If foreign changes are found, exclude them from staging.
+3. **Stage only agent-changed files.** Stage only the files the agent modified in this request. Never use `git add -A` or `git add .` — another agent or session may have unrelated changes in the working tree. Stage files by explicit path: `git add <path1> <path2> ...`.
+4. **Form commit message.** Write a conventional commit message (`fix:`, `feat:`, `refactor:`, `docs:`, `chore:`) based on the work performed in this request. The agent determines the type and description from the context of the request.
+5. **Commit in monorepo.** `git commit -m "<message>"` with the staged files.
+6. **Commit in mission workpiece (if applicable).** If the agent changed files in the active mission workpiece, commit there via the kernel's mission git commit command with the same message.
+
+## What this skill does NOT do
+
+- Does not push to remotes (commits are local).
+- Does not run `git status` after commit or report to the operator.
+- Does not create empty commits (no changes = no commit).
+- Does not stage files the agent did not change in this request.
+
+## Opt-out
+
+The operator can skip the auto-commit for a specific request by saying "не коммить", "don't commit", or similar. The skill MUST respect explicit operator instructions to skip committing.
+
+## Failure modes
+
+- **No changes**: skill detects clean working tree and skips — no error, no commit.
+- **Workpiece not found**: if no active mission workpiece exists, skip workpiece commit. Monorepo commit still proceeds.
+- **Workpiece commit fails**: if the workpiece commit fails (e.g. dirty tree from another agent), the skill does not block the monorepo commit. The agent reports the failure to the operator.