@warpgogol/forge 0.3.1

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

@@ -0,0 +1,276 @@
+---
+name: fo-session-retro
+description: Session-end insight triage — review what was discovered, categorize each insight, and route it to the right durable home (AGENTS.md rule, ADR, DNA invariant, forge pattern, or memory).
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: []
+  optional: [paths.invariantsFile]
+triggers: ["session retrospective", "capture insights from this session", "triage session discoveries"]
+---
+
+# Session Retro
+
+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.
+
+Review the current session for discoveries that other agents would benefit from knowing. Categorize each insight and route it to the appropriate durable home. This skill is the **knowledge capture entry point** — it does not duplicate the work of `fo-extract-dna`, `fo-harvest`, or `fo-idea-create-adr`; it triages and delegates.
+
+## When to invoke
+
+- **At session end** — after completing work, before closing the conversation. The operator runs `/fo-session-retro` to check if any insights emerged that deserve to outlive the session.
+- **After a debugging session** — when root-cause analysis revealed non-obvious behavior that others would rediscover.
+- **After exploring a new area** — when conventions or patterns were learned that are not yet documented.
+- **Inline by other skills** — `fo-doc-audit` or session-end workflows may delegate here for the "what did you learn?" step.
+
+## What this skill is NOT
+
+- It is not `fo-doc-audit` — that skill checks whether existing docs are in sync with code changes. This skill captures **new knowledge** that does not yet exist in any doc.
+- It is not `fo-harvest` — that skill scans for portable code patterns. This skill handles all insight types, including non-code knowledge.
+- It is not `fo-extract-dna` — that skill formalizes architectural invariants through RFCs. This skill may **delegate** to it when an insight is DNA-grade.
+- It is not a memory dump — memory DB is one of five routing targets, not the default. Most insights belong in version-controlled files, not ephemeral memory.
+
+## Insight categories and routing
+
+Each discovered insight is categorized into exactly one of six types. The category determines where the knowledge lives and how it reaches other agents.
+
+| Category | What it is | Destination | Mechanism |
+| --- | --- | --- | --- |
+| **Rule** | A convention or behavioral expectation that agents must follow | Nearest applicable `AGENTS.md` | Direct edit by this skill |
+| **Decision** | An architectural choice with rationale that should be preserved | `docs/adrs/` | Delegate to `fo-idea-create-adr` |
+| **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 |
+
+### Category criteria
+
+**Rule** — the insight is:
+
+- A convention agents should follow (not a one-off observation).
+- Actionable: "always do X" or "never do Y", not "we learned that...".
+- Not architectural enough for DNA (local to one workspace, or not enforceable by a command).
+- Already followed in practice but not written down.
+
+**Decision** — the insight is:
+
+- A choice between alternatives with a clear rationale.
+- Architectural in nature (package boundaries, technology selection, pattern adoption).
+- Not a cross-workspace invariant — it is a point-in-time decision that future changes may revisit.
+
+**Invariant** — the insight is:
+
+- Cross-workspace (applies to multiple apps/packages, not just one).
+- Stable (not temporary or migration-period).
+- Enforceable (a command could verify it, or it is documentation-only but permanent).
+- Not already recorded in `ref(forge.yaml bindings.paths.invariantsFile)`.
+
+**Pattern** — the insight is:
+
+- A code abstraction, utility, or convention that appears in 2+ places.
+- Genuinely portable (not project-specific).
+- Worth extracting into `packages/forge/` for reuse across projects.
+
+**Context** — the insight is:
+
+- Session-local: relevant to the current task or current state, not a durable rule.
+- Not worth a version-controlled file (too specific, too ephemeral).
+- Useful for the next agent picking up this work area.
+
+**Operator** — the insight is:
+
+- About the operator's preferences, communication style, or working rhythm (not about code or architecture).
+- Cumulative: builds a profile over time that helps the agent calibrate behavior.
+- Not a rule for all agents — it is specific to this operator.
+- Examples: "prefers concise responses", "works best in morning sessions", "dislikes long explanations", "responds well to visual summaries".
+
+## Process
+
+### 1. Read preferences and shared conventions
+
+Read `PREFERENCES.md` at the repository root. Use `aiLanguage` for all communication.
+
+Read `_shared/fo-pipeline-conventions.md` for commit discipline, language policy, and recoverable error handling.
+
+### 2. Gather session insights
+
+Review the current session to identify discoveries. Use in priority order:
+
+1. **Explicit operator input** — if the operator described what they learned, use that.
+2. **Session conversation** — scan for debugging discoveries, non-obvious behaviors, convention realizations, and "we always do X" moments.
+3. **Git diff** — run `git diff HEAD` and `git log --oneline -10` to see what changed; changes may reveal patterns worth recording.
+
+For each candidate, ask: "Would another agent working in this area benefit from knowing this?" If no, drop it. If yes, proceed to categorization.
+
+### 3. Categorize and present
+
+Present each insight with a proposed category and routing:
+
+```
+## Session Insight Triage
+
+| # | 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 |
+```
+
+Ask the operator to confirm, adjust categories, or drop items using `ask_user_question`. Do not proceed without explicit confirmation.
+
+### 4. Route each confirmed insight
+
+#### 4a. Rule → AGENTS.md
+
+For each rule insight:
+
+1. **Identify the nearest applicable `AGENTS.md`** — root, `packages/AGENTS.md`, `services/AGENTS.md`, `docs/authoring/site-composition.md`, or a workspace-specific `AGENTS.md`. Use the same hierarchy rules as `fo-doc-audit` step 2a.
+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.
+
+#### 4b. Decision → ADR
+
+Invoke `fo-idea-create-adr` via the `skill` tool with the decision title and rationale gathered from the session. Let it run fully — it will grill, create the file, and validate.
+
+#### 4c. Invariant → DNA
+
+Invoke `fo-extract-dna` via the `skill` tool in convention description mode. Provide the invariant formulation from the session. Let it run fully — it will grill, create the RFC, and report.
+
+#### 4d. Pattern → forge
+
+Invoke `fo-harvest` via the `skill` tool with the pattern description. Let it run fully — it will grill on portability and port if accepted.
+
+#### 4e. Operator → operator-profile.md
+
+For each operator insight:
+
+1. **Read `.agents/operator-profile.md`** if it exists. If it does not exist, create it from the template below.
+2. **Determine the target section** based on the insight type:
+   - Communication preferences → `## Communication style`
+   - Working rhythm / session patterns → `## Working rhythm`
+   - Feedback / corrections → `## Feedback history`
+   - Emotional state / mood patterns → `## Emotional rhythm`
+   - Aesthetic preferences / creative influences → `## Aesthetic preferences`
+   - General preferences → `## Preferences`
+3. **Add the entry** in a concise form with a date stamp: `- [YYYY-MM-DD] <insight>`.
+4. **Entry expiry:** Entries in `## Emotional rhythm` and `## Feedback history` expire after 90 days unless refreshed. When adding a new entry, check existing entries in these sections:
+   - If an entry is older than 90 days and has not been refreshed, mark it as `[expired YYYY-MM-DD]` (where the date is the expiry date, not today).
+   - An entry is "refreshed" if the same insight is re-confirmed in a later session (update the date stamp).
+   - Do not delete expired entries — they remain as historical context but are marked expired.
+5. **Zugangsstufen tagging:** Each section must be tagged with an access level:
+   - `[Öffentlich]` — visible to co-creators and in developer handoffs.
+   - `[Vertraulich]` — private to the operator and the agent; NOT included in developer handoff summaries.
+   - `## Emotional rhythm` and `## Feedback history` are always `[Vertraulich]`.
+   - `## Communication style`, `## Working rhythm`, `## Aesthetic preferences`, and `## Preferences` are `[Öffentlich]` by default.
+6. **Do not include operator-profile.md contents in developer handoff summaries.** Only technical architecture, decisions, and code structure belong in handoffs.
+
+**operator-profile.md template:**
+
+```markdown
+# Operator Profile
+
+Cumulative knowledge about the operator. This file is gitignored by default to protect privacy.
+
+## Communication style [Öffentlich]
+
+- [YYYY-MM-DD] <insight>
+
+## Working rhythm [Öffentlich]
+
+- [YYYY-MM-DD] <insight>
+
+## Preferences [Öffentlich]
+
+- [YYYY-MM-DD] <insight>
+
+## Aesthetic preferences [Öffentlich]
+
+- [YYYY-MM-DD] <insight>
+
+## Feedback history [Vertraulich]
+
+- [YYYY-MM-DD] <insight>
+
+## Emotional rhythm [Vertraulich]
+
+- [YYYY-MM-DD] <insight>
+```
+
+#### 4f. Context → memory
+
+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.
+
+### 5. Commit
+
+Commit rule edits to `AGENTS.md` files separately from any delegated skill output (ADRs, RFCs, forge ports — those skills commit their own files).
+
+```txt
+docs: add <rule description> to <AGENTS.md path>
+
+Session retro: captured <N> rule(s) from session insights.
+```
+
+Stage only the `AGENTS.md` files this skill edited. Do not stage unrelated changes. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+
+If no rule insights were confirmed (all were delegated or context), skip this step — the delegated skills handle their own commits.
+
+### 6. Profile review
+
+If any operator insights were routed to `.agents/operator-profile.md`, offer the operator a profile review:
+
+1. **Show the current profile** (or the relevant sections that changed).
+2. **Ask:** "Would you like to review or adjust any of these entries?"
+3. **Apply adjustments** if the operator requests changes.
+4. **Remind the operator** that they can delete `.agents/operator-profile.md` at any time — it is their personal knowledge file.
+
+### 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.
+
+```
+## <Session Retro Summary in aiLanguage>
+
+### <Insights discovered>: <N>
+### <Insights confirmed>: <M>
+
+| # | <Insight> | <Category> | <Routed to> | <Status> |
+| --- | --- | --- | --- | --- |
+| 1 | ... | Rule | packages/AGENTS.md | committed |
+| 2 | ... | Decision | fo-idea-create-adr | ADR-XXXX created |
+| 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 |
+
+### <Delegated skills invoked>: <count>
+### <Direct edits>: <count>
+### <Commit>: <hash | none — no direct edits>
+```
+
+## Relationship to other session-end skills
+
+| Skill | Question | Overlap |
+| --- | --- | --- |
+| `fo-doc-audit` | "Are existing docs accurate?" | Complementary — checks accuracy of existing docs. `fo-session-retro` captures new knowledge. Run `fo-doc-audit` first, then `fo-session-retro`. |
+| `fo-handoff` | "What does the next agent need?" | Complementary — writes a handoff doc for continuity. `fo-session-retro` captures durable knowledge. A handoff doc may reference insights captured by `fo-session-retro`. |
+
+Recommended session-end sequence: `fo-doc-audit` → `fo-session-retro` → `fo-handoff`.
+
+## 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.
+- **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.
+- **Read before edit.** Always read the target `AGENTS.md` before editing to preserve structure and avoid duplicates.
+- **Commit only your own files.** Stage only `AGENTS.md` files this skill edited. Delegated skills commit their own output. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **No pauses for recoverable tool errors.** See `_shared/fo-pipeline-conventions.md` §Recoverable errors.
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.

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

