jorgex-stack 1.9.11 → 1.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.9.11",
+  "version": "1.9.13",
   "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/agents/code-reviewer.md

@@ -13,8 +13,8 @@ You are an expert code reviewer specializing in modern software development acro
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Get the diff.** When you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, review the working diff (`git diff`).
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** Explicit primary/support scope and pinned base/head SHAs override defaults: review the primary hunks and only the support needed for that contract or risk, including unchanged files. Otherwise, resolve supplied branches to SHAs before diffing, or use the working diff when none are supplied. Never assume `main` or silently widen the assignment.
 3. Load the `agent-delegation` skill.
 
 **Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.

package/stack/agents/code-simplifier.md

@@ -15,8 +15,8 @@ You are read-only: you analyze recently modified code and **propose** refinement
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Resolve scope.** If you're given an audit scope (repo/path root), audit only that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Resolve scope.** An explicit repo/path audit stays within that audit target, not a default diff. For diff review, explicit primary/support scope and pinned base/head SHAs override defaults: inspect primary hunks and only the support needed for the assigned simplification. Otherwise, resolve supplied branches to SHAs, or use the working diff when none are supplied. Never assume `main` or silently widen the assignment.
 3. Load the `lean-code` skill.
 4. Load the `agent-delegation` skill.
 

package/stack/agents/docs-maintainer.md

@@ -1,6 +1,6 @@
 ---
 name: docs-maintainer
-description: Evidence-first documentation specialist. Use it AFTER behavior or APIs change to keep the repo's /docs folder and any public docs site (website, app, docs portal) accurate and in sync — content, navigation and metadata. Writes docs only — not for product logic, features or bug fixes.
+description: Evidence-first documentation specialist. Use when changed use, contracts or operations need explanation, or existing documentation becomes inaccurate. Updates affected internal/public content, navigation and metadata — not product logic or documentation for every edit.
 mode: subagent
 tier: cheap
 readonly: false
@@ -17,20 +17,20 @@ You handle functional or technical documentation. It may be public, internal or
 
 ## Targets
 
-You are responsible for keeping these up to date whenever they exist:
+Start with the affected surfaces in the assignment and their necessary references; discover additional surfaces only when the impact is unclear:
 
-1. **Repo `/docs` folder** — the project's internal/technical documentation (always check this first).
+1. **Repo `/docs` folder** — affected internal/technical documentation, when relevant to the change.
 2. **Public docs site** — any user-facing documentation living in a website, app or docs portal (e.g. a `docs` route, a docs app, a separate docs package or site).
 
 When a change affects both, keep them consistent with each other.
 
 ## Goal
 
-Keep the documentation artifacts that exist in the project in sync, without assuming a fixed structure.
+Keep the affected documentation accurate without assuming a fixed structure or documenting every implementation detail. Internal docs should explain non-obvious contracts and operations; public docs should help users complete tasks with simple language. Avoid volatile versions or duplicated history unless they are operationally necessary.
 
 ## Possible layers
 
-Not every project has all of them. Check which ones exist:
+Not every affected surface has all of these layers. Check those relevant to the changed pages:
 
 1. **Content** — markdown, mdx, text docs
 2. **Navigation** — sidebar, tree, index, menu, docs routing
@@ -44,7 +44,7 @@ If you change a page, check whether navigation or metadata must also be updated.
 
 - Establish the **allowed write root**. An explicit worktree or write-root path in the assignment always wins; otherwise use the current repository root.
 - Run `git rev-parse --show-toplevel` and inspect the current branch before the first write. Resolve every target path and confirm it stays inside the allowed write root. If the current checkout or any target does not match, do not write: return `blocked` with the mismatch.
-- Search for references to the title, slug, path or concept you are about to change.
+- Use the assignment's scope and existing source-to-claim evidence; search for references to changed titles, slugs, paths or concepts only where needed to keep affected content coherent.
 - Identify whether the documentation is public, internal or hybrid.
 - Follow the project's real pattern; do not impose a new one without need.
 
@@ -52,7 +52,7 @@ If you change a page, check whether navigation or metadata must also be updated.
 
 Documentation is an evidence task, not a creative reconstruction.
 
