jorgex-stack 1.9.6 → 1.9.8

package/README.md

@@ -106,21 +106,21 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. The published Stack `1.9.5` recognizes the exact package **`jorgex-pi@0.8.3`**. The Stack `1.9.6` candidate prepares adoption of the published package **`jorgex-pi@0.8.4`**, but `1.9.6` is not published yet.
+Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. The published Stack `1.9.7` recognizes the exact package **`jorgex-pi@0.8.4`**. Pi `0.8.5` is published independently; this checkout keeps the Stack `1.9.7` baseline with the Pi `0.8.5` candidate pin. On merge, Stack is expected to auto-bump to `1.9.8` and publish without waiting 24 hours.
 
-The current published command set uses Stack `1.9.5` with Pi `0.8.3`:
+The current published command set uses Stack `1.9.7` with Pi `0.8.4`:
 
 ```bash
-pnpm dlx jorgex-stack@1.9.5 install --agents pi
-pnpm dlx jorgex-stack@1.9.5 doctor --agents pi
-pnpm dlx jorgex-stack@1.9.5 models --agents pi
-pnpm dlx jorgex-stack@1.9.5 sync --agents pi
-pnpm dlx jorgex-stack@1.9.5 uninstall --agents pi
+pnpm dlx jorgex-stack@1.9.7 install --agents pi
+pnpm dlx jorgex-stack@1.9.7 doctor --agents pi
+pnpm dlx jorgex-stack@1.9.7 models --agents pi
+pnpm dlx jorgex-stack@1.9.7 sync --agents pi
+pnpm dlx jorgex-stack@1.9.7 uninstall --agents pi
 ```
 
-Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. The historical `0.8.0` tarball was `89128340` bytes; the exact current artifact and integrity values are authoritative in `src/lib/pi-runtime.ts`. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. After the package is healthy, Stack projects the shared resources into Pi: marked `jorgex:system-prompt` and `jorgex:engram-protocol` sections in `~/.pi/agent/AGENTS.md`, canonical skills under `~/.agents/skills`, and `~/.pi/agent/prompts/lean-audit.md`. When the managed Playwright preference is active, the projection also adds or removes the marked `jorgex:browser` section dynamically. The Pi-only `install --agents pi --playwright` flow installs and persists that Playwright capability just like the other harnesses. Chrome DevTools MCP and Context7 remain outside the Pi scope. The published `1.9.5` entry remains `{ "source": "npm:jorgex-pi@0.8.3", "skills": [], "prompts": [] }`; the `1.9.6` candidate changes that entry to `{ "source": "npm:jorgex-pi@0.8.4", "skills": [], "prompts": [] }`. Its code already recognizes the 0.8.4 receipt, while published-channel commands must wait for Stack 1.9.6 to be published. Filters are applied only after this projection exists, so the package does not duplicate shared resources. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Both receipts are scope-bound and fail closed for manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state.
+Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. The historical `0.8.0` tarball was `89128340` bytes; the exact current artifact and integrity values are authoritative in `src/lib/pi-runtime.ts`. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. After the package is healthy, Stack projects the shared resources into Pi: marked `jorgex:system-prompt` and `jorgex:engram-protocol` sections in `~/.pi/agent/AGENTS.md`, canonical skills under `~/.agents/skills`, and `~/.pi/agent/prompts/lean-audit.md`. When the managed Playwright preference is active, the projection also adds or removes the marked `jorgex:browser` section dynamically. The Pi-only `install --agents pi --playwright` flow installs and persists that Playwright capability just like the other harnesses. Chrome DevTools MCP and Context7 remain outside the Pi scope. The published `1.9.7` entry is `{ "source": "npm:jorgex-pi@0.8.4", "skills": [], "prompts": [] }`; the checkout's `0.8.5` entry is a candidate only. Filters are applied only after this projection exists, so the package does not duplicate shared resources. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Both receipts are scope-bound and fail closed for manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state.
 
-Historically, the published Pi 0.8.0 direct-package snapshot added `work-audit`: the snapshot grew from **17 to 18 skill trees** (96 to 97 files), and the active runtime allowlist grew from **16 to 17 skills**. `playwright-cli` remains in the snapshot but inactive because browser automation is a separate opt-in integration. The published 0.8.3 package preserves that work-audit introduction.
+Historically, the published Pi 0.8.0 direct-package snapshot added `work-audit`: the snapshot grew from **17 to 18 skill trees** (96 to 97 files), and the active runtime allowlist grew from **16 to 17 skills**. The Pi 0.8.5 candidate records 18 skill trees and 98 files; reference F2-A is included while the private F1 skills remain preserved. `playwright-cli` remains in the snapshot but inactive because browser automation is a separate opt-in integration.
 
 The historical published artifact has two separate provenance anchors. The local size/SHA-256/SHA-512 checks bind the downloaded bytes to Stack's accepted artifact; they are checks within that checkout, not independent trust roots. npm's external provenance/attestation is outside Stack runtime verification, and `provenance.commit` is informative unless that external attestation is independently verified.
 
@@ -132,9 +132,9 @@ The package owns Pi's native primary-model projection: `openai-codex/gpt-5.6-sol
 
 Engram remains mandatory and user-owned. An existing binary is preserved. Interactive install may offer the native `brew`/`go`/release channel with explicit confirmation; `--yes` and non-TTY installs fail with a remedy when Engram is absent. The database and memories are never updated or deleted, and uninstall never deletes the Engram binary. Under `--target-dir`, Stack accepts only `<target>/bin/engram`, isolates Pi/Home/XDG/AppData/temp/npm-cache paths inside the target, and never consults the host Engram or Pi configuration.
 
