@noir-ai/skills 1.9.3 → 1.9.4-beta.2

package/builtin/noir-subagent/SKILL.md

@@ -1,47 +1,46 @@
 ---
 name: noir-subagent
-description: Use when executing an implementation plan with independent tasks — to drive a fresh subagent per task with review between.
+description: Use when dispatching independent implementation tasks as fresh subagents — one task per subagent with review between. Use when the user says "use subagents" or "dispatch these". Do NOT use for sequential tasks that share state; use noir-executing-plans instead.
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - dispatch-guide.md
 ---
 
-Execute an implementation plan by dispatching a fresh implementer subagent per task, a task review (spec compliance + code quality) after each, and a broad whole-branch review at the end. The controller curates exactly what each subagent needs; subagents never inherit the controller's session history, and artifacts move as files rather than pasted text. This keeps each subagent focused and preserves the controller's context for coordination.
+# noir-subagent
+
+Dispatch each independent task to a fresh subagent with a brief, then review the result. Parallel execution with review gates — the fastest path through a fan-out plan.
+
+## When to use
+
+- An implementation plan has independent tasks (no shared state, no ordering).
+- The user says "use subagents", "dispatch these", or "run them in parallel."
+- **Do NOT use:** for sequential tasks (task B reads task A's output) — use `noir-executing-plans`. For general concurrent work without per-task review, use `noir-parallel`.
 
 ## Procedure
 
 ### Pre-flight
-1. **Read the plan once.** Note the global constraints (exact values, formats, cross-task relationships) and any conflicts between tasks. If you find tasks that contradict each other or the plan's own constraints, surface the whole batch to the user as one question before dispatching Task 1 — not one interrupt per conflict mid-plan.
-2. **Open a progress ledger.** Create `.noir/sdd/progress.md`. Each task gets one line when its review comes back clean: `Task N: complete (commits <base7>..<head7>, review clean)`. After any compaction or resume, trust the ledger and `git log` over your recollection — controllers that lost their place have re-dispatched entire completed sequences.
+1. **Write a brief per task.** Each subagent gets: the task goal, the files it touches, the expected output, and a deadline. The brief lives at `.noir/sdd/task-N-brief.md`.
+2. **Validate independence.** If task B needs task A's output, they're not independent — order them or merge them.
 
 ### Per task
-3. **Brief the implementer.** Extract the task's full text to `.noir/sdd/task-N-brief.md` (the single source of requirements — exact values, signatures, test cases live there). Compose the dispatch with: one line on where this task fits, the brief path ("read this first — it is your requirements"), interfaces and decisions from earlier tasks the brief cannot know, your resolution of any ambiguity you noticed, and the report path `.noir/sdd/task-N-report.md`. Name the model explicitly — omitted models inherit the session default and silently defeat the cost/performance choice below.
-4. **Handle implementer status.**
-   - **DONE** — generate the review package and dispatch the task reviewer.
-   - **DONE_WITH_CONCERNS** — read the concerns; address correctness/scope concerns before review, note observations and proceed.
-   - **NEEDS_CONTEXT** — provide the missing context, re-dispatch.
-   - **BLOCKED** — change something before retrying: more context, a more capable model, a smaller task, or escalate to the user if the plan itself is wrong.
-5. **Review the task.** Run `git diff <BASE> <HEAD>` for the task's commit range into a file (BASE = the commit you recorded before dispatching the implementer, never `HEAD~1` — multi-commit tasks get truncated) and pass the path to the reviewer along with the brief and the report. The reviewer returns two verdicts: spec compliance and code quality. Both are required.
-6. **Adjudicate findings.** Dispatch fix subagents for Critical and Important findings (one fixer carrying the complete list, not one per finding — per-finding fixers each rebuild context and re-run suites). Re-review until clean. Resolve "cannot verify from diff" items yourself before marking the task complete — you hold the plan and cross-task context the reviewer lacks. If a finding conflicts with what the plan's text mandates, present the finding and the plan text to the user and ask which governs; do not dismiss it and do not silently fix past the plan.
-7. **Mark complete.** Append the ledger line, move to the next task. Do not pause for check-ins between tasks — execute the plan through, stopping only on BLOCKED status you cannot resolve, genuine ambiguity, or all tasks complete.
+3. **Dispatch the subagent.** Fresh subagent, clean context, reads the brief and the spec. On Claude Code, use the `Task` tool with a specific subagent type (e.g. `Explore` for search, `Plan` for design) — or use `Agent` with `subagent_type` for custom configurations. On other hosts, dispatch whatever agent/subagent runner is available. **Issue multiple dispatches in ONE response to run them concurrently.**
+4. **Receive the report.** The subagent returns a `.noir/sdd/task-N-report.md` — what was done, test results, any issues.
+5. **Review.** Verify: tests pass, spec satisfied, commits are clean. If not, return to the subagent with the specific issues — don't rewrite their code yourself (that defeats the isolation). If a task needs rework, re-dispatch with the issues as context.
 
 ### Final
-8. **Dispatch the whole-branch review.** Package the branch diff with `MERGE_BASE = git merge-base main HEAD` and dispatch the final reviewer on the most capable available model — this is the judgment step, not the session default. If it returns findings, dispatch one fix subagent carrying the complete list.
-9. **Record and route.** Capture the per-task reviews and the final verdict via `noir.checkpoint` (the SDD execute/verify gates). Hand off to `noir-document`.
+6. **Integrate.** All tasks done, all tests green, all briefs archived. Hand off to `noir-verifying`.
+
+## Reference
 
-## Constructing reviewer prompts
-- Do not add open-ended directives ("check all uses", "run race tests if useful") without a concrete, task-specific reason.
-- Do not ask a reviewer to re-run tests the implementer already ran on the same code — the implementer's report carries the evidence.
-- Do not pre-judge findings for the reviewer. If your prompt contains "do not flag", "don't treat X as a defect", "at most Minor", or "the plan chose" — stop. You are pre-judging, usually to spare yourself a review loop. Let the reviewer raise it and adjudicate in the loop.
-- The global-constraints block you hand the reviewer is its attention lens: copy the binding requirements verbatim from the plan (exact values, formats, stated relationships). Process rules (YAGNI, test hygiene) already live in the reviewer template.
-- Every fix dispatch carries the implementer contract: re-run the tests covering the change and report the result (test files, command, output). Re-dispatch the reviewer only once all three are present.
+For brief-writing, independence validation, and review mechanics, see [dispatch-guide.md](references/dispatch-guide.md).
 
-## Model selection
-Use the least powerful model that handles each role.
-- Mechanical, well-specified implementation (complete spec, 1–2 files, or plan text that already contains the code): cheap/fast tier.
-- Integration and judgment (multi-file coordination, pattern matching): standard tier.
-- Architecture, design, and the final whole-branch review: most capable tier. Always specify the model explicitly; an omitted model inherits the session default.
+## When done → next skill
 
-Cheapest models often take 2–3× the turns on multi-step work — use a mid-tier model as the floor for reviewers and for implementers working from prose. Turn count beats token price.
+→ `noir-verifying` for the full integration gate, then `noir-shipping`.
 
 ## Notes
-- One dispatch describes one task, not the session's history. Do not paste accumulated prior-task summaries into later dispatches — a fresh subagent needs its task, its interfaces, and the global constraints. Nothing else.
-- Never start implementation on `main`/`master`; never run multiple implementation subagents in parallel (they conflict on the working tree); never let a subagent self-review replace the actual task review — both are needed.
-- Discipline is observable, not rhetorical: the SDD engine records each per-task review and the final whole-branch review, with the diff packages and verdicts attached.
+- This skill is a playbook — the host decides which tools to use.

package/builtin/noir-subagent/references/dispatch-guide.md

@@ -0,0 +1,50 @@
+# Subagent dispatch guide — briefs, independence, review
+
+Deep reference for `noir-subagent`. The mechanics of dispatching fresh subagents per task and reviewing between.
+
+## The brief — what a subagent needs
+
+A subagent starts cold. Its brief must be self-contained:
+
+- **Goal** — one sentence: what must be true when done.
+- **Files** — the exact files it may touch (and which it must NOT touch).
+- **Constraints** — the interface contract it must satisfy (signatures, formats).
+- **Acceptance** — how it proves done (tests pass, output shape).
+- **Context pointer** — where to read the relevant spec/plan/background (NOT a dump of everything).
+
+A good brief is 5-10 lines. If it needs a paragraph of caveats, the task isn't independent yet.
+
+## Independence validation
+
+Two tasks are independent only if:
+
+- B does not need A's output to start (or you ORDER them: A then B).
+- They do not write the same file in conflicting ways.
+- They do not share mutable state (a DB, a cache, a port).
+
+If any dependency exists, you have two choices: run them sequentially (`noir-executing-plans`), or merge them into one task. Dispatching dependent tasks in parallel produces merge hell.
+
+## The review step (non-negotiable)
+
+After each subagent returns, REVIEW before integrating:
+
+1. **Tests pass?** Run the suite. Don't trust the subagent's "all green."
+2. **Spec satisfied?** The output meets the brief's acceptance criteria.
+3. **No collateral?** The subagent didn't touch files outside its brief, didn't leave debug logs, didn't commit garbage.
+
+If any item fails, return the report to the subagent with the specific issue. Do NOT rewrite their code yourself — that defeats the isolation.
+
+## Files as the contract
+
+Subagents communicate through FILES, not conversation. Each task writes:
+- `task-N-brief.md` — what it was asked (you write before dispatch).
+- `task-N-report.md` — what it did + test results (it writes on return).
+
+These become the integration record and the `noir-wrap` handoff input. Structured outputs (JSON, CSV, markdown tables) beat prose for machine consumption.
+
+## When NOT to dispatch a subagent
+
+- The task is a single small change (a subagent adds more overhead than value).
+- The task requires deep conversation context you already hold.
+- The task touches the same file as a parallel task.
+- The model is simpler than the task warrants — match subagent capability to task difficulty.

package/builtin/noir-sync/SKILL.md

@@ -1,18 +1,45 @@
 ---
 name: noir-sync
-description: Use at the start of a session — to load project context (anchors, git state, setup) and recall prior memory before doing anything else.
+description: Use when starting any session or conversation — load project context and route to the relevant noir skill. Fires on explicit signals (feature start, spec request, new task). Do NOT use mid-session for a status update; use noir-checkpoint.
+metadata:
+  category: discovery
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Load project context at session start. Read-only — do not edit project files. Discipline comes from the SDD engine's observable gates, not from this skill.
+# noir-sync — Session starter and skill router
+
+Load the project context AND route to the right skill. This is the entry point for every session — read anchors, check state, recall memory, then hand off to the noir skill that matches the task. Stay silent on trivial edits; fire on explicit signals.
+
+## When to use
+
+- Start of a session — before any other action.
+- The user opens a new conversation or says "let's work on X."
+- **Do NOT use:** mid-session for progress — use `noir-checkpoint`. Do NOT use for a one-line fix with no design.
 
 ## Procedure
-1. **Read anchors.** Read `CLAUDE.md` / `AGENTS.md` (always-on context) to ground the session.
-2. **Project setup.** Detect stack + the test/run command from manifests and `CLAUDE.md`; note project type. Informational — flag anything non-conventional, do not mutate.
-3. **Git state.** `git rev-parse --abbrev-ref HEAD`; `git status --porcelain`; `git log --oneline -5`.
-4. **Noir state.** Read `.noir/NOIR.md`; check `.noir/tasks/` for an in-flight task (the engine's persisted state). If one exists, surface its phase via `noir.workflow_status` and offer to resume it through the SDD lifecycle — do not auto-resume.
-5. **Recall memory.** Query Noir memory (or the host's recall tooling, if any); surface 2–4 top facts relevant to the current task. If empty, say so — `.noir/` artifacts are the durable fallback.
-6. **Print a brief** of essentials only (project type, stack, key commands, in-flight task) — no large dumps. Then await the user; do not auto-start work.
-
-## Fallbacks
-- No memory found → say so; `.noir/NOIR.md` + `.noir/tasks/` are always the durable record.
-- Not initialized (no `.noir/`) → tell the user to run `noir init` before continuing.
+
+1. **Read anchors.** `CLAUDE.md`, `AGENTS.md`, `.noir/NOIR.md` — always-on context to ground the session. On Claude Code, use `Read`; on other hosts, use the equivalent file tool.
+2. **Check git state.** `git rev-parse --abbrev-ref HEAD`, `git status --porcelain`, `git log --oneline -5`. Note any dirty tree or in-progress work.
+3. **Check Noir state.** Read `.noir/tasks/` for an in-flight task. If one exists, surface its phase and offer to resume.
+4. **Recall memory.** Query Noir memory (or the host's recall tooling) for 2-4 top facts relevant to this session. If empty, say so — `.noir/` is the durable fallback.
+5. **Skill triage.** Map the user's intent to the right noir skill. These are the high-value skills:
+   - Feature/idea → `noir-brainstorming` → `noir-spec` → `noir-planning` → `noir-executing-plans`
+   - Bug/crash → `noir-systematic-debugging`
+   - Implement with TDD → `noir-test-driven-development`
+   - Verify/PR → `noir-verifying`
+   - Ship/integrate → `noir-shipping`
+   - Close session → `noir-wrap`
+   - Code exploration → `noir-exploring`
+   - Skill authoring → `noir-writing-skills`
+6. **Print a brief** — project type, stack, key commands, in-flight task. Then hand off to the routed skill.
+
+## Notes
+
+- Don't auto-start work. Surface the state and let the user confirm direction.
+- If no skill matches, ask what the user wants to do — the route is a suggestion, not a mandate.
+
+## When done → next skill
+
+Route to the matched skill. Or is there something else you'd like to do first?

package/builtin/noir-systematic-debugging/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: noir-systematic-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior — find the root cause methodically before proposing any fix. Use when the user says "this is broken", "it fails intermittently", or pastes a stack trace. Do NOT use for a known fix where the root cause is already confirmed.
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - tracing.md
+---
+
+# noir-systematic-debugging
+
+Find root cause before attempting any fix. Symptom patches waste time and create new bugs; the path is investigate → hypothesize → test → fix, in that order. Skipping ahead is the most expensive move in debugging.
+
+## When to use
+
+- A bug, test failure, or unexpected behavior appears — and you don't know the root cause yet.
+- The user says "this is broken", "it fails", "something's wrong", or pastes a stack trace.
+- A test passed yesterday and fails today, or it fails intermittently.
+- **Do NOT use:** when the root cause is already clear and the fix is obvious (one-line patch with no risk of side effects).
+
+## Procedure
+
+### 1. Reproduce and read
+- Read the error completely. Stack traces, line numbers, file paths, error codes — do not skim past the message; it usually narrows the search immediately.
+- Reproduce reliably. Find the minimal, repeatable trigger. If you cannot reproduce it, gather more data; do not guess at a fix from a single trace.
+- Check recent changes. `git diff` and recent commits often point straight at the cause. Note new dependencies, config edits, and environmental differences.
+
+### 2. Gather evidence at component boundaries
+When the system has multiple layers (CLI → adapter → daemon → store, or API → service → database), instrument each boundary before proposing fixes: log what enters and exits, verify config propagation, check state at each layer. On Claude Code, use `Bash` to run the exact failing command with verbose flags; on other hosts, use whatever shell/execution tool is available. Run once, read the output, then investigate the specific layer the evidence implicates.
+
+### 3. Trace data flow to the source
+For a bad value deep in a call stack, trace backward: where does it originate, who passed it down, who created it. Fix at the source, not at the symptom. Resist the urge to patch where the symptom surfaces.
+
+### 4. Find the pattern
+Locate similar working code in the same codebase and list every difference from the broken path — however small. When applying a known pattern, read the reference implementation completely; partial understanding is a common cause of the bug you are now debugging.
+
+### 5. Form one hypothesis and test minimally
+State the hypothesis explicitly ("I think X is the root cause because Y"). Make the smallest possible change that would prove or disprove it — one variable at a time, never a bundle. If the hypothesis survives the minimal test, proceed; if not, form a new hypothesis with the new information. Do not stack fixes on top of a failed one.
+
+### 6. Fix at the root, with a regression test
+- Write the simplest failing test that reproduces the bug (see `noir-test-driven-development`).
+- Implement the single fix at the root cause.
+- Verify the test goes green and that no other test regressed.
+- One change at a time; no "while I'm here" refactors bundled into the fix.
+
+### 7. Know when to stop fixing
+If three or more fixes have failed, each revealing a new problem in a different place, the issue is likely architectural, not a missing patch. Stop, name the pattern that is not holding, and surface the architectural question (with evidence) instead of attempting fix number four.
+
+## Verification
+
+- [ ] The bug is reproduced reliably (the trigger is documented).
+- [ ] A root cause hypothesis is stated explicitly ("X because Y").
+- [ ] The fix is at the source, not the symptom.
+- [ ] A regression test passes and no other tests regressed.
+- [ ] One commit per fix — no bundled refactors.
+
+## Notes
+
+- "No root cause found" is usually an incomplete investigation. If the bug is genuinely environmental or timing-dependent after a complete pass, document what you investigated, implement appropriate handling (retry, timeout, error message), and add monitoring — but say so plainly rather than implying the root cause is unknowable.
+- If the bug spans multiple services, use `noir-exploring` to fan out the evidence search first.
+
+## Reference
+
+For deeper detail, see [tracing.md](references/tracing.md).
+
+## When done → next skill
+
+→ `noir-verifying` to confirm the fix is complete. Or do you need to investigate another bug?

package/builtin/noir-systematic-debugging/references/tracing.md

@@ -0,0 +1,51 @@
+# Root-cause tracing — evidence at every boundary
+
+Deep reference for `noir-systematic-debugging`. Use this when the bug spans multiple layers or the root cause is not obvious from the first stack trace.
+
+## Why boundaries matter
+
+A bug is rarely where it surfaces. "The API returns 500" could mean the route handler, the service, the DB layer, or the config. If you fix at the surface, you patch a symptom; the same root cause fails again through another path. Tracing evidence at each boundary converts a guess into a data-backed narrowing.
+
+## The boundary checklist
+
+For a request that flows CLI → adapter → daemon → store (Noir's own shape), or API → service → DB, instrument each layer BEFORE proposing a fix:
+
+1. **Entry** — what arrived? Log the raw request: method, path, headers, body (sanitized).
+2. **Validation** — did the input pass validation? A rejected payload fails here.
+3. **Auth/context** — was identity resolved? A missing token fails here.
+4. **Service logic** — what did the service compute? Log inputs + outputs at the boundary.
+5. **Persistence** — what SQL/query ran? Log the query + params, then the result/error.
+6. **Exit** — what returned? Compare the response to the handler's intent.
+
+## Technique: log at the boundary, not inside
+
+Put one log line at each boundary (enter/exit) rather than scattering logs through the middle. The boundary log answers "did X reach layer N correctly?" — the middle log answers "what happened inside layer N?" Start with boundaries; only go inside when a boundary shows the input was wrong.
+
+## Technique: binary search the layers
+
+Instead of instrumenting all 6 boundaries, bisect: check the MIDDLE layer first. If the middle sees the right input and produces the wrong output, the bug is in the middle or below. If the middle sees wrong input, the bug is above. Each check halves the search space.
+
+## Technique: the "did it change?" check
+
+The most common root cause is a recent change. Before tracing:
+- `git log --oneline -10` — what changed recently?
+- `git diff HEAD~1` — what's different in the code that touches this path?
+- Check config/dependency changes: a new package version, a toggled feature flag, an env var change.
+
+## Recording the trace
+
+For a debugging session, keep a compact trace log:
+
+```
+REQUEST  GET /api/v2/task/86eyeryfe?include_subtasks=true
+VALIDATE ok
+AUTH     pk_*** (ok)
+SERVICE  fetched task, subtasks=[] (NOT null!)   ← suspicious: empty array
+FINDING  subtasks excluded by default; include_subtasks=true missing
+```
+
+The trace makes the evidence explicit and reviewable — the same honesty `noir-verifying` demands.
+
+## When the trace points to an architectural issue
+
+If 3+ fixes have failed, each revealing a new problem in a different layer, stop fixing and name the pattern that is not holding (e.g. "the daemon caches process.env at spawn, so any env-var-dependent path is stale"). Surface it as an architectural question with the trace as evidence.

package/builtin/noir-test-driven-development/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: noir-test-driven-development
+description: Use when implementing any feature or bugfix — write the failing test first with the RED→GREEN→REFACTOR loop. Do NOT use for pure refactors where behavior doesn't change.
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - tdd-worked-example.md
+---
+
+# noir-test-driven-development
+
+Every feature starts with a failing test. The RED → GREEN → REFACTOR loop is the proof: if there's no failing test, there's no evidence the feature is needed. This skill absorbs `noir-test` — test design guidance lives here too.
+
+## When to use
+
+- You're about to implement a feature or fix a bug.
+- The user says "write a test", "test this", or "TDD this".
+- The implementation is non-trivial — a behavior change, new logic, or API contract.
+- **Do NOT use:** for a pure rename, formatting change, or refactor where the existing test suite already covers the behavior.
+
+## Procedure
+
+### RED — Write the failing test
+1. **Write the test FIRST.** Before any implementation code. The test must fail for the RIGHT reason (the feature is missing), not because of a syntax error or a broken import.
+2. **The test is the spec.** Write it with the behavior you want to see — the input, the expected output, the edge cases. A good test reads like a user story: "given X, when Y, then Z."
+3. **Run the test to confirm it fails.** The failure message must be clear — "feature not yet implemented", not "undefined is not a function."
+
+### Verify RED — confirm it fails for the right reason
+- The test fails on the assertion you wrote, not on setup/import/boot.
+- If it fails for the wrong reason, fix the test (not the code under test) until it fails cleanly.
+
+### GREEN — Implement the minimal code
+- Write the smallest amount of production code that makes the test pass. Nothing more — no "future-proofing," no "while I'm here."
+- Run the test. It must pass. Run the full suite to confirm no regression.
+
+### Verify GREEN — confirm it passes legitimately
+- The test passes on the assertion you wrote — not on a coincidental edge case.
+- No other test broke. If one did, fix it NOW; do not carry a broken suite.
+
+### REFACTOR — Clean up
+- With a green suite as the safety net, clean up: remove duplication, improve naming, simplify logic. The test suite protects you — a broken refactor fails immediately.
+- Run the full suite after every refactor step.
+
+### Repeat
+- For the next behavior, go back to RED. One test → one implementation → one refactor per cycle.
+
+## Why order matters
+Writing the test first forces you to state the desired behavior before you're influenced by the implementation. Writing the implementation to the test keeps you from building more than needed. Refactoring last, with a green suite, makes cleanup safe.
+
+## Verification
+
+- [ ] A failing test was written BEFORE the implementation.
+- [ ] The test failed for the right reason (feature missing, not broken import).
+- [ ] The minimal implementation made the test pass.
+- [ ] The full test suite is green after the change.
+- [ ] Refactored code is cleaner, not just different.
+
+## Notes
+
+- Don't test the framework. Test YOUR logic.
+- One assertion per behavior, one test per behavior. A test that asserts five things is five tests fighting for attention.
+- If TDD feels slow, you're probably fixing a bug that someone else shipped because they skipped it.
+
+## Reference
+
+For a worked RED → GREEN → REFACTOR walkthrough, see [tdd-worked-example.md](references/tdd-worked-example.md).
+
+## When done → next skill
+
+→ `noir-verifying` to gather evidence the work is complete. Or is there another behavior to implement?

package/builtin/noir-test-driven-development/references/tdd-worked-example.md

@@ -0,0 +1,65 @@
+# TDD worked example — RED → GREEN → REFACTOR
+
+Deep reference for `noir-test-driven-development`. A complete walkthrough of the loop on a real-shaped problem.
+
+## The problem
+
+Add a function that counts words in a string, ignoring punctuation and case.
+
+## RED — write the failing test first
+
+```ts
+import { describe, expect, it } from 'vitest';
+import { countWords } from './count-words.js';
+
+describe('countWords', () => {
+  it('counts simple words', () => {
+    expect(countWords('hello world')).toBe(2);
+  });
+  it('ignores punctuation and is case-insensitive', () => {
+    expect(countWords('Hello, WORLD!')).toBe(2);
+  });
+  it('returns 0 for empty/whitespace input', () => {
+    expect(countWords('   ')).toBe(0);
+  });
+});
+```
+
+Run it. Expected: FAIL with `Cannot find module './count-words.js'` or `countWords is not a function` — the failure is because the feature doesn't exist, which is the RIGHT reason.
+
+**Verify RED:** the failure is on your assertion / missing module, NOT on a broken import in the test itself.
+
+## GREEN — minimal implementation
+
+```ts
+export function countWords(text: string): number {
+  const words = text.toLowerCase().match(/[a-z]+/g);
+  return words ? words.length : 0;
+}
+```
+
+Run the test. PASS. Run the full suite — no regression.
+
+**Verify GREEN:** it passes for the right reason (the regex matches words), not a coincidental edge case.
+
+## REFACTOR — clean up with the green suite as a net
+
+```ts
+const WORD = /[a-z]+/g;
+export function countWords(text: string): number {
+  return text.toLowerCase().match(WORD)?.length ?? 0;
+}
+```
+
+Run the suite again. Still green. The refactor is safe because the tests prove behavior.
+
+## Repeat
+
+Add the next behavior → back to RED. One test → one implementation → one refactor per cycle. Never skip RED: a feature without a failing test has no evidence it was needed.
+
+## Anti-patterns this example guards against
+
+- Writing the implementation before the test (no RED) — you can't prove the feature is needed.
+- A test that passes before the implementation — you're not driving new behavior.
+- Bundling a refactor into the GREEN step — the refactor belongs AFTER green.
+- One test asserting five behaviors — split into five tests, each with one clear failure.

package/builtin/noir-verifying/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: noir-verifying
+description: Use when about to claim work is complete — gather evidence (tests, gate, criteria) before asserting success. Use when the user says "is this done?" or "verify this". Do NOT use mid-implementation for a progress check; use noir-checkpoint.
+metadata:
+  category: verify
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - verification-checklist.md
+---
+
+# noir-verifying
+
+Gather evidence before asserting success. Absorbs `noir-verify` and `noir-review` into one gate: run, read, verify, then claim done.
+
+## When to use
+
+- About to claim a task, feature, or fix is complete.
+- The user says "verify this", "is this done?", "check everything."
+- **Do NOT use:** mid-implementation — use `noir-checkpoint`.
+
+## Procedure
+
+1. **IDENTIFY criteria.** Load spec/plan — each acceptance criterion is a verification item.
+2. **RUN the gate.** Execute the project's test command. The output IS the evidence.
+3. **READ results.** A passing suite is the minimum; verify each criterion explicitly.
+4. **Check side effects.** New lint warnings? Type errors? Doc links? Run the full gate.
+5. **ONLY THEN claim done.** State "verified: <evidence>" — never "verified: looks good."
+
+## Reference
+
+For the full claim-done + PR-review checklist, see [verification-checklist.md](references/verification-checklist.md).
+
+## When done → next skill
+
+→ `noir-shipping` to commit and integrate, or `noir-wrap` to close. Or something else?
+
+## Notes
+- This skill is a playbook — the host decides which tools to use. On Claude Code, prefer `AskUserQuestion` for choices; on other hosts, ask in text.

package/builtin/noir-verifying/references/verification-checklist.md

@@ -0,0 +1,29 @@
+# Verification checklist — evidence before "done"
+
+Deep reference for `noir-verifying`. A copyable checklist for the two moments it covers: claiming a task done, and reviewing a PR.
+
+## The claim-done gate
+
+Before asserting "this is done," satisfy EVERY item with evidence:
+
+- [ ] **Spec criteria met** — every acceptance criterion from the spec/plan is citable to an actual behavior, test, or output. Not "looks implemented" — point to the evidence.
+- [ ] **Tests green** — the full suite passes. The OUTPUT was read, not assumed. Quote the result line.
+- [ ] **No regression** — tests that passed before still pass. A green suite isn't enough if you deleted a test to make it green.
+- [ ] **Lint/typecheck** — the project's static checks pass (e.g. `pnpm lint`, `pnpm typecheck`).
+- [ ] **Side effects checked** — docs, generated files, or config that the change touches reflect the new reality (docs reflect shipped state, never stale).
+- [ ] **The claim is evidence-backed** — "verified: <test output / command result>" not "verified: looks good."
+
+## The PR-review gate
+
+Beyond the claim-done gate, review asks "does this make sense?"
+
+- [ ] **Approach** — is this the right way to solve it, or a workaround?
+- [ ] **Naming** — do names say what things are?
+- [ ] **Scope** — does the PR do one thing, or did "while I'm here" changes creep in?
+- [ ] **Security** — user input, auth, secrets: any exposure?
+- [ ] **Tests** — do the tests test the behavior, not the implementation detail?
+- [ ] **Diff hygiene** — no commented-out code, no debug logs, no accidental files.
+
+## The honesty rule
+
+**"Seems right" is never sufficient.** State the evidence and let it stand on its own. If you cannot produce evidence for an item, the item is NOT done — say so, rather than asserting completion. The same discipline that keeps a debugging trace honest keeps a "done" claim honest.

package/builtin/noir-worktree/SKILL.md

@@ -1,12 +1,31 @@
 ---
 name: noir-worktree
-description: Use when starting feature work that needs isolation from the current workspace.
+description: Use when creating an isolated git workspace for feature work — keeping the main checkout clean. Use when the user says "worktree" or "isolate this work".
+metadata:
+  category: git
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
 # noir-worktree
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
 
-**When to use:** you are starting work that should not disturb the current workspace (long-running branch, parallel feature, risky change).
+## When to use
+- When the user triggers this skill.
 
-**For now:** create an isolated worktree on a fresh branch, do the work there, and merge or discard when done — keep the main workspace clean.
+Isolate feature work from the current workspace via git worktrees. One feature, one directory, no cross-contamination.
+
+## Procedure
+
+1. **Confirm the feature needs isolation.** A single-file fix in a clean repo doesn't need a worktree. A multi-file feature with branches and dependencies does.
+2. **Create the worktree.** `git worktree add -b <feature-branch> <path> <base-branch>`. On Claude Code, if a `.claude/worktrees/` pattern exists, follow it.
+3. **Work in the isolated directory.** The worktree has its own checkout, and the original directory is untouched.
+4. **When done, clean up.** `git worktree remove <path>` + `git branch -d <feature-branch>` (after merge).
+
+## When done → next skill
+
+→ `noir-shipping` to integrate the finished work. Or continue in the worktree.
+
+## Notes
+- This skill is a playbook — the host decides which tools to use. On Claude Code, prefer `AskUserQuestion` for choices; on other hosts, ask in text.

package/builtin/noir-wrap/SKILL.md

@@ -1,23 +1,39 @@
 ---
 name: noir-wrap
-description: Use when closing a session cleanly — run tests, curate docs, confirm commits, save memory, emit a host handoff.
+description: Use when closing a work session cleanly — running final verification, updating docs and CHANGELOG, saving memory, and emitting a host handoff. Do NOT use mid-session for a checkpoint — use noir-checkpoint.
+metadata:
+  category: document
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
 # noir-wrap
 
-Use when you are ending a session and want to leave the work in a clean, recoverable state — and hand off to the host CLI with a ready-to-paste prompt.
+Close a session in a clean, recoverable state. This skill absorbs `noir-document` (update docs/CHANGELOG/memory) — wrap is the superset that covers the full close.
 
-## Steps
+## When to use
 
-1. Run the project's test command (the host detects it; if unknown, `pnpm test` / `npm test`).
-2. Curate or delete ephemeral notes (scratch docs, dead branches, tmp files).
-3. Confirm commits are made — and pushed or intentionally local (Noir keeps commits local + conservative by default).
-4. Save durable memory before closing: observations, decisions, patterns the next session should recall. Prefer `noir memory save` (or the `noir.remember` MCP tool from the host) so cross-session recall works.
-5. Advance the workflow task if a gate is satisfied: `noir task advance --to <phase>` (the verify gate prints the handoff hint automatically).
-6. Emit the host handoff — run `noir handoff` (or the session-end alias `noir wrap`). This prints a ready-to-paste markdown prompt to STDOUT that names the active task, the next gate's skill, a bounded context/memory seed, and the exact host-launch directive. Pipe it straight into the host, or persist with `noir handoff --write` (the path is gitignored under `.noir/handoff/`).
+- Ending a work session.
+- The user says "wrap up", "I'm done", "close this out."
+- **Do NOT use:** mid-session — use `noir-checkpoint`.
 
-## Notes
+## Procedure
 
-- `noir handoff` reuses the same snapshot as `noir status` and the same phase→skill map as `noir task next`, so the handoff is always consistent with the live state.
-- The handoff directive is TEXT ONLY — Noir never launches the host. Paste the block into the host CLI to resume.
-- For a machine-readable handoff (e.g. a CI consumer), use `noir handoff --json`.
+1. **Run final verification.** Same gate as `noir-verifying`: test suite, lint, typecheck. Evidence, not assumption.
+2. **Update docs.** CHANGELOG, ADRs, decisions, reference docs — anything that should reflect the session's work. The rule: docs reflect shipped reality, never a stale plan.
+3. **Save memory.** Persist observations, decisions, patterns the next session should recall. `noir memory save` (or `noir.remember` MCP tool).
+4. **Confirm commits.** Commits are made and intentional (local or pushed). Noir defaults to local.
+5. **Advance the workflow task.** `noir task advance --to <phase>` if a gate is satisfied.
+6. **Emit the handoff.** `noir handoff` (text-only prompt; `--write` persists to `.noir/handoff/`; `--json` for CI). Names the active task, next gate's skill, and the host-launch directive.
+
+## Verification
+
+- [ ] Gate is green (tests, lint, typecheck).
+- [ ] Docs are synced (CHANGELOG, decisions, references).
+- [ ] Memory is saved (key observations + decisions).
+- [ ] Handoff emitted (the next session can resume).
+
+## When done → next skill
+
+The session is closed. Until next time.