nexus-dev-toolkit 3.1.7__tar.gz → 3.1.8__tar.gz

{nexus_dev_toolkit-3.1.7/nexus_dev_toolkit.egg-info → nexus_dev_toolkit-3.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.1.7
+Version: 3.1.8
 Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8}/nexus_cli.py

@@ -22,7 +22,7 @@ app.add_typer(agent_app, name="agent")
 
 console = Console()
 
-_VERSION = "3.1.7"
+_VERSION = "3.1.8"
 
 
 def _fetch_latest_pypi_version() -> str | None:
@@ -98,6 +98,8 @@ _BUILTIN_SKILLS = [
     "monitoring-review.md",
     "commit.md",
     "create-pr.md",
+    "pr-review.md",
+    "dev-tasks-planner.md",
 ]
 
 _AGENTS_SRC = Path(__file__).parent / "tools" / "agents"
@@ -108,6 +110,7 @@ _BUILTIN_AGENTS = [
     "performance-reviewer.md",
     "monitoring-reviewer.md",
     "database-reviewer.md",
+    "pr-verifier.md",
 ]
 
 

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8/nexus_dev_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nexus-dev-toolkit
-Version: 3.1.7
+Version: 3.1.8
 Summary: Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV
 Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
 License-Expression: MIT

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8}/nexus_dev_toolkit.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ tools/agents/database-reviewer.md
 tools/agents/deployment-reviewer.md
 tools/agents/monitoring-reviewer.md
 tools/agents/performance-reviewer.md
+tools/agents/pr-verifier.md
 tools/epav/__init__.py
 tools/epav/arch_ingest.py
 tools/epav/graph_backend.py
@@ -31,10 +32,12 @@ tools/epav/skills/commit.md
 tools/epav/skills/create-pr.md
 tools/epav/skills/database-review.md
 tools/epav/skills/deployment-review.md
+tools/epav/skills/dev-tasks-planner.md
 tools/epav/skills/epav.md
 tools/epav/skills/evaluate.md
 tools/epav/skills/monitoring-review.md
 tools/epav/skills/performance-review.md
 tools/epav/skills/plan.md
+tools/epav/skills/pr-review.md
 tools/epav/skills/scaffold.md
 tools/epav/skills/validate.md

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nexus-dev-toolkit"
-version = "3.1.7"
+version = "3.1.8"
 description = "Developer workflow toolkit for Claude Code — Day 0 scaffold + Day 1 EPAV"
 authors = [
     {name = "Ronald dela Cruz", email = "rcdelacruz@users.noreply.github.com"}

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8}/tests/test_cli.py

@@ -253,8 +253,8 @@ def test_doctor_healthy_project(tmp_project):
     result = runner.invoke(app, ["doctor", str(tmp_project)])
     assert result.exit_code == 0
     assert "✓" in result.output
-    assert "all 11 present" in result.output
-    assert "all 5 present" in result.output
+    assert f"all {len(_BUILTIN_SKILLS)} present" in result.output
+    assert f"all {len(_BUILTIN_AGENTS)} present" in result.output
 
 
 def test_doctor_missing_skills(tmp_project):

nexus_dev_toolkit-3.1.8/tools/agents/pr-verifier.md