-- Build a **source-to-claim** map before drafting: every new technical claim must trace to current code, schemas or migrations, tests, canonical project docs, or git history.
+- Trace every added or changed technical claim to current code, schemas or migrations, tests or canonical project docs; reuse an existing **source-to-claim** map when still valid rather than creating another artifact. A plan states intent, not proof of implemented or published behavior. Distinguish current, candidate and conditional states when that difference changes the claim.
 - Use implementation to classify components. An invocation name is not proof of its implementation type; inspect the defining file before calling something an RPC, database function, API route, Edge Function, job or service.
 - Use git history only when claiming when or in which change something was introduced. Current existence does not prove recent origin.
 - **Never invent** names, paths, symbols, chronology, or snippets. Copy identifiers exactly from a source that exists in the allowed write root.
@@ -70,13 +70,15 @@ Documentation is an evidence task, not a creative reconstruction.
 
 ## Before reporting
 
-- Review the final documentation diff sentence by sentence. Re-check each added or changed factual claim against its source and confirm every mentioned file exists.
+- Review the final documentation diff sentence by sentence. Verify added or changed factual claims against inspected sources or still-valid evidence, and confirm mentioned files exist. Reread sources when they change, conflict or no longer support the claim; do not repeat unrelated investigation.
 - Re-run the location check and confirm all changed files are inside the allowed write root.
 - Remove unsupported claims instead of weakening them with vague language.
 
 ## Rules
 
 - Scope your work to the affected documentation.
+- A consolidated pass is not a prohibition on corrections: reopen affected pages when their contract changes, without restarting all documentation work.
+- Documentation-site and help content belong here. Product logic, ordinary UI text, comments and translation retain their existing owners; PRD, plan, task specs, memory and PR descriptions remain coordination work.
 - If the docs system has separate content, navigation and metadata, keep them in sync.
 - Do not touch product logic except for minimal edits strictly needed to link docs.
 

package/stack/agents/security-auditor.md

@@ -11,8 +11,8 @@ bash: git-read
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** Explicit primary/support scope and pinned base/head SHAs override defaults: audit primary hunks and the support needed to trace the assigned security risk, including unchanged dependencies or consumers. Otherwise, resolve supplied branches to SHAs, or use the working diff when none are supplied. Never assume `main` or silently widen the assignment.
 3. Load the `agent-delegation` skill.
 
 **Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.

package/stack/agents/silent-failure-hunter.md

@@ -13,8 +13,8 @@ You are an elite error handling auditor with zero tolerance for silent failures
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Get the diff.** When you're given BASE and HEAD branches, audit only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no branches are given, audit the working diff (`git diff`).
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** Explicit primary/support scope and pinned base/head SHAs override defaults: audit primary hunks and the support needed to trace the assigned failure paths, including unchanged dependencies or consumers. Otherwise, resolve supplied branches to SHAs, or use the working diff when none are supplied. Never assume `main` or silently widen the assignment.
 3. Load the `agent-delegation` skill.
 
 **Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.

package/stack/agents/test-analyzer.md

@@ -13,8 +13,8 @@ You determine whether the diff has sufficient evidence for its meaningful regres
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria, current PR slice and testing decision. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Get the diff.** When given BASE and HEAD, review only `git diff <BASE>...HEAD` using exactly those branches—never assume `main`. Otherwise review the working diff (`git diff`). Identify the behavior changed by that diff and inspect the relevant evidence, including existing tests outside the diff and related test infrastructure when needed. Do not turn the analysis into a repository-wide suite or unrelated CI audit.
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria, current PR slice and testing decision. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Get the diff.** Explicit primary/support scope and pinned base/head SHAs override defaults. Evaluate protection of the assigned contract using its primary diff and necessary production code, tests and runner evidence, including unchanged files; do not audit the entire implementation by default. Otherwise, resolve supplied branches to SHAs, or use the working diff when none are supplied. Never assume `main` or widen this into an unrelated repository/CI audit.
 3. Load the `tdd` skill. Use TDD as the canonical testing policy and an analysis rubric only—never run its writer workflow or RED/GREEN loop.
 4. Load the `agent-delegation` skill.
 

package/stack/agents/type-design-analyzer.md

