@warpgogol/forge 0.3.1

package/profiles/forge-shell.yaml

@@ -0,0 +1,77 @@
+schema: forge/stack-profile@1
+id: forge-shell
+displayName: Forge Shell (minimal)
+detect:
+  anyOf:
+    - forge-shell.marker
+workspace:
+  dirs:
+    - docs
+    - scripts
+  files:
+    - path: .gitignore
+      content: |
+        node_modules
+        dist
+        .turbo
+        .cache
+        operator-profile.md
+    - path: package.json
+      content: |
+        {
+          "name": "__PROJECT_NAME__",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "engines": {
+            "node": ">=22"
+          },
+          "scripts": {
+            "clean": "node scripts/clean.mjs",
+            "format": "prettier --write .",
+            "format:check": "prettier --check .",
+            "test": "vitest run --passWithNoTests",
+            "upgrade-packages": "pnpm up"
+          }
+        }
+    - path: scripts/clean.mjs
+      content: |
+        import { readdir, rm } from "node:fs/promises";
+        import { join } from "node:path";
+        import { fileURLToPath } from "node:url";
+
+        const TARGETS = new Set(["node_modules", ".turbo", "dist", ".astro", ".cache", ".wrangler"]);
+
+        const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+        async function walk(dir, toDelete) {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const name = entry.name;
+            const fullPath = join(dir, name);
+            if (TARGETS.has(name)) {
+              toDelete.push(fullPath);
+              continue;
+            }
+            await walk(fullPath, toDelete);
+          }
+        }
+
+        const toDelete = [];
+        await walk(repoRoot, toDelete);
+
+        if (toDelete.length === 0) {
+          console.log("Nothing to clean.");
+          process.exit(0);
+        }
+
+        await Promise.all(toDelete.map((p) => rm(p, { recursive: true, force: true })));
+
+        for (const p of toDelete) {
+          console.log("deleted", p.replace(repoRoot + "/", ""));
+        }
+
+        console.log(`Cleaned ${toDelete.length} directories.`);
+install:
+  - pnpm add -D @warpgogol/forge prettier vitest

package/profiles/phaser-turborepo.yaml