@@ -0,0 +1,63 @@
+---
+name: pr-verifier
+description: MUST BE USED to deep-verify a specific commit/PR against its own claims — reads every changed file's actual diff, cross-references project specs/docs, traces runtime/lifecycle claims to ground truth, and actually builds/tests the code in an isolated git worktree. Use for "review this PR/commit" requests that include a SHA or GitHub URL, as opposed to reviewing the current branch's uncommitted changes.
+tools: Read, Bash, Grep, Glob
+model: sonnet
+---
+
+You are a rigorous PR/commit reviewer. Your job is not to summarize what a commit's message claims — it is to independently verify whether those claims are actually true, using the real diff and a real build/test run. A well-written commit message or retro doc is a claim to check, never evidence on its own.
+
+## Ground rule: verify, don't trust
+
+Every review in this style follows the same discipline:
+
+- **Read the full diff of every changed file**, not just the hunks. For a non-trivial logic change, read the whole function/class it lives in — including code the diff didn't touch — so you understand the surrounding contract, not just the delta.
+- **Treat every factual claim as a hypothesis to check.** "X always fires when Y," "this can never happen," "the old behavior was Z" — grep/read the referenced code yourself before accepting it. This applies equally to the commit message, inline code comments, and any retro/knowledge docs the commit adds. A dev's own self-critical writeup (a real repro, a documented trade-off) is evidence of good process — it still isn't a substitute for you checking the code yourself.
+- **Trace lifecycle/timing/concurrency claims through actual execution order.** If a claim depends on "this runs before/after X" or "this store survives Y," find where X/Y actually happens in the code and confirm the ordering or lifetime genuinely holds — don't pattern-match the prose.
+- **Actually run the build and tests.** A claimed test count or "all green" is not verified until you've run it yourself, through the same task runner the project's CI uses — not a package's tests run in isolation if the project has a monorepo task graph, since that can hide a missing cross-package build dependency and produce a false failure that isn't actually the commit's fault.
+
+## Step 1: Understand what this commit is supposed to do — and against what
+
+- Read the full commit message/body via `git show --format="%H%nAuthor: %an <%ae>%nDate: %ad%nSubject: %s%n%nBody:%n%b" <sha>`. Treat it as the author's claim, not the spec.
+- Check whether the task references a spec, ADR, ticket, or a prior gap it's meant to close. If the repo has architecture docs, ADRs, or a `docs/` directory, check whether they describe requirements this change should satisfy. If a prior related commit exists (`git log`, `git branch -a --contains <sha>`, related branch names), read it too — a fix commit often only makes sense in light of what it's fixing.
+- Do not assume the commit's own stated goal is the real goal — if project docs or an explicit instruction from whoever asked for this review narrows or contradicts the commit's own framing, the narrower/explicit one governs. If you're unsure what the actual bar is, say so in your report rather than picking one silently.
+
+## Step 2: Read every changed file's actual diff
+
+`git show --stat <sha>` for the file list, then `git show <sha> -- <path>` per file (or per logical group of related files). For each substantive change:
+
+- **Read un-diffed context via `git show <sha>:<path>`, never a plain file path.** The plain working-directory path reflects whatever is currently checked out — often a different branch or commit than the one under review — and can silently diverge from the commit you're actually verifying, especially for a change with ancestor commits not yet on the base branch. Reading the wrong state produces a confidently-wrong finding, not a missing one, because the file still reads and parses fine — it's just not the code this commit actually contains. If you already created the isolated worktree from Step 3, reading files from inside it also works and is pinned correctly; either is fine as long as it's never the bare repo-root path.
+- Confirm the surrounding function/class context by reading the file directly (via one of the two pinned methods above) when the diff hunk alone doesn't show enough to judge correctness.
+- For anything touching concurrency, shared state, caching, or lifecycle (process boot, request scope, connection reuse, singleton lifetime), trace the actual mechanism — don't take a doc comment's word for "this is safe because...". Find the thing it claims to depend on and confirm it's true.
+- If the commit touches a shared package other apps/repos also depend on, check whether other consumers needed to change too, and whether they did — an unwired shared primitive is a common half-finished state.
+
+## Step 3: Build and test for real, in an isolated worktree
+
+Never touch the user's working directory or currently-checked-out branch.
+
+```
+git worktree add <scratchpad-dir>/wt-<short-name> <sha> --detach
+```
+
+Install dependencies and run the project's real CI-equivalent commands — check `.github/workflows/*.yml` (or whatever CI config exists) for the actual invocation, typically: install deps → any codegen step (e.g. Prisma generate) → typecheck → lint → build → test. If the project uses a task-graph tool (turbo, nx, etc.), run through it (`turbo run typecheck lint build test --filter=<pkg>`) rather than calling each package's own script directly — a direct call can skip building a workspace dependency first and produce a false failure that looks like the commit's fault.
+
+If a check fails, determine whether it's caused by the commit under review or by your own environment (e.g. a missing env var a real deploy would already have set) before reporting it as a finding — an environment gap isn't a code defect. Fix the environment gap yourself if it's cheap (e.g. export a dummy env var) rather than reporting a false failure.
+
+Compare any test/pass counts the commit or its own docs claim against what you actually observed. A discrepancy either direction is worth a line in the review — fewer failures than claimed is good news, worth a brief mention; more or different failures is a real finding.
+
+Clean up the worktree when done (`git worktree remove <path> --force`) — never leave it behind, and never touch the user's actual working directory's branch or state to do any of this.
+
+## Step 4: Adversarial pass on the highest-risk claims
+
+Before writing anything up, pick the 1–3 claims in this commit that would be most damaging if wrong (a resilience/fallback mechanism that doesn't actually trigger, a lock that doesn't actually prevent a race, a migration that doesn't actually run, a cache invalidation that doesn't actually invalidate) and try specifically to break them: trace the exact sequence of calls, check what state actually exists at the moment the mechanism is supposed to act, and look at what the tests substituted away. A mock or fixture that quietly assumes away the exact failure mode being "fixed" is one of the most common ways a fully green test suite hides a real gap — if every test for a fix depends on the very infrastructure the fix claims to be resilient to, that's worth naming explicitly.
+
+## Step 5: Report
+
+Write a narrative review, not a bare findings list:
+
+1. **What's done well** — specific, with file:line references, and *why* it's correct (not just "looks good"). Give real credit for genuine rigor (repro-driven bug fixes, real infra/integration testing, honestly-documented trade-offs) — the goal is an accurate verdict, not fault-finding for its own sake.
+2. **Gaps, ranked by severity** — each with the concrete file/line, the failure scenario (specific input/state → specific wrong outcome or crash), and why it matters. Drop anything you can't state a concrete failure scenario for.
+3. **Minor/non-blocking items** — real but low-severity, clearly labeled as such so they don't get conflated with blockers.
+4. **Verdict** — one clear recommendation: approve, send back (naming exactly what needs to change), or needs a human decision (when the finding is a genuine trade-off or scope question, not a defect).
+
+Do not soften a real finding to be polite, and do not manufacture a finding to seem thorough. If everything you checked held up, say that plainly and explain what you actually verified (not just what you read).

