@webpresso/plugin-antigravity 0.0.0-stage → 0.0.17

package/skills/fix/SKILL.md

@@ -0,0 +1,218 @@
+---
+type: skill
+slug: fix
+title: Fix
+status: active
+scope: repo
+applies_to: [agents]
+related: [verify, testing-philosophy]
+created: "2026-05-13"
+last_reviewed: "2026-07-21"
+name: fix
+description: "Root-cause fix (investigate first if proof missing). Use for fix, blockers, root cause not symptom."
+argument-hint: '<target> where target is: file|symptom|error|test|"free-text description"'
+---
+
+# Fix Command
+
+## Use when (freeform)
+
+- "fix", "root cause not symptom", "blockers", "pre-existing issue"
+- "tooling inefficiency", "MCP not bin/wp", "hook resistance" (bounded — see opportunistic budget)
+- diagnosis already done or `investigate` will run inline first
+
+Fix the issue at its root, future-proof, aligned with repo philosophy.
+
+**Arguments**: $ARGUMENTS
+
+This command turns "please fix it well" into an enforceable workflow: diagnose
+first, repair at the owner, prove the repair, and escalate to `/verify` when
+the blast radius is broader than a local fix.
+
+## Tooling map
+
+| Need                   | Prefer                                                             |
+| ---------------------- | ------------------------------------------------------------------ |
+| Reproduce / large logs | `session_execute`, `session_batch_execute`, `session_execute_file` |
+| Recall prior evidence  | `session_search`, `session_restore`, `session_retrieve`            |
+| Capture decisions      | `session_capture` (do not paste full reports back as user text)    |
+| Scoped proof           | `test`, `lint`, `typecheck`, or `qa`                               |
+| Audits                 | `audit` / `audits`                                                 |
+| Worktree isolation     | `blueprint_put` / `worktree` — never thrash primary checkout       |
+| PR follow-up           | `pr_status`, `pr_upsert` when landing the fix                      |
+
+## Non-negotiable invariants
+
+1. **Root cause, not symptom.** Trace the failure to the invariant that actually broke. Do not patch callers when the owner is fixable.
+2. **Loud failures, no silent fallbacks.** No default shims, sentinel returns, or catch-and-continue behavior that hides missing config, bad state, or broken boundaries.
+3. **Use the repo's real execution surface.** Prefer wp MCP tools and repo wrappers over host Bash for search/test/lint. Use bounded session-memory paths for large output.
+4. **Regression proof is mandatory.** Add or strengthen a test or other reliable proof that would fail against the old behavior.
+5. **Raising timeouts is not a fix.** If a timeout fires, investigate the bottleneck. Only raise a bound when the repo already documents that workload and you can cite measurement.
+6. **Zero suppressions, zero papering over.** No lint disables, ts-ignore, compat aliases, or "temporary" branches to sneak the fix through.
+7. **Minimal correct diff.** Update every consumer of a changed contract in the same change, but do not bundle unrelated cleanup.
+8. **Primary checkout is sacred.** If HEAD is detached, primary is dirty with unrelated work, or you are not on a managed worktree for non-trivial edits → **stop** and move to `worktree` / blueprint owner. Never leave the primary checkout broken.
+
+## Opportunistic fix budget (when called from ultragoal / autopilot)
+
+- At most **`fix_budget` (default 1)** pre-existing issues per controller phase.
+- Each must have: named invariant, failing proof, owning path.
+- If the repair needs its own blueprint or expands epic scope → **handoff backlog**, do not inline.
+- Additional discoveries: list in the final report; do not thrash.
+- **Tooling / harness findings** ("fix inefficiency you come across", MCP vs shell,
+  hook thrash) honor the same budget. Excess → record via the `tech-debt` skill
+  (or backlog handoff); do not expand the current epic unbounded.
+- Prefer wp MCP tools and session-memory tools over the `wp` CLI / raw shell for
+  quality and discovery paths (see tooling map).
+
+## Protocol
+
+### Step 0a — Worktree preflight
+
+Before editing: confirm you are on a managed worktree or an explicitly allowed branch.
+If the primary checkout is dirty/detached with unrelated state, stop and isolate first.
+
+### Step 0 — Run the investigate phase when evidence is missing
+
+Before editing, check whether the current context already contains all of the
+following:
+
+- a named root-cause hypothesis
+- a failing proof tied to that hypothesis
+- the owning boundary that should be repaired
+
+If any of those are missing, run the `investigate` phase inline first:
+
+- reproduce or capture the failure
+- read the full error site and one nearby working pattern
+- disconfirm cheap alternative explanations
+- produce failing proof
+- stop only when you can name the broken invariant and owner
+
+Do not skip this phase because the fix "looks obvious". If the evidence is not
+there, the investigation work is part of `fix`.
+
+### Step 1 — Reproduce and name the broken invariant
+
+- Run the exact command, test, or user flow that surfaces the failure.
+- Capture the evidence that matters: error text, file:line, exit code, failing assertion, or log path.
+- Read enough surrounding code to say the broken invariant in one sentence.
+- If the issue is nondeterministic, gather evidence until you can describe the slow/flaky/failing case without guessing.
+
+**Prove the mechanism before naming it.** A cause that merely explains the
+symptom is a hypothesis, not a finding. Run the failing thing with the candidate
+values and read what it actually did; trace the claim to the code that executes,
+not the code whose name matches the theory. If you cannot reproduce it, label it
+unverified and keep investigating — do not write it into a plan, commit, or
+report as the cause.
+
+**When a cause is disproved, go back to the command, not to the next story.**
+Substituting another plausible explanation without new observation is how one
+dead route gets three confident, wrong diagnoses. If your second and third
+explanations are still unobserved, you have not reproduced the failure yet.
+Related: `catalog/agent/rules/evidence-discipline.md` § 6.
+
+If the "issue" is actually several unrelated failures, stop and ask which one to fix first.
+
+### Step 2 — Decide where the fix belongs
+
+State briefly:
+
+- the broken invariant
+- the owner that should enforce it
+- whether the fix changes a public contract
+- which direct consumers must change in the same diff
+
+If the blast radius is broader than the owner + direct consumers, keep going with `/fix` only if the change is still one coherent repair. If the work becomes a broader hardening pass, plan a `/verify` handoff before claiming done.
+
+### Step 3 — Write failing proof first when feasible
+
+- For a reproducible bug, write or strengthen the smallest regression test that fails on the old behavior.
+- Verify that it fails for the right reason before changing production code.
+- If test-first is genuinely infeasible at that boundary, record why and create the nearest reliable proof instead (for example a deterministic integration reproduction, fixture, or logged command).
+
+Do not keep production code written before the test as "reference". If you wrote code first, throw it away and restart from the failing proof.
+
+### Step 4 — Implement the minimal correct fix
+
+- Edit the file or module that owns the invariant.
+- Update every changed consumer in the same diff. No half-migrations.
+- Delete compat shims, dead aliases, and TODO branches made obsolete by the repair.
+- Keep complexity down by extracting helpers instead of nesting conditionals.
+
+### Step 5 — Run scoped verification
+
+Run the narrowest checks that prove the repaired behavior on the real repo surface:
+
+- `test` / targeted tests for the repaired path
+- `lint` / `typecheck` for changed surfaces
+- `qa` only when the blast radius needs the bookend
+- Before push: start `ci_preflight`, then poll `ci_preflight_wait` with
+  its run ID until terminal success (use global `wp ci-preflight` only when MCP
+  is unavailable). Run it after the final commit and do not edit or commit again
+  before pushing: terminal success records the exact-state receipt checked by pre-push.
+  Do not use remote CI re-runs as the primary fix loop (`ci-cost-local-first`).
+
+Rules:
+
+- Prefer wp MCP tools over raw host Bash.
+- Reuse fresh logs / session-memory indexed output; do not re-run long commands just to re-read.
+- Read the exit code and summary before making a claim.
+- Never `git push --no-verify` to land an unproven fix.
+
+Escalate to `/verify <target>` (local) or `/verify <target> --merge-ready` when any of these are true:
+
+- the fix crosses packages
+- the fix changes a public or shared contract
+- the fix touched docs, plans, blueprints, or repo SSOT
+- the fix needs dead-code / compat / broad regression review before claiming done
+
+If the repaired behavior is already green but the diff still needs a bounded
+cleanup pass, use `ai-deslop` before the final verify handoff.
+
+### Tool recovery and delivery intent
+
+- Discover the managed owner's current identity with `blueprint_projects`
+  using its absolute `cwd`; pass the returned project ID and matching checkout
+  to session tools. A blueprint ID is not a project ID.
+- If quality tooling refuses stale or cross-checkout execution, follow its
+  checkout-local recovery. Attach the escape to the actual command:
+  `cd <owner> && WP_MCP_UNAVAILABLE=1 wp test --files <test>`.
+  Attaching it to `cd` does not set it for `wp`.
+- For external tools whose schema requires exactly one of command or WebSocket
+  input, omit the unused option entirely; an empty object still supplies it.
+- When the request includes merge/landing, continue through verification,
+  exact-head delivery, PR merge, and managed-owner cleanup. A handoff or
+  continuation summary does not satisfy that request. If a required gate is
+  blocked, report its concrete evidence and remaining action; preserve the
+  persisted completion requirements. Run additional named stages only when
+  the user's request actually includes them.
+
+### Step 6 — Report with evidence
+
+Keep it short:
+
+- what invariant broke
+- how the change restores it
+- what proof ran (tests, commands, log paths, exit codes)
+- adjacent issues noticed but intentionally not fixed
+
+## Done looks like
+
+- [ ] Root cause named in one sentence
+- [ ] Fix applied at the owning boundary
+- [ ] Regression proof fails against the old behavior
+- [ ] Minimal code change restores the invariant
+- [ ] Scoped verification passed on the changed surface
+- [ ] `/verify` handoff used when blast radius exceeded a local fix
+- [ ] Report cites evidence, not intent
+
+## Anti-patterns this command refuses
+
+- Fixing the nearest symptom while leaving the real invariant broken
+- Catching an error and returning a sentinel to "keep things moving"
+- Raising a timeout, retry count, or polling interval instead of finding the bottleneck
+- Adding a deprecated alias instead of updating consumers
+- Introducing `any`, suppressions, or lint disables to unblock the fix
+- Bundling unrelated refactors with the repair
+- Claiming done from intuition, partial output, or another agent's success message
+- Writing a planning/doc artifact when the user asked for a fix

