@imix-js/taproot 0.2.0

package/skills/promote.md

@@ -0,0 +1,69 @@
+# Skill: promote
+
+## Description
+
+Escalate a significant finding from implementation or behaviour level up to the intent. Use when implementation reveals that a higher-level assumption is wrong — not a detail-level bug, but a structural mismatch between what was intended and what is actually achievable or desirable.
+
+## Inputs
+
+- `path` (required): Path to the `impl.md` or `usecase.md` where the finding originated.
+- `finding` (required): Description of the discovery that affects the parent intent.
+
+## Steps
+
+1. Read the artifact at `path`. Identify its type.
+
+2. Walk up the hierarchy to find the parent `intent.md`. If `path` is an `impl.md`, walk up through the behaviour to the intent.
+
+3. Read the `intent.md`. Identify which success criteria, goal statement, or constraints are affected by the finding.
+
+4. Classify the finding's severity:
+   - **Intent goal is unachievable as stated**: the goal cannot be reached given discovered constraints (technical, regulatory, dependency)
+   - **Success criterion is unmeasurable or wrong**: a criterion turns out to be impossible to verify, or measures the wrong thing
+   - **New constraint discovered**: a real-world constraint exists that the intent didn't account for (compliance requirement, third-party limitation, performance ceiling)
+   - **Scope is wider than understood**: achieving the intent requires significantly more work than originally estimated
+   - **Dependency discovered**: this intent cannot be achieved without another intent or external project being completed first
+
+5. Draft the update to `intent.md`:
+   - Add a **Review Note** to the Notes section (do not modify the Goal or Success Criteria directly without user confirmation):
+     ```
+     **Review Note (<date>):** <summary of finding and its impact>
+     Source: <path-to-origin-artifact>
+     ```
+   - Update Status **State** to `active` if it was `draft` (the finding makes it concrete)
+   - Update "Last reviewed" to today
+
+6. Show the proposed changes. Ask: "Do you want me to also update the Goal/Success Criteria directly, or just add the review note for now?"
+
+7. If the user wants to update Goal or Success Criteria, make those changes collaboratively, respecting the original intent while incorporating the finding.
+
+8. List all behaviours under the affected intent. For each, assess whether the finding might require the behaviour to be re-evaluated:
+   - "Behaviours that may need review given this finding:"
+   - List each with a one-line explanation of why it might be affected
+
+9. Write the updated `intent.md`.
+
+10. Run `taproot validate-format --path <intent-folder>`.
+
+11. Report: "Intent updated. <N> behaviours flagged for potential re-evaluation."
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+    **What's next?**
+    [A] `/tr-refine taproot/<intent-slug>/<behaviour-slug>/` — refine the most-affected behaviour
+    [B] `/tr-review taproot/<intent-slug>/intent.md` — stress-test the updated intent
+
+## Output
+
+An updated `intent.md` with a Review Note and updated status. A list of behaviours that may need re-evaluation.
+
+Importantly, this skill does **not** auto-modify other behaviours — it creates a review task. The user decides what to act on.
+
+## CLI Dependencies
+
+- `taproot validate-format`
+
+## Notes
+
+- Use this skill when the finding changes the answer to "is this intent achievable?" or "are we building the right thing?" — not for normal implementation learnings (use `/taproot:refine` for those).
+- If multiple findings accumulate in the Notes section without being resolved, that is a signal to run a full `/taproot:review` or `/taproot:review-all` on the intent.

package/skills/refine.md