nexus_dev_toolkit-3.1.8/tools/epav/skills/dev-tasks-planner.md

@@ -0,0 +1,196 @@
+# /dev-tasks-planner
+
+Generates (or updates) `docs/dev-tasks/*.csv` files for a module/epic from its architecture doc + ADRs, holding every task to the accuracy bar described below. Use this instead of hand-writing dev-tasks CSVs from scratch — the format, the accuracy rules, and the required per-row content below are each easy to silently skip if you're not deliberately checking for them.
+
+Follows the same EVALUATE → PLAN → APPLY → VALIDATE cycle as `/evaluate` `/plan` `/apply` `/validate`, self-contained in this one command (the same shape `/scaffold` uses) since CSV generation is one continuous task, not four separately-invoked ones. **Stop at the end of EVALUATE and PLAN and wait for explicit approval before continuing** — do not run straight through to APPLY.
+
+## Arguments
+
+`/dev-tasks-planner <module> based on <arch-doc-path>`
+
+Example: `/dev-tasks-planner billing based on docs/arch-docs/billing/`
+
+It can also be pointed at existing CSVs to re-evaluate/correct them (as opposed to generating new ones from a blank slate) — e.g. `/dev-tasks-planner re-evaluate docs/dev-tasks/billing/*.csv against docs/arch-docs/billing/`. The EVALUATE/PLAN/APPLY/VALIDATE shape is the same either way; APPLY edits existing rows instead of writing a new file.
+
+## Prerequisites — MANDATORY, check before doing anything else
+
+Both of the following must be true before this command does any real work. Verify each with an actual check (`ls`/`find`, not an assumption) — do not skip straight to EVALUATE on the assumption they're probably fine.
+
+1. **The module's ARCH doc (+ per-epic ADR files, if any) exist under `docs/arch-docs/<module>/`.** Without a real spec to generate tasks from, there is nothing to reconcile against — a CSV built from no source is fabrication, not planning, no matter how well-formatted it looks.
+2. **The module's boilerplate/scaffold already exists in the repo** (e.g. `<module>/web/`, `<module>/api/` with real files, not empty directories) **— produced by `/scaffold`, not by this command.** `/dev-tasks-planner` reconciles CSV rows against real code (Step 3 of PLAN, "STATUS must reflect actual repo state"); if no code exists at all yet, every row would trivially be `To Do` with nothing to verify, which defeats the entire STATUS-accuracy discipline this command exists to enforce. This command **generates task lists, it does not bootstrap a module** — `/scaffold` is Day 0, this is what comes after.
+
+**If either is missing, STOP immediately and warn — do not proceed to EVALUATE, do not generate a CSV against a doc-only or code-only module, and do not silently substitute one for the other.** State plainly which one is missing and what to do about it:
+
+```
+⚠ /dev-tasks-planner cannot run for <module> yet.
+
+Missing: <"ARCH doc / ADRs under docs/arch-docs/<module>/" and/or "scaffolded code under <module>/web, <module>/api">
+
+<module> needs <the missing piece(s)> before dev-tasks-planner has anything to plan against or
+reconcile STATUS with. Run <the specific missing step — e.g. "the architecture-authoring process
+for this module" and/or "/scaffold <module> based on docs/arch-docs/<module>/ and docs/figma/<module>/">
+first, then re-run /dev-tasks-planner.
+```
+
+Only once both checks pass — confirmed by actually looking, not inferred from the module being named in conversation — continue to EVALUATE below.
+
+---
+
+## EVALUATE — Read the source material and the real repo state
+
+Read the ARCH doc's own Component Breakdown section (usually §3) end to end, and every per-epic ADR file completely — not a grep for keywords. Each epic maps to one output CSV; each component in the breakdown maps to roughly one task row. Also check:
+
+- `knowledge/prompts/dev/` for existing "wire real X" templates (e.g. `wire-real-auth.md`) — match their acceptance-criteria style for any "Day 1: wire real X" task you write, don't invent a different shape.
+- Every sibling module's own `docs/dev-tasks/<module>/*.csv` for the closest precedent to copy conventions from — check header rows directly with `head -1` across a few files rather than assuming they all match. Column count and casing can drift between an older module's CSVs and a newer one in the same repo; prefer whichever convention is more recently updated over the oldest file you find.
+- If CSVs already exist for this module, read them in full (`csv.DictReader`, not `head`/`cat` guessing at columns) — this is the "before" state PLAN will diff against.
+
+**Then verify the real repo state component-by-component** — this is the input PLAN's STATUS decisions depend on, so do it here, not later:
+
+- `grep`/`find`/`Read` the actual files each component would live in. A filename-only search (`find -iname "*device*"`) is not sufficient proof of absence — a feature's code can live inside a differently-named sibling file. Also `grep -rn -i "<feature-keyword>"` across the app's component directory for the literal domain terms before concluding something isn't built.
+- Where a component appears built, check whether it's *fully* wired, not just visually present — a button can exist with a no-op `onClick={() => {}}`, or a filter control that renders but doesn't actually filter. Read the actual handler, don't infer completeness from the UI alone.
+- If a component needs a live DB, live Redis, or another app's not-yet-built API, confirm the blocker is real by checking the other app's own code/README, not by assuming from the ARCH doc alone.
+- Boot the app if you're not sure — a live `curl` against a running dev server is more trustworthy than reading source and guessing whether it's wired end-to-end.
+- Note any ADR that looks stale against a platform-wide correction elsewhere (e.g. a design a sibling module's own ADR "Corrections" section has already superseded) — flag it as a doc-staleness gap for PLAN to caveat, not something to silently "fix" by ignoring the ADR's literal text.
+
+### Output — EVALUATE SUMMARY
+
+```
+EVALUATE SUMMARY
+────────────────
+Module:       <module>
+Epics/CSVs:   <one line per epic → output filename>
+Repo state:   <per-component: file(s) found, built/partial/absent, wired/stub/no-op — the evidence, not conclusions>
+Doc gaps:     <stale ADRs, unresolved Open Questions, contradictions found>
+Constraints:  <schema/format precedents found in sibling CSVs>
+```
+
+Do NOT plan row content or write any CSV yet. End with:
+
+> "Ready to plan. Reply to proceed with PLAN, or give feedback to redo EVALUATE."
+
+---
+
+## PLAN — Decide every row's content against these rules
+
+Using the repo-state evidence from EVALUATE, plan the exact row-by-row content. Every rule below is mandatory — each addresses a real way dev-tasks CSVs go stale or misleading, and is easy to silently skip if you're not deliberately checking for it.
+
+### File structure and exact schema
+
+One CSV per epic, one folder per module: `docs/dev-tasks/<module>/<epic-slug>-tasks.csv` (e.g. `docs/dev-tasks/billing/invoice-export-tasks.csv`). The module is the folder, not a filename prefix — don't repeat it in the filename (`docs/dev-tasks/billing/invoice-export-tasks.csv`, never `docs/dev-tasks/billing/billing-invoice-export-tasks.csv`). The header below is a common baseline — verify it against this repo's own existing CSVs with `head -1` on a few files rather than assuming it applies universally, and adopt the repo's real convention if it differs:
+
+```
+TASK_ID,ISSUE_TYPE,SUMMARY,USER_STORY,DESCRIPTION,ACCEPTANCE_CRITERIA,PRIORITY,ESTIMATE,STORY_POINTS,ROLE,ASSIGNEE,STATUS,LABELS,EPIC_LINK,DEPENDENCIES,BE ESTIMATE,BE - ACTUAL EFFORT,FE ESTIMATE,FE - ACTUAL EFFORT,QA ESTIMATE
+```
+
+- First row: `EPIC-<NAME>`, `ISSUE_TYPE=Epic`, empty `EPIC_LINK`, summarizing the whole epic and its overall completion state (`In Progress` if any sub-task is `Done` while others aren't — don't leave the epic row `To Do` once real work exists under it).
+- One row per component/story after that, `ISSUE_TYPE=Task`, `EPIC_LINK=EPIC-<NAME>`.
+- `ROLE`: `Backend` / `Frontend` / `Fullstack`.
+- `STATUS`: exactly one of `Done` / `To Do` / `Blocked` / `In Progress` — verified as the actual allowed set by reading existing files, not assumed.
+- `LABELS`: comma-tag convention, no spaces — `backend,<epic-slug>,<module>-app[,blocked][,export][,rbac]`, `frontend,ui,<epic-slug>,<module>-app`, `testing,...`. Check an existing file's actual `LABELS` values before inventing a new tag shape.
+- `DEPENDENCIES`: `TASK-XXX` (comma-separated for multiple), referencing task IDs within the same file, or `EPIC-<NAME>` from another file for cross-epic deps.
+
+### STATUS must reflect actual repo state, not the ARCH doc in the abstract
+
+**This is the single most important rule and the easiest one to get wrong.** A CSV generated once and never reconciled against the code that moved past it will list already-built work as "Not started." A future `/evaluate` trusts the CSV's STATUS column at face value — a wrong status there doesn't just look bad, it causes real work to be replanned or real gaps to be missed.
+
+Use the EVALUATE-stage evidence directly:
+- Found and complete → `Done`. Don't default to `To Do` just because that's the ARCH doc's implied starting point.
+- Found but only partially wired (e.g. a no-op button, filters that render but don't filter) → `In Progress`, with the exact code evidence cited — never round this up to `Done`.
+- Needs a live DB, live Redis, or another app's not-yet-built API → `Blocked`, only once the blocker was verified real in EVALUATE.
+- Genuinely nothing started and nothing blocks it → `To Do`.
+
+### Every `Blocked` row cites the exact reason and states the fallback
+
+Two things every `Blocked` row's `DESCRIPTION` must contain, not just one:
+
+1. **The exact ADR/ARCH-doc Open Question number** it's blocked on (e.g. "BLOCKED — Open Question #22"), never a vague "pending" or "TBD." Check whether existing CSVs in this repo already have a convention for citing this, and match it if so.
+2. **An explicit `**Fallback:**` sentence** stating what actually happens in the meantime — not what it's waiting on (that's #1), but the interim behavior. Most of the time this is already true in the code and just needs stating: "the mock data continues to serve the UI," "the stub service returns non-persisted success," "no enforcement exists yet, a known accepted Day-0 gap." Occasionally there's genuinely no fallback (e.g. a Submit button that currently no-ops, or a blocker so early nothing is exposed yet) — say that plainly rather than implying one exists. Never leave a `Blocked` row silent on this.
+
+### Every `Done` row states its own Day-1 forward path
+
+A `Done` row describes Day-0 mock/UI work. Its `DESCRIPTION` must also say, explicitly, one of:
+- **What swaps in on Day 1** and where — name the mock generator function and the task that replaces it (e.g. "swap `genInvoiceId()` for a real server-side query response in the identical row shape — see TASK-003"), so the swap-in point doesn't need rediscovering later.
+- **That nothing swaps** — some Day-0 work (a shared UI shell, a client-side-only interaction, an already-real integration like real SSO wiring) is permanent, not a placeholder. Say so directly ("no swap needed — this is permanent UI, not a mock") rather than leaving it ambiguous whether it's temporary.
+
+`Blocked` and `To Do` rows don't need a separate Day-1 note — they already describe Day-1 work directly by definition; adding a redundant pointer to them is noise, not signal. `In Progress` rows don't get a Day-1 note either — state what's missing to reach Done instead.
+
+### Every task cites the project's own established patterns by name, not generic prose
+
+Many projects have a dominant cross-cutting pattern for splitting Day-0 mock work from Day-1 real integration — commonly an **interface-abstraction-for-a-blocked-dependency** shape, where an ADR calls for building a named internal service/interface now (stubbed today, swapped to the real integration later — e.g. a `PermissionService`, `OrderService`, or similar named shape). Discover whatever this project's actual pattern is (grep ADRs and existing code for named services/interfaces) before writing tasks, and when a task touches it, the row must:
+- Name the exact interface/file the ADR calls for.
+- **Check whether it was actually built** — don't assume the abstraction exists just because the ADR says to build it. A Day-0 build can bypass a called-for abstraction entirely and call mock data directly instead; if that happened, the missing abstraction is its own `To Do` task, not folded silently into the "wire the real API" task.
+- If the module has no backend feature modules at all yet (a Day-0/FE-only build), this pattern may genuinely not apply — say so rather than forcing a citation onto a gap that isn't actually a bypassed abstraction.
+
+Same rule for shared UI components — name the actual component this project already has (its own shared table/list-screen component, whatever it's called) and say "extend/reuse X," never "build a new one" — and for any mock-data-mirrors-real-shape convention already in place (generator functions named so they can be swapped in place, preserving the row shape, not rewritten).
+
+### Output — PLAN blueprint
+
+```
+PLAN
+────
+Files:  <filename> — <row count, new vs. corrected, epic status>
+        ...
+
+Per-file row plan (for each changed/new row):
+  <TASK_ID> — STATUS: <value> — <one-line reason citing the EVALUATE evidence>
+
+Constraints applied: <schema precedent, pattern citations, ADR-staleness caveats from EVALUATE>
+```
+
+Output as a blueprint. No CSV writes yet. End with:
+
+> "Waiting for approval. Reply to apply, or give feedback to revise the plan."
+
+---
+
+## APPLY — Generate the CSV(s) programmatically
+
+**Never hand-type the CSV.** `DESCRIPTION`/`ACCEPTANCE_CRITERIA` cells routinely contain commas, quotes, and multi-line bulleted lists — hand-writing CSV text with that much embedded punctuation reliably produces silent quoting bugs.
+
+- Write a small Python script using `csv.DictWriter` (new file) or `csv.DictReader`+`csv.DictWriter` (correcting an existing file) with the rows/overrides as data (dicts).
+- Write with plain `encoding='utf-8'` (no BOM) even if the source file being corrected has one (`encoding='utf-8-sig'` on read handles that transparently) — a UTF-8 BOM can silently break a plain `open(..., encoding='utf-8')` parse.
+- Run the script, then delete it — keep only the CSV output.
+- Follow exactly what PLAN decided. If verification during APPLY turns up something PLAN didn't anticipate (e.g. a row's real code state differs from what EVALUATE found), stop, flag it, and confirm before deviating — the same "stay in scope" discipline `/apply` uses generally. A deeper verification that corrects PLAN's own STATUS call for a row (not a scope change, just PLAN being wrong) can proceed as part of finishing the row-accuracy work PLAN already authorized — but say so explicitly in the report rather than silently overriding what was planned.
+
+### Output — APPLY COMPLETE
+
+```
+APPLY COMPLETE
+──────────────
+Created:   <new files>
+Modified:  <corrected files, rows touched per file>
+Skipped:   <anything intentionally deferred>
+```
+
+Then prompt to continue to VALIDATE.
+
+---
+
+## VALIDATE — Structurally re-validate before calling it done
+
+Don't rely on eyeballing the rendered output. Write (and run, then delete) a short validation script that checks, as data, across every file touched:
+
+- Header matches the exact expected schema.
+- Every row has the exact expected column count.
+- Every `STATUS` value is one of the four allowed values.
+- Every `Blocked` row contains `**Fallback:**`.
+- Every `Done` row (`ISSUE_TYPE=Task`) contains `Day 1` or `Day-1`.
+- No BOM at the start of the file.
+
+Run it against **every row in the file**, not just the rows this pass touched — a prior pass may have left pre-existing rows non-compliant that this pass alone wouldn't otherwise catch. Fix anything the check finds, then re-run until clean.
+
+If a genuinely new pattern or non-obvious constraint was discovered during this run (e.g. a search-methodology gap, a new ADR-staleness case), append it to `knowledge/retros/` the same way `/validate` does generally.
+
+### Output — VALIDATE COMPLETE
+
+```
+VALIDATE COMPLETE
+─────────────────
+Files validated:  <list>
+Rows checked:     <total>
+Checks passed:    header / column-count / STATUS-enum / Fallback / Day-1 / no-BOM
+Issues fixed:     <list, if any>
+Backlog items:    <retro file added, if any>
+```
+
+> "Task complete."

nexus_dev_toolkit-3.1.8/tools/epav/skills/pr-review.md

@@ -0,0 +1,35 @@
+---
+name: pr-review
+description: Rigorously verify a specific commit or PR against its own claims — read every changed line, cross-reference project specs, and actually build/test the code in an isolated worktree instead of trusting the commit message or a green CI badge.
+---
+
+**pr-review** — deep-verify a specific commit/PR by SHA or GitHub URL, and report a narrative review with a clear verdict.
+
+## When to use
+
+Invoke when the user asks to review a specific commit, PR, or "the dev's latest work" and gives a SHA or a GitHub commit/PR URL (`/pr-review <sha-or-url>`). This is not the same as `/code-review` — that reviews the *current* branch's uncommitted/ahead-of-base changes; this reviews one specific, already-made commit, often not on the branch currently checked out, and holds it to a higher bar: every claim in the commit message gets checked against the actual diff, and the build/tests actually get run, not assumed from a green CI badge.
+
+## Steps
+
+### 1 — Resolve the target
+
+Extract the SHA from the user's input (a GitHub commit/PR URL ends in the SHA — a PR URL may need `gh pr view <n> --json commits` or the PR's own "Files changed" page to find the head SHA if the user only gave a PR number/URL). Confirm it exists locally (`git cat-file -e <sha>`); if not, `git fetch origin` and retry.
+
+### 2 — Delegate to the pr-verifier agent
+
+Launch the `pr-verifier` agent (Agent tool, `subagent_type: "pr-verifier"`) with the resolved SHA and any context the user gave about what this commit is supposed to fix or do (a prior gap, a ticket, a specific goal they stated). Let the agent discover repo-specific context (specs, ADRs, related docs, prior related commits) itself — do not pre-summarize it, and do not do the review yourself in the main thread.
+
+### 3 — Output
+
+Load the `artifact-design` skill, then build the review as a Claude Artifact and publish it — this is the primary deliverable, not an optional extra. Treat it as a utilitarian report (per artifact-design's calibration guidance): real typographic hierarchy, a considered palette, generous structure — but no flashy hero or landing-page treatment.
+
+Structure it around what the agent actually verified, not just its prose:
+
+- A masthead naming the repo and the compare range/PR, with the verdict as a plain, unambiguous badge (approve / send back / needs a human decision) — never buried.
+- If this same commit/PR/branch has been reviewed before in this session, show the commit history and a findings ledger tracking each finding's status across rounds (open → resolved, still open, or newly found in this round). This is real, meaningful structure whenever there's more than one round — not decoration.
+- The full narrative from the agent's report — what's done well, gaps ranked by severity with concrete failure scenarios, minor items, verdict. Condense formatting, not substance: every concrete claim, file path, number, and quote the agent actually verified should survive into the artifact.
+- A verification-method section naming what was actually run: build/test commands, the worktree, real test counts, and any adversarial check performed against real infrastructure rather than mocks.
+
+Give the artifact a specific title naming the actual package/feature under review (never a generic "PR Review Report"), and a favicon/icon fitting the subject.
+
+In chat: lead with the verdict plainly — if it's "send back" or flags a high-severity finding, say so before anything else — give a short summary of the highest-severity finding(s), and hand over the artifact link. Don't also re-paste the agent's full narrative verbatim in chat once it's published as an artifact; that duplicates the deliverable instead of pointing to it.

{nexus_dev_toolkit-3.1.7 → nexus_dev_toolkit-3.1.8}/tools/epav/skills/scaffold.md

@@ -45,6 +45,29 @@ Load `docs/arch-docs/` (ARCH doc + ADRs) and the Figma export. Then walk through
 9. Layout patterns (grid, breakpoints, responsive behavior)
 10. Iconography (style, sizes, library)
 
+**Read the design-system reference file itself, in full — not a summary of
+it.** If a `knowledge/*.md` design-system doc already exists from a prior
+pass, treat it as a lead, not a substitute: it can go stale or compress away
+detail. Read the actual `Design System.dc.html` (or equivalent) export
+directly before relying on any derived summary.
+
+**These generated design-system pages often restate the same fact in
+multiple places, and the restatements can disagree** — an early illustrative
+example may show one value while the file's own underlying data (the
+JS/script section actually driving the page's swatches, e.g. a `TYPE_SCALE`
+or `COLORS` array) declares another. Don't stop at the first section that
+seems to answer the question — read the whole file. When two statements in
+the same file conflict, prefer whichever one is more specific or names an
+actual file path in the codebase (e.g. "`lib/icons.jsx` now imports from
+lucide-react") over a generic illustrative swatch — the specific one is
+usually the more recently updated, authoritative one.
+
+**Also check for sibling token files in the same export folder** (e.g.
+`tokens.css`, `design-tokens.css`, `tailwind.config.js` alongside the `.dc.html`
+files) — these can be more authoritative than the HTML page, or in rare cases
+be misplaced/leftover from a different sibling app's export (verify the
+palette and page names inside actually match this app before trusting one).
+
 **Design token conversion (before writing any design file):**
 Figma exports colors in oklch or hex — never copy them raw. Convert to the target stack's native format:
 - Web (Tailwind v4): `hsl()` — never oklch, hex, or rgb
@@ -143,6 +166,20 @@ NEVER write patch versions from AI memory — training data is always stale.
 
 **2. UI shell (matching Figma exactly):**
 - Design system config (tailwind.config.ts, globals.css — tokens from Figma)
+- **Any hand-written base selector in globals.css (`a`, `body`, `input:focus`,
+  `thead th`, etc.) MUST be wrapped in `@layer base { ... }`.** Tailwind v4
+  emits its own utilities into a cascade layer; an unlayered rule beats a
+  layered one regardless of specificity — so a plain `a { color: ... }` will
+  silently override every `text-*` utility ever applied to a link, app-wide,
+  not just on hover. This is invisible when diffing declared values against
+  the Figma export (which sets colors via inline `style`, immune to this),
+  and only shows up once rendered — verify by checking the generated
+  `globals.css` has no selector outside `@layer base`/`@theme`/`@import`.
+- Icons ported from a Figma export's raw `<svg>` relying on a parent's
+  `text-align: center` for centering will NOT center once run through
+  Tailwind: preflight sets `svg { display: block }`, and block elements
+  ignore `text-align`. Give such icons `mx-auto` (or center via flex)
+  instead — don't assume `text-align: center` survives the port.
 - All components with TypeScript props and ALL visual states:
   (default, hover, focus, disabled, loading, empty, error)
 - All page layouts responsive to Figma breakpoints
@@ -237,6 +274,16 @@ Review everything against the architecture doc AND Figma.
 14. Accessibility — keyboard nav, WCAG AA contrast?
 15. Prop interfaces typed for Day 1 wiring?
 16. No business logic or API calls in components?
+17. `grep` `globals.css` for any selector outside `@layer base { }` /
+    `@theme { }` / `@import` — an unlayered rule there silently overrides
+    every matching Tailwind utility app-wide (not just on hover; see
+    "UI shell" above). Matching declared hex/px values against the Figma
+    export is NOT sufficient proof of correctness — that only confirms the
+    *value* is present somewhere, not that the cascade actually resolves to
+    it once rendered.
+18. Any icon centered via a parent's `text-align: center` — confirm it
+    carries `mx-auto` (or sits in a flex-centered parent), since Tailwind's
+    preflight makes `<svg>` block-level and text-align won't center it.
 
 **AGENTS.md + knowledge directory:**
 17. Coding standards match the architecture?