bigpowers 2.86.4 → 2.86.6

package/.opencode/skills/develop-tdd/SKILL.md

@@ -0,0 +1,416 @@
+---
+name: develop-tdd
+model: sonnet
+description: "Test-driven development with red-green-refactor loop using vertical slices. Use for features (epic tasks) or bugs (specs/bugs/BUG-*.md)."
+---
+
+# Develop TDD
+
+> **HARD GATE** — Do NOT proceed if on `main` or `master`. Run `kickoff-branch` first to create a feature branch or worktree.
+>
+> **HARD GATE** — Do NOT write code before you have a plan. New feature: `plan-work` → epic capsule tasks. Bug: `investigate-bug` → `specs/bugs/BUG-*.md` (or use `fix-bug` orchestrator).
+>
+> **RECURSIVE DISCIPLINE** — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."
+
+## Philosophy
+
+Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail.
+
+## Red Flags
+
+If you catch yourself thinking these, stop and reconsider — you are likely deviating from production-grade craft.
+
+| Red Flag | Reality |
+| :--- | :--- |
+| "This is too simple to need tests." | Simple code is where bugs hide. If it's simple, the test is cheap. |
+| "I'll refactor this later." | "Later" is when technical debt becomes bankruptcy. Refactor while Green. |
+| "The tests are already comprehensive." | If you're adding behavior, you need a new test. Coverage ≠ Correctness. |
+| "I'm just fixing a small bug." | Small bugs often indicate deep interface flaws. Investigate root cause. |
+| "I need to mock this internal class." | Mocking internals couples tests to implementation. Mock only I/O. |
+| "This refactor is out of scope." | Leave the code cleaner than you found it (Boy Scout Rule). |
+| "Preflight failed but it's unrelated." | **Always Green:** any reproducible gate failure routes **quick-fix → fix-bug** before forward work. Session boundaries do not waive Preflight. |
+| "I'll note the red gate and continue." | Narrating a failure is banned. fix-or-log is mandatory per CONVENTIONS § Discovered Defects. |
+
+## Workflow
+
+> **Timing:** `bash scripts/bp-timing.sh start develop-tdd` at invocation; `bash scripts/bp-timing.sh end develop-tdd` before handoff.
+
+### 1. Planning
+
+- [ ] Read active `specs/epics/*/epic.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps
+- [ ] If `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` exists for the active epic, read it before writing the first test. Implement P0 scenarios (`SC-*-P0-*`) before P1. P2/P3 scenarios are optional per time budget.
+- [ ] Confirm interface changes and behaviors to test (prioritize)
+- [ ] Design interfaces for testability — identify [deep modules](deep-modules.md) opportunities
+- [ ] Get user approval on the plan
+
+Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:    Write test for first behavior → test fails → commit: test(<scope>): ...  (test-only; red in CI)
+GREEN:  Write minimal code to pass → test passes → commit: feat(<scope>): ...   (fix commit; green)
+REFACTOR (optional): clean up → commit: refactor(<scope>): ...
+```
+
+> **Two-commit red/green policy (HARD GATE — e45s08)** — Each behavior cycle requires **two separate commits**: (1) test-only commit that fails in CI (RED), then (2) implementation commit that makes it pass (GREEN). Never combine test + fix in one commit. Before proceeding, run the mechanical RED isolation check:
+
+```bash
+bash scripts/verify-tdd-red-commit.sh
+```
+
+Show `git log -2 --oneline` **and** the script output as evidence. If the test-only commit passes in isolation, the RED gate is violated — stop and fix before GREEN.
+
+> **tasks.yaml ledger (e45s06)** — After each task's `verify:` exits 0, update `eNNsYY-tasks.yaml`: set that task's `status: passing`. Story-level `status: passing` only when all tasks pass.
+
+### 3. Incremental Loop
+
+> **Snapshot-before-transition (e45s34):** Before each RED → GREEN or GREEN → REFACTOR transition, create a checkpoint so a failed transition can be rolled back cleanly:
+
+```bash
+bash scripts/bp-yaml-snapshot.sh specs/state.yaml   # if state changed this cycle
+git stash push -m "tdd-checkpoint-$(git rev-parse --short HEAD)-red" --keep-index 2>/dev/null || true
+```
+
+After GREEN passes and is committed, drop the stash (`git stash drop` if empty). Never refactor while RED.
+
+For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at a time. **Two commits per behavior** (test-only RED, then fix GREEN). Commit after every GREEN phase.
+
+### 4. Visual Slices (UI alternate workflow)
+
+For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See [REFERENCE.md](REFERENCE.md) for the full Visual Slices procedure.
+
+### 5. Refactor
+
+After all tests pass: extract duplication, deepen modules, apply SOLID principles. **Never refactor while RED.**
+
+### 6. Verify
+
+After every behavior cycle, run the verify command from the active epic task. Show evidence before declaring the step done.
+
+### 7. Manual Verification Handover
+
+Once all tests pass: locate the Verification Script in the active epic capsule, present it to the user step-by-step, and wait for confirmation of behavioral correctness.
+
+
+### 6a. CI dry-run sub-step
+
+If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](REFERENCE.md#ci-dry-run).
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] No test is ignored without an explicit ambiguity note (T4)
+[ ] Boundary conditions tested: empty, max, min, off-by-one (T5)
+[ ] Tests verify behavior through public interface only — no private methods (T8)
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+[ ] Every new abstraction has an explicit "Reason for Depth" justification
+[ ] Progress committed (Conventional Commits)
+[ ] verify: command passes
+```
+
+
+
+## Handoff
+
+Gate: READY -> next: verify-work
+Writes: state.yaml handoff.next_skill = verify-work
+
+## BCP Plus Integration
+
+At story completion, if the story was sized with BCP Plus (13-dimension breakdown), log the `bcp_plus.total` alongside the standard `bcps:` count in the story's tasks.yaml. The breakdown is available from the epic capsule's `bcp_plus_breakdown` field. See `docs/references/bcp-plus.md` for the full methodology and NFR Gate pattern.
+
+## Verify
+
+→ verify: `test -x scripts/verify-tdd-red-commit.sh && bash scripts/verify-tdd-red-commit.sh --self-test && grep -q 'verify-tdd-red-commit' skills/develop-tdd/SKILL.md && echo OK`
+
+
+<!-- story: e02s04 -->
+
+---
+
+# Develop TDD — Reference
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" — treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things rather than user-facing behavior
+- Tests become insensitive to real changes
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail.
+
+## TDD Phases (Detail)
+
+### Red Phase
+
+Write a failing test first:
+- Test describes the desired observable behavior through the public interface
+- Run the test to confirm it fails for the right reason (not a syntax error, not a typo)
+- Commit: `git commit -m "test(<scope>): <description>"`
+
+### Green Phase
+
+Write the minimum code to make the test pass:
+- No extra logic, no anticipated future cases, no premature optimization
+- Focus only on making the current test pass
+- Commit: `git commit -m "feat(<scope>): <description>"` or `"fix(<scope>): <description>"`
+
+### Refactor Phase
+
+Improve structure without changing behavior:
+- Extract duplication, apply SOLID principles where natural, deepen modules
+- Run tests after each refactor step to ensure behavior is preserved
+- Commit: `git commit -m "refactor(<scope>): <description>"`
+- Apply the Boy Scout Rule: leave the code cleaner than you found it
+
+## Visual Slices (UI Alternate Workflow)
+
+For UI components (SwiftUI, React, Flutter) where behavioral unit testing is brittle or low-signal:
+
+1. **Test-First Logic**: Extract logic (state transitions, formatting, validation) into a Controller, ViewModel, or Hook. This logic MUST follow pure TDD.
+2. **Visual Verification**: For the View/Component itself:
+   - **RED**: Write the component signature and a basic preview/snapshot that fails (or displays placeholder).
+   - **GREEN**: Implement the UI and verify visually via manual run, preview, or snapshot test.
+   - **REFINE**: Adjust styling and layout until it matches the design.
+3. **COMMIT**: `git commit -m "feat(ui): <component name> visual slice verified"`
+
+---
+
+# Deep Modules
+
+From "A Philosophy of Software Design":
+
+**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 interfaces, ask:
+
+- Can I reduce the number of methods?
+- Can I simplify the parameters?
+- Can I hide more complexity inside?
+
+---
+
+# Interface Design 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
+
+---
+
+# 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
+
+---
+
+# Refactor Candidates
+
+After TDD cycle, look for:
+
+- **Duplication** → Extract function/class
+- **Long methods** → Break into private helpers (keep tests on public interface)
+- **Shallow modules** → Combine or deepen
+- **Feature envy** → Move logic to where data lives
+- **Primitive obsession** → Introduce value objects
+- **Existing code** the new code reveals as problematic
+
+---
+
+# 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");
+});
+```
+
+## Clean Test Heuristics (Uncle Bob, Ch 17)
+
+Apply these specific heuristics to maintain a high-quality suite:
+
+- **T1: Insufficient Tests**: A test suite should test everything that could possibly break. Don't stop at "it seems to work."
+- **T4: Ignored Tests**: Never ignore a test without documenting the ambiguity. An ignored test is a silent warning of a gap in understanding.
+- **T5: Test Boundary Conditions**: Most bugs happen at the edges. Test the exact boundaries (e.g., empty strings, max integers, off-by-one indices).
+- **T6: Exhaustively Test Near Bugs**: Bugs congregate. If you find one, there are likely others nearby; test that area thoroughly.
+- **T9: Tests Should Be Fast**: Slow tests don't get run. Keep them fast so they remain part of the core developer loop.

