@webpresso/agent-kit 3.1.26 → 3.1.28

package/catalog/agent/skills/ultragoal/SKILL.md

@@ -5,9 +5,9 @@ title: Ultragoal
 status: active
 scope: repo
 applies_to: [agents]
-related: [autopilot, plan-refine, verify]
+related: [autopilot, plan-refine, verify, pll, fix, opencode-go]
 created: "2026-07-10"
-last_reviewed: "2026-07-20"
+last_reviewed: "2026-07-21"
 name: ultragoal
 description: "Run durable multi-blueprint ultragoals through evidence-gated handoffs."
 argument-hint: "<new|status|handoff|run|cancel> [brief]"
@@ -15,30 +15,158 @@ argument-hint: "<new|status|handoff|run|cancel> [brief]"
 
 # Ultragoal
 
-Use `wp ultragoal` as the durable controller for work spanning one or more blueprints.
+Use `wp ultragoal` / MCP `wp_ultragoal_*` as the durable controller for work spanning
+one or more blueprints. Prefer this spine over host-local mega-sessions or ad-hoc
+multi-agent swarms.
+
+## Default budgets (override only when the user sets them)
+
+| Budget          | Default   | Meaning                                                    |
+| --------------- | --------- | ---------------------------------------------------------- |
+| `concurrency`   | 4 (max 8) | Parallel ready tasks / implementer lanes                   |
+| `fix_budget`    | 1         | Pre-existing issues fixable via `/fix` this phase          |
+| `review_budget` | 1         | Outside-voice reviewers for merge-ready (0 for local work) |
+| `loop`          | off       | Do not run `/loop` or unbounded stop-hooks                 |
+
+Reject unbudgeted sleep-mode briefs (“complete all”, “full autopilot”, “go to sleep”)
+unless they name a blueprint/slug, budgets, and a stop condition. Route vague briefs
+through `plan-refine` first (or require `force:` only when the user explicitly opts out).
+
+## Tooling map (use these; do not reimplement with Bash)
+
+| Phase                  | Prefer MCP / CLI                                                                       | Purpose                                             |
+| ---------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| Create / resume        | `wp_ultragoal_new`, `wp_ultragoal_status`                                              | Durable controller state                            |
+| Isolation              | `wp_worktree`                                                                          | Owner / lane worktrees; never primary as controller |
+| Blueprint read         | `wp_blueprint_list`, `wp_blueprint_get`, `wp_blueprint_context`                        | Ready-set and deps                                  |
+| Blueprint write        | `wp_blueprint_put`, `wp_blueprint_transition`                                          | Spec edits (MCP-only for blueprints)                |
+| Task done              | `wp_blueprint_task_verify` only                                                        | Evidence-gated completion                           |
+| Parallel execute       | `/pll` or ready-queue + host subagents                                                 | Max parallel when deps allow                        |
+| Context-light delegate | `wp_session_context`                                                                   | Manifest for subagents (no history paste)           |
+| Continuity             | `wp_session_capture`, `wp_session_search`, `wp_session_restore`, `wp_session_snapshot` | Decisions / resume                                  |
+| Large command / file   | `wp_session_execute`, `wp_session_batch_execute`, `wp_session_execute_file`            | Bounded output + index                              |
+| QA                     | `wp_qa` (or `wp_lint` + `wp_typecheck` + `wp_test`)                                    | Affected quality gates                              |
+| PR / land              | `wp_pr_upsert`, `wp_pr_status`, `wp_pr_wait`                                           | Open early; wait on required checks                 |
+| Fleet / workers        | `wp_fleet_status`, `wp_worker_tail`                                                    | Multi-session visibility                            |
+| Token gain             | `wp_gain`                                                                              | Optional efficiency check after heavy execute       |
+| Advance loop           | `wp_ultragoal_run`, `wp_ultragoal_handoff`, `wp_ultragoal_cancel`                      | Controller steps only                               |
+
+Fallback to `wp …` CLI only when the matching MCP tool is unavailable. Prefer `wp` >
+`vp` > raw package managers. Never raise timeouts to hide hangs.
 
 ## Protocol
 