@@ -0,0 +1,144 @@
+schema: forge/stack-profile@1
+id: phaser-turborepo
+displayName: Phaser + Turborepo
+detect:
+  anyOf:
+    - phaser.config.*
+    - package.json
+workspace:
+  dirs:
+    - games
+    - packages
+    - services
+    - scripts
+  files:
+    - path: pnpm-workspace.yaml
+      content: |
+        packages:
+          - "games/*"
+          - "packages/*"
+          - "services/*"
+    - path: turbo.json
+      content: |
+        {
+          "$schema": "https://turbo.build/schema.json",
+          "tasks": {
+            "build": {
+              "dependsOn": ["^build"],
+              "outputs": ["dist/**"]
+            },
+            "build:check": {
+              "dependsOn": ["^build:check"]
+            },
+            "test": {
+              "dependsOn": ["^build:check"]
+            }
+          }
+        }
+    - path: tsconfig.base.json
+      content: |
+        {
+          "compilerOptions": {
+            "target": "ESNext",
+            "module": "ESNext",
+            "moduleResolution": "bundler",
+            "strict": true,
+            "esModuleInterop": true,
+            "skipLibCheck": true,
+            "forceConsistentCasingInFileNames": true
+          }
+        }
+    - path: .gitignore
+      content: |
+        node_modules
+        dist
+        .turbo
+        .cache
+        operator-profile.md
+    - path: package.json
+      content: |
+        {
+          "name": "__PROJECT_NAME__",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "engines": {
+            "node": ">=22"
+          },
+          "scripts": {
+            "clean": "node scripts/clean.mjs",
+            "format": "prettier --write .",
+            "format:check": "prettier --check .",
+            "build": "turbo run build",
+            "build:check": "turbo run build:check",
+            "test": "turbo run test",
+            "upgrade-packages": "pnpm -r up"
+          }
+        }
+    - path: scripts/clean.mjs
+      content: |
+        import { readdir, rm } from "node:fs/promises";
+        import { join } from "node:path";
+        import { fileURLToPath } from "node:url";
+
+        const TARGETS = new Set(["node_modules", ".turbo", "dist", ".astro", ".cache", ".wrangler"]);
+
+        const repoRoot = join(fileURLToPath(import.meta.url), "..", "..");
+
+        async function walk(dir, toDelete) {
+          const entries = await readdir(dir, { withFileTypes: true });
+          for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const name = entry.name;
+            const fullPath = join(dir, name);
+            if (TARGETS.has(name)) {
+              toDelete.push(fullPath);
+              continue;
+            }
+            await walk(fullPath, toDelete);
+          }
+        }
+
+        const toDelete = [];
+        await walk(repoRoot, toDelete);
+
+        if (toDelete.length === 0) {
+          console.log("Nothing to clean.");
+          process.exit(0);
+        }
+
+        await Promise.all(toDelete.map((p) => rm(p, { recursive: true, force: true })));
+
+        for (const p of toDelete) {
+          console.log("deleted", p.replace(repoRoot + "/", ""));
+        }
+
+        console.log(`Cleaned ${toDelete.length} directories.`);
+install:
+  - pnpm add -D typescript turbo @warpgogol/forge prettier
+firstWorkspace:
+  path: games/my-game
+  files:
+    - path: package.json
+      content: |
+        {
+          "name": "my-game",
+          "version": "0.1.0",
+          "private": true,
+          "type": "module",
+          "scripts": {
+            "build:check": "pnpm exec tsc -p tsconfig.json --noEmit",
+            "test": "vitest run --passWithNoTests"
+          }
+        }
+    - path: tsconfig.json
+      content: |
+        {
+          "extends": "../tsconfig.base.json",
+          "compilerOptions": {
+            "outDir": "./dist"
+          }
+        }
+  install:
+    - pnpm add phaser
+    - pnpm add -D vitest

package/skills/_shared/fo-pipeline-conventions.md

