@use-the-fork/spindle 0.0.0-stage → 0.0.1

package/build/Assets/Blueprints/skills/grill-design/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: grill-design
+description: "Challenge and refine an existing design through an interview, updating the design and relevant domain documentation."
+argument-hint: "[design.md path or feature directory]"
+disable-model-invocation: true
+user-invocable: true
+metadata:
+  spindle:
+    version: 1.1.0
+---
+
+Challenge and refine an existing design through an interview, keeping the selected design as the source of truth. A feature design is optional, but when present it precedes the spec and tickets.
+
+## Select the design
+
+- **The user supplies a design:** read that file. For a supplied numbered SDD feature directory, read its `design.md`. An explicit target takes precedence over discovery and may have `spec.md`, `sdd.json`, and issue data alongside it. If the target is missing or unreadable, report the problem and ask for a corrected path; keep the target unresolved.
+- **No design supplied:** scan numbered feature directories directly under `.scratch/` for `design.md` files whose sibling `spec.md` is still an unfilled template. Do not require `design.md` to be the directory's only file; SDD workspaces also contain their spec template, ledger, and tracker folders. Inspect candidates and present their paths; ask the user which design to grill, even when there is only one. Never automatically pick the newest.
+- If `.scratch/` is absent or no candidates qualify, explain that no unfilled SDD design was found and ask for a design path. Do not substitute an ineligible design or create a new one.
+
+**Complete when:** the user has supplied or selected one readable design.
+
+## Required skills
+
+Before acting, read and understand each required skill:
+
+- **REQUIRED:** `grill`
+- **REQUIRED:** `int-domain-modeling`
+
+These skills define the interview and domain-modeling workflows.
+
+## Refine and finish
+
+Aim for the smallest design that satisfies the agreed goal and success criteria. Challenge unnecessary requirements and complexity as actively as missing decisions. Recommend additional scope only when needed to meet those criteria, explaining the concrete failure it prevents; optional improvements remain out of scope unless the user expands the goal.
+
+Read the selected design and relevant supporting context, including its feature spec when present. Ground the interview in the proposal, verified facts, and unresolved decisions. When a spec already contains substantive content, preserve the design-before-spec sequence: do not silently reorder or overwrite either document.
+
+As answers settle decisions, update the selected design in place, reconciling affected passages and preserving unrelated content. Keep unresolved questions explicit; recommendations are not accepted decisions. Recording accepted decisions in the design and relevant domain documentation is part of the interview: the shared-understanding confirmation gate in `grill` does not defer these updates.
+
+Once every decision branch within the agreed scope is settled and the design and relevant domain documentation are consistent, summarize the refinements, link the changed documents, and ask the user to confirm shared understanding. Revise and repeat if corrections remain.
+
+Stop when the user confirms the refined design. Do not generate a spec, tickets, or implementation, or automatically invoke a delivery workflow.

package/build/Assets/Blueprints/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+user-invocable: true
+metadata:
+  spindle:
+    version: 1.0.1
+---
+
+Before acting, read and understand each required skill:
+
+- **REQUIRED:** `grill`
+- **REQUIRED:** `int-domain-modeling`

