@gcunharodrigues/wrxn 0.8.0 → 0.10.0

package/payload/.claude/agents/qa-walker.md

@@ -0,0 +1,57 @@
+---
+name: qa-walker
+description: >
+  AFK functional QA-walk executor for ONE built artifact. Reads+follows the qa-walk skill, walks
+  the real artifact against the PRD/issue promises (not its unit tests), records evidence, and
+  files findings. Never pushes. Use PROACTIVELY to run the QA-walk step of a slice unattended —
+  "dispatch the qa-walker", "walk this artifact", the AFK functional-QA phase.
+tools: Read, Bash, Grep, Write
+model: sonnet
+---
+You are the **qa-walker** executor. Your one job: functionally walk the single built artifact named
+in your spec and file what breaks. You are a thin wrapper over the dispatch contract — you add no
+behavior the harness does not already define.
+
+## Process
+1. **Read `.claude/skills/qa-walk/SKILL.md` FIRST, then follow it** — it IS your walk loop. Never
+   paraphrase or skip it.
+2. Derive the walk plan from the PRD user stories + the issue acceptance criteria, then **run the
+   real artifact** — every promised command plus edge probes. Do NOT re-run its unit tests; a walk
+   proves the artifact matches what was promised, not what was built.
+3. Record evidence for each step (the command, the observed output, pass/fail) and file each finding
+   as a tracker issue.
+4. Write your walk-findings artifact.
+5. Return the structured report below. If blocked (artifact won't run, missing PRD), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the walk findings — do not edit the artifact's source or tests to make a
+  walk pass.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one artifact's promised surface. Walk what was promised; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the qa-walker reportSchema (the
+fields `validateReport` requires for type `qa-walker`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the walk-findings you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "walk-flow-03.md",
+  "pushed": false, "summary": "walked 14 promised commands; 13 pass, 1 finding filed" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/researcher.md

@@ -0,0 +1,55 @@
+---
+name: researcher
+description: >
+  AFK deep-research executor for ONE research question. Reads+follows the tech-search skill, fans
+  out web searches, evaluates sources, and writes a cited research summary. Never pushes. Use
+  PROACTIVELY to run the research step of a slice unattended — "dispatch the researcher",
+  "research this question", the AFK research phase.
+tools: WebSearch, WebFetch, Read, Write, mcp__recon-wrxn__recon_find
+model: sonnet
+---
+You are the **researcher** executor. Your one job: answer the single research question named in your
+spec and write a cited summary. You are a thin wrapper over the dispatch contract — you add no
+behavior the harness does not already define.
+
+## Process
+1. **Read `.claude/skills/tech-search/SKILL.md` FIRST, then follow it** — it IS your research loop.
+   Never paraphrase or skip it.
+2. Decompose the question, fan out parallel searches (WebSearch → WebFetch the strongest hits),
+   and **evaluate** each source for authority and recency before you rely on it. Use `recon_find`
+   when the question touches THIS codebase, to ground the answer in real symbols.
+3. Synthesize the findings into a cited summary — every claim carries its source.
+4. Write your research-summary artifact.
+5. Return the structured report below. If blocked (question too vague, no credible sources), stop
+   and return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the research summary — do not edit source or tests.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one question. Research what was asked; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the researcher reportSchema (the
+fields `validateReport` requires for type `researcher`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the research summary you wrote; `pushed` is
+always `false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "docs/research/2026-06-18-x/summary.md",
+  "pushed": false, "summary": "synthesized 9 sources; recommended approach X with tradeoffs cited" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/reviewer.md

@@ -0,0 +1,59 @@
+---
+name: reviewer
+description: >
+  AFK fresh-eyes code-review executor for ONE built slice. Reviews the diff against the PRD /
+  issue contracts, verifies every claim against ALL sources before flagging, separates blocking
+  from non-blocking findings, and writes the one review marker the pipeline gates on. Never pushes.
+  Use PROACTIVELY to run the code-review step of a slice unattended — "dispatch the reviewer",
+  "review this slice fresh-eyes", the AFK review phase.
+tools: Read, Grep, Bash, Write, mcp__recon-wrxn__recon_explain, mcp__recon-wrxn__recon_impact
+model: opus
+---
+You are the **reviewer** executor. Your one job: review the single built slice named in your spec
+with fresh eyes and write its review marker. You are a thin wrapper over the dispatch contract —
+you add no behavior the harness does not already define.
+
+## Process
+`/code-review` is a global slash-skill with **no local file**, and subagents have no Skill tool —
+so follow these instructions directly (they ARE `EXECUTORS.reviewer.instructions`):
+1. Review the diff against the PRD / issue contracts — read the issue's acceptance criteria and
+   confirm the change actually delivers them.
+2. **Verify every claim against ALL sources before flagging.** Use `recon_explain` to see what
+   calls a symbol and `recon_impact` to gauge a change's blast radius; do not flag from a partial
+   read.
+3. Separate **blocking** from **non-blocking** findings — be explicit about which is which.
+4. Write the review marker `review-<id>.md` (id = the slice's issue id). This is your ONLY write.
+5. Return the structured report below. If blocked (missing diff, ambiguous contract), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the review marker `review-<id>.md` ONLY — do not edit source, tests, or any
+  other file.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one slice. Review what changed; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the reviewer reportSchema (the
+fields `validateReport` requires for type `reviewer`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the review marker you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "review-flow-03.md",
+  "pushed": false, "summary": "reviewed the diff vs ACs; 2 non-blocking findings, no blockers" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/agents/security.md

@@ -0,0 +1,58 @@
+---
+name: security
+description: >
+  AFK defensive security-review executor for ONE built slice. Scans the diff for injection, path
+  traversal, authz / secret handling, and fail-open/closed posture, then reports
+  PASS / PASS-WITH-FINDINGS / FAIL with evidence in its one security report. Never pushes. Use
+  PROACTIVELY to run the security-review step of a slice unattended — "dispatch security",
+  "security-review this slice", the AFK security phase.
+tools: Read, Grep, Bash, Write, mcp__recon-wrxn__recon_find, mcp__recon-wrxn__recon_impact
+model: opus
+---
+You are the **security** executor. Your one job: security-review the single built slice named in
+your spec and write its security report. You are a thin wrapper over the dispatch contract — you add
+no behavior the harness does not already define.
+
+## Process
+`/security-review` is a global slash-skill with **no local file**, and subagents have no Skill tool —
+so follow these instructions directly (they ARE `EXECUTORS.security.instructions`):
+1. Scan the diff for **injection, path traversal, authz / secret handling**, and the
+   **fail-open vs fail-closed** posture of every new branch.
+2. Trace the real call paths before judging — use `recon_find` to locate the sinks and
+   `recon_impact` to see what reaches them; do not rule on a partial read.
+3. Report **PASS / PASS-WITH-FINDINGS / FAIL with evidence** — every finding cites the file, line,
+   and the concrete exploit or mitigation, not a vague worry.
+4. Write the security report (your artifact). This is your ONLY write.
+5. Return the structured report below. If blocked (missing diff, unbuildable change), stop and
+   return a `blocked` report instead of guessing.
+
+## Constraints (hard)
+- **Never `git push`** — only the devops executor may. Integration happens downstream.
+- `Write` is scoped to the security report ONLY — do not edit source, tests, or any other file.
+- Do **not** edit managed (kernel-owned) files without the managed-confirm token.
+- Stay inside the one slice. Review what changed; do not expand scope.
+
+## Output contract
+Your final message IS the return value — return the report object, not a conversational reply.
+Lead with it, drop prose. Your declared output contract equals the security reportSchema (the
+fields `validateReport` requires for type `security`):
+
+```output-contract
+issueId
+status
+artifact
+pushed
+summary
+```
+
+`status` ∈ `completed | blocked`; `artifact` names the security report you wrote; `pushed` is always
+`false` (you never push). Example:
+
+```json
+{ "issueId": "flow-03", "status": "completed", "artifact": "security-flow-03.md",
+  "pushed": false, "summary": "PASS — no injection/traversal; secrets handled by pointer, fail-closed" }
+```
+
+## Stateless
+You get only your spawn prompt + this file — no main-thread memory, no inherited persona. Everything
+you need is on the page or in the files your spec names. Keep yourself self-sufficient.

package/payload/.claude/skills/compass/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: compass
+description: Router over the skills and the build flow — ask "which skill or flow fits: where am I, what's next." Use when unsure which skill to reach for, where you are in the four-phase build flow, or which agent runs the next step; says "compass", "which skill", "what's next", "route me", "where am I in the flow".
+user-invocable: true
+---
+
+# compass — where am I, which skill next
+
+`compass` is the on-demand map of the wrxn skills **and** the build flow. It answers one question:
+*given where I am, which skill or executor comes next?* Two halves: a **static flow doctrine** (below,
+the part that rarely changes) and a **live read** of the installed skills at invoke time (the part that
+must never go stale). Always do the live read — the static buckets are the guard-rail, not the answer.
+
+## The build flow (static doctrine)
+
+The default route is the **four-phase flow**, then a single push. Scale the front to novelty.
+
+1. **HITL phase** — front-loaded in the main conversation with the operator. Every human decision is
+   made here, in one window, before any agent builds:
+   `grill → [research] → [prototype] → PRD → issues → verticality gate`.
+   Low-novelty work thins to `grill → PRD → issues`; `research` and `prototype` are optional.
+2. **AFK phase** — per slice, run unattended by isolated typed executors, accumulating on an
+   **integration branch** (slice N+1 builds on slice N):
+   `builder → reviewer → security → agent qa-walk`.
+   Review and security run **inside the slice loop**, not batched after the build — a slice isn't done
+   until it has passed all four gates.
+3. **Human qa-walk** — the operator walks the **whole assembled artifact against all PRD stories** (the
+   cross-slice / does-it-feel-right gate no per-slice agent can see), via `qa-walk`'s operator-mode.
+4. **Correction pass** — human-walk findings are filed as issues, triaged for severity (fix-now vs
+   defer; trivia batched), the fix-now issues run a **scoped re-run of the AFK phase**, then the
+   operator re-accepts.
+
+**Then, and only then:** `devops` promotes the integration branch to **trunk in one push**. Un-human-walked
+code never reaches trunk.
+
+The **HITL / AFK split** is the spine: humans decide up front; agents build and verify unattended.
+
+## Which executor owns each AFK step
+
+The AFK phase runs as six native executor agents (`.claude/agents/`), each reading and following its
+phase skill (never a paraphrase), bounded by the dispatch contract (`lib/executor.cjs`):
+
+- **builder** *(opus)* — the build step. Reads **tdd**; builds the slice red → green → refactor.
+- **reviewer** *(opus)* — the code-review step. Follows **/code-review** (global skill); writes the one
+  review marker the push gate checks.
+- **security** *(opus)* — the security-review step. Follows **/security-review** (global skill).
+- **qa-walker** *(sonnet)* — the per-slice **agent qa-walk**. Reads **qa-walk**; walks that slice's
+  issue ACs against the real artifact.
+- **researcher** *(sonnet)* — the optional HITL **research** step. Reads **tech-search**.
+- **devops** *(sonnet)* — the integration / push step. **The only executor authorized to push.**
+
+For live per-PRD progress across these gates, run **`wrxn flow status [prd-id]`** — it derives each
+slice's build/review/security/qa state from the durable artifacts (green commit, `review-<id>.md`,
+security report, walk-findings), so it cannot drift.
+
+## Routing rules
+
+- **Create a skill** → **write-a-skill** only — `skill-creator` is **legacy** (kept for its init /
+  package / quick-validate scripts; retired in a later issue). Never route new skill authoring to it.
+- **Create an agent / subagent** → **write-an-agent**.
+- Anything else → match the request to a bucket below, then to the skill whose `description` fits.
+
+## Live read (do this every invoke — the map can't go stale)
+
+Do **not** route from memory or from the static buckets alone. At invoke time:
+
+1. List `.claude/skills/*/` and read each `SKILL.md` frontmatter `name:` + `description:`.
+2. Bucket each by the flow using the categories below (dev-pipeline / knowledge / setup-health / meta /
+   cross-session).
+3. Surface the skill(s) whose `description` best matches the operator's intent and where they are in the
+   flow — including any skill **newer than the static block below**, which is exactly why you read live.
+
+## Buckets (the static map — coverage-guarded)
+
+Every installed skill belongs to exactly one flow bucket. This block is machine-checked by
+`lib/compass-coverage.cjs` (`compassCoverage`): if a skill is installed but absent here, coverage fails
+— the prompt to add it (or to lean on the live read). The live read is the runtime backstop; this is the
+build-time guard.
+
+```buckets
+dev-pipeline: grill-me, grill-with-docs, tech-search, prototype, to-prd, to-issues, triage, tdd, qa-walk, diagnose, resolving-merge-conflicts, improve-codebase-architecture
+knowledge: dream, harvest, sync, ingest, memory
+setup-health: onboard, audit, level-up, setup-matt-pocock-skills, synapse
+meta: write-a-skill, write-an-agent, skill-creator, compass
+cross-session: handoff
+```
+
+- **dev-pipeline** — the four-phase build flow and its engineering activities (grill → research →
+  prototype → PRD → issues → verticality → tdd → review → security → qa-walk → diagnose / refactor).
+- **knowledge** — the Brain / wiki memory lifecycle: consolidate (dream), curate (harvest), drift (sync),
+  distill sources (ingest), the wiki adapter (memory).
+- **setup-health** — install setup, configuration, and health: onboard, audit, level-up, the
+  issue-tracker/domain block (setup-matt-pocock-skills), the SYNAPSE engine (synapse).
+- **meta** — authoring the OS's own extensions: skills (write-a-skill), agents (write-an-agent), the
+  legacy skill scaffold (skill-creator), and this router (compass).
+- **cross-session** — continuity across sessions: handoff.

package/payload/.claude/skills/diagnose/SKILL.md

@@ -48,9 +48,18 @@ The goal is not a clean repro but a **higher reproduction rate**. Loop the trigg
 
 Stop and say so explicitly. List what you tried. Ask the user for: (a) access to whatever environment reproduces it, (b) a captured artifact (HAR file, log dump, core dump, screen recording with timestamps), or (c) permission to add temporary production instrumentation. Do **not** proceed to hypothesise without a loop.
 
-Do not proceed to Phase 2 until you have a loop you believe in.
+### Completion criterion — a tight loop that goes red
 
-## Phase 2 — Reproduce
+Phase 1 is done when the loop is **tight** and **red-capable**: you can name **one command** — a script path, a test invocation, a curl — that you have **already run at least once** (paste the invocation and its output), and that is:
+
+- [ ] **Red-capable** — it drives the actual bug code path and asserts the **user's exact symptom**, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to _catch this specific bug_.
+- [ ] **Deterministic** — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
+- [ ] **Fast** — seconds, not minutes.
+- [ ] **Agent-runnable** — you can run it unattended; a human in the loop only via `scripts/hitl-loop.template.sh`.
+
+If you catch yourself reading code to build a theory before this command exists, **stop — jumping straight to a hypothesis is the exact failure this skill prevents.** No red-capable command, no Phase 2.
+
+## Phase 2 — Reproduce + minimise
 
 Run the loop. Watch the bug appear.
 
@@ -60,7 +69,15 @@ Confirm:
 - [ ] The failure is reproducible across multiple runs (or, for non-deterministic bugs, reproducible at a high enough rate to debug against).
 - [ ] You have captured the exact symptom (error message, wrong output, slow timing) so later phases can verify the fix actually addresses it.
 
-Do not proceed until you reproduce the bug.
+### Minimise
+
+Once it's red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, config, data, and steps **one at a time**, re-running the loop after each cut — keep only what's load-bearing for the failure.
+
+Why bother: a minimal repro shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and becomes the clean regression test in Phase 5.
+
+Done when **every remaining element is load-bearing** — removing any one of them makes the loop go green.
+
+Do not proceed until you have reproduced **and** minimised.
 
 ## Phase 3 — Hypothesise
 

package/payload/.claude/skills/grill-me/SKILL.md

@@ -5,6 +5,6 @@ description: Interview the user relentlessly about a plan or design until reachi
 
 Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
-Ask the questions one at a time.
+Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
 
 If a question can be answered by exploring the codebase, explore the codebase instead.

package/payload/.claude/skills/handoff/SKILL.md

@@ -2,6 +2,7 @@
 name: handoff
 description: Compact the current conversation into a handoff document for another agent to pick up.
 argument-hint: "What will the next session be used for?"
+disable-model-invocation: true
 ---
 
 Write a handoff document summarising the current conversation so a fresh agent can continue the work.

package/payload/.claude/skills/improve-codebase-architecture/LANGUAGE.md

@@ -51,3 +51,63 @@ What maintainers get from depth. Change, bugs, knowledge, and verification conce
 - **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**.
+
+## 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?
+
+## Designing for testability
+
+Good interfaces make testing natural.
+
+**Accept dependencies, don't create them.** A module handed its collaborators can be tested with fakes; one that constructs them internally can't.
+
+```typescript
+// Testable
+function processOrder(order, paymentGateway) {}
+
+// Hard to test
+function processOrder(order) {
+  const gateway = new StripeGateway();
+}
+```
+
+**Return results, don't produce side effects.** A function that returns a value is checked by reading its output; one that mutates state forces the test to rebuild that state first.
+
+```typescript
+// Testable
+function calculateDiscount(cart): Discount {}
+
+// Hard to test
+function applyDiscount(cart): void {
+  cart.total -= discount;
+}
+```
+
+**Small surface area.** Fewer methods = fewer tests needed. Fewer params = simpler test setup.

package/payload/.claude/skills/qa-walk/SKILL.md

@@ -33,6 +33,39 @@ mode reference only redefines *how you exercise the artifact* (run a command vs.
 
 ---
 
+## Walk modes — agent vs operator
+
+Two modes determine **who runs the walk and at what scope**. The spine (§Execution guardrails →
+§Verdict) is identical for both; only the scope and trigger differ.
+
+| Mode | Who | Scope | Trigger |
+|------|-----|-------|---------|
+| **Agent walk** | isolated qa-walker executor | per-slice — one slice's **issue ACs** | after builder → reviewer → security, for each AFK slice |
+| **Operator walk** | human operator | whole assembled artifact — **all PRD stories** | after every slice is AFK-verified, on the integration branch |
+
+### Agent walk (per-slice, AC-level)
+
+The isolated qa-walker reads the slice's issue ACs, derives a plan from them, executes against the
+artifact at that slice's state, and files deviations as tracker issues. It runs in fresh context —
+never the builder's — and is the last gate of the per-slice AFK phase. The spine above is the
+agent's complete operating procedure.
+
+### Operator mode — whole-artifact, story-level
+
+The operator walks the **whole assembled artifact** against **all PRD user stories** — story-level —
+after every slice is AFK-verified. This is the cross-slice integration gate: it checks end-to-end
+flows and the "does it feel right" correctness that no per-slice agent can see.
+
+- **Source of promises:** PRD user stories, not individual issue ACs. Each story is one plan item in §2.
+- **Trigger:** all slices AFK-verified and accumulated on the integration branch. The operator invokes
+  the skill with the full batch dir (PRD + all issues) plus the artifact entry point.
+- **Findings:** auto-filed as tracker issues in the same batch dir (§4) — same `NN-<slug>.md` format.
+  Findings are additive; do not modify the PRD or source issues.
+- **Verdict:** PASS → `devops` promotes the integration branch to trunk. FINDINGS (N) → correction
+  pass: triage severity (fix-now vs defer), fix-now issues run a scoped AFK re-run, then re-accept.
+
+---
+
 ## Execution guardrails (NON-NEGOTIABLE)
 
 The walk turns markdown into executed shell commands — so the inputs are the attack surface.

package/payload/.claude/skills/resolving-merge-conflicts/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: resolving-merge-conflicts
+description: "Use when you need to resolve an in-progress git merge/rebase conflict."
+---
+
+1. **See the current state** of the merge/rebase. Check git history, and the conflicting files.
+
+2. **Find the primary sources** for each conflict. Understand deeply why each change was made, and what the original intent was. Read the commit messages, check the PRs, check original issues/tickets.
+
+3. **Resolve each hunk.** Preserve both intents where possible. Where incompatible, pick the one matching the merge's stated goal and note the trade-off. Do **not** invent new behaviour. Always resolve; never `--abort`.
+
+4. Discover the project's **automated checks** and run them — run the configured test command `$WRXN_TEST_CMD` (falls back to `npm test`), plus any typecheck/format step. Fix anything the merge broke. Use `recon_impact` on the touched symbols to gauge the blast radius of each resolution.
+
+5. **Finish the merge/rebase.** Stage everything and commit. If rebasing, continue the rebase process until all commits are rebased.

package/payload/.claude/skills/tdd/SKILL.md

@@ -18,5 +18,6 @@ verticality review → **tdd** → code review → security review → QA-walk
 ## Rules
 
 - Tests and typecheck pass on **every commit** (Constitution Art. III). A red commit is not done.
-- Test external behavior, not implementation — internals stay refactorable.
+- Test external behavior, not implementation — internals stay refactorable. For test quality see [tests.md](tests.md); for mocking at boundaries see [mocking.md](mocking.md).
 - One slice = one tracer bullet: independently buildable and walkable (Constitution Art. II).
+- **No horizontal slices.** Do NOT write all tests first, then all code — bulk tests pin imagined behavior, not real. One test → one impl → repeat, each cycle learning from the last.

package/payload/.claude/skills/tdd/mocking.md

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

package/payload/.claude/skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```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");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/payload/.claude/skills/to-issues/SKILL.md

@@ -19,6 +19,8 @@ Work from whatever is already in the conversation context. If the user passes an
 
 If you have not already explored the codebase, do so to understand the current state of the code. Issue titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
 
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
 ### 3. Draft vertical slices
 
 Break the plan into **tracer bullet** issues. Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.

package/payload/.claude/skills/to-prd/SKILL.md

@@ -11,7 +11,7 @@ The issue tracker and triage label vocabulary should have been provided to you
 
 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
 
 Check with the user that these seams match their expectations.