@@ -13,8 +13,8 @@ You are a type design expert with extensive experience in large-scale software a
 
 **First actions, in order**:
 
-1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Resolve scope.** If you're given an audit scope (repo/path root), inspect only type/interface/schema/contract definitions in that path and do not fall back to `git diff`. Otherwise, when you're given BASE and HEAD branches, review only `git diff <BASE>...HEAD` using exactly those branches — never assume `main`. If no audit scope or branches are given, review the working diff (`git diff`).
+1. **Load the work context when provided.** If the caller gives you an exact work context path, read only the sections of its `PRD.md` and `plan.md` needed for the assigned scope before inspecting the diff; do not preload unrelated checkpoints or history. Use them to understand the goal, non-goals, constraints, success criteria and current PR slice. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
+2. **Resolve scope.** An explicit repo/path audit targets its type/interface/schema/contract definitions, not a default diff. For diff review, explicit primary/support scope and pinned base/head SHAs override defaults: inspect primary definitions and only the supporting usages needed for their invariants. Otherwise, resolve supplied branches to SHAs, or use the working diff when none are supplied. Never assume `main` or silently widen the assignment.
 3. Load the `agent-delegation` skill.
 
 **Final output, last of all**: your final report (ending with the Result contract) must be the very last thing you emit. If you need to save anything to memory, do it BEFORE that output — never after.

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

@@ -132,11 +132,11 @@ 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, 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.
+- The review boundary is the final draft diff. If reliable review coverage is missing for the current candidate, 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 for the missing coverage on that exact diff. When an orchestrator owns an active work context, it must pass the exact \`work/{name}\` to every reviewer. Retain still-valid review evidence and do not open another panel merely because readiness was attempted.
+- After fixing findings, revalidate coverage: fix-check for the finding, delta-review for affected contracts or risks, and full review only when reliable coverage must be established or broadly rebuilt. A material change requires reassessment, not automatically the same full panel. Retain prior evidence only where its assumptions remain valid; a previously clean role reopens when its dependencies or risks change.
 - 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.
-- Immediately before reporting or merging, compare \`gh pr view --json headRefOid\` with the recorded candidate SHA. Merge still requires explicit user approval.
+- Immediately before reporting or merging, compare \`gh pr view --json headRefOid\` with the recorded candidate SHA and recheck the effective base and integration context; the same head alone does not preserve review coverage. Merge still requires explicit user approval.
 </pr-lifecycle-state-required>`;
 
 let raw = "";

package/stack/skills/orchestrator/SKILL.md