-1. Create or resume the ultragoal in a managed blueprint owner worktree (never main as controller).
-2. Read `wp ultragoal status`, execute only the current phase handoff, then call `wp ultragoal run` again.
-3. Complete blueprint tasks only through `wp_blueprint_task_verify` with passing evidence.
-4. Stop when the controller reports `complete`, `cancelled`, blocked guard exhaustion, or `WP_ULTRAGOAL_DISABLE=1`.
+1. Create or resume the ultragoal in a **managed blueprint owner worktree** (`wp_worktree` /
+   `wp blueprint start`). Never use `main` or the primary checkout as controller.
+2. Print the **ready-set**: tasks whose dependencies are satisfied (from blueprint tools).
+3. Launch up to `concurrency` independent ready tasks in parallel (worktree-isolated).
+   Serialize only when file ownership overlaps or deps require it.
+4. Execute only the current phase handoff; call `wp_ultragoal_run` again after evidence.
+5. Mark tasks done **only** via `wp_blueprint_task_verify` with passing evidence.
+6. **Opportunistic `/fix`:** at most `fix_budget` pre-existing issues per phase, each with
+   named invariant + failing proof. Excess → handoff backlog (do not expand epic).
+7. **Validate / land:** local proof with `wp_qa` / targeted tools; outside review only when
+   merge-ready and within `review_budget` (default **exactly 1** sequential outside voice).
+   Prefer `wp review gate` for lifecycle authority. Use `wp_pr_*` for PR babysit — no
+   multi-sleep poll loops; no parallel multi-reviewer stampede.
+8. Stop on `complete`, `cancelled`, blocked guard exhaustion, or `WP_ULTRAGOAL_DISABLE=1`.
+
+The blueprint engine owns task status and approval gates. The ultragoal controller must
+never self-approve, directly mark a task done, bypass review provenance, or mutate the
+primary checkout.
+
+## Failure / cascade
+
+- Hard fail on a task → mark blocked with reason; **cascade-skip** dependents that cannot
+  proceed; continue independent ready work.
+- Lifecycle mutation failure → stop (do not continue on stale plan state).
+- On block: call `wp_ultragoal_handoff` and emit a **≤40-line handoff**: goal, done, blockers,
+  evidence refs (`wp_session_*` ids if any), next 3 commands. Do not paste full transcripts.
+
+## Outside-voice review (required for autopilot)
+
+Autopilot and agent-driven ultragoal loops **must** request an **OpenCode Go** outside-voice review after each **goal/phase milestone**, and must pick the model by purpose. Direct `wp review run` output is advisory only. Lifecycle authority that can satisfy promotion/completion gates comes only from a converged **`wp review gate`** (content-addressed ledger + bound artifact).
+
+Count each milestone review against `review_budget` for merge-ready claims: **exactly one sequential** reviewer path unless the user sets N. Prefer purpose-matched OpenCode Go first; do not fan out multi-host review swarms.
+
+### Milestones that require a review
+
+Run a distinct OpenCode Go review (via `wp review gate` when the milestone is a promotion/approval gate; otherwise `wp review gate` or a purpose-matched gate resume) after each of:
+
+| Milestone          | When                                                                                                                             |
+| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Plan gate          | Before `draft` → `planned` / when ultragoal phase is `plan` and promotion is required                                            |
+| Phase advance      | After ultragoal advances `plan` → `execute`, `execute` → `qa`, `qa` → `validate`, `validate` → `land`, or lands `complete`       |
+| Task batch handoff | After a meaningful execute batch when the phase remains `execute` (at least once per blueprint before claiming execute-complete) |
+
+Do **not** invent ledger approvals. If OpenCode Go is unavailable or hits a provider-wide usage limit, capture the failure evidence and stop; do not substitute a forged approval.
+
+### Purpose → model routing (no hardcoding IDs)
+
+Resolve models from the live catalog every time:
+
+```bash
+opencode models opencode-go
+```
+
+Pick by purpose (same intent as the committed OpenCode reviewer policy / `opencode-go` skill):
+
+| Purpose                                     | Preferred family (live catalog)                                                                  | Why                        |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------- |
+| Plan / architecture critique                | DeepSeek **Pro** (`opencode-go/deepseek…-pro`)                                                   | Deeper plan review depth   |
+| Coding / implementation quality             | Kimi **Code** first (`…kimi…-code`)                                                              | Coding quality lane        |
+| Cheap recheck / high-availability follow-up | DeepSeek **Flash** (`…deepseek…-flash`)                                                          | Fast secondary pass        |
+| Aggregate / unspecified                     | Follow `opencode-go` skill order: Kimi Code → DeepSeek Pro → DeepSeek Flash → remaining families | Default outside-voice lane |
+
+Resolve the actual model ID with catalog greps (never paste a fixed model string into agent instructions as the only option):
+
+```bash
+CATALOG=$(opencode models opencode-go)
+# plan critique example:
+MODEL=$(echo "$CATALOG" | grep '^opencode-go/deepseek' | grep -- '-pro$' | sort -V | tail -1)
+# coding example:
+# MODEL=$(echo "$CATALOG" | grep '^opencode-go/kimi' | grep -- '-code$' | sort -V | tail -1)
+```
+
+Treat a provider-wide usage limit as terminal for every OpenCode Go model in the current review window; do not hop families to evade a usage block on the same provider.
+
+### Gate invocation shape
+
+```bash
+wp review gate <blueprint-slug> \
+  --purpose plan|delivery \
+  --provider opencode \
+  --model "$MODEL" \
+  --effort medium|high \
+  --target HEAD \
+  --json
+```
+
+Use `--purpose plan` for plan-phase promotion and `--purpose delivery` for implementation/delivery validation. Resume interrupted gates with `--resume <gate-id>` against the same immutable target.
+
+### Honesty rules (non-negotiable)
 