package/.opencode/skills/diagnose-root/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: diagnose-root
+model: sonnet
+description: "Run 4-phase root cause analysis — reproduce, isolate, hypothesize, verify. Use when a bug is confirmed but root cause is unclear, after investigate-bug, or when user mentions root cause analysis."
+---
+
+# Diagnose Root
+
+**Boundary**: Canonical, reusable 4-phase RCA engine. Invoked by `investigate-bug` (as step 2 of the end-to-end flow) and by `fix-bug` (when no bug file exists). Does not write the bug file — that is `investigate-bug`'s responsibility.
+
+Four phases — do not skip. Update the active `specs/bugs/BUG-*.md` file at each phase.
+
+## Phases
+
+1. **Reproduce** — minimal steps; record environment; capture logs.
+2. **Isolate** — narrow to module/function; binary-search commits or config.
+3. **Hypothesize** — list ranked hypotheses with falsification test each.
+4. **Verify** — run falsification; confirm single root cause; link to fix plan.
+
+> **HARD GATE** — Do not propose a fix until phase 4 confirms one root cause with evidence.
+
+## Verify
+
+→ verify: `[ "$(grep -lE 'Reproduce' specs/bugs/BUG-*.md 2>/dev/null | grep -cv "\.okf\.md$")" -ge 1 ]`