@@ -0,0 +1,71 @@
+---
+name: fo-session-save
+description: Enhance saved session transcripts with semantic annotations, summaries, and quality checks. Self-learning via knowledge files.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+knowledge: [qa-log.md, learned-principles.md, fix-patterns.md]
+bindings:
+  requires: [paths.sessionsDir]
+  optional: []
+triggers: ["save this session", "enhance session transcript with annotations", "save session with quality checks"]
+---
+
+# fo-session-save
+
+Enhance saved session transcripts with semantic annotations, summaries, and quality checks. Self-learning via knowledge files.
+
+## When to use
+
+- At the end of a coding session, after `session.save` has converted raw ATIF files to structured markdown.
+- When the operator asks to "save this session" or "annotate the session transcript".
+- NOT for session-end insight triage — use `fo-session-retro` for that.
+
+## Process
+
+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
+   ```
+
+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.
+
+5. **Analyze the transcript semantically:**
+   - Generate a 1-3 sentence `summary` of the session's purpose and outcome.
+   - Identify key `decisions` made during the session (not just commands mentioned).
+   - Identify `relatedArtifacts` — RFCs, ADRs, files, commits that are semantically related.
+   - Refine auto-detected `types` — override or extend based on semantic understanding.
+   - Verify auto-extracted metadata is accurate; flag and fix false positives.
+
+6. **Update the session file:**
+   - Update frontmatter: `summary`, `decisions`, refined `types`, corrected metadata.
+   - Append a `## Session notes` section with structured annotations.
+
+7. **Update knowledge files** with any new insights:
+   - `qa-log.md`: Log any questions asked and operator answers.
+   - `learned-principles.md`: New principles learned across sessions.
+   - `fix-patterns.md`: Patterns of errors in auto-extraction and their fixes.
+
+8. **Report** what was annotated/changed.
+
+## Autonomy
+
+- Do NOT ask the operator questions unless you encounter a genuine ambiguity you cannot resolve.
+- Read `PREFERENCES.md` at start and no-op if `saveSessions: false`.
+- Read knowledge files for accumulated knowledge before processing.
+- Write to knowledge files after processing (self-learning).
+
+## Constraints
+
+- **Redact sensitive information**: Remove API keys, passwords, PII from the transcript before saving. Same redaction pattern as `fo-handoff`.
+- **Do not modify the `## Transcript` section** — that is the deterministic output of `session.save`. Only add/modify `## Session notes` and frontmatter.
+- **Do not delete session files** — archiving is handled by `session.archive`.
+- **Verify RFC-ids exist** before listing them in `relatedRfcs` (learned-principles: "always verify RFC-id exists before listing as related").

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