@@ -0,0 +1,78 @@
+# Skill: refine
+
+## Description
+
+Update a behaviour spec (`usecase.md`) based on what was learned during or after implementation. Implementations frequently reveal that specs were incomplete, ambiguous, or wrong — this skill brings the spec back into alignment with reality (or reality into alignment with the spec).
+
+## Inputs
+
+- `path` (required): Path to the behaviour folder containing the `usecase.md` to refine.
+- `finding` (required): Description of what changed or was discovered. Can be free-form.
+
+## Steps
+
+0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the `finding` input for semantic matches. Match signals:
+   - "applies to all / every implementation should" → `check-if-affected-by`
+   - "enforce a rule / architectural constraint" → `check-if-affected-by`
+   - "docs should stay current / keep X updated" → `document-current` or `check-if-affected: X`
+
+   If a match is found, **interrupt before reading the spec**:
+   > "Before I refine this — that finding sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md`."
+   > **[A] Apply the pattern** — configure it in `.taproot/settings.yaml` instead of editing the spec
+   > **[B] Continue refining** — the spec change is the right approach
+
+   - **[A]**: guide through applying the pattern. Do not modify `usecase.md`.
+   - **[B]** or no match: proceed to step 1.
+
+1. Read `<path>/usecase.md`. Read all `impl.md` files under `<path>/` to understand the current implementation state.
+
+2. Classify the finding into one or more categories:
+   - **Missing flow**: a scenario that happens in reality but isn't in the spec (add alternate flow or error condition)
+   - **Incorrect flow**: a step in the spec that doesn't match how the system actually behaves (correct it)
+   - **Missing postcondition**: something that is now true after the behaviour that wasn't listed
+   - **New constraint**: a limit discovered during implementation (rate limit, quota, timeout) that should be in the spec
+   - **Scope change**: the behaviour is actually larger or smaller than originally specified
+   - **Actor change**: the actor is different from what was specified, or multiple actors are involved
+   - **State machine issue**: the preconditions or postconditions interact with other behaviours in ways not reflected
+
+3. Draft the changes to `usecase.md`. Show the diff to the user: "Here's what I'm changing: [before/after for each section]." Ask for confirmation before writing.
+
+4. Update the `usecase.md`:
+   - For missing flows: add to Alternate Flows or Error Conditions
+   - For incorrect flows: correct the Main Flow steps or affected sections
+   - For new constraints: add to Preconditions or Error Conditions
+   - Update "Last reviewed" to today
+   - If the finding is significant enough to change the state, update Status
+   - **Preserve the `## Implementations <!-- taproot-managed -->` section exactly** — read and re-insert it unchanged before `## Status` after applying other edits. Never discard it during a rewrite.
+   - **Preserve `## Acceptance Criteria` IDs** — you may update the Given/When/Then wording, but never change an existing AC-N ID. If a new flow is added, assign the next available ID (highest existing + 1). If a criterion is retired, mark it `~~AC-N: deprecated~~` rather than removing it.
+
+5. Run `taproot sync-check --path <taproot-root>`. If any `impl.md` files under this behaviour are flagged as `SPEC_UPDATED`, list them explicitly: "These implementations may need to be reviewed against the updated spec: [list]."
+
+6. Check if the change cascades upward: does the finding imply that the parent intent's goal, success criteria, or constraints are wrong or incomplete? If yes: "This finding may affect the parent intent at `<intent-path>`. Consider running `/taproot:promote` to update the intent and flag any other behaviours that may be affected."
+
+7. Run `taproot validate-format --path <path>`.
+
+8. Report what changed.
+
+9. Present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] Commit the spec change — `git add <path>/usecase.md && git commit`
+   [B] `/tr-implement <path>/` — spec changed significantly; reimplementation needed
+
+## Output
+
+An updated `usecase.md` reflecting the new understanding. A list of any downstream effects (impl.md files that may need review, intent-level implications).
+
+## CLI Dependencies
+
+- `taproot sync-check`
+- `taproot validate-format`
+
+## Notes
+
+- If the finding is so significant that the behaviour needs to be split into two, suggest that explicitly and offer to run `/taproot:behaviour` to create the new one, then `/taproot:decompose` to restructure.
+- Never silently remove steps or error conditions that may still be relevant. When in doubt, ask the user whether the old spec was wrong or whether the implementation is wrong.
+- If the implementation diverged from the spec and both are acceptable, clarify with the user which is the "true" state and update accordingly.

