@warpgogol/forge 0.3.1

package/skills/fo/fo-add-tests/pbt-guide.md

@@ -0,0 +1,193 @@
+# Property-Based Testing Guide
+
+Reference for writing property-based tests (PBT) using `fast-check` + `vitest`. Check the project's invariants file for the canonical PBT rule.
+
+## Decision tree
+
+Every function MUST be classified per this tree. The decision is made **per-function**, not per-file.
+
+```
+Is the function pure (no I/O, no side effects, no mutation of inputs)?
+├── No → Use example-based tests or integration tests. Do NOT use PBT.
+└── Yes → Does the function have at least one verifiable algebraic property?
+    ├── No → Use example-based tests. Do NOT use PBT.
+    └── Yes → Is the input domain large enough that examples are insufficient?
+        ├── No (small enum, <10 values) → Use example-based tests with exhaustive coverage. Do NOT use PBT.
+        └── Yes → Write a property-based test in a *.pbt.test.ts file using fast-check.
+            ├── Check if a *.pbt.test.ts already exists for this function.
+            │   ├── Yes → Add the new property to the existing file.
+            │   └── No → Create a new *.pbt.test.ts file alongside the existing tests.
+            └── Choose the property pattern from the catalog below.
+```
+
+## When PBT is required
+
+ALL of the following must be true:
+
+1. **Pure function** — output determined solely by input. No I/O, no `Date.now()`, no `Math.random()`, no side effects, no mutation of input arguments.
+2. **Verifiable property** — at least one algebraic property holds and is non-trivial.
+3. **Non-trivial input space** — large enough that hand-picked examples are unlikely to cover all edge cases. Functions with a small enum input (<10 values) do not need PBT.
+
+## When PBT is NOT required
+
+ANY of the following:
+
+1. **Impure function** — I/O, `Date.now()`, `Math.random()`, external state mutation.
+2. **UI / Astro component** — verified by visual inspection, Playwright, or snapshot tests.
+3. **Build pipeline / OS command** — reads files, runs processes, orchestrates pipelines. Integration-tested.
+4. **Content validation rules** — deterministic rule checks (e.g. "does this YAML key exist?").
+5. **Small input domain** — closed enum with <10 values. Exhaustive example-based coverage is sufficient.
+6. **Thin delegation** — one-line pass-through to another function that is already property-tested.
+7. **No verifiable property** — behavior cannot be expressed as a universal quantifier over input.
+
+## Property patterns catalog
+
+Each pattern shows the fast-check idiom. Use the pattern names exactly — do not invent custom property names.
+
+### Idempotency
+
+`f(f(x)) == f(x)` for all valid `x`.
+
+```ts
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { normalizeText } from "../text-normalize.ts";
+
+test("normalizeText is idempotent", () => {
+  fc.assert(
+    fc.property(fc.string({ maxLength: 500 }), (input) => {
+      const once = normalizeText(input, ALL_ON);
+      expect(normalizeText(once, ALL_ON)).toBe(once);
+    }),
+  );
+});
+```
+
+### Round-trip
+
+`g(f(x)) == x` for all valid `x`.
+
+```ts
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { parseSemver, formatSemver } from "../semver.ts";
+
+test("parseSemver and formatSemver are round-trip", () => {
+  fc.assert(
+    fc.property(
+      fc.record({
+        major: fc.nat({ max: 999 }),
+        minor: fc.nat({ max: 999 }),
+        patch: fc.nat({ max: 999 }),
+      }),
+      ({ major, minor, patch }) => {
+        const formatted = formatSemver({ major, minor, patch });
+        const reparsed = parseSemver(formatted);
+        expect(reparsed).toEqual({ major, minor, patch });
+      },
+    ),
+  );
+});
+```
+
+### Immutability
+
+`f(x)` does not mutate `x`; `x` is deep-equal before and after.
+
+```ts
+import { test, expect } from "vitest";
+import fc from "fast-check";
+import { substituteRefsDeep } from "../substitute-deep.ts";
+
+test("substituteRefsDeep does not mutate input", async () => {
+  fc.assert(
+    fc.asyncProperty(
+      fc.object({ maxLength: 5, maxDepth: 3 }),
+      fc.func(fc.string()),
+      async (input, resolve) => {
+        const snapshot = JSON.parse(JSON.stringify(input));
+        await substituteRefsDeep(input, resolve);
+        expect(input).toEqual(snapshot);
+      },
+    ),
+  );
+});
+```
+
+### Transitivity
+
+`a < b and b < c implies a < c`.
+
+```ts
+test("compareSemver is transitive: a < b and b < c implies a < c", () => {
+  fc.assert(
+    fc.property(
+      semverStringArbitrary,
+      semverStringArbitrary,
+      semverStringArbitrary,
+      (a, b, c) => {
+        if (compareSemver(a, b) < 0 && compareSemver(b, c) < 0) {
+          expect(compareSemver(a, c)).toBeLessThan(0);
+        }
+      },
+    ),
+  );
+});
+```
+
+### Antisymmetry
+
+`f(a, b) == -f(b, a)`.
+
+```ts
+test("compareSemver is antisymmetric: compare(a, b) == -compare(b, a)", () => {
+  fc.assert(
+    fc.property(semverStringArbitrary, semverStringArbitrary, (a, b) => {
+      expect(compareSemver(a, b)).toBe(-compareSemver(b, a));
+    }),
+  );
+});
+```
+
+### Other patterns
+
+- **Commutativity:** `f(a, b) == f(b, a)` for all valid `a`, `b`.
+- **Associativity:** `f(f(a, b), c) == f(a, f(b, c))` for all valid `a`, `b`, `c`.
+- **Monotonicity:** `a <= b => f(a) <= f(b)` for all valid `a`, `b`.
+- **Reflexivity:** `f(x, x) == 0` (or identity element).
+- **Distributivity:** `f(a, g(b, c)) == g(f(a, b), f(a, c))` for all valid inputs.
+- **Invariance:** `p(f(x)) == p(x)` for some invariant `p` and all valid `x`.
+
+## Agent rules (MUST / MUST NOT)
+
+- **MUST** use `vitest` as the test runner for all packages with real test scripts.
+- **MUST** add `fast-check` as a dev dependency before writing PBT in a package.
+- **MUST** place PBT in `*.pbt.test.ts` files (not in regular `*.test.ts` files).
+- **MUST** use `fc.assert(fc.property(...))` or `fc.assert(fc.asyncProperty(...))` as the PBT idiom.
+- **MUST** set a `numRuns` value when the default 100 is insufficient: `fc.assert(fc.property(...), { numRuns: 1000 })`.
+- **MUST NOT** use PBT for impure functions, I/O-bound code, UI components, or build pipelines.
+- **MUST NOT** replace existing example-based tests with PBT. PBT complements example-based tests.
+- **MUST NOT** use `fast-check` in production code or runtime dependencies. It is dev-only.
+- **MUST NOT** invent custom property names. Use the names from the catalog above.
+- **MUST** write a comment above each property stating which algebraic property it verifies and why it holds.
+- **MUST** ensure PBT tests are deterministic. If the property involves randomness, the random source must be the fast-check generator, not `Math.random()` or `Date.now()`.
+- **MAY** use `fc.pre()` to constrain generated inputs to the function's valid domain.
+- **MAY** create custom arbitraries with `fc.record()`, `fc.array()`, `fc.tuple()`, etc.
+
+## Functions that qualify for PBT (non-exhaustive)
+
+| Function | Package | Property | Pattern |
+| --- | --- | --- | --- |
+| `normalizeText` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeHtml` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeMarkdown` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `normalizeJson` | `@warpgogol/share` | `normalize(normalize(x)) == normalize(x)` | Idempotency |
+| `compareSemver` | `@warpgogol/site-kernel-handoff` | `a < b and b < c implies a < c` | Transitivity |
+| `compareSemver` | `@warpgogol/site-kernel-handoff` | `compare(a, b) == -compare(b, a)` | Antisymmetry |
+| `parseSemver` / `formatSemver` | `@warpgogol/site-kernel-handoff` | `parse(format(parsed)) == parsed` | Round-trip |
+| `substituteRefsDeep` | `@warpgogol/share` | Input is not mutated after call | Immutability |
+| `markdownTwinRelPath` | `@warpgogol/share` | `twinUrlPath(twinRelPath(x))` is consistent for valid paths | Round-trip |
+| `deepMergeEntryData` | `@warpgogol/share` | Merge is associative for nested objects (not arrays) | Associativity |
+| `citySlug` | `@warpgogol/geo` | Output only contains lowercase alphanumeric and hyphens | Invariance |
+| `redactUrl` | `@warpgogol/observability` | Output never contains a query string | Invariance |
+| `validateAgainstCapabilitySchema` | `@warpgogol/agent-gate` | Non-object input always fails validation | Invariance |

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