@@ -0,0 +1,33 @@
+# 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.

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

@@ -0,0 +1,19 @@
+# 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
+
+Each principle: a concise statement, optionally with a rationale.
+
+---
+
+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/`.
+
+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.
+
+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.
+
+4. **The `## Transcript` section is deterministic output.** Never modify it. Only add `## Session notes` and update frontmatter.
+
+5. **Redact sensitive information before saving.** API keys, passwords, PII must be removed from the transcript. Same redaction pattern as `fo-handoff`.

package/skills/fo/fo-session-save/qa-log.md

@@ -0,0 +1,11 @@
+# Q&A Log
+
+This file logs questions the `fo-session-save` skill asked (if any) and operator answers, for meta-analysis and self-learning.
+
+## Format
+
+Each entry: date, question, answer, context.
+
+---
+
+*(no questions asked yet — initial creation)*

package/skills/fo/fo-spec-ingest/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: fo-spec-ingest
+description: Ingest an external specification package into docs/specs/ or author a spec skeleton from fo-idea escalation. Builds forge-spec.yaml, validates, grills the spec delta, and obtains operator acceptance.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'grilling']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: [commands.specValidate]
+  optional: [paths.invariantsFile]
+triggers: ["ingest external specification", "vendor spec package into docs", "author spec skeleton"]
+---
+
+# Spec Ingest
+
+Before starting, read `PREFERENCES.md` at the repository root. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+> **This is a document-only skill.** It produces files under `docs/specs/<id>/` — snapshot, `forge-spec.yaml`, `integrity.yaml`, and `amendments/`. It must never modify source code in `apps/`, `packages/`, `services/`, or any other directory.
+
+## Two modes
+
+### Ingest mode
+
+Invoked as `/fo-spec-ingest <path-to-package>` when the operator has an external specification package (e.g. a consultant deliverable, an Obsidian vault export).
+
+### Authoring mode
+
+Invoked inline by `fo-idea` when decomposition yields more than 7 atomic decisions with at least one dependency edge. The skeleton is built from `fo-idea`'s decomposition + grilling output instead of an external package.
+
+## Process (ingest mode)
+
+### 1. Locate and inventory the package
+
+List all files in the package directory. Identify candidate roles by filename and headings:
+
+- **Spec / overview** — README, index, overview
+- **Entity model** — files with "entity", "model", "schema", "field" in name or headings
+- **Roadmap** — files with "roadmap", "plan", "wave", "stage", "phase" in name or headings
+- **Decision log** — files with "decision", "adr", "architecture" in name or headings
+
+Facts are looked up from the files. Only ambiguous role mappings become operator questions — one at a time, recommended answer first.
+
+### 2. Choose spec-id
+
+Propose a kebab-case `spec-id` from the package title. Ask the operator to confirm.
+
+### 3. Vendor the snapshot
+
+Copy files byte-exact into `docs/specs/<id>/`. Generate `integrity.yaml` with SHA-256 hashes for every snapshot file (excluding `forge-spec.yaml`, `integrity.yaml`, and `amendments/**`). Create an empty `amendments/` directory.
+
+### 4. Build forge-spec.yaml
+
+Extract from the package documents:
+
+- `documents` — logical name → relative path mapping
+- `decisions[]` — id, title, status, rationale (from the decision log)
+- `rfcs[]` — id, title, dependsOn, wave, sources (from the roadmap)
+- `waves[]` — id, name, goal
+
+Where the package predefines an RFC granularity that mismatches repository practice, you MAY merge nodes — but MUST respect any explicit "do not combine" constraints in the package, and MUST record every merge as a mapping note in the node's title suffix `(merges <id>, <id>)`.
+
+### 5. Validate
+
+Run `ref(forge.yaml bindings.commands.specValidate) --spec=<id>`. Fix projection errors until clean. **Never touch snapshot files** — if the package itself is inconsistent (e.g. a real dependency cycle), record the finding and ask the operator.
+
+### 6. Spec-level grilling
+
+Invoke `/grilling` to stress-test the spec delta against the project:
+
+- Conflicts with the invariants file (`ref(forge.yaml bindings.paths.invariantsFile)`)
+- Forward-only violations
+- Storage policy conflicts
+- Naming collisions
+- Unrealistic dependencies
+
+If `ref(forge.yaml bindings.paths.invariantsFile)` is `null` or the file is absent, skip the DNA-alignment part and report `Degraded: invariantsFile not configured — DNA alignment skipped`.
+
+Findings that require spec changes are recorded as **pre-acceptance amendments** in `amendments/` (RFC-XXXX format). The snapshot stays immutable even before acceptance.
+
+### 7. Acceptance decision
+
+Present a compact summary in `aiLanguage`. **Translate all labels, headings, and column names to `aiLanguage`** — the template below is structural only.
+
+```
+## <Spec Ingest Summary in aiLanguage>
+
+### Spec: <id> (<title>)
+### Snapshot: <N> files vendored, integrity manifest written
+### Projection: <N> decisions, <N> roadmap nodes, <N> waves
+### spec.validate: pass
+### Spec-level grilling: <N> findings, <N> pre-acceptance amendments
+### Degraded: <none | list of skipped capabilities>
+### Acceptance: accepted by human:<handle> | declined (status: vendored)
+### Next step: /fo-spec-materialize <id>
+```
+
+Ask the operator to accept or decline.
+
+- **On acceptance**: set `status: accepted`, `reviewers: [human:<handle>]` in `forge-spec.yaml`.
+- **On decline**: leave `status: vendored` and stop.
+
+### 8. Commit
+
+Commit with message `spec: ingest <id> …` staging only `docs/specs/<id>/**`.
+
+### 9. Report
+
+Present the summary above as the final report.
+
+## Process (authoring mode)
+
+Steps 2, 4–9 with the skeleton built from `fo-idea`'s decomposition + grilling output instead of an external package. `documents` may be empty. Set `sourceNote: "authored in-repo via fo-idea escalation"`.
+
+## Failure modes
+
+- Package path unreadable or empty: stop before touching `docs/specs/`.
+- `spec-id` already exists in `docs/specs/`: stop; re-vendoring is RFC-XXXX's `@N+1` path.
+- `spec.validate` cannot pass by projection fixes alone: record the finding, ask the operator — amend at ingest or abort.
+- Operator declines acceptance: spec stays `vendored`; materialization refuses non-accepted specs.
+
+## MUST NOT
+
+- MUST NOT set `status: accepted` without an explicit operator acceptance in the session.
+- MUST NOT modify snapshot files during ingest, including "obvious typo fixes" — pre-acceptance amendments are the only correction channel.
+- MUST NOT ask mapping questions about anything derivable from the package files.
+- MUST NOT record node merges silently — every merge must be noted in the node's title.

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