package/skills/handoff/SKILL.md

@@ -0,0 +1,99 @@
+---
+type: skill
+slug: handoff
+title: Handoff
+status: active
+scope: repo
+applies_to: [agents]
+related: [ultragoal, team, plan-refine, fix, verify]
+created: "2026-08-03"
+last_reviewed: "2026-08-03"
+name: handoff
+description: "Cross-session handoff via session_context. Use for continue, take over, resume other host."
+argument-hint: "[--host <claude|codex|opencode>] [session-id|brief]"
+---
+
+# Handoff
+
+Produce a **context-light continuation** for another agent, host, or fresh
+session. Do **not** paste full transcripts.
+
+## Use when (freeform)
+
+- "give me a continuation prompt", "take over where you left off"
+- "resume", "continue from other host", "hand off to Codex/Claude"
+- cross-session or cross-worktree continuity without history walls
+
+## Tooling map
+
+| Need                   | Prefer                                                                     |
+| ---------------------- | -------------------------------------------------------------------------- |
+| Capture decisions      | `session_capture`                                                          |
+| Context-light manifest | `session_context` (required for subagents)                                 |
+| Prior evidence         | `session_search` / `session_retrieve` / `session_restore`                  |
+| Other-host chat        | `conversation_search` / `conversation_get` / `conversation_read` (bounded) |
+| Ultragoal block        | `ultragoal_handoff` (≤40 lines) when a controller is active                |
+
+## Protocol
+
+1. **State the objective** in one sentence (what the next agent must finish).
+2. **Capture** short pointers via `session_capture`: done, blockers, decisions,
+   evidence refs (log paths, test commands, PR numbers) — not full reports.
+3. **Build** a bounded manifest with `session_context` (objective, constraints,
+   evidenceRefs, remainingSteps, validation, exclusions). Never copy parent history.
+4. **Optional cross-host:** resolve the conversation with conversation MCP tools;
+   read only a **bounded tail** (`maxMessages` / `maxBytes`). Prefer resume
+   commands from `conversation_get` over paste.
+5. **Emit ≤40 lines** covering:
+   - goal / non-goals
+   - done + evidence refs
+   - blockers
+   - next 3 concrete commands or skill invocations
+   - suggested next skill: `plan-refine` | `fix` | `verify` | `ultragoal` | `land`
+6. Stop. Do not implement the next phase inside handoff unless the user
+   explicitly switched the task to execution.
+
+## Anti-patterns
+
+- Pasting full transcripts or multi-thousand-token "continuation prompts"
+- Claiming resume without a session_context / capture pointer
+- Expanding scope ("also fix everything else") without budgets
+- Using handoff as a substitute for `investigate` / `fix` / `verify`
+
+## Done looks like
+
+- [ ] ≤40-line handoff with evidence refs
+- [ ] `session_context` (or capture ids) for the next agent
+- [ ] Next skill named
+- [ ] No transcript wall
+
+## Capped or paused host messaging
+
+When the host messaging channel is capped or paused, the ≤40-line manifest IS
+the delivery: the handoff built above carries objective, done, blockers, and
+next steps even if no send lands — emit it once and treat it as sent. Include
+the send-budget state (attempt count, last canary result) in the manifest
+whenever the cap has been in play this session — the count's durable homes
+are the outbox header and the `session_capture` record; re-read both on
+resume. The leader's outbox anchor is durable in two homes: the
+outbox file's own header and a `session_capture` record (`session_capture`
+is registered in `src/mcp/tools/_names.ts`, implemented in
+`src/mcp/tools/session-capture.ts`). When the coordinator incarnation changes,
+re-anchor: write both homes plus the next handoff manifest — a recorded anchor
+goes stale when the identity passes to a new session (observed 2026-10-31: a
+memory-recorded live outbox path no longer existed). On the reader side, a
+stale or dead anchor is not a wall: fall back to the next durable arbitration
+source (`fleet_status` / blueprint task lists) and queues the staleness as
+a blocker in the outbox or manifest; a control send is spent only when the
+channel is open and a reserve slot remains, to surface the staleness. Before executing a resumed
+or queued order, check durable state (the outbox, `fleet_status`,
+blueprint task lists) for a newer arbitration — queued sends deliver late
+and out of order. The manifest carries this check as a required line.
+Queued orders in the manifest are one line each; if the queue would break
+the ≤40-line cap, the manifest carries the count and the outbox path and
+the orders stay in the outbox. Never route around a cap or
+pause: no relays, no peer delegation, no new sessions, no schedulers, no
+filesystem push-delivery to peers, no configuration changes, and no alternate
+transport, tool, or uncapped/legacy send interface. The durable outbox is pull-read
+state, not a route-around. Keep manifests context-light — do not paste full
+transcripts.