package/skills/research.md

@@ -0,0 +1,122 @@
+# Skill: research
+
+## Description
+
+Research any domain or technical subject before writing a behaviour spec — by scanning local resources, searching the web, and drawing on expert knowledge.
+
+## Inputs
+
+- `topic` (required): The domain, technology, or subject to research. Can be a phrase or a few words — the skill will sharpen it if ambiguous.
+- `context` (optional): Additional context from the calling skill (e.g. the raw requirement from `/tr-ineed`) that informs search queries and expert questions.
+
+## Steps
+
+1. **Announce the topic** and confirm scope: `"Researching: <topic>."` If the topic is a single word or lacks domain context (e.g. `"sort"`, `"auth"`), ask one clarifying question before proceeding: `"What domain or language context should I scope this to?"` Incorporate the answer into all subsequent steps.
+
+2. **Scan local resources** in this order:
+   - `research/` folder — any `.md` or `.pdf` files
+   - `docs/` and project root — any `.pdf` files
+   - Files linked from `taproot/OVERVIEW.md`
+
+   Use the topic as a **semantic** query against file content — do not rely on filename matching alone. A file named `thermal-design.pdf` may be relevant to `"heat dissipation"`. For each relevant file found, note the path and a one-line summary of what it contributes.
+
+3. **Check for prior research:** if `research/<topic-slug>.md` already exists, present it:
+   > "Found existing research at `research/<topic-slug>.md` (last updated: `<date>`). [U]se it / [R]efresh it / [S]tart fresh?"
+   - **[U]** — load the existing document as the synthesis; skip to step 7
+   - **[R]** — run the full flow (steps 4–6); merge new findings with the existing document, updating citations and conclusions; preserve prior expert insights unless explicitly superseded
+   - **[S]** — discard the existing document; run the full flow
+
+4. **Multi-query web search** — issue several targeted queries rather than one literal search:
+   - `"<topic> existing library OR package"`
+   - `"<topic> algorithm OR implementation paper"`
+   - `"<topic> production implementation OR best practice"`
+   - Add domain-specific variants based on context (e.g. `"<topic> RFC"` for protocol topics, `"<topic> npm"` for JavaScript)
+
+   For each result that looks substantive, read it and extract: name/title, URL or reference, what it solves, and any known limitations or trade-offs.
+
+   If web search is unavailable, note: `"Web search unavailable — continuing with local sources and expert knowledge only."` and proceed to step 5.
+
+   If no local resources were found in step 2, note this and continue — the web search is still valuable.
+
+5. **Present a preliminary synthesis:**
+   ```
+   ## Preliminary findings: <topic>
+
+   ### Local resources
+   - <file path> — <one-line summary>
+   (or: none found)
+
+   ### Web findings
+   - <name/title> (<URL or reference>) — <what it solves / key trade-offs>
+   (or: none found / web unavailable)
+
+   ### Key take-aways so far
+   - <insight 1>
+   - <insight 2>
+   ```
+
+6. **Expert check** — ask: `"Are you an expert on this subject?"`
+   - **Yes** → delegate to `/tr-grill-me` seeded with the preliminary synthesis as grilling material. The grill session should ask questions that reference specific findings — library names, paper conclusions, known trade-offs — not generic questions. Terminate when the developer says `[Done]` or after ≤3 rounds where no new information is surfacing. Incorporate the expert answers into the synthesis.
+   - **No** → proceed with the gathered synthesis.
+
+7. **Present the final structured research summary:**
+   ```
+   ## Research summary: <topic>
+
+   ### Local sources
+   - <path> — <summary>
+
+   ### Web sources
+   - <name> (<URL>) — <summary>
+
+   ### Expert insights
+   - <insight from grilling> (or: none)
+
+   ### Key conclusions
+   - <conclusion 1>
+   - <conclusion 2>
+
+   ### Open questions
+   - <question that research did not resolve>
+
+   ### References
+   - <full citation: title, URL or path, accessed/published date>
+   ```
+
+8. **Propose slug and output choice.** Derive a kebab-case slug from the topic:
+   > `"I'll save this as research/<topic-slug>.md — is that right?"`
+
+   Developer confirms or corrects the slug. Then ask:
+   > **`[S] Save to research/<topic-slug>.md with citations`**
+   > **`[F] Feed directly into a spec`**
+   > **`[Q] Discard and stop`**
+
+   - **[S]** — create `research/` directory if absent; write `research/<topic-slug>.md` using the final summary structure from step 7; present:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+     **What's next?**
+     [A] `/tr-behaviour taproot/<intent>/` — write a spec informed by this research
+     [B] `/tr-ineed "<topic>"` — route it as a requirement with research context attached
+   - **[F]** — pass the final summary as input context to `/tr-behaviour`; no file written
+   - **[Q]** — discard the synthesis; exit without writing any file or chaining to another skill
+
+## Output
+
+One of:
+- A saved `research/<topic-slug>.md` document with full citations and structured findings
+- The research synthesis passed as input context to a downstream skill (`/tr-behaviour` or `/tr-ineed`)
+- Nothing (if the developer chose `[Q]`)
+
+## CLI Dependencies
+
+None — pure agent skill. Uses agent tools: file reading (local scan), web search (step 4).
+
+## Notes
+
+- **Auto-trigger mode:** when called from `/tr-ineed`, step 8 is skipped — the synthesis is always fed forward to the calling skill without prompting. The `context` input carries the original requirement to sharpen search queries.
+- **Graceful degradation:** if both local resources and web search produce nothing, and no expert is available, announce: `"No research sources available."` Ask whether to proceed with the spec based on the stated requirement alone, or abort. Never silently produce an empty synthesis.
+- **Slug derivation:** kebab-case the topic words, drop stop words, keep max 4 words. `"satellite tracking algorithm"` → `satellite-tracking-algorithm`. Confirm with the developer before writing.
+- **Refresh merges, not overwrites:** when `[R]efresh` is chosen, append new citations to the References section, update Key conclusions, and add a `Last refreshed:` date — do not discard prior expert insights.
+- **Expert grilling is domain-aware:** the grill session is seeded with what was actually found, not generic questions. If the synthesis found `satellite.js`, ask about its limitations, alternatives, and when it breaks — not `"what do you know about satellite tracking?"`
+- `/tr-research` is the Claude Code adapter command name for this skill.