@@ -0,0 +1,92 @@
+# Test Reference — Good vs Bad
+
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
+
+## Good: Tests observable behavior
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+## Bad: Tests implementation details
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = vi.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+This test breaks if you rename `paymentService.process`, switch to a different payment API, or inline the call — even if checkout still works perfectly. It tests _how_, not _what_.
+
+## Bad: Tautological test
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+```
+
+If `calculateTotal` has a bug (e.g. off-by-one in the reduce), the test still passes — the expected value has the same bug. Use an independent known literal:
+
+```typescript
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```
+
+## Bad: Horizontal slicing
+
+```typescript
+// BAD: Tests only one layer, missing the integration
+test("validateInput returns true for valid input", () => {
+  expect(validateInput("valid")).toBe(true);
+});
+
+test("processData returns result for valid input", () => {
+  // Mocks validateInput, so the real validation is never tested
+  vi.mock("../validate").mockReturnValue(true);
+  const result = processData("invalid-but-mocked-valid");
+  expect(result).toBeDefined();
+});
+```
+
+The first test checks validation in isolation. The second mocks it out. If `validateInput` changes its rules, the second test still passes — but the integration is broken. Prefer a vertical slice that exercises the real validation through the public API.
+
+## Good: Integration-style test through public API
+
+```typescript
+// GOOD: Exercises the full path through the public interface
+test("processData rejects invalid input through the public API", () => {
+  const result = processData("invalid input here");
+  expect(result.ok).toBe(false);
+  expect(result.error).toMatch(/invalid/);
+});
+```
+
+This test survives internal refactors — `validateInput` can be renamed, split, or inlined — as long as `processData` still rejects invalid input, the test passes.
+
+## Test naming
+
+Name tests as specifications, not as test cases:
+
+- Good: `"user can checkout with valid cart"`
+- Good: `"processData rejects invalid input"`
+- Good: `"normalizeText is idempotent"`
+- Bad: `"test1"`
+- Bad: `"checkout test"`
+- Bad: `"should work"`
+
+The name is the specification. If you can't name what behavior you're testing, you don't know what you're testing.

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

@@ -0,0 +1,83 @@
+---
+name: fo-architecture
+description: Scan a codebase for deepening opportunities, present as HTML report, then grill through the chosen one. Uses deep-module vocabulary.
+invocation: user
+category: fo
+concerns: document-only
+dependsOn: ['my-preferences', 'grilling']
+languagePolicy: ref(PREFERENCES.md)
+triggers: ["analyze codebase architecture", "find deepening opportunities", "review code structure quality"]
+---
+
+# fo-architecture
+
+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.
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This skill uses the deep-module vocabulary from `architecture-vocabulary.md` (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+
+## Process
+
+### 1. Explore
+
+The scope of the review must be determined **explicitly** before any other action. Search for the package or repository root to review in this order:
+
+1. **Prompt** — the operator's invocation arguments (a package path, a folder, or the repository root).
+2. **Session context** — files open in the IDE or prior conversation context that clearly indicates which package to review.
+3. **Stop** — if no scope is found, ask: "Which package or folder should I review? Provide a path like `packages/growth` or specify the repository root for a full review."
+
+Read the project's domain glossary (`CONTEXT.md` or `UBIQUITOUS_LANGUAGE.md`) and any ADRs in the area you're touching first.
+
+Then explore the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file into `docs/reviews/architecture/`. Derive the subfolder name from the relative path of the reviewed module folder, converted to kebab-case and lowercased (for example, `packages/agent-gate` becomes `packages-agent-gate`). Name the file `arch-[YYYY-MM-DD]-[HH]-<short-desc>.html`.
+
+If the review target is the repository root, use `root` as both the subfolder and the `<short-desc>`.
+
+See `html-report.md` for the full HTML scaffold, diagram patterns, and styling guidance.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+Use domain glossary vocabulary for the domain, and the deep-module vocabulary for the architecture. If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card.
+
+Do NOT propose interfaces yet. After the file is written, ask the operator: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the operator picks a candidate, run the `grilling` skill to walk the design tree — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize:
+
+- **Naming a deepened module after a concept not in the domain glossary?** Add the term. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update the glossary right there.
+- **Operator rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer.
+- **Want to explore alternative interfaces for the deepened module?** Use the design-it-twice parallel sub-agent pattern from `design-it-twice.md`.
+
+## Constraints
+
+- **Document-only.** This skill produces HTML reports and domain glossary updates — it does not modify source code.
+- **Use the deep-module vocabulary exactly.** Don't substitute "component," "service," "API," or "boundary." See `architecture-vocabulary.md`.
+- **Commit only your own files.** Stage only the HTML report and glossary updates. 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-architecture/architecture-vocabulary.md

@@ -0,0 +1,104 @@
+# Architecture Vocabulary — Deep Modules
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone.
+
+## Glossary
+
+Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+
+**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+
+**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+
+**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+
+**Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
+
+**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the _location_ at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+
+**Adapter** — a concrete thing that satisfies an interface at a seam. Describes _role_ (what slot it fills), not substance (what's inside).
+
+**Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
+
+**Locality** — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place rather than spreading across callers. Fix once, fixed everywhere.
+
+## Deep vs shallow
+
+**Deep module** = small interface + lots of implementation:
+
+```
+┌─────────────────────┐
+│   Small Interface   │  ← Few methods, simple params
+├─────────────────────┤
+│                     │
+│  Deep Implementation│  ← Complex logic hidden
+│                     │
+└─────────────────────┘
+```
+
+**Shallow module** = large interface + little implementation (avoid):
+
+```
+┌─────────────────────────────────┐
+│       Large Interface           │  ← Many methods, complex params
+├─────────────────────────────────┤
+│  Thin Implementation            │  ← Just passes through
+└─────────────────────────────────┘
+```
+
+When designing an interface, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+## Principles
+
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. If you want to test _past_ the interface, the module is probably the wrong shape.
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
+
+## Designing for testability
+
+Good interfaces make testing natural:
+
+1. **Accept dependencies, don't create them.**
+
+   ```typescript
+   // Testable
+   function processOrder(order, paymentGateway) {}
+
+   // Hard to test
+   function processOrder(order) {
+     const gateway = new StripeGateway();
+   }
+   ```
+
+2. **Return results, don't produce side effects.**
+
+   ```typescript
+   // Testable
+   function calculateDiscount(cart): Discount {}
+
+   // Hard to test
+   function applyDiscount(cart): void {
+     cart.total -= discount;
+   }
+   ```
+
+3. **Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.
+
+## Relationships
+
+- A **Module** has exactly one **Interface** (the surface it presents to callers and tests).
+- **Depth** is a property of a **Module**, measured against its **Interface**.
+- A **Seam** is where a **Module**'s **Interface** lives.
+- An **Adapter** sits at a **Seam** and satisfies the **Interface**.
+- **Depth** produces **Leverage** for callers and **Locality** for maintainers.
+
+## Rejected framings
+
+- **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.

package/skills/fo/fo-architecture/deepening.md

@@ -0,0 +1,37 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in `architecture-vocabulary.md` — **module**, **interface**, **seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The category determines how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. Always deepenable — merge the modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies that have local test stand-ins (PGLite for Postgres, in-memory filesystem). Deepenable if the stand-in exists. The deepened module is tested with the stand-in running in the test suite. The seam is internal; no port at the module's external interface.
+
+### 3. Remote but owned (Ports & Adapters)
+
+Your own services across a network boundary (microservices, internal APIs). Define a **port** (interface) at the seam. The deep module owns the logic; the transport is injected as an **adapter**. Tests use an in-memory adapter. Production uses an HTTP/gRPC/queue adapter.
+
+Recommendation shape: _"Define a port at the seam, implement an HTTP adapter for production and an in-memory adapter for testing, so the logic sits in one deep module even though it's deployed across a network."_
+
+### 4. True external (Mock)
+
+Third-party services (Stripe, Twilio, etc.) you don't control. The deepened module takes the external dependency as an injected port; tests provide a mock adapter.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a port unless at least two adapters are justified (typically production + test). A single-adapter seam is just indirection.
+- **Internal seams vs external seams.** A deep module can have internal seams (private to its implementation, used by its own tests) as well as the external seam at its interface. Don't expose internal seams through the interface just because tests use them.
+
+## Testing strategy: replace, don't layer
+
+- Old unit tests on shallow modules become waste once tests at the deepened module's interface exist — delete them.
+- Write new tests at the deepened module's interface. The **interface is the test surface**.
+- Tests assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors — they describe behaviour, not implementation. If a test has to change when the implementation changes, it's testing past the interface.

package/skills/fo/fo-architecture/design-it-twice.md

@@ -0,0 +1,44 @@
+# Design It Twice
+
+When the operator wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best.
+
+Uses the vocabulary in `architecture-vocabulary.md` — **module**, **interface**, **seam**, **adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate:
+
+- The constraints any new interface would need to satisfy
+- The dependencies it would rely on, and which category they fall into (see `deepening.md`)
+- A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete
+
+Show this to the operator, then immediately proceed to Step 2. The operator reads and thinks while the sub-agents work in parallel.
+
+### 2. Spawn sub-agents
+
+Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module.
+
+Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from `deepening.md`, what sits behind the seam). Give each agent a different design constraint:
+
+- Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point."
+- Agent 2: "Maximise flexibility — support many use cases and extension."
+- Agent 3: "Optimise for the most common caller — make the default case trivial."
+- Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies."
+
+Include both `architecture-vocabulary.md` vocabulary and domain glossary vocabulary in the brief so each sub-agent names things consistently.
+
+Each sub-agent outputs:
+
+1. Interface (types, methods, params — plus invariants, ordering, error modes)
+2. Usage example showing how callers use it
+3. What the implementation hides behind the seam
+4. Dependency strategy and adapters (see `deepening.md`)
+5. Trade-offs — where leverage is high, where it's thin
+
+### 3. Present and compare
+
+Present designs sequentially so the operator can absorb each one, then compare them in prose. Contrast by **depth** (leverage at the interface), **locality** (where change concentrates), and **seam placement**.
+
+After comparing, give your own recommendation: which design you think is strongest and why. If elements from different designs would combine well, propose a hybrid. Be opinionated — the operator wants a strong read, not a menu.

package/skills/fo/fo-architecture/html-report.md

@@ -0,0 +1,104 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in `docs/reviews/architecture/<kebab-case-module-path>/arch-[YYYY-MM-DD-HH].html` under the repository root. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each.
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+### Mermaid graph (dependencies / call flow)
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG. Use when Mermaid's layout fights you.
+
+### Cross-section (layered shallowness)
+
+Stack horizontal bands to show layers. Before: 6 thin layers. After: 1 thick band.
+
+### Mass diagram (interface vs implementation)
+
+Two rectangles per module. Before: interface nearly as tall as implementation (shallow). After: interface short, implementation tall (deep).
+
+### Call-graph collapse
+
+Before: tree of calls as nested boxes. After: same tree collapsed into one box, internal calls faded.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace.
+- Colour sparingly: one accent plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall for side-by-side viewing.
+- Use `text-xs uppercase tracking-wider` for module labels.
+- Only scripts: Tailwind CDN and Mermaid ESM import.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card.
+
+## Tone
+
+Use exactly: module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+Never substitute: component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module).
+
+Wins bullets name the gain in glossary terms: "locality: bugs concentrate in one module", "leverage: one interface, N call sites". Don't write "easier to maintain" or "cleaner code".