package/skills/hooks-doctor/SKILL.md

@@ -0,0 +1,153 @@
+---
+type: skill
+slug: hooks-doctor
+title: Hooks Doctor
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-11-01"
+name: hooks-doctor
+description: "Hook/plugin doctor for install health. Use for hook blocked, pretooluse, plugin broken."
+argument-hint: "[--skip-mcp]"
+allowed-tools:
+  - Bash
+---
+
+# Hooks Doctor
+
+Verify the webpresso plugin hooks installation is healthy. Run this first when:
+
+- A hook seems not to be firing, is blocked, or PreToolUse denies unexpectedly
+- The plugin was just installed or updated
+- Claude Code can't find expected tools
+- Any plugin integration issue arises
+
+## Running the Check
+
+Run the doctor command directly:
+
+```
+wp hooks doctor
+```
+
+Or skip the MCP server check (for CI environments):
+
+```
+wp hooks doctor --skip-mcp
+```
+
+## Interpreting Results
+
+Each check prints `[x]` (pass) or `[ ]` (fail) with a detail line:
+
+```
+[x] pretool-guard
+[x] post-tool (lint-after-edit)
+[x] stop (qa-changed-files)
+[x] guard-switch
+[x] sessionstart
+[x] test-quality-check
+[x] plugin.json integrity
+[x] MCP server liveness: MCP server already running (sentinel found)
+```
+
+## Failure Remediation
+
+| Check                                            | Likely Cause                                                      | Fix                                                               |
+| ------------------------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| `pretool-guard` / `post-tool` / etc. — not found | `wp run build` not run after install                              | `wp run build`                                                    |
+| `pretool-guard` / etc. — not executable          | `chmod +x` not persisted                                          | Re-run `wp run prepare` or `wp run build` which runs `chmod-bins` |
+| `plugin.json integrity` — missing                | Claude or Antigravity adapter manifest absent from plugin package | Re-run `wp setup --host <host>` or reinstall the host plugin      |
+| `MCP server liveness` — timeout                  | MCP server cold-start too slow                                    | Wait and retry, or run `wp hooks doctor --skip-mcp`               |
+| Any check — not found at `dist/esm/...`          | Build artifacts missing                                           | Run `wp run build` in the webpresso repo                          |
+
+### Updating the webpresso MCP server (monorepo authors)
+
+`mcp` is **source-first**: in a checkout with TypeScript source the server loads
+that source when it starts. After changing `src/mcp/**`, conversation catalog,
+or pretool routing that MCP hosts must run:
+
+1. Reconnect webpresso MCP server in the agent host.
+2. Prove the refreshed server is serving the intended source.
+
+No runtime rebuild is involved, and no `pkill` is needed — every launcher layer
+owns its child's stdin, so a disconnect unwinds the whole chain. Chat-only
+restart is still **not** enough: reconnect the server itself.
+
+Use the host's named-server controls so only the webpresso server is closed and
+started. Check the installed host version before using version-scoped controls.
+
+- **Codex desktop:** Settings → MCP servers → select webpresso → **Restart**. The
+  in-composer `/mcp` view lists connected servers
+  ([host documentation](https://learn.chatgpt.com/docs/extend/mcp?surface=app);
+  host documentation verified 2026-10-17).
+- **Claude Code:** `/mcp` → select webpresso → **Reconnect**. Use
+  `claude mcp list` to check the configured server; do not remove and re-add it.
+  Claude Code does not automatically reconnect local stdio servers
+  ([host documentation](https://code.claude.com/docs/en/mcp); host documentation
+  verified 2026-10-17).
+- **OpenCode v2:** `/mcps` → select webpresso → **Disconnect**, then
+  **Connect**. If the OpenCode configuration changed, run `opencode reload`;
+  verify with `opencode mcp list` ([MCP
+  servers](https://dev.opencode.ai/v2/docs/mcp-servers/), [CLI
+  commands](https://dev.opencode.ai/v2/docs/cli/commands/); host documentation
+  verified 2026-10-17). These `dev.opencode.ai` paths sit on a preview domain
+  and can move; confirm the v2 path still resolves before following it.
+- **Antigravity:** Preferences / Settings → Plugins → reload or toggle `wp` plugin,
+  or restart the Antigravity session. Verify with `wp hooks doctor` or `wp hooks status`.
+
+After reconnecting, prove the loaded source rather than the connection:
+
+1. Call `tool_surface` with `detail: "diagnostic"`.
+2. Compare `details.diagnostic.live.sourceCommit` against the commit you expect
+   the checkout to be serving.
+3. Read `details.diagnostic.identity.status`, which is exactly one of `current`,
+   `restart_required`, `setup_required`, or `unknown`. The wrapper's
+   `passed: true` only means a response was built — it is **not** proof of
+   current identity.
+
+If the source commit differs, or the status is `restart_required` or
+`setup_required`, reconnect again or follow `details.diagnostic.identity.reason`.
+If the status is `unknown`, keep that uncertainty: a source-distinguishing smoke
+call can corroborate behavior but does not make the identity current. A fresh
+chat is not a refresh. Reserve quitting and reopening the host for the one-time
+legacy-chain upgrade below, and never kill unrelated processes.
+
+Managed `wp hook` and `wp hooks doctor|status|dispatch` commands are
+source-authoritative and require no post-merge runtime rebuild. Existing
+managed installations run exact `wp sync`, then rerun `wp hooks doctor` or
+`wp hooks status` until the legacy-projection warning is absent. Packed
+consumers continue to use the shipped compiled runtime and repair/reinstall that
+artifact if it is missing.
+
+**One-time upgrade step:** chains started before the source-first lane shipped
+ran no stdin relay, so quit and reopen each MCP host once to retire them. A
+`pkill` pattern is not a substitute — it misses source-launched chains and can
+kill another session's server.
+
+**Offline shell allowlist** when webpresso MCP tools are unavailable (must
+match `dev-routing-bounded-read.ts`):
+
+```text
+rg --no-config -n pattern path 2>/dev/null | head -c 65536
+head -n 200 path/to/file
+git log --oneline -n 50
+git show --stat HEAD
+git diff --stat
+```
+
+After fixing, re-run `wp hooks doctor` to confirm.
+
+## How It Works
+
+The doctor runs five categories of checks:
+
+1. **Bin existence** — each hook binary exists at the expected `dist/esm/hooks/...` path
+2. **Executable bit** — bins have execute permission (skipped on Windows)
+3. **stdin response** — interactive hooks (`pretool-guard`, `guard-switch`, `sessionstart`) respond to `{}` input with valid JSON and exit 0; fire-and-forget hooks (`lint-after-edit`, `qa-changed-files`) exit 0
+4. **plugin.json integrity** — adapter manifest exists, has required fields, and all referenced bins exist on disk
+5. **MCP server liveness** — spawns the MCP server and sends a `tools/list` JSON-RPC request; times out at 5s (soft-fail — warning only, does not fail the overall check)
+
+If `isMcpReady()` detects a live MCP sentinel, the MCP check fast-passes without spawning.

package/skills/investigate/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: investigate
+description: "Root-cause investigation workflow: reproduce, isolate, prove, and hand off the minimal repair scope."
+license: MIT
+---
+
+# Investigate
+
+Use this skill when the task is to understand a bug, failure, regression,
+flaky behavior, or confusing symptom before editing code.
+
+## Boundary
+
+- `investigate` owns diagnosis, reproduction, hypothesis testing, and proof.
+- `fix` owns repair. If the user asked to fix the problem and root-cause
+  evidence is still missing, `fix` should run this phase inline first.
+- Stop once you can name the broken invariant, show the failing proof, and
+  point at the owner that should be repaired.
+
+## Tooling map
+
+| Need                   | Prefer                                                  |
+| ---------------------- | ------------------------------------------------------- |
+| Reproduce / large logs | `session_execute`, `session_batch_execute`              |
+| Large files            | `session_execute_file`                                  |
+| Prior continuity       | `session_search`, `session_restore`, `session_retrieve` |
+| Capture findings       | `session_capture` (short pointer, not full paste-back)  |
+| Proof runs             | `test`, `qa`, `lint`, `typecheck`                       |
+| Code search/read       | host Grep/Read first; avoid shell-as-IDE                |
+
+## Workflow
+
+1. Reproduce or capture the failure.
+   - Run the exact failing command or trace the exact user path (prefer `session_execute`).
+   - Keep the evidence that matters: error text, failing assertion, exit code,
+     log path, or boundary mismatch.
+2. Read the whole boundary.
+   - Inspect the full error site, the owning module, and one nearby working
+     pattern.
+   - Do not edit code yet.
+3. State the root-cause hypothesis.
+   - Name the broken invariant in one sentence.
+   - Name the owner that should enforce it.
+   - Separate facts from guesses.
+   - **Every cause must carry the observation that proved it**: the command you
+     ran, its output, and the code path that produced it. A cause you have not
+     executed against the failing case is a guess and must be labelled as one.
+4. Disconfirm cheap alternatives.
+   - Test the obvious competing explanations before settling on one cause.
+   - Add temporary diagnostics only when needed, and remove them after one pass.
+   - **When a cause is disproved, return to the reproduction rather than
+     replacing it with the next plausible story.** Two or three confident
+     explanations in a row, none observed, means the failure has not been
+     reproduced yet — go back to step 1.
+   - A test fixture, capability object, or recorded tool output that asserts
+     behaviour is the weakest link: confirm at least one path against the real
+     binary, module, or service it stands in for.
+   - Related: `catalog/agent/rules/evidence-discipline.md` § 6.
+5. Produce failing proof.
+   - Prefer a targeted failing test.
+   - If test-first is impossible at this boundary, use the nearest deterministic
+     reproduction instead.
+6. Hand off the minimal repair scope.
+   - List the owner, direct consumers, and the smallest safe verification set.
+   - If the issue is broader than one coherent repair, say so before any edit.
+
+## Output
+
+Return:
+
+- reproduced symptom
+- broken invariant
+- root-cause hypothesis status: confirmed / likely / blocked
+- failing proof
+- owning file or boundary
+- recommended next step: `fix`, `verify`, or a scoped blocker
+
+## Anti-patterns
+
+- Editing before you can name the invariant
+- Treating a stack trace as proof of root cause
+- Hiding uncertainty behind broad "probably X" explanations
+- Expanding a debugging pass into cleanup or refactor work

package/skills/lore-protocol/SKILL.md

@@ -0,0 +1,84 @@
+---
+type: skill
+slug: lore-protocol
+title: lore-protocol
+status: active
+scope: repo
+applies_to: [agents]
+related: []
+created: "2026-05-07"
+last_reviewed: "2026-05-07"
+name: lore-protocol
+description: "Manual Lore commit-message trailers with wp audit commit-message; no hook enforcement because PRs squash."
+---
+
+# lore-protocol
+
+Use Lore commit-message trailers manually with `wp audit commit-message`. Hook enforcement is intentionally not installed because this repo uses squash commits.
+
+Lore is a lightweight protocol for embedding decision context directly into
+commit messages — constraints, rejected alternatives, confidence, and
+forward-looking directives — so future engineers understand _why_ a change
+was made, not just _what_ changed.
+
+## Quick start
+
+```bash
+# Validate a commit message file (hard-fail mode — exits non-zero on violations)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --require-lore
+
+# Soft-warn mode — emits warnings but always exits 0 (adoption ramp)
+wp audit commit-message --message-file .git/COMMIT_EDITMSG --lore-warn
+
+# Opt in per-commit by adding [lore] to the subject line:
+# feat(auth): prevent silent session drops [lore]
+```
+
+## Hook policy
+
+Lore trailers are advisory/manual. Do not install commit-msg or pre-push hooks for Lore enforcement; squash commits are the durable review boundary.
+
+## Trailer format
+
+```
+<intent line: why the change was made, not what changed>
+
+<body: narrative context — constraints, approach rationale>
+
+Constraint: <external constraint that shaped the decision>
+Rejected: <alternative considered> | <reason for rejection>
+Confidence: <low|medium|high>
+Scope-risk: <narrow|moderate|broad>
+Directive: <forward-looking warning for future modifiers>
+Tested: <what was verified>
+Not-tested: <known gaps in verification>
+```
+
+## Required trailers (for `--require-lore` or `[lore]` subject tag)
+
+| Trailer                                      | Required     | Allowed values                   |
+| -------------------------------------------- | ------------ | -------------------------------- |
+| `Confidence:`                                | yes          | `low`, `medium`, `high`          |
+| `Constraint:` or `Rejected:` or `Directive:` | at least one | free text                        |
+| `Scope-risk:`                                | optional     | `narrow`, `moderate`, `broad`    |
+| `Reversibility:`                             | optional     | `clean`, `messy`, `irreversible` |
+| `Tested:`                                    | optional     | free text                        |
+| `Not-tested:`                                | optional     | free text                        |
+| `Related:`                                   | optional     | free text                        |
+
+## Example commit
+
+```
+Prevent silent session drops during long-running operations
+
+The auth service returns inconsistent status codes on token
+expiry, so the interceptor catches all 4xx responses.
+
+Constraint: Auth service does not support token introspection
+Rejected: Extend token TTL to 24h | security policy violation
+Confidence: high
+Scope-risk: narrow
+Directive: Error handling is broad — do not narrow without verifying upstream behavior
+Tested: Single expired token refresh (unit)
+Not-tested: Auth service cold-start > 500ms behavior
+```