@@ -0,0 +1,119 @@
+# WG Pipeline Shared Conventions
+
+Reference file for all `fo-*` skills. Each skill links to the sections it needs via context pointers like "Read `_shared/fo-pipeline-conventions.md` §Recoverable errors".
+
+## PREFERENCES
+
+Read `PREFERENCES.md` at the repository root before starting. If the file is missing or `aiLanguage` is unset, ask the operator once and create the file using the `my-preferences` skill semantics.
+
+## Language policy
+
+- Every natural-language message shown to the operator — greetings, questions, explanations, summaries, status updates — must use `aiLanguage`.
+- Generated documentation, commit messages, and persisted artifacts must use `documentationLanguage`.
+- Internal reasoning, tool-call planning, and intermediate agent monologue may stay in the agent's working language (usually English).
+- Do not translate existing files automatically; preferences affect only new output and the current session.
+- **Report and summary templates in skill definitions are structural examples only.** All labels, headings, table headers, column names, and descriptions in operator-facing output must be translated to `aiLanguage`. Only identifiers (RFC-XXXX, ADR-XXXX, file paths, slash commands, CLI flags) stay in their original form. Do not copy English template labels verbatim into the operator-facing output.
+
+## Recoverable errors
+
+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".
+
+## Commit discipline
+
+Stage only the files this skill produces or modifies. Another agent may be working in a different session; `git add -A` or `git add .` is forbidden.
+
+## Pipeline reference
+
+- **RFC pipeline**: create → audit → enhance → plan → implement (includes review → fix)
+- **ADR pipeline**: create → implement (includes review → fix)
+
+## Forward-only discipline
+
+The ecosystem is forward-only. No backward compatibility layers, no shims, no dual-paths. Legacy code paths are deleted, not maintained behind a flag. Deprecation means removal in the same change, not an indefinite grace period.
+
+## Compass terminology
+
+Use Compass (not GRACE) in all new code, documentation, and log messages.
+
+## Compass scaffolding
+
+Non-trivial new source files in `apps/` or `packages/` must carry `MODULE_CONTRACT` and `CHANGE_SUMMARY` scaffolding. Check the project's invariants file for the canonical Compass markup rule.
+
+## Build verification discipline
+
+MUST NOT run root `root build` or `turbo run build` — these build every workspace and are prohibitively expensive for iterative workflows. Run scoped checks only: `astro check` for touched apps, `tsc --noEmit` (via `build:check`) for touched packages. See root AGENTS.md §Build verification discipline.
+
+## Command execution timeout discipline
+
+Every `run_command` call MUST use a 6-minute (360 000 ms) execution budget. This prevents the agent from blocking on hung or excessively long commands.
+
+### Rules
+
+1. **Always non-blocking**: Call `run_command` with `Blocking: false` and `WaitMsBeforeAsync: 360000` (6 min). This lets the agent regain control if the command hasn't finished.
+2. **Check status**: After `WaitMsBeforeAsync` elapses, call `command_status` with `WaitDurationSeconds: 0` to see if the command completed.
+3. **If completed**: Read the output and proceed normally.
+4. **If still running after 6 min**: Abandon the command — do not wait further. Try an alternative approach (different command, different scope, or skip the step). If no alternative exists, retry the same command once with the same 6-min budget.
+5. **Max retries**: 2 attempts per command. After 2 failed attempts, report to the operator and ask how to proceed.
+6. **No infinite waits**: NEVER call `command_status` with `WaitDurationSeconds` > 60. NEVER use `Blocking: true` for commands that may hang (builds, checks, `site-kernel run`, `astro check`, `tsc`, `pnpm install`).
+7. **Exceptions**: `Blocking: true` is allowed only for trivially fast commands (e.g., `node --version`, `git log -n 1`, `git status --short`) that are guaranteed to complete in seconds.
+
+### Rationale
+
+- The `run_command` tool has no built-in timeout parameter. `WaitMsBeforeAsync` is the only mechanism to regain control after a fixed duration.
+- Abandoning a still-running process is acceptable — the process may complete in the background, but the agent is unblocked and can retry or try an alternative.
+- This covers all command classes: `pnpm exec site-kernel run ...`, `pnpm --filter <pkg> run build:check`, `astro check`, `git`, `pnpm install`, etc.
+- Site-kernel commands already have internal `timeoutMs`, but the agent-side 6-min budget is a safety net for ALL commands, not just site-kernel.
+
+## Binding resolution and degradation
+
+### How to resolve bindings
+
+Skills reference bindings by key, never by value. To resolve a binding:
+
+1. Read `forge.yaml` at the project root.
+2. Navigate to the `bindings` section.
+3. Resolve the key (e.g. `commands.validateRfc`) to its value.
+4. If the value contains placeholders (`{id}`, `{workspace}`, `{file}`), substitute them with the actual values for the current operation.
+5. If the binding is `null` or the `bindings` section is absent, the capability is absent.
+
+### Binding keys
+
+| Key                     | Type                   | Description                            |
+| ----------------------- | ---------------------- | -------------------------------------- |
+| `commands.validateRfc`  | string \| null         | Command to validate an RFC             |
+| `commands.validateAdr`  | string \| null         | Command to validate an ADR             |
+| `commands.typecheck`    | string \| null         | Scoped typecheck command               |
+| `commands.test`         | string \| null         | Scoped test command                    |
+| `commands.scopedBuild`  | string \| null         | Scoped build command                   |
+| `commands.specValidate` | string \| null         | Spec validation command                |
+| `paths.invariantsFile`  | string \| null         | Path to the project's invariants file  |
+| `paths.compassDocs`     | string[]               | Machine-readable semantic docs to sync |
+| `paths.reviewsDir`      | string \| null         | Directory for code reviews             |
+| `paths.handoffsDir`     | string \| null         | Directory for handoff documents        |
+| `terminology`           | Record<string, string> | Project-specific terminology mapping   |
+
+### Degradation contract
+
+- **Required binding unresolvable** (missing or `null`): the skill refuses to start with: `Skill <name> requires binding <key>; add it to forge.yaml or mark the capability absent deliberately.`
+- **Optional binding absent** (`null` / empty): the dependent step is skipped and the skill's final report MUST contain a `Degraded:` line naming each skipped capability.
+- **Silent skips are a contract violation.** Every skipped capability must appear in the final report.
+
+### Worked example
+
+A skill needs to run `rfc.validate` for `RFC-XXXX`:
+
+1. Read `forge.yaml` → `bindings.commands.validateRfc` = `"pnpm exec site-kernel run rfc.validate {id} --json"`
+2. Substitute `{id}` → `"pnpm exec site-kernel run rfc.validate RFC-XXXX --json"`
+3. Run the resolved command.
+
+If `bindings.commands.validateRfc` were `null`, the skill would skip the step and report: `Degraded: commands.validateRfc — not configured in forge.yaml`.
+
+## Session-end sequence
+
+After completing implementation work, the operator may run a three-step session-end sequence. These are **operator-invoked**, never automatic:
+
+1. **`fo-doc-audit`** — are existing docs in sync with code changes? (mechanical check)
+2. **`fo-session-retro`** — did the session produce insights worth routing to a durable home? (reflective triage)
+3. **`fo-handoff`** — what does the next agent need? (continuity document)
+
+Most sessions need only `fo-doc-audit`. `fo-session-retro` is valuable after debugging sessions, exploratory work, or when non-obvious behaviors were discovered. `fo-handoff` is needed when work is incomplete and another agent will continue.