-The published Stack `1.9.5` recognizes the exact Pi receipt `npm:jorgex-pi@0.8.3`. The Stack `1.9.6` candidate code already recognizes `npm:jorgex-pi@0.8.4`; consuming that pairing through the published channel waits until Stack `1.9.6` is published. Use exact versions, never `latest`, and never edit receipts or hashes or delete `HOME`, Engram, or another runtime's projection to force trust. The transition and rollback commands are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
+The published Stack `1.9.7` recognizes the exact Pi receipt `npm:jorgex-pi@0.8.4`. Use exact versions, never `latest`, and never edit receipts or hashes or delete `HOME`, Engram, or another runtime's projection to force trust. The transition and rollback commands are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
-Stack 1.9.5 → Pi 0.8.3 is the current published pairing. Stack 1.9.6 → Pi 0.8.4 is only a candidate until Stack 1.9.6 is published. The 24-hour managed-consumption maturity rule applies only to real installation or consumption of the new Pi package; development, PR validation, merge and Stack publication may proceed immediately. Installing it on a real user scope before the maturity window requires Jorge's explicit exception.
+The 24-hour managed-consumption maturity rule applies only to real installation or consumption of the new Pi package; development, PR validation, merge and Stack publication may proceed immediately. Installing it on a real user scope before the maturity window requires Jorge's explicit exception.
 
 `update --agents pi` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` is a read-only Pi doctor. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 

package/dist/cli.js

@@ -5142,16 +5142,16 @@ import { createHash } from "crypto";
 var PI_RUNTIME_CANDIDATE = {
   package: {
     name: "jorgex-pi",
-    version: "0.8.4",
-    source: "npm:jorgex-pi@0.8.4"
+    version: "0.8.5",
+    source: "npm:jorgex-pi@0.8.5"
   },
   provenance: {
-    commit: "2b5cf37d9bfdb0c574e66712000ecc432eca8a69"
+    commit: "57cb15413c1dda408251ff80ff9d5658b7e91793"
   },
   tarball: {
-    bytes: 89133070,
-    sha256: "e30cbc0595bfbaa35b37f97096b77d46749315e3cf6ab13f830fe84432798b10",
-    sha512: "39255e7ccf7aad2cbe1069e2dbeb3335dc59f28ad1f0f32b677889e39e167e5fd39b546da9f448c33fad4581f0b4a8f1dda95a2f1b1bce010cc031b188ffc292"
+    bytes: 89133857,
+    sha256: "ea7ce0fa88c324d15756fbb1f7e222d2d87156de8a17cede8f3f317ad0d90c7e",
+    sha512: "0f6be4e79be3b7add6949b0d3d913a79acb0dd338ea0459d500358fec46ddb1925ad2ec926d0fbe899c7e48f0a7cb9681424fc1a0d1ab104e7e25d350478b989"
   },
   pi: {
     testedVersions: ["0.84.2"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.9.6",
+  "version": "1.9.8",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI, OpenCode y Pi",
   "type": "module",
   "license": "MIT",

package/stack/scripts/post-pr-review.cjs

@@ -132,8 +132,7 @@ function isPrReadinessCommand(command) {
 const message = `<pr-lifecycle-state-required>
 A PR readiness transition was attempted through \`gh pr create\` without \`--draft\` or through \`gh pr ready\`. Do not infer success or PR state from the command text. Resolve the current PR and run \`gh pr view --json number,isDraft,headRefOid\` before the next action.
 
-- The review boundary is the final draft diff. If the full review was not already completed, ensure the PR is draft (run \`gh pr ready --undo <number>\` if necessary), finish code, the applicable version bump, local tests, \`pnpm qa:quality\` when defined, Vercel preview review when applicable, and final diff inspection.
-- Load and run the portable \`xreview\` skill against that exact final diff. When an orchestrator owns an active work context, it must pass the exact \`work/{name}\` to every reviewer.
+- The review boundary is the final draft diff. If the full review was not already completed, ensure the PR is draft (run \`gh pr ready --undo <number>\` if necessary), finish code, the applicable version bump, local tests, \`pnpm qa:quality\` when defined, Vercel preview review when applicable, and final diff inspection, then load and run the portable \`xreview\` skill against that exact final diff. When an orchestrator owns an active work context, it must pass the exact \`work/{name}\` to every reviewer. If the review was already completed, retain its evidence and do not open another panel merely because readiness was attempted.
 - After fixing findings, repeat xreview only when the fixes materially change the diff or introduce a distinct risk. For ordinary fixes, explicit evidence of the prior review plus deterministic verification is sufficient even though \`headRefOid\` changed.
 - If the PR is actually ready, do not push. If the project has PR checks configured, wait for the complete Quality Gates, run \`gh pr checks <number>\`, and verify the checked headRefOid is the candidate SHA.
 - If no PR checks are configured, confirm that from project configuration such as workflows, rulesets or integrations, and record it; their absence does not block the merge. An empty \`gh pr checks\` result immediately after ready is not evidence that no checks are configured.

package/stack/skills/orchestrator/SKILL.md

@@ -1,241 +1,69 @@
 ---
 name: orchestrator
-description: Main coordinator for non-trivial tasks. Designs, plans and delegates to specialized subagents. Use it when the work spans several layers, several files or requires coordination. Invoke to switch into orchestrator mode and apply its flow to the current task.
+description: Main coordinator for non-trivial tasks. Routes work through a short or standard path, then coordinates the appropriate work. Use it when work spans several layers, several files, or requires coordination.
 ---
 
 # Orchestrator
 
-You coordinate the work. You think, design, split and delegate according to the **Delegation map**. Don't stay implementing yourself except for minimal documentation or coordination tasks.
+Route the work before starting a workflow. `short` and `standard` are routes, not new human/programmatic modes: their existing output contracts stay intact.
 
-## Phases
+## Routing
 
-```text
-INIT → EXPLORE → SPEC → PLAN → EXECUTE → VERIFY → SHIP → CLOSE
-```
+Choose **short** only when the objective is clear, the affected contract is understood, the scope is bounded, and the change has sufficient verification. Choose **standard** when scope, uncertainty, risk, or verification needs the formal workflow. A small change is not automatically safe: assess configuration, publication, security, and other affected contracts before routing.
 
-### Autonomy
+Short work has one primary responsible person; involve a specialist only when it adds value. It has no mandatory analyst, PRE, or POST chain. A short standalone change does not create a PRD, plan, formal task spec, PRE, or POST merely for ceremony.
 
-The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no confirmation pauses: plan approval authorizes commits, pushes to the work branch, draft PR creation, final review, and the draft-to-ready transition after verification. Task-critical uncertainty from a subagent is an operational blocker, not a pause in autonomy: answer from existing context first; only if the decision genuinely cannot be made from available context may you ask the user, then relaunch with explicit guidance. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished. Dependent PRs are sequential: after a checkpoint merge, update the production branch and create the next worktree/branch from that updated base.
+If short work expands in scope, risk, uncertainty, verification needs, or requires a material decision, promote it to standard **before** continuing. Do not use file counts, elapsed time, or delegation mechanics as routing rules.
 
-## 1. INIT
+An existing or active formal SDD work keeps its approved scope, Spec, plan row, ownership, and lifecycle even when a bounded implementation step is handled short. Do not create child formal tasks for phases or polls; if the work grows into an independent or persistent item, formalize it through `work-lifecycle` before continuing.
 
-- Load previous context from Engram memory: for non-trivial reads, delegate to the `engram` subagent (`mem_context` / `mem_search` filtered to the task).
-- Identify the project's constraints.
-- Detect whether there is documentation, issues or artifacts already created.
+The primary may implement or execute when a handoff or delegation adds no value. Otherwise, use the `agent-delegation` skill for the specialist's defined scope. Every subagent keeps that assigned scope and does not spawn subagents.
 
-## 2. EXPLORE
+Apply the `lean-code` skill as a scope gate for code-bearing work: ask whether the code is needed at all, whether project or platform capabilities already solve it, and whether the smallest obvious change is enough.
 
-Launch analysts according to scope:
+For the **standard** route, explicitly read and follow [references/standard-workflow.md](references/standard-workflow.md). Resolve that reference relative to this skill directory, never the repository CWD; if it cannot be read, report a blocker rather than silently falling back to short. It contains the formal PRD, plan, PRE, POST, change-first, and delivery workflow. Do not load it for short work unless the work is promoted.
 
-- `backend-analyst` if it affects backend, DB, APIs or server functions
-- `frontend-analyst` if it affects UI, hooks, state or rendering
-- `security-auditor` if the area is sensitive
+## Shared guards
 
-## Base rule
-
-- Your priority is to delegate.
-- If a task has a clear subagent scope, delegate.
-- If previous context is needed, gather context or analyze before deciding implementation.
-
-### Delegation triggers
-
-Once a task crosses any of these thresholds, delegating stops being optional:
-
-| Trigger | Expected behavior |
-| --- | --- |
-| Reading 4+ files just to understand a flow | Delegate exploration to the matching analyst. |
-| Wrong cwd, git/worktree accident, confusing test or env failure | Stop; re-explore with fresh context before continuing. |
-| Long session with accumulating complexity | Pause and re-plan or delegate — or state explicitly why not. |
-
-The goal is not ceremony: it is one responsible coordinator, one writer per scope, deterministic feedback while the diff is evolving, and fresh eyes at the PR boundary.
-
-## 3. SPEC
-
-- Synthesize findings.
-- Propose a simple approach.
-- Clarify only the real ambiguities.
-- Apply the `lean-code` skill as a scope gate for any code-bearing task: ask whether the code is needed at all, whether stdlib/native/project helpers already solve it, and whether the smallest obvious change is enough.
-- Backlog items phrased as "consider/evaluate X" are questions, not requirements: answer them HERE — who consumes it, what real case needs it — before they enter the PRD as committed scope. A contract nobody consumes is born dead; drop it or defer it explicitly instead of inheriting it as a fact.
-- Create the PRD before moving to PLAN (see PRD rules).
-
-### PRD rules
-
-The PRD is **mandatory by default** when you work as orchestrator. If you were invoked, the work is non-trivial (several layers, several files or coordination) and deserves a spec before executing. The PRD captures decisions before implementing and leaves traceability towards the tasks.
-
-Use the `to-prd` skill to turn the current context into the PRD (`work/{name}/PRD.md`) before planning execution.
-
-**Escape valve (measurable)**: skip the PRD only if one of these applies:
-
-- the user explicitly asks to skip it, or
-- ALL of these hold: the change touches ≤ 3 files, AND stays in a single layer (only backend, only frontend, only docs…), AND changes no public contract (API, schema, exported types consumed elsewhere). In that case, consider returning the work to the normal flow instead of orchestrating.
-
-If you skip it, say so explicitly and state which condition applied.
-
-When presenting the PRD for review, offer a disposable HTML view (rules in the `work-lifecycle` skill).
-
-If the work is large enough to benefit from explicit vertical slices, use the `to-issues` skill after the PRD to split it into independently executable slices before detailed planning.
-
-## 4. PLAN
-
-- Use the PRD as the base input for planning (it normally exists; only absent if the escape valve was used).
-- If a slice breakdown exists from `to-issues`, use it as the structure for planning and task sequencing.
-- Divide the work into clear tasks.
-- One task = one agent = one scope.
-- For tasks that add or grow code, record the lean-code outcome in the task spec/acceptance criteria so implementer and simplifier apply the same ladder.
-- The PRD does not replace the plan or task breakdown: the PRD captures decisions; the plan and tasks turn those decisions into executable work.
-- **Change-first**: for intentional material contract changes discovered in EXECUTE or VERIFY—not bugfixes that restore the approved contract—return to SPEC before further implementation. Update the PRD first, then propagate it to the plan, task specs, `SC-*` success criteria and testing decisions; rerun PRE until `clean`, obtain human approval of the delta, then resume EXECUTE and repeat VERIFY.
-- Materialize the plan per the Work state rules: `work/{name}/plan.md` with the task table and one declared recoverable spec source per formal task — an Engram observation or canonical Markdown (templates in the `work-lifecycle` skill). Record the exact source in `Spec`; never create two active copies.
-- Load and run the `work-audit` skill in **PRE** mode after the plan and task specs exist and before presenting the final plan. Pass the exact active `work/{name}` path and the exact PR/checkpoint scope; never infer either from the branch or scan other work folders. PRE is read-only: during audit remediation you are the only writer of active work artifacts. Route every finding to its owner artifact, correct it, and rerun PRE until it reports `clean`.
-- An unresolved `[NEEDS CLARIFICATION: ...]` marker blocks PRE. Return to SPEC and resolve the ambiguity with the user only when existing context cannot answer it; never approve or execute a plan while PRE is not clean.
-- When presenting the plan for human review, offer a disposable HTML view (rules in the `work-lifecycle` skill). If human review changes the PRD, plan or task specs, rerun PRE and require `clean` again before approval or EXECUTE. Requested changes go to plan.md; delete the HTML once its artifact is approved, before EXECUTE.
+Both routes preserve mandatory memory/Engram saves, testing/TDD by risk, Git/worktree discipline, final-draft review, configured gates, and explicit user approval for merge. Security, permissions, ownership, backups, dependency consent, and the existing human/programmatic output contracts are never relaxed by routing. Product documentation remains with `docs-maintainer` when it is needed; short routing does not absorb that owner's scope.
 
 ## Work state
 
-The `work-lifecycle` skill is the single source of this flow. Summary — every piece has exactly ONE home:
+The `work-lifecycle` skill is the single source for **formal SDD** work. Each formal task has one recoverable Spec source and one plan row. A direct or inline message is an auxiliary microassignment under a parent task, never a formal or independent task or a second Spec; if it grows into independent work, persist its formal task spec and plan row before continuing. Pass a delegated worker the exact Spec as read-only. Its distinct outcome topic_key must never overwrite that Spec; significant decisions and findings still require immediate memory saves, and checkpoint outcomes persist as required. Do not write memory for a poll or status without new information.
 
-- `work/{name}/` (gitignored, exists only while the work is in progress) holds the human-reviewed artifacts: `PRD.md` and `plan.md`. They stay resident across intermediate PR merges; `plan.md` is the ONLY task status board — flip statuses with surgical edits; don't re-read the whole plan after every task (re-read it on resume).
-- The full spec of each formal task has one declared recoverable source: an Engram observation identified by project + topic_key `work/{name}/task/{NN}` with verified identity/access, or canonical Markdown at `work/{name}/tasks/{NN}.md`. Record it in the plan's `Spec` column; existing Engram specs remain valid and need no migration. When you delegate, pass the title and exact `Spec` reference as read-only for the worker: Engram project + topic_key and an optional ID already bound to that identity in the current store, or the accessible absolute Markdown path. Follow the lifecycle handoff: direct get only with a known current-store binding; otherwise resolve by project/topic before get or block, then recheck identity.
-- A direct or inline message is an auxiliary, self-contained microassignment under a parent task, never a formal or independent task. If it grows or becomes independent, persist its task spec and add the plan row before continuing.
-- Phase outcomes, decisions and PR checkpoints → Engram under `work/{name}/{phase}` and `work/{name}/pr/{NN}`; when assigning a phase outcome, give the subagent an outcome topic_key distinct from its `Spec` reference. Never direct `mem_save` or `mem_update` of a result to the Spec observation or its topic_key.
-- Pending work → the project's single `work/backlog` topic_key, or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder. For Engram, you are the **single writer**: before every change, retrieve the exact observation with `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify. Never write it concurrently or use a blind topic-key upsert. Do not split it into per-item memories until Engram supports complete paginated topic-prefix listing.
-- On final close: `mem_save` the outcome under `work/{name}/done`, move the PRD to the project's docs only if it has lasting documentation value, then delete `work/{name}/`. `work/{name}/done` is only for the last PR / final outcome. History is memory + git.
+Phase outcomes, decisions and PR checkpoints → Engram under `work/{name}/{phase}` and `work/{name}/pr/{NN}`. The coordinator is the single writer for `work/backlog`: call `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify. Never mutate it concurrently. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished.
 
 ## Delegation map
 
-Load the `agent-delegation` skill: it defines the available subagents, the scope of each and when to delegate. It is the single source of the agent map — don't duplicate the list here.
-
-Every subagent follows its active result contract. Process it:
-
-- Launch every specialist named by the active delegation field or format.
-- A delegation is unfinished work in another scope, not a request to append a generic quality pipeline. Normal handoffs between `implementer` and `tester` do not by themselves justify reviewers or analyzers.
-- If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance.
-- If a subagent reports `blocked` with one concrete uncertainty question, answer it from existing context when possible; if it still cannot be resolved, ask the user only if genuinely necessary, then relaunch the original or a suitable specialist with explicit guidance.
-- Don't declare a phase done while a delegation remains unprocessed.
-- If the reported status is `partial` or `blocked`, resolve the cause before moving on.
-
-## 5. EXECUTE
-
-### Worktree
-
-Before the first task, create a git worktree for this work and run the ENTIRE execution inside it — implementation, tests, commits and pushes happen there, never on the user's main checkout.
-
-Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints (branch = worktree name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
-
-Every delegation prompt must state the worktree path as the ONLY allowed write root. After each writer subagent finishes, verify the user's main checkout is still clean (`git status` there); if the subagent wrote outside the worktree, STOP, move those changes into the worktree (patch/apply) and restore the main checkout before continuing. Subagent obedience is not a safety boundary — this check is.
-
-### Commit cadence
-
-Commit after each task or bounded group of tasks, with a message that reflects that task — the branch history must map to the plan. Never accumulate the whole work into one giant commit at the end.
-
-### Draft PR cadence
-
-- After the first coherent commit, push the branch and create the PR against its real base with `gh pr create --draft`. Do not wait until SHIP to open it.
-- Keep every code change, commit and push inside the draft phase. The PR remains draft until the code, applicable version bump, local tests, project quality command (`pnpm qa:quality` when defined), Vercel preview when applicable, final diff, and full review are complete.
-- Never push to a ready PR. If a ready PR needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft and repeat VERIFY and the final review before readying it again.
-
-### Handoff rule
-
-The analyst's **Recommendation** is the implementer's input. Sequence: analyst (map + design) → you turn it into tasks → `implementer`/`tester` execute. Don't launch `implementer` on an area no analyst has mapped unless the design is already clear from existing context.
-
-### Testing decision
-
-Every implementation task needs a testing decision, not automatically a new test. Establish:
-
-- the meaningful regression risk introduced by the change
-- the existing test that already protects it, if any
-- the new or changed behavior that needs protection
-- the strongest seam closest to that risk
-- the action: TDD/new test, update, reuse existing coverage, or no new test with a concrete trivial/mechanical/already-covered reason
-
-Prefer one authoritative test per behavior. Another layer is justified only when it protects a distinct contract. The task spec carries this decision so `tester` and `implementer` do not invent different strategies.
-
-### TDD mode
-
-Use for business rules, bugs/regressions, public contracts, invariants, security/data boundaries, or other behavior whose risk warrants new protection.
-
-```text
-tester (RED) → implementer (GREEN/REFACTOR)
-```
-
-### Direct mode
-
-Use for styling, wiring, generated code, mechanical refactors, trivial code, or changes already covered by an authoritative test. Direct mode still runs the cheapest sufficient verification and records why no new test was needed.
-
-```text
-implementer (direct change)
-```
-
-### Special delegations
-
-- `translator` for translations or multilingual visible text
-- `docs-maintainer` for documentation
-- `security-auditor` for sensitive review
-
-### Verification cadence
-
-Deterministic checks are the routine feedback loop while implementation is in progress: run the relevant tests, lint and typecheck/build checks at the cheapest seam that can catch the section's regressions. Verify by bounded, coherent sections (e.g. when a wave completes), not after every small change — and don't defer everything to a single big-bang check at the end either.
-
-Each writer verifies its own bounded area (e.g. its test file). The orchestrator runs shared checks such as the global typecheck once when the wave closes, never concurrently or repeatedly through several writers. Reserve the full suite for VERIFY unless a wave changed broad cross-cutting behavior and an earlier run has a concrete benefit.
-
-### CI and workflow scope
-
-CI guidance belongs here only when the task explicitly affects workflows, gates, path filters, execution frequency, or CI cost. Inspect the actual provider, workflows, triggers, jobs, commands, required checks, refs, and publication/recovery semantics; do not invent a universal CI recipe. For performance claims, compare like-for-like samples and label wall time, summed job time, queue time, and billing/usage separately.
-
-- Use explicit base/head (or equivalent) refs for diff and path decisions; validate command errors and shared configuration. If paths or configuration cannot be classified confidently, run the relevant lane or fail closed—never skip optimistically.
-- Draft/candidate validation may cancel obsolete validation runs when project semantics allow it, but never cancel a mutable publish/release job or leave publication halfway. Preserve required gates and recovery; do not change settings or fabricate checks without permission.
-
-### Early-review budget
+Load the `agent-delegation` skill: it defines the available subagents, their scopes, and when a specialist adds value. A delegation is unfinished work in another scope, not a generic quality pipeline. If a subagent reports `partial`, keep the safe work and relaunch only what still needs guidance. If a subagent reports `blocked` with one concrete uncertainty question, answer it from existing context when possible; if a material decision still cannot be resolved, suspend the work and ask the user for guidance before relaunching the original or a suitable specialist with that explicit guidance.
 
-An early review during EXECUTE is an **exception**, not a default phase. Use it only when there is a concrete risk that deterministic checks cannot cover and the feedback can materially change the remaining implementation. Typical candidates are a sensitive authorization boundary, a destructive migration, subtle concurrency/state consistency, or a broad public contract change.
+### Worktree and PR lifecycle
 
-- State the exact risk and the bounded diff section to inspect before launching anyone.
-- Use the single most relevant specialist. Do not load the `xreview` skill or run a generic multi-agent panel during EXECUTE.
-- Run at most one early review per bounded critical section, after that section is coherent rather than after each task inside it.
-- Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer` or `silent-failure-hunter` merely because a writer finished, a test task completed, several files changed or a commit is due.
-- File count, writer completion, commit, push, or draft PR creation are not early-review triggers. The review boundary is the final candidate SHA while the PR is still draft, immediately before `gh pr ready` in SHIP.
+Both routes follow the project Git/worktree rules; short is not an exception. Where those rules explicitly permit a trivial direct-main change, keep that exception; otherwise resolve the root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, and create/use `<project-root>/worktrees/<canonical-name>` or `<project-root>/worktrees/<canonical-name>-prNN` with the branch matching the worktree name.
 