package/skills/review-all.md

@@ -0,0 +1,92 @@
+# Skill: review-all
+
+## Description
+
+Run a comprehensive review of an entire subtree — an intent and all its descendants, or the entire `taproot/` root. Applies the per-artifact review logic from `/taproot:review` to each node, then adds cross-cutting analysis that can only be done by comparing artifacts against each other. Produces a consolidated report.
+
+## Inputs
+
+- `path` (optional): Path to an intent folder or the `taproot/` root. Defaults to `taproot/`.
+
+## Steps
+
+1. Run `taproot validate-structure --path <path>` and `taproot validate-format --path <path>`. Include any validation errors in the report as **Structural Issues** (resolve these before addressing semantic issues — a structurally invalid hierarchy produces unreliable analysis).
+
+2. Run `taproot check-orphans --path <path> --include-unimplemented`. Include results in the report as **Orphan & Coverage Issues**.
+
+3. Run `taproot sync-check --path <path>`. Include results in the report as **Staleness Warnings**.
+
+4. Walk the subtree top-down. For each artifact found:
+   - Read the file
+   - Apply the review logic from `/taproot:review` (Steps 3 of that skill)
+   - Record findings tagged with the artifact path
+
+5. After reviewing all individual artifacts, perform **cross-cutting analysis**:
+
+   **Intent ↔ Behaviours:**
+   - For each intent, check every success criterion against the list of behaviours. Is there at least one behaviour that, if implemented, would contribute to satisfying each criterion? Flag criteria with no corresponding behaviour as **Coverage Gaps**.
+   - Are there behaviours that don't obviously serve any success criterion? Flag as **Potentially Gold-Plated**.
+   - Do sibling behaviours have contradictory postconditions? (e.g., behaviour A sets a flag, behaviour B assumes that flag is unset)
+
+   **Behaviours ↔ Implementations:**
+   - For each behaviour, check whether its main flow steps are traceable to at least one implementation. Steps with no implementation are **Unimplemented Flows**.
+   - Do implementations reference source files that have been modified more recently than the spec was last reviewed? (Cross-reference with `taproot sync-check` output.)
+
+   **Across the hierarchy:**
+   - Are there behaviours that are nearly identical across different intents? Possible duplication.
+   - Are there intents at similar levels of completion, where one could be sequenced to unblock the other?
+
+6. Assemble the consolidated report:
+
+```
+# Taproot Review: <path>
+
+## Structural Issues
+<from validate-structure and validate-format>
+
+## Orphan & Coverage Issues
+<from check-orphans>
+
+## Staleness Warnings
+<from sync-check>
+
+## Cross-Cutting Issues
+### Coverage Gaps
+### Contradictions
+### Duplication
+
+## Per-Artifact Findings
+
+### <artifact-path>
+**Blockers**: ...
+**Concerns**: ...
+**Suggestions**: ...
+
+```
+
+7. Close with a prioritized action list: "Recommended next steps: (1) resolve structural issues, (2) address blockers in [artifact], (3) fill coverage gaps for [criterion]."
+
+8. Present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-refine <highest-priority-path>` — fix the top-priority finding
+   [B] `/tr-plan` — surface the next implementable behaviour
+   [C] `/tr-ineed` — add a requirement surfaced by the review
+
+## Output
+
+A consolidated review report covering the entire subtree, with structural issues, cross-cutting analysis, and per-artifact findings.
+
+## CLI Dependencies
+
+- `taproot validate-structure`
+- `taproot validate-format`
+- `taproot check-orphans`
+- `taproot sync-check`
+
+## Notes
+
+- For large hierarchies (>20 artifacts), batch the per-artifact review by intent to avoid overwhelming the user. Present one intent at a time and ask if they want to continue.
+- If the user wants to act on findings immediately, each finding can link to the skill that fixes it: `/taproot:refine` for behaviour and impl issues, `/taproot:intent` for intent issues, `/taproot:implement` for unimplemented flows.

package/skills/review.md

@@ -0,0 +1,80 @@
+# Skill: review
+
+## Description
+
+Stress-test a single Taproot artifact — an `intent.md`, `usecase.md`, or `impl.md` — by challenging it from multiple angles. Produces a structured critique with prioritized findings. Does **not** auto-modify the artifact; the user decides what to act on.
+
+## Inputs
+
+- `path` (required): Path to a Taproot artifact (`intent.md`, `usecase.md`, or `impl.md`).
+
+## Steps
+
+1. Read the artifact at `path`. Identify its type by filename.
+
+2. If the artifact has a parent (e.g., a `usecase.md` has a parent `intent.md`), read the parent to understand context. If siblings exist (other behaviours under the same intent), read those too — cross-checking is part of a thorough review.
+
+3. Apply the challenge set appropriate to the artifact type:
+
+   **For `intent.md`:**
+   - Is the goal measurable? Can you unambiguously declare it achieved?
+   - Are the success criteria specific enough, or can you hit them without delivering real value?
+   - Who is missing from the stakeholder list? (security team? operations? legal? downstream systems? support?)
+   - What happens if this is never built? Is the status quo actually acceptable, or is the cost of inaction undersold?
+   - Is this one intent or multiple intents in a trenchcoat? (Signs: "and" in the goal, >4 success criteria, multiple unrelated stakeholder groups)
+   - What is the smallest version of this that would deliver value? Is the current scope justified?
+   - Do any success criteria contradict each other, or compete for the same finite resource (time, budget, attention)?
+   - Are the constraints real constraints (regulatory, physical, contractual) or assumed constraints that should be challenged?
+
+   **For `usecase.md`:**
+   - Does every step in the main flow have a clear actor and a clear outcome?
+   - What happens when step N fails? Map every failure mode — missing network, invalid state, concurrent users, timeout.
+   - What are the performance expectations? Is 100ms acceptable? 10 seconds? Does it matter? (Unstated = undefined = will cause conflict later.)
+   - How does this behave under load? Concurrent executions? Race conditions on shared state?
+   - What data does this touch, and what happens if that data is malformed, missing, or stale?
+   - Is this one UseCase or two? (Signs: "or" in the main flow, alternate flow that rewrites most of the main flow, two distinct actors)
+   - What happens at the boundaries — first use ever, N+1th use, quota exhaustion, rollback after failure?
+   - Are the postconditions complete? Does something need to be notified? Logged? Cleaned up?
+   - Do the error conditions cover all failure modes discovered above, with specific system responses?
+
+   **For `impl.md`:**
+   - Is each design decision justified by the usecase requirements, or is it "we always do it this way"?
+   - What are the failure modes of the chosen approach? Under what conditions does it break?
+   - Are the tests verifying observable behaviour from the actor's perspective, or are they testing implementation details?
+   - What is NOT covered by the listed tests that should be? (Error paths, concurrent access, edge inputs, integration with external systems)
+   - Will this implementation survive the next likely change to the behaviour spec? (e.g., if a new actor is added, or a new postcondition)
+   - Are the source files listed complete? Could the behaviour actually be satisfied by these files, or are there missing dependencies?
+   - Do the commits listed account for all the code in the source files? Are there uncommitted changes?
+
+4. Categorize every finding:
+   - **Blocker** — must be resolved before proceeding (spec is incomplete or contradictory in a way that will cause implementation failures)
+   - **Concern** — should be addressed soon (spec has a gap or assumption that will likely cause problems)
+   - **Suggestion** — worth considering (improvement that reduces risk or improves clarity, but not urgent)
+
+5. Present findings in priority order (blockers first), using concrete examples from the artifact text. For each finding, quote the specific line or section being challenged.
+
+6. Present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-refine <path>` — apply the findings to the spec
+   [B] `/tr-implement <path>/` — spec is clean; proceed to implementation
+
+## Output
+
+A structured critique report with findings grouped as **Blockers**, **Concerns**, and **Suggestions**. Each finding quotes the relevant artifact text and explains the risk.
+
+The artifact is NOT modified.
+
+## CLI Dependencies
+
+None during review. The user then decides whether to run:
+- `taproot validate-format` (to check current state)
+- `/taproot:refine` (to apply suggested changes)
+- `/taproot:intent` (to revise the intent)
+
+## Notes
+
+- Do not soften the critique. The purpose is to find real problems before implementation, not to validate the work. A review that finds nothing is not a success — it means you weren't looking hard enough.
+- If the artifact is clearly a placeholder or stub (lots of `<placeholder>` text), flag this explicitly rather than reviewing the placeholders themselves.

