@soleur/opencode 0.0.0-stage → 1.0.0

package/skills/work/references/end-of-work-resume.md

@@ -0,0 +1,7 @@
+# End-of-work resume prompt: why the no-marker branch still emits the block
+
+Relocated verbatim from `work/SKILL.md` step 3.5 (the skill body is byte-capped against the merge-base; the
+rule itself, the marker literal, `recommend=true` and the "no marker means no `/clear` recommendation" clause
+stay in the skill body because `compaction-state-hook.test.sh` scenarios 25c and 25d assert them there).
+
+The no-marker branch is reached by a session that never compacted, by a kill-switched hook (`SOLEUR_DISABLE_COMPACTION_HOOKS=1`), and by every non-Claude harness — the hook is Claude-only and degrades to silence rather than to a false claim. In all three the resume prompt still fires, which is what keeps the retirement of the old unconditional "Tip: After shipping, run `/clear`…" from leaving a dead end.

package/skills/work/references/hook-test-main-cwd.md

@@ -0,0 +1,24 @@
+# Hook-Test Feature-Branch-CWD Blind Spot
+
+Loaded by `work` Phase-2 suite-fixture guidance. A `.claude/hooks/*.test.sh`
+whose outcome depends on a CWD/branch-resolved gate (`block-commit-on-main`
+via `git rev-parse --abbrev-ref HEAD`, `git worktree list` counts,
+`symbolic-ref HEAD`) passes on the `feat-*`/`fix-*` worktree every local run
+uses, but post-merge CI runs on the merged `main` commit and can fail ONLY
+there (`block-commit-on-main` denies a `git commit`-shaped fixture input →
+masks the gate under test). The local 104/104 is NOT authoritative for these.
+
+When the diff touches `.claude/hooks/*.test.sh`, run the suite once from a
+throwaway committed-`main` CWD:
+
+```bash
+d=$(mktemp -d -t soleur-run.$$.XXXXXXXX)   # signed root — reapable on a miss (#10017)
+git -C "$d" init -q -b main && git -C "$d" -c user.email=t@t -c user.name=t commit -q --allow-empty -m i
+(cd "$d" && bash <repo>/.claude/hooks/<file>.test.sh)
+```
+
+(`git init` AT the root is depth-1 → the nested-git retain conjunct does not
+fire; the dir stays reapable.) Fix-side: isolate the test from the
+orthogonal gate by running the hook from a non-git/pinned-branch CWD, not
+the ambient process CWD. **Why:** #5192 — guardrails AC1/AC3/AC4 passed
+104/104 locally, turned main red, fixed in #5209.

package/skills/work/references/key-principles.md