-The blueprint engine owns task status and approval gates. The ultragoal controller must never self-approve, directly mark a task done, bypass review provenance, or mutate the primary checkout. Keep every loop bounded and never increase timeouts.
+- Never self-approve or hand-edit `reviews.md` / `review-events.jsonl` / frontmatter approvals to fake OpenCode Go authority.
+- Never mark blueprint tasks done except through `wp_blueprint_task_verify` with real evidence.
+- Never run ultragoal mutations on `main` or a primary checkout; use the managed blueprint owner worktree.
+- Keep every loop bounded and never increase timeouts.
+- When the controller returns `waiting` (`blueprint-promotion`, `approval-gate`, `blueprint-tasks`, …), fix the named gap; do not spin `wp ultragoal run` without progress.
 
 ## Tooling-aligned evidence (QA / land)
 
-- **QA phase** prefers **GitHub required checks** for the worktree PR (`gh pr view` + `gh pr checks --required`) when:
-  - PR is `OPEN` or `MERGED`
-  - required checks are green (same evaluator as land)
-  - PR head source snapshot matches the clean worktree HEAD snapshot
-- If no PR-bound green CI is available, ultragoal falls back to local **`wp qa`** (`vp run qa`).
-- Do **not** raise timeouts to paper over incomplete worktrees; open a PR early so CI can satisfy QA.
-- Prefer `wp pr wait` / `gh run watch` while babysitting; do not invent multi-sleep poll loops.
-- **Land** still requires a **MERGED** PR with green required checks bound to the projected source snapshot.
+- **QA phase** prefers **GitHub required checks** for the worktree PR (`wp_pr_status` /
+  `wp_pr_wait` or `gh pr checks --required`) when PR is `OPEN`/`MERGED`, checks green, and
+  PR head matches clean worktree HEAD.
+- If no PR-bound green CI is available, fall back to local **`wp_qa`**.
+- Open a PR early so CI can satisfy QA. Do **not** raise timeouts.
+- **Land** still requires a **MERGED** PR with green required checks bound to the projected
+  source snapshot. Use `/verify --merge-ready` (review_budget=1), not default local verify.
 
 ## Snapshot / dirty worktree
 
-- Ultragoal ledger appends to blueprint `reviews.md` / `review-events.jsonl` / `review-artifacts/**`.
-- These paths under both `blueprints/**` and monorepo `webpresso/blueprints/**` are **evidence-only dirt** and must not fail `createCleanSourceSnapshot`.
-- Dirty **source** paths (including `_overview.md` task status edits) still fail closed until committed.
+- Ultragoal ledger appends to blueprint `reviews.md` / `review-events.jsonl` /
+  `review-artifacts/**`.
+- These paths under both `blueprints/**` and monorepo `webpresso/blueprints/**` are
+  **evidence-only dirt** and must not fail `createCleanSourceSnapshot`.
+- Dirty **source** paths (including `_overview.md` task status edits) still fail closed
+  until committed. Use `wp_session_snapshot` before risky branch switches.

package/catalog/agent/skills/verify/SKILL.md

@@ -7,10 +7,10 @@ scope: repo
 applies_to: [agents]
 related: [testing-philosophy, tph]
 created: "2026-05-07"
-last_reviewed: "2026-07-13"
+last_reviewed: "2026-07-21"
 name: verify
 description: "Post-implementation quality gate: run checks, TPH audit, cleanup, docs, proof."
-argument-hint: "<target> [--full] where target is: package|file|plan-slug|all"
+argument-hint: "<target> [--full|--merge-ready] where target is: package|file|plan-slug|all"
 ---
 
 # Verify