package/skills/status.md

@@ -0,0 +1,103 @@
+# Skill: status
+
+## Description
+
+Generate a health dashboard for the requirement hierarchy. Combines `taproot coverage`, `taproot check-orphans`, and `taproot sync-check` into a synthesized narrative summary with actionable next steps.
+
+## Inputs
+
+- `path` (optional): Path to scope the report to a subtree. Defaults to `taproot/`.
+
+## Steps
+
+1. Run `taproot coverage --path <path> --format json` and parse the output. Key fields: `totals.behaviours`, `totals.implementations`, `totals.completeImpls`, `totals.testedImpls`, `totals.deferredBehaviours`, `totals.deferredImpls`. Use `deferredBehaviours` and `deferredImpls` to populate the **Parked** section; omit the section entirely if both are zero.
+
+2. Run `taproot check-orphans --path <path> --include-unimplemented` and collect violations.
+
+3. Run `taproot sync-check --path <path>` and collect warnings.
+
+4. Run `taproot validate-structure --path <path>` and `taproot validate-format --path <path>`. Any errors here are top-priority — flag them before the narrative.
+
+5. Synthesize into a structured report:
+
+```
+# Taproot Status Report
+Generated: <date>
+
+## Validation
+✓ Structure valid  |  ✗ 2 format errors (fix these first)
+
+## Coverage
+<N> intents · <N> behaviours · <N> implementations
+█████████░░░ <N>/<N> implementations complete
+█████████░░░ <N>/<N> implementations with tests
+
+## What's Working
+- Intent "<name>": all <N> behaviours implemented and tested ✓
+- Behaviour "<name>": <N>/<N> implementations complete ✓
+
+## What Needs Attention
+- <N> behaviours specified but not implemented:
+    · taproot/<intent>/<behaviour>/ [proposed since <date>]
+- <N> implementations missing tests:
+    · taproot/<path>/impl.md ⚠
+- <N> potentially stale specs (code changed after spec):
+    · taproot/<path>/impl.md — source file modified <N> days ago
+
+## Parked
+- <N> behaviours deferred: (omit section entirely if 0)
+    · taproot/<intent>/<behaviour>/ — <reason if provided>
+- <N> implementations deferred:
+    · taproot/<path>/impl.md — <reason if provided>
+
+## Structural Issues
+- <from check-orphans>
+
+## Suggested Next Actions
+1. Fix format errors: `taproot validate-format --fix`
+2. Implement next behaviour: `/taproot:implement taproot/<path>/`
+3. Add tests to: `/taproot:refine taproot/<path>/`
+4. Review stale spec: `/taproot:refine taproot/<path>/`
+```
+
+6. Prioritize suggestions by severity:
+   - Validation errors first (broken structure/format)
+   - Orphaned or broken references second
+   - Unimplemented behaviours third (sorted by how long they've been in `proposed` state)
+   - Missing tests fourth
+   - Stale specs fifth
+
+7. If no issues are found: "Everything looks healthy. <N> intents, <N> behaviours, <N> implementations — all valid, complete, and tested."
+
+   Present next steps based on what was found:
+
+   - **If specific priority items were found** (unimplemented behaviours, missing tests, validation errors): surface the top 1–2 as direct lettered options with the exact command and path pre-filled. Add one generic fallback option last. Example:
+
+     **What's next?**
+     [A] `/tr-implement taproot/<intent>/<behaviour>/` — implement unimplemented behaviour
+     [B] `/tr-refine taproot/<intent>/<behaviour>/` — add missing tests
+     [C] `/tr-plan` — pick a different next item
+
+   - **If no specific items were found** (healthy project): show the generic fallback menu:
+
+     **What's next?**
+     [A] `/tr-plan` — pick the next behaviour to implement
+     [B] `/tr-ineed` — capture a new requirement
+     [C] `/tr-review-all` — deeper semantic review of specs
+
+## Output
+
+A narrative health summary with metrics, issue categorization, and prioritized action list.
+
+## CLI Dependencies
+
+- `taproot coverage`
+- `taproot check-orphans`
+- `taproot sync-check`
+- `taproot validate-structure`
+- `taproot validate-format`
+
+## Notes
+
+- This skill is read-only. It reports, it does not modify.
+- For deep semantic issues (unclear specs, over-scoped intents), this skill will not catch them — suggest `/taproot:review-all` for that.

package/skills/sweep.md

@@ -0,0 +1,89 @@
+# Skill: sweep
+
+## Description
+
+Apply a uniform task to a filtered set of hierarchy files — enumerate matching items, confirm with the developer, then process each file in-session with live progress marking.
+
+## Inputs
+
+- `task` (required): Natural language description of the task to apply to each item (e.g. "add a Notes section to every usecase").
+- `scope` (optional): Subtree to limit enumeration to (defaults to `taproot/`).
+- `type` (optional): File type filter — `usecase`, `intent`, or `impl` (defaults to all three).
+
+## Steps
+
+1. Read the task description and determine the target file type(s):
+   - If the developer mentions "all usecases" / "every usecase" → filter to `usecase.md` files
+   - If the developer mentions "all intents" / "every intent" → filter to `intent.md` files
+   - If the developer mentions "all impls" / "every implementation" → filter to `impl.md` files
+   - If ambiguous, ask: "Should I apply this to usecases, intents, implementations, or all three?"
+
+   Also check if the task requires **cross-item context** (e.g. "renumber all AC IDs globally" — needs awareness of IDs across files). If yes, warn:
+   > "This task needs cross-item context — consider `/tr-review-all` instead."
+   > And stop.
+
+2. Enumerate matching files under the scope path (default: `taproot/`). Walk the hierarchy and collect all files matching the target type(s). Exclude any files that are clearly not candidates (e.g. OVERVIEW.md, impl.md files in `proposed` state for an intent-only sweep).
+
+   If no files are found:
+   > "No `<type>` items found under `<scope>`."
+   > Stop.
+
+3. Present the list and ask for confirmation:
+   > "Found **N** `<type>` files under `<scope>`:"
+   > ```
+   > taproot/intent-a/behaviour-b/usecase.md
+   > taproot/intent-a/behaviour-c/usecase.md
+   > ...
+   > ```
+   > "Apply '`<task>`' to each of these **N** files? **[Y] Yes** / **[N] No**"
+
+   If the developer says **[N]** or "no" or "cancel":
+   > "Cancelled."
+   > Stop.
+
+4. For each file in the confirmed list, process it in-session:
+   a. Read the file to understand its current content
+   b. Apply the task directly — edit the file in place
+   c. Output progress immediately after completing each file:
+      ```
+      [x] taproot/intent-a/behaviour-b/usecase.md
+      ```
+
+   **For tasks requiring codebase exploration** (e.g. "add ACs from existing tests", "fill in missing fields from source code"), before processing each file:
+   - Identify **where to look**: explicit directory paths relevant to the file (e.g. `test/integration/`, `src/commands/`)
+   - Find the **matching artefact**: use the usecase slug (second-to-last path segment) to locate a related test file, source file, or doc (e.g. slug `validate-format` → `test/integration/validate-format.test.ts`)
+   - If no match is found for a file, mark it skipped and move on:
+     ```
+     [ ] taproot/intent-a/behaviour-c/usecase.md — no matching test file found
+     ```
+
+   If the task description is vague, ask one clarifying question before processing the first file: "What specifically should change — is there a pattern to add, a section to fill, or a format to fix?"
+
+5. After all files are processed, show a summary:
+   > "Sweep complete — N files processed: M modified, K skipped"
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+6. Present next steps:
+
+   **What's next?**
+   [A] `/tr-sweep` again — run another sweep with a different task or scope
+   [B] `/tr-status` — see the full project health after these changes
+
+## Output
+
+- In-session edits to each matched file
+- Live `[x]` progress line per file
+- Summary: N processed, M modified, K skipped
+
+## CLI Dependencies
+
+None — all processing is done in-session by the agent.
+
+## Notes
+
+- The developer confirmation at step 3 is non-negotiable — no files are processed before confirmation.
+- Each file is processed independently — the agent reads and edits it directly in context. No temp files or subprocesses.
+- For codebase-exploration tasks: use the usecase slug (second-to-last path segment) to find related artefacts. Always verify the match exists before assuming it applies.
+- If the task description is vague ("improve them"), ask one clarifying question before proceeding: "What specifically should change — is there a pattern to add, a section to fill, or a format to fix?"
+- `/tr-sweep` is the Claude Code adapter command name for this skill.