jorgex-stack 1.0.28 → 1.0.30

package/stack/skills/to-prd/SKILL.md

@@ -9,7 +9,9 @@ This skill takes the current conversation context and codebase understanding and
 
 1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the PRD, and respect any ADRs in the area you're touching.
 
-2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can.
+2. Sketch out the seams at which you're going to test the feature. Prefer an existing seam when it is strong enough, and choose the closest seam that can fail for the concrete regression risk. Introduce a new seam only when existing ones cannot provide reliable evidence.
+
+Do not choose from a fixed test pyramid or a requirement to add tests. Prefer one authoritative test at the strongest seam closest to the risk; another layer is justified only for a distinct contract. Record existing coverage and valid no-new-test decisions for trivial, mechanical, generated, styling, or wiring changes.
 
 Check with the user that these seams match their expectations.
 
@@ -67,9 +69,13 @@ Keep this static: describe the planned delivery slices, not the current state.
 
 A list of testing decisions that were made. Include:
 
-- A description of what makes a good test (only test external behavior, not implementation details)
-- Which modules will be tested
-- Prior art for the tests (i.e. similar types of tests in the codebase)
+- The meaningful regression risk introduced by each behavior change
+- Which existing tests already protect it
+- Which new behavior requires protection
+- The chosen seam and why it is closest to the risk
+- Why another layer would protect a distinct contract rather than duplicate the same behavior
+- Why no new test is needed for trivial, mechanical, generated, styling, wiring, or already-covered changes
+- Prior art for the selected tests (i.e. similar valuable tests in the codebase)
 
 ## Out of Scope
 

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