@@ -21,6 +21,33 @@ Post-implementation quality gate. Run after implementation exists, before claimi
 repair. `/verify` owns the broader question: **is this work actually complete,
 integrated, and free of stale garbage?**
 
+## Modes
+
+| Invocation                       | Outside voice                      | When                           |
+| -------------------------------- | ---------------------------------- | ------------------------------ |
+| `/verify <target>` (default)     | **0**                              | Local completeness / iteration |
+| `/verify <target> --full`        | **0** (broader local gates)        | Full local QA bookend          |
+| `/verify <target> --merge-ready` | **exactly 1** (unless user sets N) | Claiming merge-ready / land    |
+
+Default `/verify` must **not** spawn outside reviewers. That stampede is a known
+token/time failure mode. Merge-ready runs **one** sequential outside voice via
+the preferred skill (`claude` / `codex` / `grok` / one OpenCode Go), then stops.
+
+## Tooling map
+
+| Gate                      | Prefer                                                          |
+| ------------------------- | --------------------------------------------------------------- |
+| Lint / types / tests / QA | `wp_lint`, `wp_typecheck`, `wp_test`, `wp_qa`                   |
+| Format                    | `wp_format`                                                     |
+| Audits                    | `wp_audit`, `wp_audits`                                         |
+| Blueprint                 | blueprint MCP tools + `wp audit blueprint-lifecycle`            |
+| PR / CI wait              | `wp_pr_status`, `wp_pr_wait` (not multi-sleep loops)            |
+| Release                   | `wp_release_readiness` when shipping                            |
+| Large output              | `wp_session_execute` / `batch_execute` / `execute_file`         |
+| Continuity                | `wp_session_capture` for verify summary; avoid paste-back walls |
+| E2E / act                 | `wp_e2e`, `wp_ci_act` when the change requires them             |
+| Outside authority         | `wp review gate` (not raw multi-agent review swarms)            |
+
 ## Iron law — evidence before claims
 
 No completion claim without fresh verification evidence.
@@ -40,15 +67,15 @@ Not sufficient: "should pass", "looks correct", lint-only evidence for runtime c
 ```bash
 /verify <target>
 /verify <target> --full
+/verify <target> --merge-ready
 ```
 
 `<target>` is a file path, package name, blueprint slug, or `all`.
 
 Follow the repo's current routing and command surface:
 
-- use repo-owned quality wrappers first
-- use injected quality-tool routing when present
-- use bounded large-output tooling when the repo instructs it
+- use MCP `wp_*` / repo-owned quality wrappers first
+- use bounded session-memory tooling for large output
 - reuse fresh logs instead of re-running broad commands just to inspect output
 
 ## Folded health dashboard
@@ -98,17 +125,17 @@ Hard stop on any failure.
 
 Run the narrowest checks that prove the touched behavior:
 
-- targeted lint
-- targeted typecheck
-- targeted tests
-- build / e2e / package checks only when the change requires them
+- `wp_lint` / targeted lint
+- `wp_typecheck` / targeted typecheck
+- `wp_test` / targeted tests
+- `wp_qa`, `wp_e2e`, build / package checks only when the change requires them
 
 Rules:
 
-- Prefer repo wrappers over raw underlying tools.
-- Reuse fresh logs if the runner auto-saves them.
+- Prefer MCP `wp_*` over raw underlying tools.
+- Reuse fresh logs / session-memory indexed output if the runner auto-saves them.
 - Never claim broader correctness than the commands actually proved.
-- If the repo documents a "full QA" bookend, reserve it for the final broad pass rather than every iteration.
+- If the repo documents a "full QA" bookend, reserve `wp_qa` / `--full` for the final broad pass rather than every iteration.
 
 ## Phase 3 — Cross-surface impact scan
 
@@ -161,59 +188,52 @@ cleanup, route that pass through `ai-deslop` first rather than broadening
 
 This phase exists to catch the garbage that often slips in beside otherwise-correct work.
 
-## Phase 6 — Outside-model approval gate
+## Phase 6 — Outside-model approval gate (**`--merge-ready` only**)
+
+**Skip this entire phase** for default `/verify` and `/verify --full`. Local
+`done` claims do not require outside voice.
 
-Before claiming merge-ready, obtain outside-voice model approvals unless the
-user explicitly asked for a different approval count or reviewer mix.
+Before claiming **merge-ready**, obtain outside-voice approvals only under this policy:
 
-Default policy:
+Default merge-ready policy:
 
