@warpgogol/forge 0.3.1

package/skills/fo/fo-compass-annotate/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: fo-compass-annotate
+description: Full-lifecycle Compass header management — generate, update, audit, validate, cleanup. Replaces removed compass.annotate/clear/migrate/invariant.add commands.
+invocation: user
+category: fo
+concerns: content-mutation
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: []
+  optional: [compass.fileExtensions, compass.testPatterns]
+triggers: ["manage Compass headers", "annotate source files with Compass", "audit Compass module contracts"]
+---
+
+# fo-compass-annotate
+
+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.
+
+Manage Compass source headers across files with a full lifecycle: discover, generate, update, audit, risk-flag, validate, and cleanup. This skill replaces the removed `compass.annotate`, `compass.clear`, `compass.markup.migrate`, and `compass.invariant.add` kernel commands.
+
+## Preconditions
+
+- The workspace has source files with Compass scaffolding requirements. Check the project's invariants file for the canonical Compass markup rule.
+- `compass.validate` is available to verify headers after updates.
+
+## Flags
+
+- `--file <path>` — process a single file instead of scanning the workspace.
+- `--changed` — process only files changed in the current git diff (unstaged + staged).
+- `--packages` — scan `packages/` instead of the default workspace scope.
+- `--package <name>` — with `--packages`, scan one package.
+- `--dry-run` — report what would change without writing files.
+
+## Process
+
+### 1. Discover files
+
+Determine the scan scope:
+
+- If `--file` is given, process only that file.
+- If `--changed` is given, run `git diff --name-only HEAD` (or `git diff --name-only --cached` + `git diff --name-only`) to get the changed file list. Filter to source files matching `ref(forge.yaml bindings.compass.fileExtensions)` (default: `.ts`, `.astro`).
+- Otherwise, scan the workspace (or `packages/` with `--packages`) for all source files matching the file extension binding.
+
+Skip files that are:
+
+- Generated (carry `GENERATED` marker or are in `dist/`, `node_modules/`, `.agents/`).
+- In `spec/`, `todo/`, or folders starting with `old-` or `-`.
+- Binary or non-text.
+
+### 2. Per-file processing
+
+For each discovered file, determine the required action:
+
+#### 2a. Generate (file has no Compass headers)
+
+If the file has no `MODULE_CONTRACT` and no `CHANGE_SUMMARY` block:
+
+1. Read the file content and understand its purpose.
+2. Use `templates/header-prompt.md` to generate a `MODULE_CONTRACT` block with `<purpose>` and `<non-goals>`.
+3. Create a `CHANGE_SUMMARY` block with a single `<item>` noting the initial creation.
+4. Insert both blocks at the top of the file, after any existing license/comment header but before imports.
+5. Use `reference/comment-styles.md` to determine the correct comment syntax for the file extension.
+
+#### 2b. Update (file has headers but content has changed)
+
+If the file has Compass headers but the content has significantly changed:
+
+1. Read the current `MODULE_CONTRACT` and compare with the file's actual purpose.
+2. Use `templates/header-prompt.md` to regenerate the `MODULE_CONTRACT` if the purpose has shifted.
+3. Add a new `<item>` to `CHANGE_SUMMARY` referencing the current RFC or change.
+4. Run `compass.summary.trim` if the `CHANGE_SUMMARY` exceeds 30 total items.
+
+#### 2c. Audit (semantic check)
+
+For each file with Compass headers:
+
+1. Use `templates/audit-prompt.md` to audit the `MODULE_CONTRACT` against the file's actual content.
+2. Check that `<purpose>` accurately describes what the file does.
+3. Check that `<non-goals>` lists at least one boundary the file does not cross.
+4. Flag files where the header is stale, misleading, or empty.
+
+#### 2d. Risk flag
+
+For each file with Compass headers:
+
+1. Use `reference/risk-patterns.md` to scan for deterministic risk patterns (sign, crypto, vault, migrate, publish, etc.).
+2. If a risk pattern is found, add a `<!-- risk: <pattern> -->` comment inside the `MODULE_CONTRACT` block.
+3. Risk patterns are deterministic — no LLM judgment needed.
+
+### 3. Batch-end validation
+
+After processing all files:
+
+1. Run `compass.validate` to verify all headers are well-formed.
+2. If any violations are found, attempt to fix them automatically (missing `<non-goals>`, empty `<purpose>`, etc.).
+3. Re-run `compass.validate` to confirm fixes.
+4. If violations persist after 3 retry attempts, report them to the operator.
+
+### 4. Cleanup (optional, with `--cleanup` flag)
+
+If `--cleanup` is given:
+
+1. Remove `TODO(compass)` sentinels from files that still have them.
+2. Replace each sentinel with a real value generated using `templates/header-prompt.md`.
+3. Run `compass.validate` to confirm no sentinels remain.
+
+### 5. Report
+
+Output a summary:
+
+```
+## Compass Annotate Report
+
+### Files scanned: <N>
+### Files generated: <N>
+### Files updated: <N>
+### Files audited: <N>
+### Files risk-flagged: <N>
+### Validation: <pass | fail>
+### Sentinels replaced: <N>
+```
+
+## Completion criteria
+
+- All discovered files have `MODULE_CONTRACT` and `CHANGE_SUMMARY` blocks.
+- `compass.validate` passes with zero errors.
+- No `TODO(compass)` sentinels remain (if `--cleanup` was used).
+- All changes are committed with message `compass: update headers for changed files`.