-## 6. VERIFY
+After the first coherent commit, push the work branch and open the PR with `gh pr create --draft`. Keep it draft while it changes. Mark it ready once with `gh pr ready <number>`. If the project has PR checks configured, wait for Quality Gates, run `gh pr checks <number>`, and verify they pass for the latest commit candidate. If no PR checks are configured, confirm and record their absence; it does not block the merge. An empty `gh pr checks` result immediately after ready is not evidence that no checks are configured. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA. If a ready PR needs a fix, run `gh pr ready --undo <number>` before editing, then repeat verification, review, ready, and configured gates.
 
-- Run the minimum verification that is sufficient.
-- Reserve heavy suites for cases where they provide real value or the project requires them.
-- If POST identifies an intentional material contract change, follow the PLAN's change-first procedure before further implementation.
-- Load and run the `work-audit` skill in **POST** mode after deterministic checks. Pass the exact active `work/{name}` path and the exact current checkpoint scope. POST is read-only and must report `converged`; when it reports `gaps`, during audit remediation you are the only writer of active work artifacts: add normal plan tasks and persist their one declared spec source when needed, return to the phase that owns each gap, and rerun POST after the fixes.
-- Only after POST reports `converged`, validate against the plan's **Success criteria** and mark the success criteria complete. Tests passing is NOT enough: a criterion left unmet means the work is not done, even with a green suite.
-- Before SHIP, ensure all applicable preflight work is complete: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), and Vercel preview review when the project uses Vercel. React Doctor is manual/local, never assumed to be a GitHub Actions gate.
-- If something fails, go back to EXECUTE with fix tasks.
-- **Anti-thrashing**: max 3 attempts per failing task or criterion. If the third attempt still fails, STOP retrying — document what was tried and why it fails (save it under the work's topic_key), then re-plan the task with a different approach or stop and report the blocker. A hard blocker is the one legitimate reason to interrupt the autonomous run; retrying blindly is never one.
+After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. Merge always requires explicit user approval.
 
-## 7. SHIP (automatic)
+### Deterministic verification
 
-When the plan is fully applied and VERIFY passes:
+Deterministic checks are the routine feedback loop while implementation is in progress: run the relevant tests, lint, and typecheck/build checks at the cheapest seam that can catch the section's regressions. Verify coherent sections rather than every small edit or one big-bang run. Normal handoffs between `implementer` and `tester` do not by themselves justify reviewers or analyzers.
 
-1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Inspect the final diff against the PR's real base.
-2. Load and run the portable `xreview` skill against that final diff while the PR is still draft. Use the exact active `work/{name}` already established for this work and include it verbatim as the work context in every review subagent prompt; never infer it from the branch or scan other `work/*` folders. This is the one multi-agent review per PR and the definitive review boundary; draft PR creation is not. Process the report by its three levels:
-   - **Critical Issues (must fix)**: apply ALL of them — the PR must not reach merge with these open.
-   - **Important Improvements (should fix)**: apply the ones worth doing now, at your judgment.
-   - **Suggestions (nice to have)**: apply only if trivial and safe.
-3. Every finding you decide NOT to apply now goes to the project's `work/backlog` single topic_key — one line each: what + why deferred. Apply the safe serialized backlog protocol above; subagents only return candidate lines.
-4. For what you DO apply: add the new tasks to plan.md and persist one declared recoverable spec source per formal task, execute them as in EXECUTE, re-verify, and push the fixes while the PR remains draft. Re-run the `xreview` skill only if the fixes materially changed the reviewed diff or introduced a materially different risk; ordinary finding fixes need deterministic re-verification, not another panel.
-5. Once code, verification, preview, final diff, and review are complete, record the candidate SHA and mark the PR ready exactly once with `gh pr ready <number>`.
-6. Determine whether the project has PR checks configured by inspecting project configuration such as workflows, rulesets or integrations. If the project has PR checks configured, wait for the complete Quality Gates, run `gh pr checks <number>`, and verify they pass for the recorded candidate SHA. If no PR checks are configured, confirm and record their absence; it does not block the merge. An empty `gh pr checks` result immediately after ready is not evidence that no checks are configured. In either case, do not push while the PR is ready. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA.
-7. If any fix is needed, run `gh pr ready --undo <number>` before editing, return to EXECUTE, and repeat the full verification, review, ready, and — when configured — gate cycle. Never treat checks from an older SHA as merge evidence.
+### Early review
 
-## 8. CLOSE
+An early review during EXECUTE is an exception, not a default phase. Use it only for a concrete risk that deterministic checks cannot cover and whose feedback can change the remaining implementation. State the bounded risk, use the single most relevant specialist, and run at most one early review per bounded critical section. Do not load the `xreview` skill or run a generic multi-agent panel during EXECUTE.
 
-- STOP here and hand control back to the user only after configured Quality Gates pass for the latest commit, or after confirming that the project has no PR checks configured: report the candidate SHA, check result or confirmed absence, review findings applied vs deferred to `work/backlog`, and whether manual testing is advisable (recommend it for big or user-facing changes; small well-tested changes may not need it).
-- NEVER merge the PR yourself — merge only on an explicit user order. After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. After the final merge: persist the final outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
-- If the repo has its own skill for the closing steps (release, deploy, git, cleanup), that skill takes precedence over the default behavior.
+Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer`, or `silent-failure-hunter` merely because a writer finished, a test task completed, several files changed, or a commit is due. File count, writer completion, commit, push, or draft PR creation are not early-review triggers.
 
-## Task rule
+### Bounded retries
 
-A task must correspond to a single agent and a single scope. Don't mix production, tests, docs and translations in the same task.
+Both routes cap a failing task or criterion at three attempts. After the third failure, stop retrying, save the meaningful failure and what was tried through the required outcome or memory path, then re-plan with a different approach or report the blocker; never loop blindly.
+### Final review and PR lifecycle
 
-## Operational rules
+The review boundary is the final candidate SHA while the PR is still draft, immediately before `gh pr ready`. It is one final review, not a mandatory panel or multiple reviewers for short work. Load and run the portable `xreview` skill only when a full review has not already covered that final draft and its multi-agent review adds value; in that case, pass the exact active `work/{name}` to every review subagent prompt and do not infer it from another `work/*` folder. Re-run it only if fixes materially change the diff or introduce a materially different risk; otherwise retain the prior review evidence and run deterministic verification.
 
-- The coordinator must not mix scopes in a single task.
-- Read-only agents can run in parallel.
-- Write agents only run in parallel if they don't touch the same files.
+Both routes keep the PR draft while it changes, use the canonical Git worktree, complete review before ready, wait for configured gates, compare the candidate SHA before reporting or merging, and never merge without explicit user approval.
 
 ## Closing rule
 
-Don't declare the task finished if you have only analyzed or planned. There must be real execution by the subagents or a concrete blocker.
+Do not declare work finished after analysis or planning alone: complete the routed execution or report the concrete blocker.

package/stack/skills/orchestrator/references/standard-workflow.md

@@ -0,0 +1,189 @@
+# Standard workflow
+
+Read this reference only after the orchestrator routes work to **standard**. The standard route uses a formal SDD PRD and plan, with PRE before approval and POST before SHIP; it preserves change-first and the shared guards in SKILL.md.
+
+## Phases
+
+```text
+INIT → EXPLORE → SPEC → PLAN → EXECUTE → VERIFY → SHIP → CLOSE
+```
+
+### Autonomy
+
+The human drives the flow UP TO the plan: the idea, the PRD review and the plan review are interactive. Once the plan is approved, EXECUTE → VERIFY → SHIP run **autonomously** — no confirmation pauses: plan approval authorizes commits, pushes to the work branch, draft PR creation, final review, and the draft-to-ready transition after verification. Task-critical uncertainty from a subagent is an operational blocker, not a pause in autonomy: answer from existing context first; only if the decision genuinely cannot be made from available context may you ask the user, then relaunch with explicit guidance. Control returns to the user at CLOSE. Merging the PR is NEVER yours: it always requires an explicit user order. For multi-PR work, each merge is a checkpoint; keep `work/{name}/PRD.md` and `plan.md` alive until the roadmap is finished. Dependent PRs are sequential: after a checkpoint merge, update the production branch and create the next worktree/branch from that updated base.
+
+## 1. INIT
+
+- Load previous context from Engram memory: for non-trivial reads, delegate to the `engram` subagent (`mem_context` / `mem_search` filtered to the task).
+- Identify the project's constraints.
+- Detect whether there is documentation, issues or artifacts already created.
+
+## 2. EXPLORE
+
+Launch analysts according to scope:
+
+- `backend-analyst` if it affects backend, DB, APIs or server functions
+- `frontend-analyst` if it affects UI, hooks, state or rendering
+- `security-auditor` if the area is sensitive
+
+## 3. SPEC
+
+- Synthesize findings.
+- Propose a simple approach.
+- Clarify only the real ambiguities.
+- Apply the `lean-code` skill as a scope gate for any code-bearing task: ask whether the code is needed at all, whether stdlib/native/project helpers already solve it, and whether the smallest obvious change is enough.
+- Backlog items phrased as "consider/evaluate X" are questions, not requirements: answer them HERE — who consumes it, what real case needs it — before they enter the PRD as committed scope. A contract nobody consumes is born dead; drop it or defer it explicitly instead of inheriting it as a fact.
+- Create the PRD before moving to PLAN (see PRD rules).
+
+### PRD rules
+
+The PRD is **mandatory by default** when you work as orchestrator. If you were invoked, the work is non-trivial (several layers, several files or coordination) and deserves a spec before executing. The PRD captures decisions before implementing and leaves traceability towards the tasks.
+
+Use the `to-prd` skill to turn the current context into the PRD (`work/{name}/PRD.md`) before planning execution.
+
+
+When presenting the PRD for review, offer a disposable HTML view (rules in the `work-lifecycle` skill).
+
+If the work is large enough to benefit from explicit vertical slices, use the `to-issues` skill after the PRD to split it into independently executable slices before detailed planning.
+
+## 4. PLAN
+
+- Use the PRD as the base input for planning.
+- If a slice breakdown exists from `to-issues`, use it as the structure for planning and task sequencing.
+- Divide the work into clear tasks.
+- One task = one agent = one scope.
+- For tasks that add or grow code, record the lean-code outcome in the task spec/acceptance criteria so implementer and simplifier apply the same ladder.
+- The PRD does not replace the plan or task breakdown: the PRD captures decisions; the plan and tasks turn those decisions into executable work.
+- **Change-first**: for intentional material contract changes discovered in EXECUTE or VERIFY—not bugfixes that restore the approved contract—return to SPEC before further implementation. Update the PRD first, then propagate it to the plan, task specs, `SC-*` success criteria and testing decisions; rerun PRE until `clean`, obtain human approval of the delta, then resume EXECUTE and repeat VERIFY.
+- Materialize the plan per the Work state rules: `work/{name}/plan.md` with the task table and one declared recoverable spec source per formal task — an Engram observation or canonical Markdown (templates in the `work-lifecycle` skill). Record the exact source in `Spec`; never create two active copies.
+- Load and run the `work-audit` skill in **PRE** mode after the plan and task specs exist and before presenting the final plan. Pass the exact active `work/{name}` path and the exact PR/checkpoint scope; never infer either from the branch or scan other work folders. PRE is read-only: during audit remediation you are the only writer of active work artifacts. Route every finding to its owner artifact, correct it, and rerun PRE until it reports `clean`.
+- An unresolved `[NEEDS CLARIFICATION: ...]` marker blocks PRE. Return to SPEC and resolve the ambiguity with the user only when existing context cannot answer it; never approve or execute a plan while PRE is not clean.
+- When presenting the plan for human review, offer a disposable HTML view (rules in the `work-lifecycle` skill). If human review changes the PRD, plan or task specs, rerun PRE and require `clean` again before approval or EXECUTE. Requested changes go to plan.md; delete the HTML once its artifact is approved, before EXECUTE.
+
+
+## 5. EXECUTE
+
+### Worktree
+
+Follow the project Git/worktree rules before the first task. Standard work uses the canonical git worktree unless those rules explicitly permit a trivial direct-main exception; short never creates its own exception.
+
+Canonical location is mandatory: resolve the project root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, create `worktrees/` inside that root if needed, and create the worktree at `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints (branch = worktree name). Do not create worktrees next to the repo, in the repo root, under `work/`, or in any external temp/shared folder.
+
+Every delegation prompt must state the worktree path as the ONLY allowed write root. After each writer subagent finishes, verify the user's main checkout is still clean (`git status` there); if the subagent wrote outside the worktree, STOP, move those changes into the worktree (patch/apply) and restore the main checkout before continuing. Subagent obedience is not a safety boundary — this check is.
+
+### Commit cadence
+
+Commit after each task or bounded group of tasks, with a message that reflects that task — the branch history must map to the plan. Never accumulate the whole work into one giant commit at the end.
+
+### Draft PR cadence
+
+- After the first coherent commit, push the branch and create the PR against its real base with `gh pr create --draft`. Do not wait until SHIP to open it.
+- Keep every code change, commit and push inside the draft phase. The PR remains draft until the code, applicable version bump, local tests, project quality command (`pnpm qa:quality` when defined), Vercel preview when applicable, final diff, and full review are complete.
+- Never push to a ready PR. If a ready PR needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft and repeat VERIFY and the final review before readying it again.
+
+### Handoff rule
+
+The analyst's **Recommendation** is the implementer's input. Sequence: analyst (map + design) → you turn it into tasks → `implementer`/`tester` execute. Don't launch `implementer` on an area no analyst has mapped unless the design is already clear from existing context.
+
+### Testing decision
+
+Every implementation task needs a testing decision, not automatically a new test. Establish:
+
+- the meaningful regression risk introduced by the change
+- the existing test that already protects it, if any
+- the new or changed behavior that needs protection
+- the strongest seam closest to that risk
+- the action: TDD/new test, update, reuse existing coverage, or no new test with a concrete trivial/mechanical/already-covered reason
+
+Prefer one authoritative test per behavior. Another layer is justified only when it protects a distinct contract. The task spec carries this decision so `tester` and `implementer` do not invent different strategies.
+
+### TDD path
+
+Use for business rules, bugs/regressions, public contracts, invariants, security/data boundaries, or other behavior whose risk warrants new protection.
+
+```text
+tester (RED) → implementer (GREEN/REFACTOR)
+```
+
+### Direct path
+
+Use for styling, wiring, generated code, mechanical refactors, trivial code, or changes already covered by an authoritative test. Direct mode still runs the cheapest sufficient verification and records why no new test was needed.
+
+```text
+implementer (direct change)
+```
+
+### Special delegations
+
+- `translator` for translations or multilingual visible text
+- `docs-maintainer` for documentation
+- `security-auditor` for sensitive review
+
+### Verification cadence
+
+Deterministic checks are the routine feedback loop while implementation is in progress: run the relevant tests, lint and typecheck/build checks at the cheapest seam that can catch the section's regressions. Verify by bounded, coherent sections (e.g. when a wave completes), not after every small change — and don't defer everything to a single big-bang check at the end either.
+
+Each writer verifies its own bounded area (e.g. its test file). The orchestrator runs shared checks such as the global typecheck once when the wave closes, never concurrently or repeatedly through several writers. Reserve the full suite for VERIFY unless a wave changed broad cross-cutting behavior and an earlier run has a concrete benefit.
+
+### CI and workflow scope
+
+CI guidance belongs here only when the task explicitly affects workflows, gates, path filters, execution frequency, or CI cost. Inspect the actual provider, workflows, triggers, jobs, commands, required checks, refs, and publication/recovery semantics; do not invent a universal CI recipe. For performance claims, compare like-for-like samples and label wall time, summed job time, queue time, and billing/usage separately.
+
+- Use explicit base/head (or equivalent) refs for diff and path decisions; validate command errors and shared configuration. If paths or configuration cannot be classified confidently, run the relevant lane or fail closed—never skip optimistically.
+- Draft/candidate validation may cancel obsolete validation runs when project semantics allow it, but never cancel a mutable publish/release job or leave publication halfway. Preserve required gates and recovery; do not change settings or fabricate checks without permission.
+
+### Early-review budget
+
+An early review during EXECUTE is an **exception**, not a default phase. Use it only when there is a concrete risk that deterministic checks cannot cover and the feedback can materially change the remaining implementation. Typical candidates are a sensitive authorization boundary, a destructive migration, subtle concurrency/state consistency, or a broad public contract change.
+
+- State the exact risk and the bounded diff section to inspect before launching anyone.
+- Use the single most relevant specialist. Do not load the `xreview` skill or run a generic multi-agent panel during EXECUTE.
+- Run at most one early review per bounded critical section, after that section is coherent rather than after each task inside it.
+- Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer` or `silent-failure-hunter` merely because a writer finished, a test task completed, several files changed or a commit is due.
+- File count, writer completion, commit, push, or draft PR creation are not early-review triggers. The review boundary is the final candidate SHA while the PR is still draft, immediately before `gh pr ready` in SHIP.
+
+## 6. VERIFY
+
+- Run the minimum verification that is sufficient.
+- Reserve heavy suites for cases where they provide real value or the project requires them.
+- If POST identifies an intentional material contract change, follow the PLAN's change-first procedure before further implementation.
+- Load and run the `work-audit` skill in **POST** mode after deterministic checks. Pass the exact active `work/{name}` path and the exact current checkpoint scope. POST is read-only and must report `converged`; when it reports `gaps`, during audit remediation you are the only writer of active work artifacts: add normal plan tasks and persist their one declared spec source when needed, return to the phase that owns each gap, and rerun POST after the fixes.
+- Only after POST reports `converged`, validate against the plan's **Success criteria** and mark the success criteria complete. Tests passing is NOT enough: a criterion left unmet means the work is not done, even with a green suite.
+- Before SHIP, ensure all applicable preflight work is complete: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), and Vercel preview review when the project uses Vercel. React Doctor is manual/local, never assumed to be a GitHub Actions gate.
+- If something fails, go back to EXECUTE with fix tasks.
+- Apply the shared **Bounded retries** guard in `SKILL.md`.
+
+## 7. SHIP (automatic)
+
+When the plan is fully applied and VERIFY passes:
+
+1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Inspect the final diff against the PR's real base.
+2. Apply **Final review and PR lifecycle** in the entry [SKILL.md](../SKILL.md) and the project's review requirements. Reuse valid prior review evidence; choosing standard does not require another panel. Process the review findings by their three levels:
+   - **Critical Issues (must fix)**: apply ALL of them — the PR must not reach merge with these open.
+   - **Important Improvements (should fix)**: apply the ones worth doing now, at your judgment.
+   - **Suggestions (nice to have)**: apply only if trivial and safe.
+3. Every finding you decide NOT to apply now goes to the project's `work/backlog` single topic_key — one line each: what + why deferred. Apply the safe serialized backlog protocol above; subagents only return candidate lines.
+4. For what you DO apply: add the new tasks to plan.md and persist one declared recoverable spec source per formal task, execute them as in EXECUTE, re-verify, and push the fixes while the PR remains draft. Re-run the `xreview` skill only if the fixes materially changed the reviewed diff or introduced a materially different risk; ordinary finding fixes need deterministic re-verification, not another panel.
+5. Once code, verification, preview, final diff, and review are complete, record the candidate SHA and mark the PR ready exactly once with `gh pr ready <number>`.
+6. Determine whether the project has PR checks configured by inspecting project configuration such as workflows, rulesets or integrations. If the project has PR checks configured, wait for the complete Quality Gates, run `gh pr checks <number>`, and verify they pass for the recorded candidate SHA. If no PR checks are configured, confirm and record their absence; it does not block the merge. An empty `gh pr checks` result immediately after ready is not evidence that no checks are configured. In either case, do not push while the PR is ready. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA.
+7. If any fix is needed, run `gh pr ready --undo <number>` before editing, return to EXECUTE, and repeat the full verification, review, ready, and — when configured — gate cycle. Never treat checks from an older SHA as merge evidence.
+
+## 8. CLOSE
+
+- STOP here and hand control back to the user only after configured Quality Gates pass for the latest commit, or after confirming that the project has no PR checks configured: report the candidate SHA, check result or confirmed absence, review findings applied vs deferred to `work/backlog`, and whether manual testing is advisable (recommend it for big or user-facing changes; small well-tested changes may not need it).
+- NEVER merge the PR yourself — merge only on an explicit user order. After each intermediate merge: persist the checkpoint to `work/{name}/pr/{NN}`, update `plan.md`, and keep `work/{name}/` alive. After the final merge: persist the final outcome to memory, clean up `work/{name}/` and remove the worktree (see Work state).
+- If the repo has its own skill for the closing steps (release, deploy, git, cleanup), that skill takes precedence over the default behavior.
+
+## Task rule
+
+A task must correspond to a single agent and a single scope. Don't mix production, tests, docs and translations in the same task.
+
+## Operational rules
+
+- The coordinator must not mix scopes in a single task.
+- Read-only agents can run in parallel.
+- Write agents only run in parallel if they don't touch the same files.
+
+## Closing rule
+
+Don't declare the task finished if you have only analyzed or planned. There must be real execution by the subagents or a concrete blocker.

package/stack/skills/work-lifecycle/SKILL.md

@@ -7,16 +7,18 @@ description: Single source for how a piece of work is tracked and advances — P
 
 One rule kills duplication: **every piece of information has exactly ONE home**. Files hold human-reviewed artifacts and task specs deliberately chosen as Markdown; memory holds Engram-backed task specs and history. Nothing is ever stored in two places.
 
+This lifecycle applies after the canonical routing in the `orchestrator` skill selects **formal SDD** work. A short standalone change stays outside this lifecycle and does not create PRD, plan, formal task specs, PRE, or POST for ceremony. A bounded short step inside active formal SDD work preserves its approved Spec, plan row, ownership, and tracking. Routing criteria live only in `orchestrator`; do not copy them here.
+
 ## Identity
 
-Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the single-PR branch/worktree name and the base name for multi-PR checkpoints. The name stays the same across its whole life — it is the key to everything else.
+Every formal SDD piece of work gets a **canonical kebab-case name** when it starts (e.g. `checkout-refactor`), shared with the single-PR branch/worktree name and the base name for multi-PR checkpoints. The name stays the same across its whole life — it is the key to everything else.
 
 ## Where everything lives
 
 | Piece | Single home | Why there |
 |---|---|---|
-| PRD | `work/{name}/PRD.md` | Written once, reviewed by the human |
-| Plan (goal, approach, task board) | `work/{name}/plan.md` | The status board: humans glance at it; statuses flip with surgical edits |
+| Formal SDD PRD | `work/{name}/PRD.md` | Written once, reviewed by the human |
+| Formal SDD plan (goal, approach, task board) | `work/{name}/plan.md` | The status board: humans glance at it; statuses flip with surgical edits |
 | Full spec of each formal task | One recoverable source: Engram project + topic_key `work/{name}/task/{NN}` **or** `work/{name}/tasks/{NN}.md` | Choose for durable access; record the exact reference in the plan |
 | PR checkpoint outcome | Engram `work/{name}/pr/{NN}` | Intermediate PR merge record |
 | Phase outcomes, decisions, findings | Engram `work/{name}/{phase}` | History — must survive the folder and compactions |
@@ -27,6 +29,8 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 
 ## Starting
 
+Use this section only after routing selects formal SDD work, including work promoted from short before it expands. Do not use it to formalize a standalone short change by ceremony.
+
 1. Pick the canonical name and create `work/{name}/`. If the item came from the backlog, remove it from `work/backlog` in the same step.
 2. Produce the PRD with the `to-prd` skill → `work/{name}/PRD.md`. The human reviews it there.
 3. Write `work/{name}/plan.md` (structure in `references/plan-template.md`): goal, chosen approach, `SC-*` success criteria, PR roadmap, and the task table — number, PR, agent, scope, **Spec**, title, one-line description, SC coverage, status, wave, deps.

package/stack/system-prompt/AGENTS.md

@@ -89,9 +89,9 @@ docs/
 
 ## Work State
 
-Every piece of information about a piece of work has exactly ONE home — never two. The `work-lifecycle` skill is the single source of this flow.
+Every piece of information about a piece of work has exactly ONE home — never two. The `work-lifecycle` skill is the single source of this flow for formal SDD work. The canonical `orchestrator` routing decides whether work is short or standard; a standalone short route does not create PRD, plan, formal Specs, PRE, or POST by ceremony, while a short step inside active formal SDD work preserves its approved tracking and ownership.
 
-- In-progress work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. They stay there across intermediate PR merges; `plan.md` is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
+- In-progress formal SDD work lives in `work/{name}/` (gitignored): `PRD.md` + `plan.md`. They stay there across intermediate PR merges; `plan.md` is the ONLY task status board — update statuses with surgical edits. An empty `work/` means nothing is half-done.
 - Execution worktrees and their branches always use the same name. Resolve the root with `git rev-parse --show-toplevel`, ensure `worktrees/` is ignored in the repo-local `.git/info/exclude`, then create/use `<project-root>/worktrees/<canonical-name>` for single-PR work or `<project-root>/worktrees/<canonical-name>-prNN` for multi-PR checkpoints; never create worktrees next to the repo, in the repo root, under `work/`, or in external temp/shared folders.
 - Every formal task has one declared recoverable spec source: an Engram observation identified by project + topic_key `work/{name}/task/{NN}` with verified identity/access (optional local ID bound in the current store; resolve per the lifecycle handoff before get), or canonical Markdown at `work/{name}/tasks/{NN}.md`; its plan `Spec` column is the reference. Direct messages are only auxiliary microassignments under a parent task; if one becomes independent, persist its spec and add its plan row before continuing. Phase outcomes, PR checkpoints and history remain in Engram under `work/{name}/{phase}`, `work/{name}/pr/{NN}` and `work/{name}/done`.
 - Pending work: the project's single `work/backlog` topic_key, or issues (`to-issues`) if the project uses a tracker. Never a TODOs folder. The coordinator/orchestrator is its **single writer**: retrieve the exact observation with `mem_get_observation`, preserve unrelated entries, send the complete content with `mem_update`, then read it again to verify; never mutate it concurrently or use a blind topic-key upsert. Do not split it into one memory per item until Engram supports complete paginated topic-prefix listing.