-- Require **one extra model approval** by default. At most **one OpenCode Go reviewer** counts toward the requirement unless the user explicitly asks for multiple OpenCode models.
-- If the user asks for more, fewer, zero, or specific reviewers, follow that
-  explicit instruction and report the chosen requirement.
-- These approvals are model outside-voice approvals, not a substitute for
-  required human GitHub reviews or branch-protection approvals.
+- Require **exactly one** extra model approval unless the user sets a different N.
+- At most **one OpenCode Go reviewer** counts toward the requirement unless the user
+  explicitly asks for multiple OpenCode models.
+- Run reviewers **sequentially** (try next only if current unavailable). Never fan out
+  parallel multi-host review swarms.
+- If the user asks for more, fewer, zero, or specific reviewers, follow that instruction
+  and report the chosen requirement.
+- These approvals are model outside-voice approvals, not a substitute for human GitHub
+  reviews or branch-protection approvals.
 
-Reviewer preference:
+Reviewer preference (pick **one** path):
 
-- When running from Codex, prefer **Claude or Grok** (fall back to one OpenCode Go reviewer if both are unavailable).
-- When running from Claude, prefer **Codex or Grok** (fall back to one OpenCode Go reviewer if both are unavailable).
-- When Codex/Claude/Grok outside voice is unavailable, use **one OpenCode Go
-  reviewer** if OpenCode is logged in.
-- Prefer the repo's outside-voice skills instead of hand-rolled commands:
-  `$agent-kit:claude`, `$agent-kit:codex`, `$agent-kit:grok`, and one OpenCode Go reviewer
-  skills such as `$agent-kit:opencode-go`, `$agent-kit:qwen`,
-  `$agent-kit:deepseek`, `$agent-kit:glm`, `$agent-kit:kimi`,
-  `$agent-kit:minimax`, or `$agent-kit:mimo`.
+- From Codex → Claude or Grok (else one OpenCode Go).
+- From Claude → Codex or Grok (else one OpenCode Go).
+- From Grok → Claude or Codex (else one OpenCode Go).
+- Prefer skills: `claude`, `codex`, `grok`, or one of `opencode-go` / `qwen` /
+  `deepseek` / `glm` / `kimi` / `minimax` / `mimo`.
 
 Approval evidence requirements:
 
-- For blueprint lifecycle approval workflows, run `wp review gate <blueprint-slug> --target HEAD --json`
-  first so exact-SHA reusable evidence and approval frontmatter are handled
-  transactionally. Use `wp review log` / `wp review read` for focused ledger
-  inspection or manual evidence recording.
-- Each outside reviewer must return a clear `APPROVED`/`BLOCKED` (or equivalent)
-  verdict with enough evidence to identify what it reviewed.
-- Record outside approval evidence as PR comments when a PR exists.
-- Each PR comment must include the approving model/tool name, provider/family
-  when known, verdict, reviewed commit or branch, and any blockers or caveats.
-- If there is no PR yet, record the same evidence in the final Verify report and
-  add the PR comments once the PR exists before calling the PR merge-ready.
-- If an outside reviewer is unavailable (not installed, not logged in, missing
-  model, timeout after the reviewer skill's allowed retry path), do not silently
-  count it. Try the next preferred reviewer. If the required count still cannot
-  be met, report the exact approval gap and say the work is **not merge-ready**.
+- Blueprint lifecycle: `wp review gate <blueprint-slug> --target HEAD --json` first.
+  Use `wp review log` / `wp review read` for inspection.
+- Each reviewer must return clear `APPROVED`/`BLOCKED` with enough evidence.
+- Record as PR comments when a PR exists (model/tool, verdict, reviewed commit).
+- Unavailable reviewer → try next preferred; if still short, report gap and
+  **not merge-ready** (never invent approvals).
 
 ## Phase 7 — Final completion statement
 
 Report:
 
-- what was verified
-- which commands/logs prove it
-- which docs/help/instruction surfaces were refreshed when command or operator guidance changed
-- which outside models approved it, with PR comment links when a PR exists
+- mode used (`local` / `full` / `merge-ready`)
+- what was verified and which `wp_*` commands/logs prove it
+- which docs/help/instruction surfaces were refreshed when guidance changed
+- outside models only if merge-ready (with PR comment links when applicable)
 - what remains intentionally out of scope
 
-When catalog assets, generated instruction templates, or checked-in generated instruction copies changed, include the repo's public-package-safety or package-surface leak checks in the verification evidence.
+When catalog assets or generated instruction surfaces changed, include public-package-safety or package-surface leak checks.
 
 If any required check is missing, the correct result is **not done yet**, not a softer claim.

package/dist/esm/audit/blueprint-lifecycle-sql.d.ts

@@ -26,5 +26,13 @@ export interface BlueprintLifecycleAuditOptions {
     readonly baseRef?: string;
     /** Restrict expensive/error-producing checks to blueprints touched in git. */
     readonly changedOnly?: boolean;
+    /**
+     * When set (from `wp audit --affected` / pre-commit staged files), restrict
+     * changed-only scope to blueprints that appear in this path set.
+     *
+     * Without this filter, porcelain includes untracked drafts and can fail an
+     * unrelated skill/docs commit that never staged any blueprint.
+     */
+    readonly affectedFiles?: readonly string[];
 }
 export declare function auditBlueprintLifecycleSql(cwd?: string, options?: BlueprintLifecycleAuditOptions): Promise<RepoAuditResult>;

package/dist/esm/audit/blueprint-lifecycle-sql.js

@@ -369,6 +369,27 @@ function changedBlueprintScope(candidates) {
     }
     return { slugs };
 }