package/.opencode/skills/diagnose-stall/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: diagnose-stall
+model: haiku
+description: "Diagnose why agent orchestration stopped producing progress — silent stalls in /loop, dispatch-agents, or execute-plan. Use when work appears hung, no output for several minutes, or a subagent never returned."
+---
+
+# Diagnose Stall
+
+> **HARD GATE** — Do NOT restart work blindly. Run this diagnostic first when orchestration goes quiet without an explicit terminal state.
+
+Explicit handler for silent stalls in long-running agent workflows (`/loop`, `dispatch-agents`, `execute-plan`, `build-epic` resume mode).
+
+## Stall signals
+
+| Signal | Likely cause |
+|--------|----------------|
+| No stdout for >5 min on a monitored loop tick | Sleep/watcher misconfigured or prompt never re-armed |
+| Subagent dispatched but no completion message | Agent hung, blocked on approval, or scope too large |
+| `dispatch-agents` cycle 3 reached with gaps | Circuit exhausted — needs human escalation |
+| Verify command running >15 min | Missing timeout or waiting on external service |
+| `handoff.next_skill` unchanged across turns | Prior skill never wrote handoff |
+
+## Process
+
+1. **Read state** — `specs/state.yaml`: `handoff.next_skill`, `active_flow`, `metrics.story_start`, open decisions.
+2. **Check locks** — `bash scripts/check-stale-locks.sh` if present; read `specs/agent-locks.yaml`.
+3. **Inspect terminals** — list background shells; note PIDs, last output timestamp, exit codes.
+4. **Classify stall type:**
+   - **waiting_approval** — tool blocked on user consent
+   - **blocked_dependency** — prior task incomplete or red gate
+   - **agent_exhausted** — max iterations/cycles reached
+   - **misconfigured_loop** — duplicate sentinel, wrong regex, or sleeper not re-armed
+   - **external_io** — network, CI, or deploy wait without timeout
+   - **unknown** — escalate with evidence bundle
+5. **Recommend recovery** — one action only (resume, kill PID, re-dispatch with smaller brief, escalate to user).
+6. **Write report** — `specs/verifications/STALL-<timestamp>.md` with classification, evidence, and recommended next skill.
+
+## Integration
+
+| Caller | When to invoke |
+|--------|----------------|
+| `/loop` (Cursor) | After two consecutive ticks with no observable progress |
+| `dispatch-agents` | When a wave exceeds expected duration with zero returns |
+| `execute-plan` | When a step checkpoint is overdue |
+| User | "Why did this stop?" / "Nothing is happening" |
+
+## Verify
+
+→ verify: `test -f specs/state.yaml`
+
+## Handoff
+
+Gate: READY → next: survey-context (if state unclear) or resume prior skill from `state.yaml`
+Writes: `specs/verifications/STALL-*.md`