package/skills/fo/fo-compass-annotate/reference/comment-styles.md

@@ -0,0 +1,25 @@
+# Comment Style Mapping by File Extension
+
+Compass headers are embedded in source file comments. The comment syntax varies by language.
+
+## Mapping
+
+| Extension | Comment syntax | Example |
+| --- | --- | --- |
+| `.ts` | `/* ... */` block comment | `/* <MODULE_CONTRACT> ... </MODULE_CONTRACT> */` |
+| `.tsx` | `/* ... */` block comment | `/* <MODULE_CONTRACT> ... </MODULE_CONTRACT> */` |
+| `.astro` | `<!-- ... -->` HTML comment | `<!-- <MODULE_CONTRACT> ... </MODULE_CONTRACT> -->` |
+| `.js` | `/* ... */` block comment | `/* <MODULE_CONTRACT> ... </MODULE_CONTRACT> */` |
+| `.mjs` | `/* ... */` block comment | `/* <MODULE_CONTRACT> ... </MODULE_CONTRACT> */` |
+| `.css` | `/* ... */` block comment | `/* <MODULE_CONTRACT> ... </MODULE_CONTRACT> */` |
+| `.yaml` | `# ` line comment | `# <MODULE_CONTRACT>` (each line prefixed with `# `) |
+| `.yml` | `# ` line comment | `# <MODULE_CONTRACT>` (each line prefixed with `# `) |
+| `.json` | Not supported | JSON files cannot carry comments; skip Compass headers |
+| `.md` | `<!-- ... -->` HTML comment | `<!-- <MODULE_CONTRACT> ... </MODULE_CONTRACT> -->` |
+
+## Rules
+
+- The XML-like tags (`<MODULE_CONTRACT>`, `<CHANGE_SUMMARY>`, `<item>`, etc.) are always preserved as-is inside the comment wrapper.
+- For `.yaml`/`.yml`, each line of the block is prefixed with `# `.
+- For `.json`, Compass headers are not applicable — skip these files.
+- The block is placed at the top of the file, after any license header but before code/imports.

package/skills/fo/fo-compass-annotate/reference/learned-principles.md

@@ -0,0 +1,12 @@
+# Learned Principles
+
+Concrete principles distilled from operator feedback during `fo-compass-annotate` sessions. Each principle has a condition and a recommended answer.
+
+<!-- Entries are appended after operator approval. -->
+<!-- Format:
+## <principle title>
+- **Condition:** <when this applies>
+- **Recommended answer:** <what to recommend>
+- **confirmations:** <N>
+- **Added:** <date>
+-->

package/skills/fo/fo-compass-annotate/reference/risk-patterns.md