+/**
+ * When `--affected` supplies an explicit file set (pre-commit staged files or
+ * branch ACMR list), only keep blueprint transition candidates that touch
+ * those paths. Untracked WIP drafts outside the set must not fail the commit.
+ *
+ * `affectedFiles === undefined` keeps the full porcelain candidate map (CLI
+ * `wp audit blueprint-lifecycle --changed-only` without a staged filter).
+ */
+function filterTransitionCandidatesByAffectedFiles(candidates, affectedFiles) {
+    if (affectedFiles === undefined)
+        return candidates;
+    const allowed = new Set(affectedFiles.map((file) => normalizeGitPath(file)));
+    const filtered = new Map();
+    for (const [currentPath, candidate] of candidates) {
+        const paths = [currentPath, ...candidate.previousPaths].map(normalizeGitPath);
+        if (paths.some((p) => allowed.has(p))) {
+            filtered.set(currentPath, candidate);
+        }
+    }
+    return filtered;
+}
 function violationTouchesBlueprintScope(violation, scope) {
     if (!violation.file)
         return false;
@@ -422,7 +443,10 @@ export async function auditBlueprintLifecycleSql(cwd = process.cwd(), options =
     const changedCandidateMap = gitHistoryAvailable
         ? listChangedBlueprintCandidates(cwd, { baseRef: options.baseRef })
         : null;
-    const changedScope = changedCandidateMap === null ? null : changedBlueprintScope(changedCandidateMap);
+    const scopedCandidateMap = changedCandidateMap === null
+        ? null
+        : filterTransitionCandidatesByAffectedFiles(changedCandidateMap, options.affectedFiles);
+    const changedScope = scopedCandidateMap === null ? null : changedBlueprintScope(scopedCandidateMap);
     // Review-evidence append-only enforcement (base-vs-head ledger prefix check).
     // Runs BEFORE the changed-only early returns: a PR that only rewrites a
     // review-events.jsonl touches zero blueprint documents, so changedScope is

package/dist/esm/ci/native-session-memory-cache.d.ts

@@ -26,7 +26,15 @@ export declare const NATIVE_SESSION_MEMORY_TRUST_CACHED_NODE_ENV = "WP_NATIVE_SE
  * Absolute cache dir still comes from env-paths / CACHE_ROOT override at runtime.
  */
 export declare const NATIVE_SESSION_MEMORY_CACHE_HASH_GLOBS: readonly ["native/session-memory-engine/Cargo.lock", "native/session-memory-engine/Cargo.toml", "native/session-memory-engine/crates/**/*.rs", "native/session-memory-engine/crates/**/Cargo.toml"];
-/** Linux CI default env-paths cache root (XDG). Documented for workflow `path:`. */
+/**
+ * Default **env-paths** Linux cache location when `WP_NATIVE_SESSION_MEMORY_CACHE_ROOT`
+ * is unset (`$HOME/.cache/webpresso-agent-kit/session-memory-engine`).
+ *
+ * Agent-kit self-CI does **not** use this path for the warm cache: it overrides via
+ * `WP_NATIVE_SESSION_MEMORY_CACHE_ROOT` → `${{ runner.temp }}/sm-native-cache` (see
+ * the Test job warm cache step in `.github/workflows/ci.agent-kit.yml`). This helper
+ * documents the unset-override default only — not the workflow `path:`.
+ */
 export declare function defaultLinuxNativeSessionMemoryCachePath(home?: string): string;
 /**
  * Trust is only safe on an exact primary-key GHA cache hit (sources match the key).

package/dist/esm/ci/native-session-memory-cache.js

@@ -31,7 +31,15 @@ export const NATIVE_SESSION_MEMORY_CACHE_HASH_GLOBS = [
     "native/session-memory-engine/crates/**/*.rs",
     "native/session-memory-engine/crates/**/Cargo.toml",
 ];
-/** Linux CI default env-paths cache root (XDG). Documented for workflow `path:`. */
+/**
+ * Default **env-paths** Linux cache location when `WP_NATIVE_SESSION_MEMORY_CACHE_ROOT`
+ * is unset (`$HOME/.cache/webpresso-agent-kit/session-memory-engine`).
+ *
+ * Agent-kit self-CI does **not** use this path for the warm cache: it overrides via
+ * `WP_NATIVE_SESSION_MEMORY_CACHE_ROOT` → `${{ runner.temp }}/sm-native-cache` (see
+ * the Test job warm cache step in `.github/workflows/ci.agent-kit.yml`). This helper
+ * documents the unset-override default only — not the workflow `path:`.
+ */
 export function defaultLinuxNativeSessionMemoryCachePath(home = "~") {
     return `${home}/.cache/${NATIVE_SESSION_MEMORY_CACHE_ENV_NAME}/${NATIVE_SESSION_MEMORY_CACHE_SUBDIR}`;
 }

package/dist/esm/ci/vitest-ci-shards.d.ts

@@ -4,11 +4,13 @@
  * All shards together still run every file discovered by vitest.config.ts
  * projects; each shard is a slice via `vitest run --shard=i/n`.
  *
- * Six shards keep max-shard job wall under the 150s Test average target when
- * serial-subprocess heavy files (package.contract, install-lock, etc.) cluster.
+ * Three shards on ubicloud-standard-2 cut billed runner-minutes (fewer
+ * parallel installs × smaller class) while keeping full suite coverage.
+ * Wall-clock per shard may rise vs the prior 6×standard-4 layout; that is an
+ * intentional minutes-vs-wall tradeoff (see docs/ci-test-perf.md).
  */
-export declare const VITEST_CI_SHARD_TOTAL = 6;
-export declare const VITEST_CI_SHARD_INDICES: readonly [1, 2, 3, 4, 5, 6];
+export declare const VITEST_CI_SHARD_TOTAL = 3;
+export declare const VITEST_CI_SHARD_INDICES: readonly [1, 2, 3];
 /** CLI args for a single shard (excludes `vitest` binary). */
 export declare function vitestCiShardArgs(shardIndex: number, shardTotal?: number): string[];
 /** Matrix values for GitHub Actions strategy.matrix.shard */

package/dist/esm/ci/vitest-ci-shards.js

@@ -4,11 +4,13 @@
  * All shards together still run every file discovered by vitest.config.ts
  * projects; each shard is a slice via `vitest run --shard=i/n`.
  *
- * Six shards keep max-shard job wall under the 150s Test average target when
- * serial-subprocess heavy files (package.contract, install-lock, etc.) cluster.
+ * Three shards on ubicloud-standard-2 cut billed runner-minutes (fewer
+ * parallel installs × smaller class) while keeping full suite coverage.
+ * Wall-clock per shard may rise vs the prior 6×standard-4 layout; that is an
+ * intentional minutes-vs-wall tradeoff (see docs/ci-test-perf.md).
  */
-export const VITEST_CI_SHARD_TOTAL = 6;
-export const VITEST_CI_SHARD_INDICES = [1, 2, 3, 4, 5, 6];
+export const VITEST_CI_SHARD_TOTAL = 3;
+export const VITEST_CI_SHARD_INDICES = [1, 2, 3];
 /** CLI args for a single shard (excludes `vitest` binary). */
 export function vitestCiShardArgs(shardIndex, shardTotal = VITEST_CI_SHARD_TOTAL) {
     if (!Number.isInteger(shardIndex) || shardIndex < 1 || shardIndex > shardTotal) {

package/dist/esm/cli/auto-update/guard-tombstone.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Observability tombstone for the self-install guard.
+ *
+ * Cycle-free leaf: no imports of the guard command or installer scheduler.
+ * Static-importable from the guard so mid-update installId package-tree
+ * deletion cannot race a package-local dynamic import.
+ *
+ * NOT a concurrency gate — the heartbeat lease in install-lock.ts owns
+ * mutual exclusion. Best-effort writes only.
+ */
+export interface Tombstone {
+    autoInstallInProgress: {
+        pid: number;
+        ts: number;
+    };
+}
+/**
+ * Build the canonical tombstone shape. Exported for testability.
+ */
+export declare function buildTombstone(pid: number, ts: number): Tombstone;
+/**
+ * Record the guard's pid + start time in the notifier cache for humans and
+ * `wp update`'s cache-reconcile step.
+ */
+export declare function writeGuardTombstone(): void;

package/dist/esm/cli/auto-update/guard-tombstone.js

@@ -0,0 +1,67 @@
+/**
+ * Observability tombstone for the self-install guard.
+ *
+ * Cycle-free leaf: no imports of the guard command or installer scheduler.
+ * Static-importable from the guard so mid-update installId package-tree
+ * deletion cannot race a package-local dynamic import.
+ *
+ * NOT a concurrency gate — the heartbeat lease in install-lock.ts owns
+ * mutual exclusion. Best-effort writes only.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { getSurfacePath } from "#paths/state-root.js";
+import { writeJsonFile } from "#shared-utils/write-json-file.js";
+import { logUpdateError } from "./log.js";
+/**
+ * Build the canonical tombstone shape. Exported for testability.
+ */
+export function buildTombstone(pid, ts) {
+    return { autoInstallInProgress: { pid, ts } };
+}
+/**
+ * Record the guard's pid + start time in the notifier cache for humans and
+ * `wp update`'s cache-reconcile step.
+ */
+export function writeGuardTombstone() {
+    try {
+        const configPath = resolveConfigPath();
+        if (configPath === null)
+            return;
+        writeTombstone(configPath, buildTombstone(process.pid, Date.now()));
+    }
+    catch (err) {
+        logUpdateError(err);
+    }
+}
+function resolveConfigPath() {
+    try {
+        return getSurfacePath("update-notifier-cache.json", "user");
+    }
+    catch {
+        return null;
+    }
+}
+function readRaw(configPath) {
+    if (!existsSync(configPath))
+        return {};
+    try {
+        const text = readFileSync(configPath, "utf-8");
+        if (text.trim().length === 0)
+            return {};
+        const parsed = JSON.parse(text);
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed))
+            return {};
+        return parsed;
+    }
+    catch {
+        return {};
+    }
+}
+function writeTombstone(configPath, tombstone) {
+    const dir = dirname(configPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const merged = { ...readRaw(configPath), ...tombstone };
+    writeJsonFile(configPath, merged, { atomic: true, indent: 0, trailingNewline: false });
+}

package/dist/esm/cli/auto-update/installer.d.ts

@@ -13,6 +13,8 @@
  * releases the lease. Concurrency control, the observability tombstone,
  * verification, and repair all live in the guard — this module only decides
  * WHETHER to spawn and wires the detached stdio to auto-update.log.
+ * Guard argv uses the cycle-free self-invocation leaf (never a full import of
+ * the guard command module).
  *
  * Invariants:
  *   - Synchronous: returns before the install starts.
@@ -25,15 +27,11 @@
  *     from a successful CLI run.
  */
 export { isProcessAlive } from "./install-lock.js";
+/** Re-export for existing call sites and tests (implementation in guard-tombstone). */
+export { buildTombstone, writeGuardTombstone, type Tombstone } from "./guard-tombstone.js";
 export interface InstallPlan {
     command: string[];
 }
-export interface Tombstone {
-    autoInstallInProgress: {
-        pid: number;
-        ts: number;
-    };
-}
 export interface ScheduleResult {
     /** Did we actually fork the guard child? */
     spawned: boolean;
@@ -56,14 +54,3 @@ export interface ScheduleDeferredInstallOptions {
  * holds the lease, the guard itself exits 12 without running anything.
  */
 export declare function scheduleDeferredInstall(plan: InstallPlan, options?: ScheduleDeferredInstallOptions): ScheduleResult;
-/**
- * Observability tombstone written by the self-install guard when it takes
- * the lease: records the guard's pid + start time in the notifier cache for
- * humans and `wp update`'s cache-reconcile step. NOT a concurrency gate —
- * the heartbeat lease in install-lock.ts owns mutual exclusion. Best-effort.
- */
-export declare function writeGuardTombstone(): void;
-/**
- * Build the canonical tombstone shape. Exported for testability.
- */
-export declare function buildTombstone(pid: number, ts: number): Tombstone;