package/.opencode/skills/dispatch-agents/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: dispatch-agents
+model: sonnet
+description: "Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate)."
+---
+
+# story: e09s04
+# story: e45s38
+<!-- story: e45s11 -->
+
+
+# story: e45s30
+
+# Dispatch Agents
+> **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents.
+
+
+Run multiple subagents in parallel on independent tasks. Use when tasks are genuinely decoupled — no agent needs the output of another to start.
+
+**Distinct from `delegate-task`:** This skill maximizes throughput via concurrency. There is no sequential review gate between tasks. Use `delegate-task` instead when a single task needs careful two-stage oversight before proceeding.
+
+## When to use
+
+- Tasks that can run simultaneously without shared state
+- Large plans that can be broken into parallel workstreams
+- Exploration: gather information from multiple parts of the codebase at once
+
+## When NOT to use
+
+- Task B depends on Task A's output
+- You need to review Task A before Task B can start safely
+- The tasks share a file and concurrent edits would conflict
+
+## Process
+
+### 1. Confirm independence
+
+Before dispatching, verify each task pair is truly independent:
+- No shared files being written
+- No shared state (DB migrations, config files)
+- No ordering dependency between outcomes
+
+If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead.
+
+## Subagent depth tiers (e45s30)
+
+Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief.
+
+| Tier | When | Brief shape | Token budget |
+|------|------|-------------|----------------|
+| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope |
+| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default |
+| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines |
+
+Record `depth: <tier>` in the Agent tool description when dispatching.
+
+### 2. Write typed task briefs (Orca message protocol)
+
+Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else.
+
+Every inter-agent message uses a **typed envelope** — no freeform prose between waves:
+
+| `type` | When | Required fields |
+|--------|------|-----------------|
+| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` |
+| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) |
+| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` |
+| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) |
+
+Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk):
+
+```yaml
+type: task_brief
+task_id: agent-1
+goal: [one sentence — what success looks like]
+in_scope: [explicit file or module list]
+out_of_bounds: [what NOT to touch]
+verify: [runnable command]
+prior_decisions: [relevant entries from specs/state.yaml — omit if none]
+```
+
+Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups.
+
+Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.
+
+### 3. Circuit breaker + iterative retrieval (max 3 cycles)
+
+Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`.
+
+After each wave completes:
+1. **Dispatch** — run parallel agents with typed `task_brief` envelopes.
+2. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits.
+3. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total).
+
+Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave.
+
+### 4. Dispatch in parallel
+
+Spawn all agents in a single message using multiple Agent tool calls. Each agent gets its own complete brief.
+
+```
+Agent 1: brief for task A
+Agent 2: brief for task B
+Agent 3: brief for task C
+```
+
+### 5. Collect and review results
+
+When all agents return: review each result, run verify commands, check diffs for scope violations.
+
+### 6. Integrate
+
+Merge accepted results. Resolve conflicts manually; note in summary.
+
+Report: which tasks succeeded, which need revision, overall verify status.
+
+## Verify
+→ verify: `test -f skills/dispatch-agents/SKILL.md && test -f scripts/lib/completeness-critic.sh`

package/.opencode/skills/edit-document/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: edit-document
+model: sonnet
+description: "Edit and improve documents by restructuring sections, improving clarity, and tightening prose. Use when user wants to edit, revise, restructure, or improve any document — including specs/ files, articles, READMEs, or technical writing."
+---
+
+# Edit Document
+
+**Distinct from `write-document`:** Use this skill when the document already exists and needs restructuring, clarity, or prose improvements. Use `write-document` to create a document from scratch.
+
+> **HARD GATE** — Document edits must preserve intent and accuracy. Do NOT remove or contradict existing content without understanding why it was written. Check git history for context.
+
+## Process
+
+1. First, divide the document into sections based on its headings. Think about the main points made in each section.
+
+Consider that information is a directed acyclic graph, and that pieces of information can depend on other pieces of information. Make sure that the order of the sections and their contents respects these dependencies.
+
+Confirm the sections with the user.
+
+2. For each section:
+
+2a. Rewrite the section to improve clarity, coherence, and flow. Use maximum 240 characters per paragraph.