@@ -0,0 +1,23 @@
+# Deterministic Risk Patterns
+
+These patterns are scanned deterministically (no LLM) to flag files that handle sensitive operations. When a pattern matches, a `<!-- risk: <pattern> -->` comment is added inside the `MODULE_CONTRACT` block.
+
+## Patterns
+
+| Pattern | Regex | Risk level | Description |
+| --- | --- | --- | --- |
+| `sign` | `\b(sign|signing|signature)\b` | high | Cryptographic signing operations |
+| `crypto` | `\b(crypto|encrypt|decrypt|cipher|aes|rsa|hmac)\b` | high | Cryptographic operations |
+| `vault` | `\b(vault|secret|password|apiKey|api_key|token)\b` | high | Secret/credential handling |
+| `migrate` | `\b(migrate|migration|migrator)\b` | medium | Data migration logic |
+| `publish` | `\b(publish|deploy|release)\b` | medium | Publishing/deployment operations |
+| `delete` | `\b(delete|remove|destroy|purge)\b` | medium | Destructive operations |
+| `network` | `\b(fetch|http|request|axios|got)\b` | low | Network requests |
+| `fs-write` | `\b(writeFile|mkdir|rm |unlink|rename)\b` | low | Filesystem write operations |
+
+## Rules
+
+- Patterns are case-insensitive.
+- A file may have multiple risk flags.
+- Risk flags are informational — they do not block validation.
+- The `risk` comment is placed after `<non-goals>` and before `</MODULE_CONTRACT>`.

package/skills/fo/fo-compass-annotate/templates/audit-prompt.md

@@ -0,0 +1,36 @@
+# Semantic Audit Prompt
+
+You are auditing a Compass `MODULE_CONTRACT` block against the file's actual content. Determine whether the header is accurate, complete, and not misleading.
+
+## Input
+
+- File path: `{path}`
+- Current `MODULE_CONTRACT` block: `{header}`
+- File content (full): `{content}`
+
+## Audit axes
+
+1. **Purpose accuracy** — does `<purpose>` describe what the file actually does? Flag if:
+   - The purpose is generic or could apply to any file.
+   - The file does something not mentioned in the purpose.
+   - The purpose references the file name instead of describing behavior.
+
+2. **Non-goals completeness** — do the `<non-goals>` items describe real boundaries? Flag if:
+   - There are zero non-goals items.
+   - Non-goals are generic ("not a utility").
+   - Non-goals describe things the file actually does (contradiction).
+
+3. **Staleness** — has the file's content changed significantly since the header was written? Flag if:
+   - New exports or functions are not reflected in the purpose.
+   - Removed functionality is still mentioned in the purpose.
+   - The file's role has shifted (e.g., from validator to generator).
+
+## Output
+
+```
+verdict: <pass | needs-update | stale>
+issues:
+  - axis: <axis name>
+    severity: <error | warning>
+    message: <description>
+```

package/skills/fo/fo-compass-annotate/templates/header-format.md

@@ -0,0 +1,57 @@
+# Canonical Compass Header Format
+
+This is the canonical format for Compass source headers. Check the project's invariants file for the canonical Compass markup rule.
+
+## Two-block contract
+
+Every non-trivial source file in `apps/`, `packages/`, or `services/` must carry:
+
+1. `MODULE_CONTRACT` — describes the file's purpose and boundaries.
+2. `CHANGE_SUMMARY` — chronological list of changes with RFC/ticket references.
+
+## MODULE_CONTRACT
+
+```
+<MODULE_CONTRACT>
+<purpose>One sentence describing what the file does.</purpose>
+<non-goals>
+  <item>At least one boundary the file does not cross.</item>
+</non-goals>
+</MODULE_CONTRACT>
+```
+
+### Rules
+
+- `<purpose>` must be specific to this file, under 100 characters.
+- `<non-goals>` must have at least one `<item>`.
+- Do not include `@ai-invariant` lines in `MODULE_CONTRACT` — they are inline comments in the file body.
+
+## CHANGE_SUMMARY
+
+```
+<CHANGE_SUMMARY>
+  <item>RFC-XXXX: one-line description of the change.</item>
+</CHANGE_SUMMARY>
+```
+
+### Rules
+
+- Each `<item>` should reference an RFC id, ticket id, or ADR id (protected items).
+- Items without an RFC/ticket reference are "unprotected" and may be trimmed by `compass.summary.trim`.
+- Maximum 30 total items per file (enforced by `compass.changesummary.validate`).
+- Boilerplate items (e.g., "Initial creation", "Compass scaffolding") are automatically removed by `compass.summary.trim`.
+
+## Comment syntax by extension
+
+See `reference/comment-styles.md` for the correct comment syntax per file extension.
+
+## Forbidden blocks
+
+The following legacy Compass blocks are forbidden and must be removed:
+
+- `GRACE_MODULE_CONTRACT` — use `MODULE_CONTRACT` instead.
+- `GRACE_CHANGE_SUMMARY` — use `CHANGE_SUMMARY` instead.
+- `AI_INVARIANTS` — use inline `// @ai-invariant` comments instead.
+- `COMPASS_AUDIT` — use the audit ledger via `compass.audit.record` instead.
+
+If `compass.validate` reports a `COMPASS-FORBIDDEN-01` violation, remove the forbidden block and run the `fo-compass-annotate` skill to generate correct headers.