package/skills/_shared/fo-session-summary.md

@@ -0,0 +1,95 @@
+# WG Session Summary & Next Steps — Mandatory Closing Block
+
+Reference file for all `fo-*` skills. Every `fo-*` skill MUST end its session by presenting the closing block defined here. This is not optional — it is the mandatory final output before the skill stops.
+
+## When to emit
+
+The closing block is emitted **once**, at the very end of the skill's execution — after all work is done, after all commits, after any batch summaries. It is the last thing the operator sees.
+
+For orchestrator skills (`fo-idea-i-just-want-to-see-the-result`, `fo-idea-i-just-want-to-see-the-plan`), the closing block replaces any ad-hoc "next step" hints with the structured format below.
+
+For skills that produce batch summaries (`fo-idea-implement`, `fo-idea-plan`, `fo-idea-enhance`, `fo-idea-audit`), the closing block comes **after** the batch summary.
+
+## Language
+
+The closing block MUST use `aiLanguage` (from `PREFERENCES.md`), same as all other operator-facing output. See `_shared/fo-pipeline-conventions.md` §Language policy.
+
+**All labels and headings in the closing block must be translated to `aiLanguage`.** The structural format below uses placeholder labels — replace them with the equivalent in the operator's language. Only slash commands and document identifiers (RFC-XXXX, ADR-XXXX, file paths) stay in their original form.
+
+## Closing block format
+
+```
+---
+
+**<Summary label in aiLanguage>**
+
+<1–3 sentences in aiLanguage: what was done in this session — concretely, with document ids, commit count, review verdict. No filler.>
+
+**<Next steps label in aiLanguage>**
+
+- `/fo-idea-audit RFC-XXXX` — <one line in aiLanguage: why>
+- `/fo-idea-enhance RFC-XXXX` — <one line in aiLanguage: why>
+- `/fo-idea-implement RFC-XXXX` — <one line in aiLanguage: why>
+```
+
+### Rules
+
+1. **Summary** — 1–3 concise sentences in `aiLanguage`. State what was done: document ids, commit count, review verdict, key outcomes. No filler, no repetition of the batch summary — the summary is the _essence_.
+2. **Next steps** — a bulleted list of 1–3 items. Each item is a copy-pasteable slash-command invocation followed by a short `aiLanguage` explanation of why the operator might want to run it.
+3. **Only relevant commands** — list only skills that are genuinely applicable as the next step given the current state. Do not list commands that were already completed or that do not apply. If the skill is terminal (e.g. `fo-idea-status` is read-only), list 0–1 relevant follow-up commands.
+4. **Copy-pasteable** — the slash command must be the exact invocation string the operator can paste into chat. Include the document id if known.
+5. **No more than 3 items** — the operator should not be overwhelmed. Pick the most relevant next steps.
+6. **Translate labels** — the section headings ("Summary", "Next steps") must be in `aiLanguage`, not English. Only slash commands and identifiers stay untranslated.
+
+### Examples
+
+**After `fo-idea-create-rfc` completes (aiLanguage = ru):**
+
+```
+---
+
+**Сводка**
+
+Создан драфт RFC-0380 «Standardize kernel execution reports» (status: draft, 1 коммит). `rfc.validate` проходит без нарушений. Документ ожидает архитектурного ревью.
+
+**Дальнейшие шаги**
+
+- `/fo-idea-audit RFC-0380` — семантический аудит RFC перед энхансментом
+- `/fo-idea-i-just-want-to-see-the-result RFC-0380` — полный пайплайн до реализации
+```
+
+**After `fo-idea-implement` completes (aiLanguage = en):**
+
+```
+---
+
+**Summary**
+
+RFC-0377 implemented: 4 plan steps, 3 commits, scoped build — pass. Review: approved (0 findings). Status: implemented (2026-07-13).
+
+**Next steps**
+
+- `/fo-idea-status` — overview of current RFC/ADR statuses
+```
+
+**After `fo-review` completes (aiLanguage = ru):**
+
+```
+---
+
+**Сводка**
+
+Ревью кода завершено: вердикт needs-revision, 3 замечания (Axis B: DNA-23 нарушение, Axis D: legacy путь, Axis E: нет Compass-разметки). Отчёт сохранён в docs/reviews/code/packages-os-site-kernel-checks/.
+
+**Дальнейшие шаги**
+
+- `/fo-fix` — применить исправления по замечаниям ревью
+```
+
+## Mandatory for new skills
+
+Any new `fo-*` skill created via `skill-create` or any other method MUST include a reference to this file in its Constraints section:
+
+```
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.
+```