@@ -41,6 +41,18 @@ Every piece of work gets a **canonical kebab-case name** when it starts (e.g. `c
 - Task status lives ONLY in the task table: flip it (⬜ → ✅) with a surgical edit when the task closes. PR status/evidence lives ONLY in the PR roadmap table. Do not mirror task progress into memory, and do not re-read the whole plan after every task — it is already in context; re-read it on resume.
 - For multi-PR work, resume from the first PR/task not done in the roadmap/table. For single-PR work, the canonical name worktree/branch is enough and the roadmap collapses to one checkpoint.
 
+## Pull request lifecycle
+
+1. Start from the updated production branch in the canonical worktree/branch. Keep one concrete objective per PR.
+2. Implement one coherent first slice, commit it, push the work branch, and open the PR immediately as draft with `gh pr create --draft`.
+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.
+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.
+
 ## HTML review view (on demand)
 
 When presenting the PRD or the plan for human review on non-trivial work, OFFER a disposable HTML view (e.g. side-by-side approach comparison for the PRD, task table + dependency graph for the plan). Rules:

package/stack/skills/work-lifecycle/references/plan-template.md

@@ -41,6 +41,8 @@ The full spec of each task is NOT a file: it lives in Engram, one observation pe
 > This is the live PR-level board: scope, PR status, and merge evidence live here.
 > Task-level status stays in the task table below.
 > Full checkpoint history lives in Engram under `work/[name]/pr/[NN]`.
+> PR status advances: ⬜ Pending → 📝 Draft → 🔍 Reviewed → ⏳ Ready / gates when configured → ✅ Merged.
+> If a ready PR changes, return it to Draft with `gh pr ready --undo`, clear stale gate evidence, and repeat review plus configured gates for the new SHA. If no PR checks are configured, confirm that from project configuration and record their absence instead of blocking 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.
 
 | PR | Scope | Branch | Worktree | Base | Status | Merge evidence |
 |----|-------|--------|----------|------|--------|----------------|
@@ -144,6 +146,16 @@ Status, wave and dependencies live in the plan.md table (single home) — do NOT
 
 - [Rule]
 
+## Testing decision
+
+- **Risk**: [meaningful regression this task can introduce]
+- **Existing protection**: [specific existing test/evidence, or none]
+- **New behavior**: [behavior needing new protection, or none]
+- **Chosen seam**: [unit/component/database/integration/contract/e2e and why it is closest to the risk]
+- **Action**: [add | update | reuse | no new test] — [concrete reason]
+
+Prefer one authoritative test per behavior. Another layer is justified only when it protects a distinct contract. Styling, wiring, generated code, mechanical refactors, and trivial changes may use `no new test`; business rules, bugs/regressions, public contracts, and invariants should normally use TDD.
+
 ## Acceptance criteria
 
 [VERIFIABLE and SPECIFIC criteria — not generic. Each must be checkable manually or automatically.]

package/stack/{commands/xreview.md → skills/xreview/SKILL.md}

@@ -1,4 +1,5 @@
 ---
+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
 ---
 
@@ -6,7 +7,7 @@ Run a comprehensive multi-agent review. Your job as the main agent: determine WH
 
 ## 0. Determine the review target
 
-User input (may be empty): {{input}}
+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 references a PR (number or URL) → use that PR's base branch as BASE.
@@ -51,19 +52,19 @@ If the diff adds or changes comments/docstrings, run `comment-fixer` ALONE befor
 
 ## 4. 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 Task tool. Each subagent fetches its OWN diff; all are read-only. Pass every one EXACTLY:
+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:
 
 - 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
 
 Subagents and their triggers:
 
-1. Task(subagent_type='test-analyzer') — only if the diff touches tests or code that should be tested
-2. Task(subagent_type='silent-failure-hunter') — only if the diff includes error handling, try/catch, fallbacks, or async flows
-3. Task(subagent_type='type-design-analyzer') — only if the diff changes types, interfaces, schemas, or public contracts
-4. Task(subagent_type='code-reviewer') — for general code quality whenever non-trivial source code changed
-5. Task(subagent_type='code-simplifier') — only if the diff introduces complexity worth simplifying; this is the lean/anti-bloat pass for diffs and PRs
-6. Task(subagent_type='security-auditor') — only if the diff touches auth, authorization, permissions, secrets/credentials, sensitive data, input validation, webhooks, or other security-critical flows
+1. `test-analyzer` — only if the diff touches tests or code that should be tested
+2. `silent-failure-hunter` — only if the diff includes error handling, try/catch, fallbacks, or async flows
+3. `type-design-analyzer` — only if the diff changes types, interfaces, schemas, or public contracts
+4. `code-reviewer` — for general code quality whenever non-trivial source code changed
+5. `code-simplifier` — only if the diff introduces complexity worth simplifying; this is the lean/anti-bloat pass for diffs and PRs
+6. `security-auditor` — only if the diff touches auth, authorization, permissions, secrets/credentials, sensitive data, input validation, webhooks, or other security-critical flows
 
 If none of a subagent's triggers are present, skip it and note that it was skipped. Always state which subagents ran and which were skipped and why.
 

package/stack/system-prompt/AGENTS.md

@@ -110,9 +110,11 @@ Every piece of information about a piece of work has exactly ONE home — never
 
 ## Testing and Verification
 
-- When the project has tests or the change affects behavior, testing is mandatory.
-- For new features, bug fixes, or behavior changes, use TDD when it fits.
-- Use the `tdd` skill for red-green-refactor, test-first work, or integration-style behavior testing.
+- When the project has tests or the change affects behavior, verification is mandatory. A new test is not.
+- Make one explicit testing decision per change: what risk it introduces, what existing test already covers it, what new behavior needs protection, and why no new test is needed when the change is trivial, mechanical, or already covered.
+- Use TDD for business rules, bugs/regressions, public contracts, and invariants. Do not impose it on styling, wiring, generated code, mechanical refactors, or trivial code unless they change meaningful behavior.
+- Prefer one authoritative test at the strongest seam closest to the risk. Add coverage at another layer only when it protects a distinct contract, not to repeat the same behavior.
+- Use the `tdd` skill for red-green-refactor, test-first work, or risk-based behavior testing.
 - Prefer targeted verification before broad suites.
 - Default order: specific test > partial suite > full suite.
 - Use the real test commands and test stack of the project.
@@ -125,7 +127,12 @@ Every piece of information about a piece of work has exactly ONE home — never
 - Commit per task or per bounded group of tasks — small, separate commits whose history maps to the work; never everything in one giant commit.
 - Never push code or behavior changes directly to production branches (main/master or the repo's protected/release branches): those always go through a work branch + PR. Pushing a work branch or a worktree branch is fine without asking.
 - Exception: TRIVIAL changes — docs, typos, content removal, config text with no behavior or code-logic impact — may be committed and pushed directly to the production branch. When in doubt about whether a change is trivial, it is not: use a PR.
-- Creating a pull request is fine without asking.
+- Start each non-trivial PR from an updated production branch in its canonical worktree/branch, and keep one concrete objective per PR. Dependent PRs are sequential: merge the first, update the production branch, then create the next branch from it.
+- After the first coherent commit, push the work branch and always open the PR as draft with `gh pr create --draft`. Creating and pushing the work branch and draft PR is fine without asking.
+- 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.
 - 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.

package/upstreams.json

@@ -74,7 +74,8 @@
     "tdd": {
       "source": "github:mattpocock/skills",
       "path": "skills/engineering/tdd",
-      "commit": "694fa30311e02c2639942308513555e61ee84a6f"
+      "commit": "694fa30311e02c2639942308513555e61ee84a6f",
+      "modified": true
     },
     "to-issues": {
       "source": "github:mattpocock/skills",