package/skills/fo/fo-compass-annotate/templates/header-prompt.md

@@ -0,0 +1,35 @@
+# Header Generation Prompt
+
+You are generating a Compass `MODULE_CONTRACT` block for a source file. The block must accurately describe the file's purpose and boundaries.
+
+## Input
+
+- File path: `{path}`
+- File content (first 100 lines): `{content}`
+
+## Output format
+
+Generate a `MODULE_CONTRACT` block with:
+
+1. `<purpose>` — one sentence describing what the file does.
+2. `<non-goals>` — at least one `<item>` describing what the file does NOT do.
+
+## Rules
+
+- The purpose must be specific to this file, not generic.
+- Non-goals must describe real boundaries the file respects.
+- Do not use vague phrases like "utility functions" or "helper code".
+- Do not reference the file name in the purpose.
+- Keep the purpose under 100 characters.
+
+## Example
+
+```
+<MODULE_CONTRACT>
+<purpose>Validates CHANGE_SUMMARY blocks for boilerplate items and over-cap items per RFC-XXXX.</purpose>
+<non-goals>
+  <item>Do not audit truthfulness of CHANGE_SUMMARY items against code — that is RFC-XXXX.</item>
+  <item>Do not delete protected (RFC/code-referencing) items under any circumstance.</item>
+</non-goals>
+</MODULE_CONTRACT>
+```

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

