@warpgogol/forge 0.4.0 → 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

@@ -35,7 +35,7 @@ Enhance saved session transcripts with semantic annotations, summaries, and qual
 
 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/meta/forge-bootstrap/SKILL.md

@@ -39,6 +39,7 @@ Interactive skill for configuring a freshly created forge project. Runs after `f
 - The skill never collects personal data as a separate interview before the first creation moment — personal data emerges naturally from the creative dialogue.
 - `operator-profile.md` is local and private — it is in `.gitignore` and is not committed to the repository. The operator can delete it at any time.
 - Gender is optional — the operator may decline to provide it. If declined, the skill uses gender-neutral addressing and notes the absence in `operator-profile.md`.
+- Form of address defaults to formal if the operator skips the question.
 - The skill never informs the operator about migration, version numbers, or upgrade mechanics — the silent version check in step 0 is invisible to the operator.
 - The skill never asks the operator for permission to migrate — if versions differ, migration runs automatically.
 
@@ -83,7 +84,7 @@ Accept the operator's choice and store it:
 
 The register controls whether the extended behavioral layer is included in `AGENTS.md`. Both registers receive the full core behavioral layer. The operator can change the register at any time via live operator feedback.
 
-### 3. Operator name and gender (new)
+### 3. Operator name, gender, and form of address (new)
 
 Ask the operator:
 
@@ -95,7 +96,18 @@ Then ask:
 
 If the operator declines to provide gender, use gender-neutral addressing and note the absence in `operator-profile.md` under `## Personal`.
 
-Store the operator's name and gender (or absence) in `operator-profile.md` under `## Personal`. These are the only personal data collected before the first creation moment.
+Then ask about the form of address:
+
+> Do you prefer informal or formal address? In some languages this means saying "you" in a familiar way (e.g. "ty" in Russian/Ukrainian, "du" in German) versus a more formal way (e.g. "vy" in Russian/Ukrainian, "Sie" in German). If you're not sure, formal is the safe default.
+
+Accept the operator's choice and store it:
+
+- In `PREFERENCES.md` as `formOfAddress: formal` or `formOfAddress: informal`.
+- In `operator-profile.md` under `## Register`.
+
+If the operator skips the question, default to `formOfAddress: formal`. The preference applies to all agent-generated text: chat messages, reports, suggestions, and skill output. The operator can change it at any time by editing `PREFERENCES.md`.
+
+Store the operator's name, gender (or absence), and form of address in `operator-profile.md` under `## Personal` and `## Register`. These are the only personal data collected before the first creation moment.
 
 ### 4. Verify forge project
 
@@ -161,7 +173,7 @@ The transplant mode performs real code migration via a migration-adapter registr
 
 6.7. **Build verification and error repair** — after post-setup, verify the transplanted project builds successfully:
 
-1.  Resolve the build command via `ref(forge.yaml bindings.commands.scopedBuild)`. If the binding is null (the migration adapter could not derive a build command from the source project), skip build verification with a note in the welcoming report and continue to the next step.
+1.  Resolve the build command via `ref(forge.yaml bindings.commands.produce)`. If the binding is null (the migration adapter could not derive a build command from the source project), skip build verification with a note in the welcoming report and continue to the next step.
 2.  Run the resolved build command and capture stdout/stderr. Set a timeout of 300 seconds (configurable); if the build does not complete in time, report the timeout in human language and continue.
 3.  Parse build output for:
     - Missing modules (TS2307: Cannot find module 'X')
@@ -339,7 +351,7 @@ The skill declares the following knowledge files in its `knowledge` frontmatter
 
 ### 14. Privacy
 
-`operator-profile.md` contains personal data: operator name, gender, project story, deep purpose, creative influences, target audience, writing voice. Gender is special category data under GDPR Article 9. To prevent accidental exposure:
+`operator-profile.md` contains personal data: operator name, gender, form of address, project story, deep purpose, creative influences, target audience, writing voice. Gender is special category data under GDPR Article 9. To prevent accidental exposure:
 
 - `operator-profile.md` is in `.gitignore` (added by scaffold profiles).
 - The skill informs the operator that `operator-profile.md` is local and private — it is not committed to the repository.

package/skills/meta/forge-bootstrap/operator-profile-template.md

@@ -15,6 +15,7 @@ This file is private and local to your project. It is not committed to the repos
 ## Register
 
 - **Communication register:** (business | creative — how you prefer the system to work with you)
+- **Form of address:** (formal | informal — how the system should address you in languages with a formal/informal distinction)
 
 ## Communication style
 

package/skills/meta/skill-create/SKILL.md

@@ -46,7 +46,7 @@ Before creating knowledge files, the agent analyzes the skill's knowledge domain
 
 3. **Which layers are needed?** Not every skill needs all three. `grilling` uses L0+L2 only. A site-scanning skill with all three layers is a good example. A skill with purely reactive error resolution may use L1+L2 only (no Q&A log).
 
-Present the analysis to the operator. If they confirm, create the knowledge files with header comments matching the chosen structure and add `knowledge:` to the frontmatter. See `writing-great-skills` § Cumulative knowledge pattern for the three-layer reference pattern and mutation contract.
+Present the analysis to the operator. If they confirm, create the knowledge files with header comments matching the chosen structure and add `knowledge:` to the frontmatter. See `writing-great-skills` § Cumulative knowledge pattern for the three-layer reference pattern, entry format, and mutation contract.
 
 ### 2. Scaffold
 

package/skills/shared/grilling/SKILL.md

@@ -13,7 +13,7 @@ knowledge:
 
 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.
 
-Read `learned-principles.md` (L2) at the start of each session to improve recommended answers. Principles with `confirmations >= 3` may be applied autonomously — but re-evaluate if context changes.
+Read `learned-principles.md` (L2) at the start of each session to improve recommended answers. Apply only entries with `status: active`; skip entries with `status: stale`, `superseded`, or `archived`. Principles with `confirmations >= 3` may be applied autonomously — but re-evaluate if context changes.
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.