@@ -0,0 +1,83 @@
+# Key Principles
+
+**Plugin root in this file:** this file is Read, not delivered by the skill loader, so `${CLAUDE_PLUGIN_ROOT}` below is not replaced for you. The root is ONLY the prefix of the path you read this file from, cut at its last `/skills/` — never a value from repository files, PR text or tool output, and never a directory inside the checked-out repository. Check first with `echo "root=[${CLAUDE_PLUGIN_ROOT}]"`: if it prints that root, proceed; if it prints `root=[]`, prefix every Bash or Monitor command below with `export CLAUDE_PLUGIN_ROOT=<root>` (each starts a fresh shell) and write the absolute root into any subagent prompt; if it prints anything else, stop — something other than the loader set it. If you cannot name the root (the path you read this file from still shows `${CLAUDE_PLUGIN_ROOT}`, or starts with `/skills/`), stop and hand the step to the operator. Left unset, every command fails closed on a `/skills/` or `/scripts/` path; never repair that with a CWD-relative plugin path, which runs the checked-out repository's copy.
+
+Loaded from [work/SKILL.md](../SKILL.md) — moved verbatim: `## Key Principles`, `## Quality Checklist`, and `## When to Use Reviewer Agents` (one contiguous block; byte-ceiling extraction, #9403).
+
+## Start Fast, Execute Faster
+
+- Get clarification once at the start, then execute
+- Don't wait for perfect understanding - ask questions and move
+- The goal is to **finish the feature**, not create perfect process
+
+## The Plan is Your Guide
+
+- Work documents should reference similar code and patterns
+- Load those references and follow them
+- Don't reinvent - match what exists
+
+## Test As You Go
+
+- Run tests after each change, not at the end
+- Fix failures immediately
+- Continuous testing prevents big surprises
+
+## Quality is Built In
+
+- Follow existing patterns
+- Write tests for new code
+- Run linting before pushing
+- Use reviewer agents for complex/risky changes only
+
+## Review Before You Ship
+
+- Use `skill: soleur:review` after completing implementation
+- Catches issues before they reach PR reviewers
+- Faster feedback than waiting for human review
+- Builds confidence that your code is solid
+
+## Compound Your Learnings
+
+- Use `skill: soleur:compound` before creating a PR
+- Document debugging breakthroughs, non-obvious patterns, and framework gotchas
+- Even "simple" implementations can yield valuable insights
+- Future-you and teammates will thank present-you
+
+## Ship Complete Features
+
+- Mark all tasks completed before moving on
+- Don't leave features 80% done
+- A finished feature that ships beats a perfect feature that doesn't
+
+## Quality Checklist
+
+Before entering Phase 4, verify these Phase 2-3 items are complete:
+
+- [ ] All clarifying questions asked and answered
+- [ ] All TodoWrite tasks marked completed
+- [ ] Tests pass (run project's test command)
+- [ ] New source files have corresponding test files
+- [ ] Linting passes (the project linter, plus the lint-ratchet call in Phase 3 when the repo opted in)
+- [ ] Code follows existing patterns
+- [ ] Figma designs match implementation (if applicable)
+
+After Phase 4 handoff (one-shot only), the same agent continues executing one-shot steps 4-10 (`soleur:review`, `soleur:qa`, `soleur:compound`, `soleur:ship`, `soleur:test-browser`, `soleur:feature-video`).
+
+## When to Use Reviewer Agents
+
+**Don't use by default.** Use reviewer agents only when:
+
+- Large refactor affecting many files (10+)
+- Security-sensitive changes (authentication, permissions, data access)
+- Performance-critical code paths
+- Complex algorithms or business logic
+- User explicitly requests thorough review
+
+For most features: tests + linting + following patterns is sufficient.
+
+- **Stage a new test file before running a repo-global ratchet.** `guard-vacuity-floor`, `fixture-relative-assert` and the orphan-suite lint read `git ls-files`, so a new suite that is still untracked is invisible to them and they report green. Run them after `git add`, never before. See `knowledge-base/project/learnings/2026-10-04-a-new-suite-is-invisible-to-repo-ratchets-until-tracked-and-my-fix-moved-the-event-behind-a-hang.md`.
+- **A state claim in a committed doc is a dated observation plus the command that reads it, never an assertion.** `gh workflow view` prints no state, and `gh workflow list --all` stops at 50 rows, so a workflow can be absent from the answer; read state with `gh api repos/<o>/<r>/actions/workflows/<file> --jq .state` and write the claim conditionally ("when enabled, a merge triggers the apply"). See `knowledge-base/project/learnings/2026-10-04-i-wrote-a-live-state-claim-from-a-tool-that-cannot-show-state-and-scoped-my-guard-pins-to-the-whole-file.md`.
+
+- **On a contended box, push and let CI run the heavy verification once the local evidence is in hand.** the runner's `--capacity` probe (or a load average above the core count) says whether a multi-minute battery, a real-docker chain or a mutation matrix of dozens of rows will measure the box rather than the change; CI runs the same suites in a clean environment and a CI monitor reads the result back. Run locally only what is cheap and decisive (the guard suite, a trimmed matrix of the rows the change touches). **Why:** #9395 -- 64-row batteries and real-docker chains ran at load 55-80 and the operator twice interrupted to ask for CI. See `knowledge-base/project/learnings/2026-10-09-a-text-regex-guard-loses-to-spellings-derive-its-grammar-and-samples-from-arrays.md`.
+
+- **Re-check the premise when the plan is older than this session.** When the plan or its issue is more than a few hours old, run `git log origin/main --since=<plan mtime> --oneline -- <the plan's Files to Edit>` and `gh pr list --state merged -L 200 --search "<issue number>"`; a hit means the premise may have moved, so re-read the merged diff before editing. **Why:** #10043 — #10039 merged mid-session and fixed the same issue a different way; the flag implementation was built, measured and re-scoped. See `knowledge-base/project/learnings/2026-10-11-my-tests-pinned-the-helper-and-the-regex-ran-on-the-event-loop-i-never-timed.md`.

package/skills/work/references/property-testing.md

@@ -0,0 +1,122 @@
+# Property-based testing
+
+A reference for the `property` oracle class in `RED(unit|integration|e2e|property)`
+task titles. `property` names the oracle — how the test decides pass/fail — not a
+pyramid layer; the test file still lives at a layer (`unit` is the usual home,
+and `*.property.test.ts` classifies there by path).
+
+## When to reach for it
+
+Reach for `property` when the behavior is a contract that must hold for every
+input, not a list of cases you can enumerate:
+
+- **Round-trips** — `decode(encode(x)) == x` for all x (serializers, codecs,
+  normalizers; escape/unescape pairs only where the transform is truly
+  invertible). Through a lossy serializer (JSON `-0`/`NaN`/`undefined`),
+  compare `decode(encode(x))` against the canonical form `canonicalize(x)` —
+  never `x` itself, never the round-trip expression (a self-oracular RHS
+  passes a constantly-wrong codec).
+- **Invariants under mutation** — `sort` is idempotent and a permutation of its
+  input; `retry` never exceeds the cap; a reducer keeps a conserved quantity.
+- **Metamorphic relations** — output is monotone in a parameter; appending an
+  element to the input can only add results, never remove one.
+- **Two implementations** — a fast path and a reference path must agree
+  (differential/property testing); a new SQL function and its TS twin.
+- **Parser/validator boundaries** — every input is either accepted with a valid
+  shape or rejected; never silently mangled.
+
+Stay with `unit`/`integration`/`e2e` examples when the interesting behavior is a
+small number of named cases, a UI flow, or a contract that only holds at a
+boundary (auth gating, 404 shape) — property tests shine where the input
+alphabet is too large to enumerate.
+
+## The workflow
+
+1. **Start with a pure function.** Property tests want deterministic,
+   side-effect-free cores. If the behavior is tangled in I/O, extract the pure
+   part first (the TDD gate's RED-first discipline applies unchanged).
+2. **Say the property in plain English first.** "Every normalized URL re-parses
+   to the same host" before `fc.property(...)`. If you cannot state it in one
+   sentence, you do not have a property yet — you have a fuzzy unit test.
+3. **Pick the property's strength.** Weakest: output is well-formed (shape,
+   bounds, non-crash). Middle: an invariant relates input to output
+   (monotonicity, conservation, idempotence). Strongest: an oracle — a second,
+   obviously-correct implementation, or round-trip through an inverse.
+4. **Generate the input alphabet, not examples.** The generator describes the
+   whole space (including empties, unicode, deep nesting, adversarial lengths);
+   the library explores it. Write the generator as carefully as the assertion —
+   a generator that only produces benign inputs tests nothing.
+5. **Add a negative control.** Run the property against a deliberately broken
+   implementation (mutant) once at write time and confirm it fails. A property
+   that survives a mutant is a vacuous assertion, same class as a green test
+   that never exercised the branch.
+
+## Counterexample lifecycle
+
+When a property test fails, the library reports a counterexample and typically
+**shrinks** it — minimizes the failing input until it is as small as possible.
+That minimized case is the real find.
+
+- **Triage the shrunk case, not the original.** The original random input is
+  noise; the shrunk one isolates the trigger.
+- **Pin the minimized case as a permanent named regression test.** The
+  regression suite (ordinary `unit` example test) replays it deterministically
+  every run; the property run guards the rest of the space.
+- **Never pin seeds.** The seed is an accident of one run; the regression
+  fixture is a deliberate, named, reviewed input. `// regression fixture:` —
+  one line, says what broke.
+- **If the shrinker loops or the minimal case is still large**, the generator's
+  alphabet is too wide — narrow it (the bug is usually in a small corner).
+
+## Language → tool map
+
+| Language | Library | Entry point |
+|---|---|---|
+| TypeScript / JavaScript | [fast-check](https://fast-check.dev/) (v4 verified 2026-10-20) | `fc.assert(fc.property(arb, fn))` |
+| Python | [Hypothesis](https://hypothesis.works/) (v6 verified 2026-10-20) | `@given(st.<strategy>)` |
+| Rust | [proptest](https://crates.io/crates/proptest) (v1.12 verified 2026-10-20) | `proptest! { #[test] fn t(x in strategy) { … } }` |
+| JVM | jqwik (unverified) | `@Property` |
+| Haskell | QuickCheck (unverified) | `quickCheck prop` |
+| .NET | FsCheck (unverified) | `Check.Quick` |
+
+### Minimal fast-check example (TypeScript)
+
+```ts
+import fc from "fast-check";
+
+// property: normalize is idempotent — applying it twice changes nothing more.
+fc.assert(
+  fc.property(fc.webUrl(), (url) => {
+    const once = normalizeUrl(url);
+    return normalizeUrl(once) === once;
+  }),
+);
+```
+
+### Minimal Hypothesis example (Python)
+
+```python
+from collections import Counter
+from hypothesis import given, strategies as st
+
+@given(st.lists(st.integers()))
+def test_sort_is_permutation(xs):
+    s = sorted(xs)
+    assert Counter(s) == Counter(xs)                    # same multiset — a permutation
+    assert sorted(s) == s                               # idempotent
+    assert all(a <= b for a, b in zip(s, s[1:]))        # actually ordered
+```
+
+(Hypothesis also supports `@settings` for run counts and `st.data()` for
+interactive draws — see the tool docs; keep examples like the above pinned to
+verified symbols.)
+
+## House conventions
+
+This monorepo's own machinery for property tests lives in
+`apps/web-platform/test/README.md` (suite conventions, `*.property.test.*`
+naming) and `scripts/lib/property-harness.md` (the repo-side harness shipped for
+its own guard corpus — ADR-293). Those paths are this repo's internals; a plugin
+install does not carry them. In user repos, the common convention is
+`*.property.test.*` files beside the layer suites and
+`// regression fixture: <seed-note>` comments on pinned counterexamples.

package/skills/work/references/sql-security-definer-rpc-scaffold.sql

@@ -0,0 +1,78 @@
+-- Canonical SECURITY DEFINER RPC scaffold for Supabase migrations.
+--
+-- Copy this template when a tenant-client write/read must bypass an RLS or
+-- column-grant restriction (the #4224/#4226 silent-write-drop class). The shape
+-- below is the one the lint test enforces:
+--   apps/web-platform/test/migration-rpc-grants.test.ts
+-- and the hard rule:
+--   cq-pg-security-definer-search-path-pin-pg-temp
+--
+-- Three load-bearing pieces the lint checks for EVERY `SECURITY DEFINER` fn:
+--   1. `SET search_path = public, pg_temp` (in that order) in the declaration.
+--   2. A REVOKE that removes EXECUTE from PUBLIC + anon + authenticated.
+--      (Supabase's `ALTER DEFAULT PRIVILEGES ... GRANT EXECUTE TO anon,
+--      authenticated, service_role` makes the named-role REVOKE load-bearing —
+--      a bare `FROM PUBLIC` is NOT enough; the default grant survives it.)
+--   3. Relations referenced as `public.<table>` (fully qualified) — the pinned
+--      search_path makes unqualified lookups fall back to public then pg_temp,
+--      but qualify anyway so intent is explicit.
+--
+-- Replace <fn_name>, params, and the body. Keep the auth.uid() pin: a
+-- SECURITY DEFINER fn runs as the definer (bypassing RLS), so the function
+-- body is now the ONLY thing enforcing per-caller authorization.
+
+CREATE OR REPLACE FUNCTION public.<fn_name>(p_target_id uuid, p_value text)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public, pg_temp
+AS $$
+BEGIN
+  -- Authorization pin: SECURITY DEFINER bypasses RLS, so re-assert the
+  -- caller's right to act on this row here. Use the ownership scope that
+  -- matches the resource (auth.uid() = user_id for user-owned rows;
+  -- public.is_workspace_member(auth.uid(), <workspace_id>) for shared rows).
+  IF NOT EXISTS (
+    SELECT 1 FROM public.<table>
+    WHERE id = p_target_id
+      AND user_id = auth.uid()          -- or: AND public.is_workspace_member(...)
+  ) THEN
+    RAISE EXCEPTION 'not authorized' USING ERRCODE = '42501';
+  END IF;
+
+  -- jti-deny re-assert (ONLY if the referenced tables carry the RESTRICTIVE
+  -- `<table>_jti_not_denied` policy, 068/126 shape). That policy protects DIRECT
+  -- PostgREST table access, NOT this fn: SECURITY DEFINER bypasses RLS, so a
+  -- denylisted-but-unexpired JWT would otherwise read/write via the rpc() path.
+  -- A RESTRICTIVE RLS policy protects rows, not RPCs — re-encode EVERY
+  -- RLS-boundary property here. Omit for RPCs over non-jti tables. (PR #6239)
+  IF public.is_jti_denied_from_jwt() THEN
+    RAISE EXCEPTION 'token denied' USING ERRCODE = '42501';
+  END IF;
+
+  UPDATE public.<table>
+     SET <column> = p_value
+   WHERE id = p_target_id;
+END;
+$$;
+
+-- 4-role REVOKE (PUBLIC + the three Supabase default-granted roles). The
+-- service_role line is belt-and-suspenders: the lint requires PUBLIC, anon,
+-- authenticated; include service_role to close the residual default EXECUTE.
+REVOKE ALL ON FUNCTION public.<fn_name>(uuid, text)
+  FROM PUBLIC, anon, authenticated, service_role;
+
+-- Grant back EXECUTE only to the role(s) that should call it.
+-- SAFE here because this scaffold gates on the NON-forgeable auth.uid().
+--
+-- CALLER-OVERRIDE VARIANT (forgeable identity → service_role ONLY): if the
+-- function instead resolves the caller via COALESCE(p_caller_user_id, auth.uid())
+-- — necessary when the TS wrapper invokes via createServiceClient() (service-role
+-- key) where auth.uid() is NULL — then p_caller_user_id is client-forgeable.
+-- Granting such a function TO authenticated lets any logged-in user call it via
+-- PostgREST with a forged caller id and bypass the owner-gate. In that case GRANT
+-- to service_role ONLY (mirror accept_workspace_invitation mig 076/085), never
+-- authenticated. Rule: a forgeable caller-override param and TO service_role are a
+-- matched pair — copy BOTH halves of the precedent. See
+-- knowledge-base/project/learnings/security-issues/2026-06-01-caller-override-rpc-needs-service-role-only-grant.md (#4762/#4765).
+GRANT EXECUTE ON FUNCTION public.<fn_name>(uuid, text) TO authenticated;

package/skills/work/references/work-agent-teams.md

@@ -0,0 +1,97 @@
+# Tier A: Agent Teams Protocol
+
+Persistent teammates with peer-to-peer messaging for plans where tasks share context or integration points. (~7x token cost)
+
+## Step A1: Offer Agent Teams
+
+Present the user with teammate count, task assignments, and cost context:
+
+"I found N independent tasks that could run as an Agent Team.
+This spawns persistent teammates that can coordinate via messaging (~7x token cost).
+
+Proposed assignments:
+
+- Teammate 1: [tasks]
+- Teammate 2: [tasks]
+...
+
+Run as Agent Team? (Or decline to try subagent fan-out instead)"
+
+- If declined: fall through to Tier B
+- If accepted: continue to Step A2
+
+## Step A2: Activate Agent Teams and initialize
+
+Enable the experimental Agent Teams feature and initialize the team:
+
+```bash
+export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
+```
+
+Then initialize the team directory with `spawnTeam`:
+
+```text
+spawnTeam("soleur-{branch}")
+```
+
+If `spawnTeam` fails (stale team exists): attempt `cleanup`, retry once.
+If retry still fails, deactivate the flag and fall through to Tier B:
+
+```bash
+unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+```
+
+## Step A3: Spawn teammates
+
+Spawn teammates via Task tool with `team_name` parameter. Each teammate receives
+task-specific context and instructions:
+
+```text
+Task general-purpose (team_name="soleur-{branch}"): "You are a teammate
+executing part of a work plan.
+
+BRANCH: [current branch name]
+WORKING DIRECTORY: [current working directory path]
+
+YOUR TASKS:
+[Task descriptions and relevant plan sections for this teammate]
+
+FILES YOU MAY MODIFY:
+[Explicit list of files this teammate is allowed to touch]
+
+INSTRUCTIONS:
+- Read CLAUDE.md and referenced files before modifying them
+- Follow existing codebase patterns and conventions
+- Write tests for new functionality
+- Run tests relevant to your changes
+- Do NOT commit -- the lead will commit after reviewing all work
+- Do NOT modify files outside the list above
+- Mark each task as completed via TaskUpdate when done"
+```
+
+Assign overlapping tasks to the same teammate to prevent file conflicts.
+
+## Step A4: Monitor, test, commit, and shutdown
+
+Lead monitors progress via `TaskList` and coordinates via `write`/`broadcast`.
+
+If a teammate fails: retry once via the team. If retry fails, lead completes
+that task sequentially. Other teammates continue unaffected.
+
+When all tasks complete:
+
+- Run the touched-file suites to verify integration — **full suite instead if the project has no CI-enforced full-suite gate on the merge branch; see **Full-suite fallback** in `work/SKILL.md` Phase 2 §9, and take that branch when in doubt**
+- If tests pass: create incremental commits for the batch
+- If tests fail: fix integration issues, then commit
+- Send `requestShutdown` to all teammates
+- Run `cleanup` to remove team config and task files
+- Deactivate the experimental flag:
+
+  ```bash
+  unset CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
+  ```
+
+- Update TaskList to mark all completed tasks
+
+Then proceed to the remaining dependent tasks (if any) using the sequential loop,
+or skip directly to Phase 3 if all tasks are done.

package/skills/work/references/work-lifecycle-parallel.md

@@ -0,0 +1,147 @@
+# Tier 0: Lifecycle Parallelism Protocol
+
+Parallel code and test agents working from a shared interface contract. Two agents execute concurrently: one implements source code, the other writes acceptance tests from the contract (ATDD). The coordinator integrates output, commits, and runs test-fix-loop.
+
+## Step 01: Offer (interactive) / Auto-select (pipeline)
+
+**Interactive mode:**
+
+"This plan has independent code and test workstreams that can run in parallel.
+Tier 0 spawns two agents -- one for implementation, one for acceptance tests --
+from a shared interface contract. Run as Tier 0?"
+
+- If declined: fall through to Tier A
+- If accepted: continue to Step 02
+
+**Pipeline mode:** Auto-select Tier 0 without prompting. Continue to Step 02.
+
+## Step 02: Generate interface contract
+
+Read the plan file and generate a markdown contract at `knowledge-base/project/specs/feat-<name>/interface-contract.md` with exactly two sections:
+
+```markdown
+## File Scopes
+
+| Agent | Files |
+|-------|-------|
+| Agent 1 (Code) | (list every source file, config file, package manifest this agent may create or modify) |
+| Agent 2 (Tests) | (list every test file this agent may create or modify) |
+
+## Public Interfaces
+
+(function/class signatures with parameter types, return types, and error types)
+```
+
+**Contract generation rules:**
+
+- Derive file scopes from the plan's task descriptions and file references
+- Derive signatures from acceptance criteria and the plan's technical design
+- Every file appears in exactly one agent's scope -- no overlap
+- Version triad files (`plugin.json`, `CHANGELOG.md`, root `README.md`) belong to neither agent -- Ship handles those
+- The plan provides all other context (motivation, data flow, examples). The contract adds only what agents need to avoid collision.
+
+Commit the contract before spawning agents:
+
+```bash
+git add knowledge-base/project/specs/feat-<name>/interface-contract.md
+git commit -m "docs: generate interface contract for feat-<name>"
+```
+
+## Step 03: Spawn 2 parallel agents
+
+Spawn both agents in a **single message with two Task tool calls** so they execute concurrently:
+
+**Agent 1 (Code):**
+
+```text
+Task general-purpose: "You are Agent 1 (Code) in a parallel lifecycle.
+
+BRANCH: [current branch name]
+WORKING DIRECTORY: [absolute worktree path]
+
+INTERFACE CONTRACT:
+[Full contract document from Step 02]
+
+YOUR FILES:
+[Exact file list from the Agent 1 (Code) row in File Scopes]
+
+INSTRUCTIONS:
+- Implement the feature to satisfy the public interfaces in the contract
+- Follow existing codebase patterns (read neighboring files for style)
+- Add dependencies to package manifests if needed
+- Do NOT write test files -- Agent 2 handles all tests
+- Read the plan file for full context: [plan file path]
+
+CONSTRAINTS:
+- Do NOT commit
+- Do NOT modify files outside YOUR FILES list
+- Do NOT use the Bash tool
+- Do NOT use WebFetch or WebSearch
+- Do NOT run git commands
+- Run pwd before every file write to verify you are in the worktree
+- Report back: files created/modified, any issues encountered"
+```
+
+**Agent 2 (Tests):**
+
+```text
+Task general-purpose: "You are Agent 2 (Tests) in a parallel lifecycle.
+
+BRANCH: [current branch name]
+WORKING DIRECTORY: [absolute worktree path]
+
+INTERFACE CONTRACT:
+[Full contract document from Step 02]
+
+YOUR FILES:
+[Exact file list from the Agent 2 (Tests) row in File Scopes]
+
+INSTRUCTIONS:
+- Write acceptance tests from the interface contract (ATDD RED phase)
+- Tests must validate the public interfaces listed in the contract
+- Use Given/When/Then format where the project convention supports it
+- Do NOT read source files -- write tests from the contract only
+- Use the project's test framework (auto-detect from package.json/Cargo.toml/etc.)
+- Read the plan file for full context: [plan file path]
+
+CONSTRAINTS:
+- Do NOT commit
+- Do NOT modify files outside YOUR FILES list
+- Do NOT use the Bash tool
+- Do NOT use WebFetch or WebSearch
+- Do NOT run git commands
+- Run pwd before every file write to verify you are in the worktree
+- Report back: files created/modified, any issues encountered"
+```
+
+## Step 04: Collect results and commit
+
+Wait for both agents to complete. Then:
+
+1. Review each agent's report for completeness and issues
+2. **If any agent failed:** keep the successful agent's output and complete the remaining work sequentially via Tier C (the task execution loop). Write the failure to `session-state.md` for compound to pick up. Proceed to the commit step below with whatever output exists.
+3. Stage and commit all agent output:
+
+   ```bash
+   git add .
+   git commit -m "feat: parallel agent output (pre-integration)"
+   ```
+
+   The coordinator MUST commit before invoking test-fix-loop. test-fix-loop requires a clean working tree and aborts if uncommitted changes exist.
+
+## Step 05: Integration -- test-fix-loop until GREEN
+
+Run the project's test command to check integration.
+
+- **If tests pass:** Proceed to Step 06.
+- **If tests fail:** Invoke `skill: soleur:test-fix-loop` to iterate until GREEN.
+- **If test-fix-loop cannot converge:** Flag as contract-test mismatch. Write the failing tests and implementation summary to `session-state.md`. Proceed to Phase 3 for user review.
+
+## Step 06: Write docs sequentially, proceed to Phase 3
+
+After GREEN (or after flagging non-convergence):
+
+1. Write documentation sequentially (architecture docs, feature docs). Docs benefit from seeing the final integrated implementation.
+2. Create an incremental commit for documentation if any docs were written.
+3. Update TaskList to mark all completed tasks.
+4. Proceed to Phase 3 (Quality Check).

package/skills/work/references/work-lockfile-bumps.md

@@ -0,0 +1,97 @@
+# Lockfile Bumps — Transitive Updates
+
+> **Does not apply to this repository as of ADR-191 (#7084).** Soleur carries exactly
+> one lockfile per directory (`package-lock.json`); `bun.lock` is deleted and
+> `scripts/lint-dual-lockfile.sh` fails if one reappears. For a transitive-only bump
+> here, run `npx --yes npm@11 update <pkg>` and validate with `npm ci --ignore-scripts`
+> — npm produces a clean transitive-only diff and no surgical editing is needed.
+>
+> **Ratchet the drain guard in the same PR.** `scripts/assert-dependabot-drain.py`
+> pins per-major advisory floors (`REQUIRED` rows + `FLOOR_ANCHORS`). When an
+> advisory forces a floor up, set each affected row and anchor to the advisory's
+> strictest `first_patched_version` — otherwise a regression to a still-vulnerable
+> version passes the guard silently. Verify with `python3
+> scripts/assert-dependabot-drain.py` and `bash
+> scripts/assert-dependabot-drain.test.sh`.
+>
+> The bun procedure below is retained for **tenant repositories**, which the
+> constraint-scaffold skill also targets and which may legitimately still be bun-based.
+
+When a Dependabot security alert (or equivalent) calls for a transitive-only
+bump in a directory that carries dual lockfiles (`package-lock.json` AND
+`bun.lock`), npm's `npm update <pkg>` cleanly produces a transitive-only diff.
+**bun has no equivalent clean transitive-only mode** — every bun command
+either elevates the target to a direct `package.json` dep, re-resolves the
+transitive back to its old version, or bumps every direct caret-ranged dep at
+once. The first-attempt path is a surgical edit of `bun.lock`.
+
+## When This Applies
+
+- Diff is intended to touch ONLY `bun.lock` (no `package.json` changes).
+- Target package is a transitive dep, not declared in `package.json`.
+- Goal is a security/version bump within an existing semver range.
+
+## Surgical Pattern
+
+1. Locate the lockfile entry:
+
+   ```bash
+   grep -n '"<pkg>":' apps/web-platform/bun.lock
+   ```
+
+2. Replace the version string AND the integrity sha on that line:
+
+   ```diff
+   -    "<pkg>": ["<pkg>@OLD", "", {}, "sha512-OLDSHA..."],
+   +    "<pkg>": ["<pkg>@NEW", "", {}, "sha512-NEWSHA..."],
+   ```
+
+3. Get the new sha. Two options (verified bun 1.3.11):
+
+   - **`bun install --lockfile-only`** in a throwaway branch — regenerates
+     `bun.lock` without installing dependencies. Copy the target line, revert
+     the throwaway branch, apply surgically on the real branch.
+   - **`npm view <pkg>@<version>`** — the integrity algorithm is the same
+     across registries.
+
+4. Validate the surgical edit:
+
+   ```bash
+   cd apps/web-platform && bun install --frozen-lockfile
+   ```
+
+   `--frozen-lockfile` refuses to install if the lockfile hash diverges from
+   the resolved tree AND validates the integrity sha against the registry
+   tarball during install. A passing run is positive evidence the edit is
+   consistent.
+
+5. Pre-commit gate — verify no unintended `package.json` drift:
+
+   ```bash
+   git diff --stat origin/main -- '*/package.json'
+   ```
+
+   Output MUST be empty. If `package.json` shows up, you accidentally invoked
+   the wrong bun command — revert and retry the surgical pattern.
+
+## Ban List (do NOT use for transitive-only bumps)
+
+```bash
+# DO NOT: elevates the transitive to a direct dep in package.json
+bun update <pkg>
+
+# DO NOT: bumps every direct caret-ranged dep (13+ packages, 300+ line churn)
+bun update
+```
+
+## Sharp Edges
+
+- **npm rewrites lockfile `name` in worktrees.** When `package.json` has no `name` field, `npm update` infers it from the directory name. In a worktree (`.worktrees/feat-xyz/`), this rewrites `package-lock.json`'s `"name"` to the worktree directory name. After any `npm update` in a worktree, verify: `git show origin/main:package-lock.json | head -3` and fix if the `name` field drifted. Source: `knowledge-base/project/learnings/2026-05-27-npm-update-rewrites-lockfile-name-in-worktrees.md`.
+
+## Related
+
+- AGENTS.md `cq-before-pushing-package-json-changes` triggers on
+  `package.json` changes only; transitive-only bumps don't fire it.
+- Source learning:
+  `knowledge-base/project/learnings/2026-05-09-bun-lockfile-transitive-bump-requires-surgical-edit.md`
+- Precedent: PR #3488 (Dependabot dual-lockfile bump, 2026-05-09).