package/skills/fo/fo-add-tests/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: fo-add-tests
+description: Write unit and property-based tests for session-produced or specified code. Uses vitest + fast-check per RFC-XXXX.
+invocation: user
+category: fo
+concerns: code-mutation
+dependsOn: ['my-preferences']
+languagePolicy: ref(PREFERENCES.md)
+triggers: ["write tests for this code", "add unit tests", "add property-based tests", "write test coverage for this function"]
+---
+
+# fo-add-tests
+
+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.
+
+Write tests for code that was produced in the current session, or for a file/module the operator points at. The skill decides per-function whether to write example-based tests, property based tests (PBT), or both — following the RFC-XXXX decision tree and the TDD discipline absorbed from the former `tdd` skill.
+
+## Preconditions
+
+- The code to test must exist in the workspace — either produced earlier in this session, or at a path the operator provides.
+- The target package must have `vitest` configured. If it does not, set it up first (see "Package setup" below).
+
+## Process
+
+### 1. Identify the code to test
+
+Determine the target in this order:
+
+1. **Operator argument** — a file path, package name, or function name.
+2. **Session context** — files created or modified earlier in this session (check git diff or the session's edit history).
+3. **Ask** — if neither yields a target, ask the operator what to test.
+
+### 2. Read the code and classify each function
+
+For each exported function in the target file(s), classify it using the RFC-XXXX decision tree (see `pbt-guide.md` for the full tree and property patterns catalog):
+
+```
+Is the function pure (no I/O, no side effects, no mutation of inputs)?
+├── No → Example-based tests or integration tests. Do NOT use PBT.
+└── Yes → Does the function have at least one verifiable algebraic property?
+    ├── No → Example-based tests. Do NOT use PBT.
+    └── Yes → Is the input domain large enough that examples are insufficient?
+        ├── No (small enum, <10 values) → Example-based tests with exhaustive coverage.
+        └── Yes → Write PBT in a *.pbt.test.ts file using fast-check.
+```
+
+Record the classification for each function. Present a brief summary to the operator before writing tests. Report in `aiLanguage`.
+
+### 3. Determine the test seam
+
+Tests verify behavior through **public interfaces**, not implementation details. The seam is:
+
+- **For exported functions** — call the function directly, assert on its return value or observable side effects.
+- **For modules** — call through the module's public API, not its internals.
+- **For integration** — call through the command handler or CLI entry point.
+
+See `tests-reference.md` for good and bad test examples — the anti-patterns (tautological, implementation-coupled, horizontal slicing) are load-bearing.
+
+### 4. Write the tests
+
+#### Example-based tests (`*.test.ts`)
+
+- Import from `vitest`: `import { test, expect } from "vitest"`.
+- Do NOT import from `node:test` or `node:assert/strict` (RFC-XXXX, forward-only).
+- One test per behavior, named as a specification: `"user can checkout with valid cart"`.
+- Expected values are independent known literals — never recompute the expected value the same way the code computes it.
+- Place in `src/tests/**/*.test.ts` (or `src/**/tests/**/*.test.ts` for nested source).
+
+#### Property-based tests (`*.pbt.test.ts`)
+
+- Import from `vitest` and `fast-check`: `import { test, expect } from "vitest"; import fc from "fast-check"`.
+- Use `fc.assert(fc.property(arb, fn))` or `fc.assert(fc.asyncProperty(arb, fn))`.
+- PBT tests are **additive** — never replace existing example-based tests with PBT.
+- Write a comment above each property stating which algebraic property it verifies and why it holds.
+- Place in `src/tests/**/*.pbt.test.ts` alongside existing tests.
+- See `pbt-guide.md` for the full property patterns catalog and worked examples.
+
+#### Mocking
+
+Mock at **system boundaries** only — external APIs, databases, time, randomness. Do NOT mock your own modules or internal collaborators. See `mocking.md` for the full rules.
+
+### 5. Run the tests
+
+For the target package:
+
+```sh
+pnpm --filter <package-name> test
+```
+
+If the tests fail (red):
+
+1. Read the failure output.
+2. Determine whether the test is wrong (bad assertion, wrong seam) or the code is wrong (bug).
+3. Fix the test or report the bug to the operator — do NOT silence a failing test by weakening it.
+
+If the tests pass (green), proceed.
+
+### 6. Commit
+
+Stage only the test files and any test infrastructure changes (e.g. `vitest.config.ts`, `package.json` devDependencies).
+
+```text
+test(scope): add unit and PBT coverage for <module>
+```
+
+Do not stage unrelated changes. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+
+### 7. Check whether AGENTS / README updates are needed
+
+This step is **always performed** — it is not optional and must not be skipped.
+
+Analyze whether the new tests introduced patterns, conventions, or infrastructure that other agents should know about:
+
+- Did you add `fast-check` to a package that didn't have it? Update the package's README or AGENTS.md.
+- Did you create a new `vitest.config.ts`? Document it.
+- Did you establish a new test seam or pattern worth documenting?
+
+If no updates are needed, state this explicitly.
+
+## Package setup (if needed)
+
+If the target package does not yet have `vitest` configured:
+
+1. Add `vitest` and `fast-check` to `devDependencies` in `package.json`.
+2. Set `"test": "vitest run"` and `"test:watch": "vitest"` in scripts.
+3. Create `vitest.config.ts` at the package root:
+
+   ```ts
+   import { defineConfig } from "vitest/config";
+
+   export default defineConfig({
+     test: {
+       environment: "node",
+       include: ["src/tests/**/*.test.ts", "src/**/tests/**/*.test.ts"],
+     },
+   });
+   ```
+
+4. Run `pnpm install` to update the lockfile.
+5. Do NOT add `node:test` shims or legacy assertion wrappers — the migration is forward-only.
+
+## TDD mode
+
+When invoked as `/fo-add-tests --tdd` or when the operator says "test-first" / "red-green":
+
+1. Write the test **before** the implementation.
+2. Watch it fail (red).
+3. Write the minimum implementation to pass.
+4. Watch it pass (green).
+5. Refactor.
+
+This is the red → green loop. Each cycle produces one test worth keeping — a test that reads like a specification and survives refactors because it doesn't care about internal structure.
+
+## Constraints
+
+- **Per-function classification.** The PBT-vs-example decision is made per-function, not per-file. A single file may have both `*.test.ts` and `*.pbt.test.ts` tests.
+- **PBT is additive.** Never replace existing example-based tests with PBT. PBT complements, not replaces.
+- **No `node:test`.** All tests use `vitest` imports. No `node:test` or `node:assert/strict` (RFC-XXXX, forward-only).
+- **No `as any` to silence type errors.** Fix the type or use proper test utilities.
+- **Do not weaken or delete existing tests** without explicit operator direction.
+- **Test through public interfaces.** Tests that couple to implementation details break on refactors and give false confidence.
+- **Deterministic PBT.** If the property involves randomness, the random source must be the fast-check generator, not `Math.random()` or `Date.now()`.
+- **Comment every property.** State which algebraic property it verifies and why it holds.
+- **Scoped verification only.** Run `pnpm --filter <package> test` — do NOT run root `build` or `turbo run build`. See `_shared/fo-pipeline-conventions.md` §Build verification discipline.
+- **Commit only your own files.** Stage only test files and test infrastructure. See `_shared/fo-pipeline-conventions.md` §Commit discipline.
+- **Session summary.** End every session with the closing block defined in `_shared/fo-session-summary.md`.

package/skills/fo/fo-add-tests/mocking.md

@@ -0,0 +1,60 @@
+# When to Mock
+
+Mock at **system boundaries** only:
+
+- External APIs (payment, email, etc.)
+- Databases (sometimes — prefer test DB)
+- Time / randomness
+- File system (sometimes)
+
+Don't mock:
+
+- Your own classes / modules
+- Internal collaborators
+- Anything you control
+
+## Designing for Mockability
+
+At system boundaries, design interfaces that are easy to mock:
+
+### 1. Use dependency injection
+
+Pass external dependencies in rather than creating them internally:
+
+```typescript
+// Easy to mock
+function processPayment(order, paymentClient) {
+  return paymentClient.charge(order.total);
+}
+
+// Hard to mock
+function processPayment(order) {
+  const client = new StripeClient(process.env.STRIPE_KEY);
+  return client.charge(order.total);
+}
+```
+
+### 2. Prefer SDK-style interfaces over generic fetchers
+
+Create specific functions for each external operation instead of one generic function with conditional logic:
+
+```typescript
+// GOOD: Each function is independently mockable
+const api = {
+  getUser: (id) => fetch(`/users/${id}`),
+  getOrders: (userId) => fetch(`/users/${userId}/orders`),
+  createOrder: (data) => fetch('/orders', { method: 'POST', body: data }),
+};
+
+// BAD: Mocking requires conditional logic inside the mock
+const api = {
+  fetch: (endpoint, options) => fetch(endpoint, options),
+};
+```
+
+The SDK approach means:
+
+- Each mock returns one specific shape
+- No conditional logic in test setup
+- Easier to see which endpoints a test exercises
+- Type safety per endpoint