@@ -0,0 +1,97 @@
+---
+name: fo-triage
+description: Move issues and external PRs through a triage state machine — categorize, verify, grill, write agent-ready briefs. Use for incoming bug reports and feature requests.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'grilling']
+languagePolicy: ref(PREFERENCES.md)
+triggers: ["triage this issue", "categorize incoming bug report", "triage external pull request", "process feature request"]
+---
+
+# fo-triage
+
+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.
+
+Move incoming issues and external PRs through a triage state machine. For each issue: categorize, verify, grill if needed, and write an agent-ready brief that a fresh agent can pick up with no human context.
+
+## State machine
+
+Five canonical roles, each mapped to a label:
+
+| Role              | Label           | Meaning                                                  |
+| ----------------- | --------------- | -------------------------------------------------------- |
+| `needs-triage`    | needs-triage    | Maintainer must evaluate                                 |
+| `needs-info`      | needs-info      | Waiting on reporter                                      |
+| `ready-for-agent` | ready-for-agent | Fully specified, agent can pick up with no human context |
+| `ready-for-human` | ready-for-human | Needs human implementation                               |
+| `wontfix`         | wontfix         | Will not be actioned                                     |
+
+The issue tracker and triage label vocabulary should have been configured. If not, ask the operator which tracker and labels to use.
+
+## Process
+
+### 1. Gather the queue
+
+Collect issues that need triage. Sources:
+
+- **GitHub** — `gh issue list --label needs-triage`
+- **GitLab** — `glab issue list --label needs-triage`
+- **Local markdown** — scan `.scratch/` or the configured local tracker
+- **External PRs** — if the operator enabled PRs as a request surface, include external PRs in the queue. Collaborators' in-flight PRs are left alone.
+
+### 2. Triage each issue
+
+For each issue, work through these steps:
+
+#### 2a. Categorize
+
+Classify as `bug` or `enhancement`:
+
+- **Bug** — the system does something it shouldn't, or doesn't do something it should.
+- **Enhancement** — a request for new functionality or improved behavior.
+
+#### 2b. Verify
+
+For bugs:
+
+- Can you reproduce it from the description?
+- Is there a clear expected vs actual behavior?
+- Are there steps to reproduce?
+
+If the issue lacks enough info to verify, move to `needs-info` and ask the reporter for specifics.
+
+#### 2c. Grill (if needed)
+
+If the issue is an enhancement that's vague or under-specified, run the `grilling` skill to stress-test the request. Ask one question at a time. Look up facts in the codebase rather than asking the reporter.
+
+#### 2d. Write the brief
+
+If the issue is fully specified, write an agent-ready brief and move to `ready-for-agent`. The brief must include:
+
+- **What to build** — the end-to-end behaviour, from the user's perspective.
+- **Acceptance criteria** — checkable, unambiguous.
+- **Domain language** — use the project's ubiquitous language, not internal module names.
+- **No file paths or line numbers** — they go stale.
+
+### 3. Update labels
+
+Apply the appropriate label to each issue after triaging it. Remove `needs-triage` and add the destination label.
+
+### 4. Report
+
+After triaging all issues in the queue, present a summary in `aiLanguage`. **Translate all labels and column names to `aiLanguage`** — the template below is structural only.
+
+| Issue | Category    | Result          | Label applied   |
+| ----- | ----------- | --------------- | --------------- |
+| #42   | bug         | ready-for-agent | ready-for-agent |
+| #43   | enhancement | needs-info      | needs-info      |
+| #44   | bug         | wontfix         | wontfix         |
+
+## Constraints
+
+- **Triage is only for issues you didn't create.** Tickets produced by other skills are already agent-ready — don't re-triage them.
+- **No file paths or line numbers in briefs.** They go stale. Use domain language.
+- **One question at a time during grilling.** See the `grilling` skill.
+- **Commit only your own files.** This skill modifies issue labels, not source files. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.