package/build/Assets/Blueprints/skills/implement/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.0.2
+---
+
+# Implement
+
+Implement the user's task or supplied ticket/spec, verify it, and obtain a clean code review before committing.
+
+## Workflow
+
+Announce `Step <node ID> - <node label>` before acting on each node, including resumed steps and loop re-entries. After each decision, state its result and selected branch.
+
+```mermaid
+flowchart TD
+    A[Prepare task and checkout] --> B[Implement]
+    A -- Ambiguous task --> X[Ask and stop]
+    A -- Dirty worktree --> X
+    B --> C[Verify implementation]
+    C -- Required check fails --> X
+    C -- Checks pass --> D[Freeze review snapshot]
+    D --> E[Review implementation]
+    E -- Snapshot changed --> C
+    E -- Commit blockers --> F[Fix blockers]
+    F --> C
+    E -- No blockers --> G[Commit and report]
+```
+
+### A. Prepare task and checkout
+
+If the user supplies a ticket reference, read it and state its title; ask if the reference is ambiguous. Preserve the original task description and any supplied ticket/spec paths for the review. Before changing files, check `git status --short`. If staged, unstaged, or untracked changes already exist, preserve them, ask the user to clean or separately preserve them, and stop. Once clean, record `git rev-parse HEAD` as the implementation base before making changes.
+
+**Complete when:** the task and requirements context are clear, the worktree is clean, and the starting base revision is recorded; otherwise stop without editing.
+
+### B. Implement
+
+Implement the requested work. Call `int-test-driven-development` at pre-agreed seams where appropriate. Keep changes within the task scope.
+
+**Complete when:** the requested implementation is complete and its changed files are known, selecting C.
+
+### C. Verify implementation
+
+Run applicable project completion checks through the repository's Just recipes. Call `int-verification-before-completion` for evidence-backed claims. If a required check fails or is unavailable, report the blocker and do not proceed to commit.
+
+**Complete when:** required checks pass and their results identify the snapshot they cover, selecting D; otherwise stop with the failing or unavailable checks.
+
+### D. Freeze review snapshot
+
+Stop implementation edits while review runs. Prepare review inputs using the existing [review-input contract](../int-subagent-driven-dev/references/review-inputs.md): absolute workspace, recorded starting base, current head, exact snapshot identity, complete changed-file inventory and diff including staged, unstaged, and untracked changes, original task description and known ticket/spec pointers, and verification evidence for the same snapshot. Use `just tool::git-detailed-diff` to capture staged, unstaged, and untracked content. Keep the implementation frozen until review returns.
+
+**Complete when:** the caller can supply a complete, internally consistent review snapshot and matching verification evidence; otherwise stop and identify the gap.
+
+### E. Review implementation
+
+Load and follow `int-code-review`. Supply the frozen review inputs and task requirements context. If the review reports a snapshot mismatch or incomplete evidence, do not commit; refresh the snapshot and required checks before reviewing again.
+
+**Complete when:** review findings identify the current snapshot and explicitly classify each finding as blocking or non-blocking, selecting F for blockers or G when there are none.
+
+### F. Fix blockers
+
+Fix every substantiated requirement defect and confirmed mandatory repository-rule violation marked as a commit blocker. Keep advisory smells and optional recommendations separate; do not treat them as blockers. After changing code, rerun affected required checks, prepare a new frozen snapshot, and rerun `int-code-review`. Do not commit while any blocker remains.
+
+**Complete when:** the updated snapshot has passing required checks and a current review with no commit blockers, selecting G; unresolved or unverified blockers remain here.
+
+### G. Commit and report
+
+Commit only the reviewed task changes after confirming the reviewed snapshot is still current and no commit blockers remain. Report the commit and verification and review outcomes.
+
+**Complete when:** the reviewed changes are committed and the caller receives the commit and evidence summary.
+
+### X. Ask and stop
+
+Request the missing task clarification, clean-worktree action, or verification correction. Preserve existing work and do not commit.
+
+**Complete when:** the blocker and required next action are explicit; stop.