@@ -27,6 +27,12 @@ For the **standard** route, explicitly read and follow [references/standard-work
 
 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.
 
+## Documentation when needed
+
+The coordinator identifies the audience and affected surfaces when a change needs an explanation of use, contract or operation, or makes an existing claim incorrect. Create documentation only for a concrete reader or operational need; an internal refactor or already-correct description does not require new prose. Product documentation stays with `docs-maintainer`, outside the review panel; code comments, ordinary UI text, translation and work-tracking artifacts keep their existing owners.
+
+Identify needs during execution, then consolidate the necessary documentation pass once the implementation and fixes are stable, before ready for each checkpoint that needs it. Do not wait until the end of a roadmap that publishes intermediate behavior. Later contract changes reopen only affected pages; a prose correction alone does not invalidate unchanged code review, while a contractual correction requires reassessing review coverage.
+
 ## Decision before delegation
 
 Use analysis only where it resolves an uncertainty that matters. An analyst's recommendation is evidence for the coordinator, not an implementation order: check the decisive sources, distinguish facts from assumptions, and close the scope, approach, relevant invariants and verification seam before delegating implementation. For formal work, record those decisions in its single Spec. Do not repeat the whole investigation or copy its report into the task.
@@ -68,7 +74,11 @@ Do not launch `code-reviewer`, `code-simplifier`, `test-analyzer`, or `silent-fa
 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
 
-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 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 when its scoped review adds value and reliable coverage is missing; pass the exact active `work/{name}` to every review subagent, never another work folder. Freeze base/head and merge-base, assign primary responsibility plus necessary support, and preserve each specialist's output contract.
+
+Use the [coverage revalidation rule](../xreview/SKILL.md#7-revalidate-coverage-and-stop): fix-check for a finding, delta-review for affected risks, full review when reliable coverage must be established or broadly rebuilt. A material change requires reassessing coverage, not automatically rerunning the same panel. Previously clean roles reopen when their contracts, dependencies or assumptions change; commits and readiness alone do not trigger reviewers. Record the scope and justification for retained evidence in the existing checkpoint, including changes to base or integration context even when head is unchanged.
+
+Triage valid findings before work/backlog creation, reconcile duplicates and reject false positives with reasons. New valid findings are not discarded for being new. Close when blocking findings and material uncertainty are resolved, fixes verified and current coverage justified, not when there are zero suggestions; the bounded-retry guard still applies.
 
 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.
 

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

@@ -79,7 +79,7 @@ Commit after each task or bounded group of tasks, with a message that reflects t
 
 - 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.
+- 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 applicable review revalidation from the common coverage rule before readying it again.
 
 ### Handoff rule
 
@@ -116,7 +116,7 @@ implementer (direct change)
 ### Special delegations
 
 - `translator` for translations or multilingual visible text
-- `docs-maintainer` for documentation
+- `docs-maintainer` for the affected documentation under [Documentation when needed](../SKILL.md#documentation-when-needed); consolidate the pass with stable implementation, not one dispatch per edit or a new review-panel member
 - `security-auditor` for sensitive review
 
 ### Verification cadence
@@ -157,16 +157,16 @@ An early review during EXECUTE is an **exception**, not a default phase. Use it
 
 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.
+1. Confirm the draft PR exists, the worktree is clean, and the draft head matches the local HEAD. Complete any necessary documentation under the common rule and inspect the consolidated final diff against the PR's real base; do not publish intermediate behavior with required documentation missing.
 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.
+3. Reconcile duplicates, false positives and disputed premises before creating work. Only valid work deliberately deferred goes to the project's `work/backlog` single topic_key — what + why deferred. Use the safe serialized protocol; subagents only return candidate lines. Do not backlog rejected findings or discard valid findings merely because they are new.
+4. For accepted fixes, reuse the bounded owning task where appropriate; formalize genuinely new independent work through the existing lifecycle. Execute and verify while draft. Apply the common coverage revalidation rule: fix-check, delta-review or full review according to affected contracts and evidence, not another full panel by default. Preserve justified clean coverage and reopen it when dependencies or assumptions change.
 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.
+7. If any fix is needed, run `gh pr ready --undo <number>` before editing, return to EXECUTE, and repeat the full verification, review revalidation, ready and configured gate cycle. Review revalidation follows the common coverage rule, not an automatic panel. Never treat checks from an older SHA as merge evidence; recheck the effective base and integration context as well.
 
 ## 8. CLOSE
 

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

@@ -55,7 +55,7 @@ Use this section only after routing selects formal SDD work, including work prom
 3. Continue implementation, commits and pushes only while the PR is draft. Draft means the code can still change; ready means the current SHA is the candidate to merge.
 4. Before ready, complete every applicable preflight item: code, version bump, local tests, project quality command (`pnpm qa:quality` when defined), Vercel preview review when the project uses Vercel, final diff inspection, and full PR review.
 5. Mark 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 the checks belong to the latest commit. 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. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA.
-6. Never push to a ready PR. If it needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat preflight and review, mark ready again, and wait for a fresh complete gate when checks are configured.
+6. Never push to a ready PR. If it needs changes, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat preflight and review revalidation, mark ready again, and wait for a fresh complete gate when checks are configured. Use [coverage revalidation](../xreview/SKILL.md#7-revalidate-coverage-and-stop), not an automatic repeated panel; preserve evidence only for still-valid contracts and integration assumptions, including the effective base.
 7. Merge only after explicit user approval. When PR checks are configured, their passing result must match the current candidate SHA.
 
 Dependent PRs are sequential: merge one checkpoint, update the production branch, then create the next worktree/branch from that updated base. Do not stack a dependent PR from an unmerged work branch unless the human explicitly chooses a stacked-PR strategy.

package/stack/skills/xreview/SKILL.md

@@ -3,13 +3,13 @@ name: xreview
 description: Conditional multi-agent code review — determines what to review (asking if unclear), resolves the exact diff, and launches only the relevant subagents in parallel
 ---
 
-Run a comprehensive multi-agent review. Your job as the main agent: determine WHAT to review, resolve the exact diff, decide which subagents apply, and launch them in parallel.
+Determine what needs review, freeze the evidence, and assign only the relevant specialist scopes. Reuse justified coverage after fixes; an explicitly requested fresh or full review still takes precedence over reuse.
 
 ## 0. Determine the review target
 
 Review target (may be empty): use the invocation context or the explicit target supplied by the caller.
 
-- If the input names a branch → review `git diff <that-branch>...HEAD`.
+- If the input names a branch → select it as BASE and resolve immutable refs before reviewing.
 - If the input references a PR (number or URL) → use that PR's base branch as BASE.
 - If the input names files/paths/areas → review the changes touching those paths.
 - If the input is empty or ambiguous: do a quick, cheap situation scan first — uncommitted changes (`git status --short`), current branch, open PR for it (`gh pr view --json baseRefName --jq .baseRefName`) — and ASK the user what to review before launching anything, offering only the options that actually apply:
@@ -23,7 +23,7 @@ Do NOT guess silently: a review against the wrong target wastes every subagent a
 
 ## 1. Resolve BASE and HEAD (branch/PR reviews)
 
-HEAD is the current branch / worktree being worked on (`git rev-parse --abbrev-ref HEAD`).
+HEAD identifies the current branch/worktree; branch names are labels, not immutable review evidence.
 
 BASE is the branch the work will merge into. Do NOT default to `main` — work is often done in sub-branches whose PR targets another branch. Resolve BASE in this order:
 
@@ -32,37 +32,43 @@ BASE is the branch the work will merge into. Do NOT default to `main` — work i
 3. Otherwise, inspect local and `origin/*` branches and choose the branch directly underneath the current branch: the candidate whose merge-base with HEAD is newest/closest to HEAD, excluding the current branch itself and its remote tracking ref.
 4. If still unsure, ask the user — never silently fall back to `main`.
 
-Print the chosen BASE and HEAD and why BASE was selected. (For working-tree reviews there is no BASE: the scope is `git diff` + `git diff --staged`.)
+Resolve the selected refs to full commit SHAs, record `BASE_SHA`, `HEAD_SHA` and their merge-base, and review `git diff <BASE_SHA>...<HEAD_SHA>`. Print the refs, SHAs and why BASE was selected; do not leave reviewers to resolve a moving `HEAD` independently. If the base or merge-base is ambiguous, resolve the scope before launching them.
+
+For working-tree reviews, state the staged, unstaged and relevant untracked changes actually included. They are not evidence for a committed SHA. If the working state changes during review, revalidate the affected coverage rather than attributing it to the old snapshot; never stage files merely to manufacture review evidence.
 
 ## 2. Decide routing (lightweight)
 
-List only the changed file NAMES to decide routing — do NOT load the full diff into your own context:
-`git diff <BASE>...HEAD --name-only` (or `git diff --name-only` + `git diff --staged --name-only` for working-tree reviews).
+Start with changed file NAMES: `git diff <BASE_SHA>...<HEAD_SHA> --name-only` (or the working-tree inventory). Read only the decisive hunks when names are insufficient to classify a contract or risk; do not preload the entire diff by habit.
 
 Sanity check: if that list is far larger than the work being reviewed (hundreds of files, unrelated areas), BASE is almost certainly wrong — STOP, re-resolve it (step 1), and only continue when the diff matches the actual work. Reviewing against the wrong BASE makes every finding worthless.
 
+Account for every changed group, including tests, docs, configuration and generated files, and explain deliberate exclusions. Assign each reviewer a **primary scope** (paths/hunks and the contract or risk it owns) and **support context** (directed dependencies, consumers, tests or docs needed to understand it, including unchanged files). Primary is responsibility, not exclusive file ownership or an access-permission boundary. Do not hand every reviewer the entire diff by default or forbid a test reviewer from reading the production contract.
+
 ## 3. Preserve the work context
 
 When running inside the orchestrator's SHIP phase, the main agent already owns the exact active `work/{name}`. Preserve it as the review context and pass it verbatim to every review subagent. Do not infer a work name from the branch or search `work/*`; several pieces of work may be active at once.
 
+Use only the goal, constraints, criteria and plan sections relevant to the assigned review. Passing the exact work path is not a request to reload every historical checkpoint or the whole conversation.
+
 For a manual xreview without an explicit work context, continue without PRD/plan context and state that it was unavailable. Never choose a work folder silently.
 
 ## 4. Comment pass FIRST (conditional)
 
 If the diff adds or changes comments/docstrings, run `comment-fixer` ALONE before the analysts — it edits comments in place (comments only, never code), so the analysts then review a diff already clean of comment noise instead of re-reporting it or mistaking its edits for contamination.
 
-- Pass it the same scope (BASE/HEAD or working diff) as everyone else.
+- Pass the frozen refs or working-state identity and the relevant comment/docstring scope.
 - When the orchestrator supplied one, pass it the same exact work context path as every other review subagent.
-- If it changed anything and the scope is a committed diff (branch/PR): comment-fixer itself never commits — YOU commit its fixes to the reviewed branch before launching the analysts, staging ONLY the files it touched (never `-a`/`-A`: don't sweep unrelated working-tree changes into the commit). If the commit can't be made (branch checked out elsewhere, hook rejection), leave the edits uncommitted and say so in the report.
+- If it changed anything and the scope is a committed diff (branch/PR): comment-fixer itself never commits — YOU commit its fixes before launching reviewers, staging ONLY its files (never `-a`/`-A`). Then freeze the new candidate SHA and refresh scopes. If a commit cannot be made, report the uncommitted state; it cannot certify the committed candidate.
 - For working-tree reviews: leave its edits uncommitted (they join the user's pending work) and say so in the report.
 - If the diff touches no comments, skip it and move on.
 
 ## 5. Launch the remaining subagents in PARALLEL
 
-All subagents are CONDITIONAL: launch one only when the changed files indicate it applies. Run them in PARALLEL via the delegation mechanism available in the current runtime. Each subagent fetches its OWN diff; all are read-only. Pass every one EXACTLY:
+All subagents are CONDITIONAL: launch one only when its contract or risk applies. Run independent scopes in PARALLEL through the available delegation mechanism. Each reviewer reads its assigned primary diff and the support it needs; all are read-only. Pass each assignment in the existing handoff, without inventing a universal output schema:
 
-- the review scope: BASE and HEAD branches (verbatim), or "working diff" for uncommitted work
-- the instruction: review only that scope — never assume `main`, use the scope given
+- the immutable base/head SHAs and merge-base, or the stated working-state scope
+- primary paths/hunks plus the contract/risk to evaluate, and directed support references
+- the instruction: use this explicit assignment, not a default whole-diff review; never assume `main`, and report material missing context instead of silently widening the audit
 - when the orchestrator supplied one, the exact work context path verbatim — never a guessed or discovered alternative
 
 Subagents and their triggers:
@@ -82,6 +88,8 @@ If none of a subagent's triggers are present, skip it and note that it was skipp
 
 After the relevant subagents complete, synthesize their findings into a unified report. Use 4R internally (Reliability / Resilience / Readability / Risk) as a checklist while synthesizing; do not add a separate 4R section or taxonomy to the final report.
 
+Reconcile duplicates and verify disputed premises before creating work. Distinguish a missed bug, a regression introduced by a fix and an optional suggestion. A new valid finding still needs triage; being new is not a reason to discard it. Record justified rejection of false positives, not backlog entries for them. Only valid work deliberately deferred belongs in the existing backlog, using its single-writer protocol.
+
 - Review scope used (BASE/HEAD or working diff) and how it was chosen
 - Subagents run vs skipped (with reason)
 - Critical Issues (must fix)
@@ -89,3 +97,17 @@ After the relevant subagents complete, synthesize their findings into a unified
 - Suggestions (nice to have)
 - Changes already applied (comment fixes: committed to the branch, or left uncommitted for working-tree reviews)
 - Positive Findings
+
+## 7. Revalidate coverage and stop
+
+Use the existing checkpoint/history for frozen refs, scopes actually reviewed, finding dispositions, verification and the reason prior coverage remains valid. No separate registry, duplicated task board or universal JSON fields are required.
+
+- **Fix-check**: verify the original finding, its correction and the nearby regression risk. Prefer deterministic evidence; ask the relevant reviewer only when judgment is still needed.
+- **Delta-review**: review changed hunks and affected contracts/dependencies when a fix invalidates coverage or introduces risk. Reopen only the relevant roles, including a previously clean role when its assumptions or dependencies changed.
+- **Full review**: establish initial coverage or rebuild it when the effective diff/integration context has changed too broadly to retain reliable coverage. Select specialists conditionally; a material change calls for reassessment, not automatically the same full panel.
+
+A role is neither exempt forever because it was clean nor mandatory forever because it found a bug. Prefer a bounded follow-up to an earlier reviewer when its context remains useful; fresh review can be appropriate when the required independence or coverage changes. Commits, readiness attempts and non-contractual typos do not by themselves trigger another panel.
+
+After a base/parent change or retarget, recompute the effective diff and merge-base and reconsider integration assumptions; an unchanged head SHA alone does not preserve coverage. Before delivery, bind retained and new evidence to the current candidate and run the applicable checks. If code must change while ready, return to draft first.
+
+Stop when no valid blocking findings remain, fixes are verified, coverage of the candidate is justified and no material uncertainty remains. Do not search indefinitely for zero suggestions. The existing task/criterion retry limit still applies: exhaustion requires replanning or a genuine blocker, never claiming success. Merge always requires explicit user approval.

package/stack/system-prompt/AGENTS.md

@@ -49,7 +49,7 @@ Ask questions when something isn't clear instead of assuming it's correct.
 - Make small, local, reviewable changes.
 - Reuse existing repo patterns before introducing new ones.
 - Do not add dependencies without explicit user approval.
-- Update docs when behavior changes.
+- Update affected docs when a change needs user or operational explanation, or makes existing claims incorrect; do not create prose for every internal edit.
 - Run lint and typecheck after significant changes when available.
 
 ---
@@ -135,7 +135,7 @@ Every piece of information about a piece of work has exactly ONE home — never
 - Keep the PR in draft while its code can still change. All subsequent commits and pushes happen while draft; never push to a ready PR.
 - Before ready, complete all applicable preflight work: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), Vercel preview review when the project uses Vercel, final diff inspection, and the full PR review. React Doctor is manual/local, not a GitHub Actions gate.
 - Mark the PR ready only once the current SHA is the candidate to merge: `gh pr ready <number>`. If the project has PR checks configured, wait for Quality Gates, run `gh pr checks <number>`, and verify the checks belong to the latest commit before reporting it mergeable. 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. Immediately before reporting or merging, compare `gh pr view --json headRefOid` with the recorded candidate SHA.
-- If a ready PR needs any code or behavior change, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat the full local verification and review, mark ready again, and wait for a fresh complete gate when PR checks are configured. Never push to a ready PR and merge without repeating the applicable cycle.
+- If a ready PR needs any code or behavior change, first run `gh pr ready --undo <number>`, then modify and push while draft, repeat the full local verification and revalidate review coverage, mark ready again, and wait for a fresh complete gate when PR checks are configured. Review revalidation means fix-check, delta-review or full review according to affected contracts and dependencies, not automatically relaunching every reviewer. Reconsider the effective base and integration context even when head is unchanged. Never push to a ready PR and merge without repeating the applicable cycle.
 - Merging a PR ALWAYS requires an explicit user request — no exceptions, in any flow.
 - Before commit or push, review `git status`, `git diff`, and `git log --oneline -10`.
 - Never add AI signatures, `Co-Authored-By`, or agent mentions.
@@ -164,7 +164,7 @@ Detect the real environment before running commands; don't assume a shell or OS.
 
 ## Documentation
 
-- Update docs when important behavior changes.
+- Keep documentation accurate for changed use, contracts and operations. Use the orchestrator's documentation rule to identify the needed surfaces and consolidate the specialist's pass; reopen only affected pages after later changes.
 - Respect the separation between public and internal docs when it exists.
 - Keep content, navigation, and metadata in sync when docs are structured that way.
 - If docs are missing and needed, create the minimum useful documentation.