@@ -0,0 +1,264 @@
+---
+name: fo-doc-audit
+description: Audit session changes and update AGENTS.md, README, Compass XML, architecture-dna.md, and templates so AI and human docs stay in sync with code. Use at session end or inline by other skills.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+bindings:
+  requires: []
+  optional: [paths.invariantsFile, paths.compassDocs]
+triggers: ["audit documentation sync", "update docs after code changes", "check AGENTS.md and README are in sync"]
+---
+
+# Documentation Audit
+
+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.
+
+Analyze the current session's code and content changes, determine which documentation surfaces are out of sync, apply updates, and commit. This skill is the single source of truth for the "are docs still accurate?" question that every session ends on.
+
+## When to invoke
+
+- **Standalone at session end** — the operator runs `/fo-doc-audit` after completing work to ensure docs reflect the changes.
+- **Inline by other skills** — `fo-fix`, `fo-idea-implement`, and other skills delegate their doc-update steps here instead of carrying inline logic.
+
+## Documentation surfaces
+
+The ecosystem has seven documentation surfaces. Each has a different audience and update trigger.
+
+| Surface | Path pattern | Audience | Update trigger |
+| --- | --- | --- | --- |
+| **AGENTS.md** | root, `apps/`, `packages/`, `services/`, nested workspace | AI agents | Contract, convention, workflow, pipeline, command, or boundary change |
+| **README** | root, `packages/*/README.md`, `services/*/README.md` | Humans (developers, operators) | Public API, CLI surface, usage pattern, or installation flow change |
+| **Compass XML** | `docs/requirements.xml`, `docs/technology.xml`, `docs/development-plan.xml`, `docs/knowledge-graph.xml`, `docs/verification-plan.xml`, `docs/source-markup.xml` | AI agents (machine-readable semantic layer) | Repository-wide requirements, shared package contracts, app-package relationships, verification policy |
+| **architecture-dna.md** | `ref(forge.yaml bindings.paths.invariantsFile)` | AI agents + humans | New DNA invariant, invariant amendment, or invariant retirement |
+| **Templates** | `packages/os/site-kernel-onboarding/src/templates/`, `packages/os/site-kernel-codegen/src/templates/` | Future apps/packages (scaffold time) | Change to what a new app or package should look like at creation time |
+| **Generated artifacts** | `docs/ecosystem.generated.json`, `docs/command-manifest.generated.yaml`, `fleet/*.generated.yaml`, `*.generated.css` | AI agents (read-only projection) | **Never edit directly** — update the generator or registry, then regenerate |
+| **COMMANDS / PACKAGE_GRAPH** | `docs/COMMANDS.md`, `docs/PACKAGE_GRAPH.md` | Humans + AI agents | New command, removed command, package graph change |
+
+## Process
+
+### 1. Gather session context
+
+Determine what changed in this session. Use in priority order:
+
+1. **Explicit scope** — if the operator or calling skill specified a git fixed point, diff range, or file list, use it.
+2. **Git diff** — run `git diff HEAD` (unstaged) and `git diff --cached` (staged) to see uncommitted changes. Run `git log --oneline -10` to see recent commits in this session.
+3. **Session conversation** — scan the current conversation for files modified, commands run, and artifacts created.
+
+Capture the full list of changed files and categorize them:
+
+- **Code** — `.ts`, `.js`, `.mjs`, `.astro`, `.css`, `.json`, `.yaml`, etc.
+- **Content** — `src/content/**/*.md`, `src/content/**/*.yaml`.
+- **Docs** — `docs/**/*.md`, `docs/**/*.xml`, `AGENTS.md`, `README.md`.
+- **Templates** — files under `packages/os/site-kernel-*/src/templates/`.
+- **Generated** — `*.generated.*`, `fleet/*.generated.*`.
+
+### 2. Run impact analysis
+
+For each documentation surface, determine whether it needs updating. Answer the trigger questions below. If any answer is "yes", that surface needs an update.
+
+#### 2a. AGENTS.md
+
+- Did a **contract, convention, or workflow** change that agents rely on?
+- Were **files, packages, commands, or pipelines** added, removed, or renamed?
+- Did **build steps, verification commands, or environment requirements** change?
+- Was a **new pattern** introduced that other agents working in the same area should know about?
+- Did **package boundaries or import rules** change?
+- Did the **RFC governance protocol, storage policy, cosmic naming contract, or Compass duties** change?
+
+If yes for a specific workspace, identify the **nearest applicable AGENTS.md**:
+
+- Root `AGENTS.md` — monorepo-wide rules.
+- `docs/authoring/site-composition.md` — shared site rules.
+- `packages/AGENTS.md` — shared package rules.
+- `services/AGENTS.md` — shared backend runtime rules.
+- `<site>/AGENTS.md` or `packages/<pkg>/AGENTS.md` — workspace-specific rules.
+
+Update only the nearest applicable file(s). Do not duplicate rules across levels — root stays cross-workspace, nested stays workspace-specific.
+
+#### 2b. README
+
+- Did a package's **public API** (exports, types, functions) change?
+- Did a **CLI surface** change (new command, removed command, changed flags)?
+- Did **usage patterns** change (how someone imports, calls, or configures the package)?
+- Did the **installation or setup flow** change?
+- Did the **root README** need updating (project overview, getting started, architecture summary)?
+
+If yes, update the relevant `README.md`. Keep READMEs concise — they are human-facing quick-start guides, not exhaustive references.
+
+#### 2c. Compass XML
+
+Per root AGENTS.md §Compass document duties: keep `docs/*.xml` synchronized with the current codebase. Check:
+
+- **`docs/requirements.xml`** — did repository-wide requirements change?
+- **`docs/technology.xml`** — did the technology stack, frameworks, or tooling change?
+- **`docs/development-plan.xml`** — did the development plan or milestone structure change?
+- **`docs/knowledge-graph.xml`** — did the knowledge graph structure or relationships change?
+- **`docs/verification-plan.xml`** — did the verification flow, check pipelines, or validation policy change?
+- **`docs/source-markup.xml`** — did the source-file Compass contract (markup patterns, anchor conventions) change?
+
+If yes, update the affected XML file(s). These are the primary machine-readable semantic layer — keep them precise.
+
+#### 2d. architecture-dna.md
+
+- Was a **new invariant** introduced (e.g., a new entry in the project's invariants file)?
+- Was an **existing invariant amended** (e.g., broadened scope, tightened rule)?
+- Was an **invariant retired** (forward-only removal)?
+
+If yes, update `ref(forge.yaml bindings.paths.invariantsFile)`. If a new invariant was introduced, also check whether `docs/source-markup.xml` needs a corresponding entry.
+
+#### 2e. Templates
+
+- Did the change affect **what a new app or package should look like at scaffold time**?
+- Did a **boilerplate file, script, or config** pattern change that onboarding/codegen templates should reflect?
+- Did a **new convention** get introduced that future apps/packages must follow from creation?
+
+If yes, update the **template** files in `packages/os/site-kernel-onboarding/src/templates/` and `packages/os/site-kernel-codegen/src/templates/`. **Never edit generated output in existing apps** — fix the template, then regenerate if needed.
+
+#### 2f. Generated artifacts
+
+- Did a **registry** change (`systems/registry.yaml`, `fleet/fleet.sites.yaml`, command module registrations)?
+- Did a **generator input** change (package manifests, command tables, fleet plan)?
+
+If yes, **do not edit the generated file directly**. Update the source registry or generator, then run the regeneration command:
+
+```sh
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=ecosystem.manifest.generate
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=command.manifest.generate
+```
+
+Note: if the regeneration command is expensive or unavailable in the current session, document the need to regenerate in the session summary and move on.
+
+#### 2g. COMMANDS.md / PACKAGE_GRAPH.md
+
+- Were **commands** added, removed, or renamed?
+- Did the **package graph** change (new package, removed package, new dependency)?
+
+If yes, update `docs/COMMANDS.md` and/or `docs/PACKAGE_GRAPH.md`. If these are generated, update the generator instead (see 2f).
+
+### 3. Present analysis to the operator
+
+Present the impact analysis as a concise table before applying any changes. This gives the operator a chance to correct the assessment.
+
+```
+## Documentation Impact Analysis
+
+| Surface | Needs update? | Reason |
+| --- | --- | --- |
+| AGENTS.md (root) | Yes | New command lifecycle rule |
+| AGENTS.md (packages/os/site-kernel) | Yes | New cache module registered |
+| README (packages/os/site-kernel) | No | No public API change |
+| Compass XML (docs/verification-plan.xml) | Yes | New check pipeline stage |
+| architecture-dna.md | No | No DNA invariant change |
+| Templates | No | No scaffold-time change |
+| Generated artifacts | Yes | Command manifest needs regeneration |
+| COMMANDS.md | Yes | Two new commands added |
+```
+
+If no surface needs updating, state this explicitly and stop:
+
+> "Документация актуальна — обновления не требуются."
+
+If the operator confirms (or if running inline and the calling skill's conventions apply), proceed to step 4.
+
+### 4. Apply updates
+
+For each surface that needs updating:
+
+1. **Read** the target file before editing.
+2. **Edit** with minimal, focused changes — follow the existing structure and tone.
+3. **Do not delete existing content** unless it describes a removed feature (forward-only: delete stale docs, do not leave them as historical notes).
+4. **Do not add comments or documentation** to code files unless the task explicitly requires it.
+5. **Generated files**: update the source (registry/generator/template), not the generated output. Run the regeneration command if available.
+
+**Forward-only rule**: if a feature, command, or pattern was removed in this session, remove all documentation references to it. Do not keep "legacy" or "deprecated" sections — the ecosystem is forward-only.
+
+**Compass scaffolding**: if new non-trivial source files were added in the session, ensure they carry `MODULE_CONTRACT` and `CHANGE_SUMMARY` scaffolding. Check the project's invariants file for the canonical Compass markup rule. This is part of documentation audit — Compass markup is a documentation surface.
+
+### 5. Verify generated artifacts
+
+If any generated artifact needed regeneration (step 2f), run the generator now:
+
+```sh
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=ecosystem.manifest.generate
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=command.manifest.generate
+```
+
+If the generator command is unavailable or too expensive for this session, note it in the summary — the operator can regenerate later.
+
+If a generated artifact was regenerated, run the drift guards:
+
+```sh
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=ecosystem.manifest.validate
+ref(forge.yaml bindings.commands.scopedBuild) --workspace=workspace.surface.validate
+```
+
+### 6. Commit
+
+Stage and commit documentation changes separately from code changes. Use focused commit messages:
+
+```txt
+docs: update AGENTS.md and Compass XML for <what changed>
+
+<one-line description of which docs were updated and why>.
+```
+
+If multiple surfaces were updated, list them in the commit body:
+
+```txt
+docs: sync documentation for <feature/RFC>
+
+- AGENTS.md (root): <what changed>
+- docs/verification-plan.xml: <what changed>
+- docs/COMMANDS.md: <what changed>
+- packages/os/site-kernel/README.md: <what changed>
+```
+
+Stage only the documentation files touched by this step. Do not stage unrelated changes — another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+
+If no documentation changes were needed, skip this step.
+
+### 7. Report
+
+Present a concise summary in `aiLanguage`. **Translate all labels and headings to `aiLanguage`** — the template below is structural only.
+
+```
+## <Documentation Audit Summary in aiLanguage>
+
+### Surfaces checked: <count>
+### Surfaces updated: <count>
+- <surface>: <one-line description of change>
+### Generated artifacts regenerated: <count | skipped — reason>
+### Commit: <hash | none — no changes needed>
+```
+
+## Inline invocation by other skills
+
+When another skill (e.g. `fo-fix`, `fo-idea-implement`) delegates its doc-update step to `fo-doc-audit`:
+
+1. The calling skill invokes `fo-doc-audit` via the `skill` tool.
+2. `fo-doc-audit` runs its full process (steps 1–7).
+3. The calling skill does **not** duplicate the doc-update logic — it trusts `fo-doc-audit` to cover all surfaces.
+4. The calling skill's completion criteria should reference `fo-doc-audit` instead of inline checks.
+
+Skills that delegate to `fo-doc-audit`:
+
+- **`fo-fix`** step 5 ("Documentation audit") — invokes `fo-doc-audit`.
+- **`fo-fix`** merge conflict resolution step 4 ("Documentation audit") — invokes `fo-doc-audit`.
+- **`fo-idea-implement`** step 3.9 ("Documentation audit") — invokes `fo-doc-audit`.
+- **`fo-idea-implement`** ADR-FLOW step 4.6 ("Documentation audit") — invokes `fo-doc-audit`.
+
+## Constraints
+
+- **Templates, not generated files.** Never edit `*.generated.*` directly — update the source and regenerate.
+- **Forward-only.** Delete documentation for removed features; do not keep stale references.
+- **Minimal edits.** Update only what is out of sync. Do not rewrite sections that are still accurate.
+- **No code comments.** Do not add or delete comments in code files unless the task explicitly requires it.
+- **Compass scaffolding is part of docs.** New non-trivial source files must carry `MODULE_CONTRACT` and `CHANGE_SUMMARY`. Check the project's invariants file for the canonical Compass markup rule.
+- **Commit discipline.** Stage only documentation files. Do not stage unrelated changes — another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+- **Read before edit.** Always read the target file before editing to preserve structure and tone.
+- **Generated artifact regeneration is best-effort.** If the generator command is unavailable or too expensive, note it and move on — do not block the session.
+- **No pauses for recoverable tool errors.** If a tool call fails with a recoverable error — `write_to_file` content too long, JSON truncation, line count/character limit exceeded, or similar — recover autonomously: split content into smaller writes, use `edit`/`multi_edit`, decompose oversized files, and retry immediately. The operator's default answer to "Shall I proceed?" is always "yes".
+- **Session summary.** End every session with a closing block in the operator's `aiLanguage`: a 1–3 sentence summary of what was done, followed by 1–3 copy-pasteable next-step slash commands with short explanations.