package/build/Assets/Blueprints/skills/implement-spec/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: implement-spec
+description: "Implement the result of /to-spec and /to-tickets in code."
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Implement a Spec
+
+Deliver the supplied spec and all associated tickets in the existing checkout. Require configured tracker guidance; if absent, request `/setup-project`.
+
+## Required Skills
+
+Before acting, read and follow each required skill:
+
+- `int-subagent-driven-dev`
+
+## Steps
+
+1. **Bind the whole-spec assignment.** Locate the full spec, every ticket and its comments, and tracker guidance. Supply accessible context pointers rather than duplicating their contents. Record the existing checkout, starting revision, existing work and permissions.
+
+   **Complete when:** the complete graph and delivery inputs are available to one controller, or missing requirements are reported for triage.
+
+2. **Execute the complete graph.** Follow [int-subagent-driven-dev](../int-subagent-driven-dev/SKILL.md) once with the entire graph and explicit ownership of frontier selection, sequential ticket delivery, aggregate review, and retrospective. Do not call it as a separate standalone delivery for every ticket. Its dependency validation, shared-checkout workflow, resume handling, review budgets, and completion criteria are authoritative. Accepted work does not unblock dependents until integrated and verified in the existing checkout.
+
+   If the tracker calls for a PR, or the user requests one, open an authorized draft during execution after the first authorized commit is available; retain it as draft while delivery is incomplete.
+
+   **Complete when:** its final report reconciles every ticket and requirement, one aggregate review, fresh verification and one retrospective for the spec, or explicitly identifies unfinished work and blockers.
+
+3. **Apply authorized publication transitions.** Mark an authorized draft ready only after the full delivery's review and checks pass. Apply closing references and ticket closure only with the user's authorization.
+
+   **Complete when:** the report identifies the verified checkout snapshot, ticket states, retrospective pointer, and any authorized PR/closure actions; unresolved work remains open with its limitations reported.

package/build/Assets/Blueprints/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,129 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two: don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review for {% raw %}{{repo name}}{% endraw %}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam {
+        stroke-dasharray: 4 4;
+      }
+      .leak {
+        stroke: #dc2626;
+      }
+      .deep {
+        background: linear-gradient(135deg, #0f172a, #1e293b);
+      }
+    </style>
+  </head>
+  <body class="bg-stone-50 font-sans text-slate-900">
+    <main class="mx-auto max-w-5xl space-y-12 px-6 py-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph. Straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/int-codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title**: short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row**: recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files**: monospaced list, `font-mono text-sm`.
+- **Before / After diagram**: the centrepiece. Two columns, side by side. See patterns below.
+- **Problem**: one sentence. What hurts.
+- **Solution**: one sentence. What changes.
+- **Wins**: bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable): one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same. Variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals, since Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module: one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams, so they read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static: no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise, but the architectural nouns and verbs come straight from the `/int-codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow: interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: _"locality: bugs concentrate in one module"_, _"leverage: one interface, N call sites"_, _"interface shrinks; implementation absorbs the wrappers"_. Don't write _"easier to maintain"_ or _"cleaner code"_, because those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/int-codebase-design` glossary, reach for one that is before inventing a new one.

package/build/Assets/Blueprints/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+metadata:
+  spindle:
+    version: 1.0.0
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities**: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Call the Skill tool with "int-codebase-design" for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `GLOSSARY.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide _where_ to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow**, with an interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user (`xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows) and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals: use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files**: which files/modules are involved
+- **Problem**: why the current architecture is causing friction
+- **Solution**: plain English description of what would change
+- **Benefits**: explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram**: side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength**: one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use GLOSSARY.md vocabulary for the domain, and the `int-codebase-design` skill vocabulary for the architecture.** If `GLOSSARY.md` defines "Order," talk about "the Order intake module," not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007, but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, call the Skill tool with "grilling" to walk the decision tree with them: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize; call the Skill tool with "int-domain-modeling" skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `GLOSSARY.md`?** Add the term to `GLOSSARY.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `GLOSSARY.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing; skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Call the Skill tool with "int-codebase-design" and use its design-it-twice parallel sub-agent pattern.

package/build/Assets/Blueprints/skills/int-code-review/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: int-code-review
+description: "{{ computed.internal_skill_description }}"
+user-invocable: false
+metadata:
+  spindle:
+    version: 1.0.1
+---
+
+# Code Review
+
+Review an implementation against its requirements and applicable repository standards before the caller commits it. The caller owns implementation, snapshot construction and freezing, corrections, and commit decisions.
+
+## Workflow
+
+Announce `Step <node ID> - <node label>` before acting on each node, including resumed steps and loop re-entries. After each decision, state its result and selected branch.
+
+```mermaid
+flowchart TD
+    A[Validate review inputs] --> B[Inspect assigned snapshot]
+    A -- Missing or inconsistent --> F[Report review blocked]
+    B --> C[Review standards]
+    B -- Incomplete snapshot --> F
+    C --> D[Review requirements]
+    D --> E{Snapshot still matches?}
+    E -- No --> F
+    E -- Yes --> G[Report findings]
+```
+
+### A. Validate review inputs
+
+Read and follow the [review-input contract](../int-subagent-driven-dev/references/review-inputs.md). The caller must provide its absolute workspace, starting base and reviewed head revisions, exact change identity, complete change inventory and diff (including staged, unstaged and untracked changes), and verification results for that same snapshot. Also require the original task description and any known ticket/spec pointers. The original task description is sufficient requirements context when no formal spec exists.
+
+Do not infer missing revisions, requirements, or changes from Git or conversational mentions. If required inputs are missing or inconsistent, request the specific correction from the caller and stop.
+
+**Complete when:** required inputs are present, mutually consistent, and identify one review snapshot; otherwise report the blocker and select F.
+
+### B. Inspect assigned snapshot
+
+Read the supplied diff, inventory, verification evidence, original task description, and any applicable ticket/spec sources. Read enough surrounding code to substantiate findings. Do not edit the implementation or spawn review sub-agents. If the change is incomplete or evidence does not cover the supplied snapshot, report the gap and select F.
+
+**Complete when:** the full assigned change and its requirements and verification evidence are understood, selecting C; missing coverage selects F.
+
+### C. Review standards
+
+Read instructions applicable to changed files and project-wide coding standards or contributor guidance when present. Do not search unrelated files for standards. Skip requirements already enforced by tooling.
+
+Report a confirmed violation of an explicit, mandatory repository rule as a commit blocker, citing the rule and changed location. Keep subjective design smells advisory. Use these as prompts for judgment, not prescribed refactors: feature envy, data clumps, primitive obsession, repeated switches, shotgun surgery, divergent change, message chains, and refused bequest. A repository rule overrides a smell heuristic.
+
+**Complete when:** every changed file is checked against its applicable written rules; confirmed mandatory violations and advisory observations are distinguished, selecting D.
+
+### D. Review requirements
+
+Compare the complete change with the original task description and supplied ticket/spec requirements. Check missing or partial requirements, unintended behavior, and implementations that appear incorrect. Ask the caller for clarification only when the requirements themselves are unclear; do not require a separate formal spec when the task description is clear.
+
+Report substantiated failures to meet requirements as commit blockers. Keep optional improvements non-blocking.
+
+**Complete when:** each supplied requirement is accounted for with evidence, selecting E.
+
+### E. Snapshot still matches?
+
+Confirm the review inputs still identify the exact change reviewed and that the caller has kept implementation frozen during review. If the checkout, revisions, or included changes no longer match, do not present findings as current; select F.
+
+**Complete when:** a matching snapshot selects G; any mismatch selects F with the invalidation evidence.
+
+### F. Report review blocked
+
+Name the missing input, evidence gap, or snapshot mismatch and what the caller must provide or refresh. Do not claim a clean review or recommend committing.
+
+**Complete when:** the caller has a specific correction request and the review stops.
+
+### G. Report findings
+
+Return findings directly to the caller under separate `Standards` and `Requirements` headings. For each finding, include its axis, changed file and location, cited rule or requirement, evidence, impact, and `Commit blocker: yes|no`. Use `None` when an axis has no findings. List subjective smells and optional recommendations as non-blocking. State the reviewed snapshot and any coverage limits. Do not change implementation files or make the commit decision.
+
+**Complete when:** both axes, blocker status, snapshot identity, and limitations are reported; return to the caller.