@imix-js/taproot 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imix-js/taproot",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "AI-driven specs, enforced at commit time. Code without traceability doesn't merge.",
   "type": "module",
   "bin": {

package/skills/backlog.md

@@ -33,12 +33,16 @@ Capture ideas, findings, and deferred work mid-session with a single command —
    ```
    Non-standard lines (not matching `- [YYYY-MM-DD] <text>`) are silently skipped in the display but preserved in the file.
 
-3. Offer: `D <n>` discard · `P <n>` promote · `A <n>` analyze · `done` finish
+3. Offer: `D <n>` discard · `P <n>` promote to /tr-ineed · `A <n>` analyze · `done` finish
 
 4. Accept commands one at a time:
    - **`D <n>`** — remove item n from `.taproot/backlog.md`. Confirm: *"✓ Discarded #n"*. Redisplay the updated numbered list.
-   - **`P <n>`** — remove item n from `.taproot/backlog.md`. Invoke `/tr-ineed` with the item text. On return, redisplay the updated numbered list.
-   - **`A <n>`** — display the full text of item n and ask: *"[P] Promote · [K] Keep · [D] Discard"*. After the choice, redisplay the updated numbered list.
+   - **`P <n>` promote to /tr-ineed** — remove item n from `.taproot/backlog.md`. Invoke `/tr-ineed` with the item text. On return, redisplay the updated numbered list.
+   - **`A <n>` analyze** — produce a structured analysis of the item:
+     - A short description of what the item is or could be (2–4 sentences)
+     - A complexity signal: **simple** / **moderate** / **significant**
+     - An impact assessment: **minor addition** / **meaningful improvement** / **major capability**
+     Then ask: *"[P] Promote to /tr-ineed · [K] Keep · [D] Discard"*. After the choice, redisplay the updated numbered list.
    - **`done`** — end triage. Items not acted on are kept implicitly.
 
 5. After `done`: *"Triage complete — X discarded, Y promoted, Z kept."*

package/skills/behaviour.md

@@ -27,7 +27,13 @@ Define a UseCase (observable system behaviour) under an intent or another behavi
    > **[B] Continue writing the spec** — the spec is distinct from the pattern
 
    - **[A]**: guide the user through applying the pattern. Do not write a new `usecase.md`.
-   - **[B]** or no match: proceed to step 2.
+   - **[B]** or no match: proceed to step 1b.
+
+1b. **Load applicable truths.** If `taproot/global-truths/` exists, collect truth files applicable at behaviour level:
+   - Include files with `_intent` or `_behaviour` suffix, in an `intent/` or `behaviour/` sub-folder, or with no scope signal (treat as intent-scoped; note inline: "Applied `global-truths/<file>` as intent-scoped (no explicit scope signal)")
+   - Do not include files scoped to `_impl` / `impl/` only
+   - Read each applicable file; note defined terms, business rules, and conventions
+   - If the draft spec contradicts an applicable truth, surface the conflict before saving: "This spec uses `<term>` in a way that conflicts with `global-truths/<file>`: `<excerpt>`. [A] update spec to align, [B] update the truth, [C] proceed with the conflict noted."
 
 2. Read all sibling `usecase.md` files (other behaviours already under the same parent). Identify any overlap with the described behaviour and flag it: "There's an existing behaviour `<slug>` that covers X — should this new behaviour focus on Y specifically?"
 

package/skills/bug.md

@@ -31,6 +31,19 @@ Diagnose a defect through structured root cause analysis (5-Why) and delegate to
    - **External cause** — dependency, environment, or configuration outside the hierarchy
    - If categories overlap, use this priority: **Spec gap > Implementation gap > Missing test**
 
+4a. **Recurrence check.** Ask: *"Could this class of bug happen again — is there a missing gate or outdated guideline that would prevent it?"*
+
+   - **No (clearly one-off** — typo, isolated misconfiguration, external incident): note this and continue to step 5.
+   - **Yes**: propose prevention across one or more of:
+     - A new DoR or DoD condition to add to `.taproot/settings.yaml`
+     - An update to `docs/architecture.md`, `docs/security.md`, or `docs/patterns.md`
+
+   If a satisfactory measure is found: present it — e.g. *"I'll add `check-if-affected-by: <gate>` to `.taproot/settings.yaml`"* or *"I'll add to `docs/security.md`: `<constraint>`"* — and wait for actor confirmation.
+   - On **confirm**: apply the change, then continue to step 5.
+   - On **reject**: record the recurrence concern in the implicated impl.md `## Notes` and continue to step 5.
+
+   If no satisfactory measure can be identified: invoke `/tr-grill-me` seeded with *"How do we prevent `<root-cause>` from recurring?"* — incorporate the answer and apply it before continuing to step 5.
+
 5. **Locate the implicated artifact.** Use reverse lookup:
    - Scan all `impl.md` files in `taproot/` for `## Source Files` entries matching the files involved in the root cause
    - If a match is found: that impl.md is implicated

package/skills/commit.md

@@ -1,5 +1,14 @@
 # Skill: commit
 
+## Autonomous mode
+
+Before following any steps, check whether autonomous mode is active:
+- `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
+- `--autonomous` was passed as an argument to this skill invocation, **or**
+- `.taproot/settings.yaml` contains `autonomous: true`
+
+If any of these is true, **autonomous mode is active** — apply autonomous notes where they appear. If none is true, show confirmation prompts as normal.
+
 ## Description
 
 Execute the full commit procedure: classify the commit type, run the appropriate gate proactively, resolve all conditions before staging, and commit. Handles implementation, declaration, requirement, and plain commits. Invoke this skill whenever you are about to commit, or when the user says "commit", "let's commit", "commit that", or similar.
@@ -20,7 +29,11 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
    To identify impl.md ownership, run `grep -rl "<filename>" taproot/` for each candidate source file.
 
-3. If nothing is staged yet, announce: "Nothing staged yet. Here's what's changed: [list]. Should I stage these and proceed with the commit?" Wait for confirmation before proceeding.
+3. If nothing is staged yet, announce: "Nothing staged yet. Here's what's changed: [list]."
+
+   **Interactive mode:** ask "Should I stage these and proceed with the commit?" and wait for confirmation before proceeding.
+
+   **Autonomous mode:** stage all relevant files and proceed directly without waiting for confirmation.
 
 4. Read `.taproot/settings.yaml` to identify all configured `definitionOfDone` and `definitionOfReady` conditions. If the file does not exist or has no `definitionOfDone`/`definitionOfReady` sections, note: "No user-configured conditions — baseline hook checks only." and proceed to the appropriate sub-flow below.
 
@@ -77,7 +90,19 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
 4. Fix any violations before staging — the hook enforces these checks and will block the commit if they fail.
 
-5. Stage the hierarchy files and commit.
+5. **Truth consistency check** — if `taproot/global-truths/` exists:
+   a. For each staged hierarchy document, determine its level (intent, behaviour, impl) and collect applicable truth files using scope rules (intent-scoped truths apply to all levels; behaviour-scoped to behaviour+impl; impl-scoped to impl only; unscoped defaults to intent-scoped).
+   b. Read each applicable truth file. If a file is unreadable, note it and skip.
+   c. Check each staged document for semantic consistency with applicable truths:
+      - Are defined terms used consistently with their definitions?
+      - Are stated business rules respected in acceptance criteria and main flow?
+      - Are project conventions followed?
+   d. If a conflict is found, surface it before proceeding:
+      > "Truth conflict in `<file>`: `<excerpt>` conflicts with `<truth file>`: `<truth excerpt>`. [A] Fix the spec | [B] Update the truth | [C] Proceed with conflict noted"
+      Wait for the developer's choice. Do not proceed to step 6 until resolved.
+   e. If no conflicts (or all resolved): run `taproot truth-sign` to record the session marker the hook validates.
+
+6. Stage the hierarchy files and commit.
 
 ### Plain commit
 

package/skills/define-truth.md

@@ -0,0 +1,96 @@
+# Skill: define-truth
+
+## Description
+
+Create or update a truth entry in `taproot/global-truths/` — a fact, business rule, glossary term, or convention that applies across the project. Accepts a pre-populated candidate from `/tr-discover-truths` or runs interactively.
+
+## Inputs
+
+- `candidate` (optional): Pre-populated context from `/tr-discover-truths` or `/tr-ineed` — includes term/rule, proposed scope, and evidence. If omitted, the skill asks interactively.
+
+## Steps
+
+### Phase 1 — Establish Content
+
+1. If `candidate` was provided, display it:
+   ```
+   Candidate: `<term or rule>`
+   Proposed scope: <intent | behaviour | impl>
+   Evidence: <spec paths where this appeared>
+   ```
+   Ask: "Does this look right, or would you like to adjust the content or scope before I write the file?"
+
+   If no `candidate`, ask:
+   > "What truth do you want to capture? Describe the term, rule, or convention — and any context that would help scope it."
+
+   Wait for the developer's description before continuing.
+
+2. Confirm the truth content — the actual text to write into the file. Ask if not already clear:
+   > "How would you like to phrase this truth? (Free-form markdown — prose, table, bullet list, or heading are all valid.)"
+
+### Phase 2 — Determine Scope
+
+3. If scope is not already confirmed, ask:
+   > "What scope should this truth have?
+   > - **intent** — applies to intent, behaviour, and implementation levels (broadest)
+   > - **behaviour** — applies to behaviour and implementation levels
+   > - **impl** — applies to implementation level only (narrowest)"
+
+   Wait for the developer's choice.
+
+### Phase 3 — Choose Convention
+
+4. Ask which storage convention to use:
+   > "Which convention do you prefer?
+   > - **[S] Suffix** — `<name>_<scope>.md` in `taproot/global-truths/` (e.g. `glossary_intent.md`)
+   > - **[F] Sub-folder** — `<scope>/<name>.md` in `taproot/global-truths/` (e.g. `intent/glossary.md`)
+   >
+   > Both are valid. Use suffix if you have few truths; sub-folder if you expect many."
+
+   If the project already has truth files using one convention, note it:
+   > "Your project currently uses the <suffix|sub-folder> convention — using it here keeps things consistent."
+
+### Phase 4 — Write the File
+
+5. Determine the file path:
+   - **Suffix**: `taproot/global-truths/<name>_<scope>.md`
+   - **Sub-folder**: `taproot/global-truths/<scope>/<name>.md`
+
+   Create `taproot/global-truths/` if it does not exist.
+
+6. If the file already exists, read it and present:
+   > "A truth file already exists at `<path>`. Here's the current content: [excerpt]. Do you want to [A] append to it, [B] replace it, or [C] cancel?"
+   Wait for the developer's choice.
+
+7. Write the truth file with the confirmed content. Report:
+   > "✓ Written: `<path>` (scope: <scope>)"
+
+8. **Scope ambiguity check** — if the file was placed directly in `taproot/global-truths/` with no `_<scope>` suffix and not inside a scoped sub-folder, warn:
+   > "`<filename>` has no scope signal — it defaults to intent scope (applies everywhere). Add a `_intent`, `_behaviour`, or `_impl` suffix, or move it to a scoped sub-folder, to make the scope explicit."
+
+9. **Conflicting scope signals check** — if the file has both a suffix and is inside a scoped sub-folder that disagree, warn:
+   > "`<path>` has conflicting scope signals — sub-folder (`<folder-scope>`) is more restrictive than suffix (`<suffix-scope>`). The restrictive scope (`<folder-scope>`) applies. Rename or move the file to resolve."
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+**What's next?**
+[A] `/tr-discover-truths` — scan the hierarchy for more truth candidates
+[B] `/tr-commit` — commit the new truth file
+[C] Define another truth — run `/tr-define-truth` again
+
+## Output
+
+- A truth file written to `taproot/global-truths/<name>_<scope>.md` or `taproot/global-truths/<scope>/<name>.md`
+- Any scope ambiguity or conflict warnings surfaced inline
+
+## CLI Dependencies
+
+None.
+
+## Notes
+
+- Truth content is free-form — no schema is enforced. The developer chooses prose, tables, bullet lists, or headings.
+- Both conventions (suffix and sub-folder) may coexist in the same project. Neither is preferred.
+- Scope resolution precedence: sub-folder takes precedence over suffix when they conflict (most restrictive wins).
+- This skill is the target of `/tr-ineed` routing when a requirement is classified as a project-wide truth.
+- When invoked from `/tr-discover-truths`, the `candidate` argument pre-populates steps 1–3, making the interaction faster.

package/skills/discover-truths.md

@@ -0,0 +1,129 @@
+# Skill: discover-truths
+
+## Description
+
+Scan the taproot hierarchy for implicit facts — recurring terms, business rules, and conventions — that are not yet captured as global truths. Present candidates to the developer for promotion, backlogging, or dismissal. Invoke standalone or as a final pass within `/tr-review-all`.
+
+## Inputs
+
+- None required. Operates on the current `taproot/` directory.
+
+## Autonomous mode
+
+Before following any steps, check whether autonomous mode is active:
+- `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
+- `--autonomous` was passed as an argument to this skill invocation, **or**
+- `.taproot/settings.yaml` contains `autonomous: true`
+
+If any of these is true, **autonomous mode is active** — skip interactive prompts and defer all candidates to `.taproot/backlog.md` as "truth candidate: `<term>`" entries, then report the summary.
+
+## Steps
+
+### Phase 1 — Pre-flight
+
+1. Verify `taproot/global-truths/` exists. If not, stop:
+   > "taproot/global-truths/ does not exist. Run `taproot init` or create it manually."
+
+2. Collect all `intent.md` and `usecase.md` files under `taproot/`, excluding `taproot/global-truths/` and any unreadable files (warn per skipped path). If the count of readable files is fewer than 3, stop:
+   > "Too few specs to surface patterns reliably (found N). Run discovery again after adding more specs."
+
+### Phase 2 — Load Existing Truths and Dismissed Entries
+
+3. Read all files in `taproot/global-truths/` (excluding `intent.md` and subdirectory `usecase.md` files — truth files are files that are NOT named `intent.md` or `usecase.md`). Collect defined terms and rules from them.
+
+4. Read `.taproot/backlog.md` if it exists. Extract all lines matching `reviewed — not a truth: <term>` — these are permanently dismissed candidates. Build a suppression list from them.
+
+### Phase 3 — Identify Candidates
+
+5. Read all collected hierarchy files and scan for three candidate categories:
+
+   **Recurring terms** — domain-specific nouns (not generic words like "user", "system", "file") that appear in 2 or more specs but have no canonical definition in `taproot/global-truths/`.
+
+   **Business rules** — constraints or invariants stated in acceptance criteria or main flows (phrases like "must", "must not", "always", "never", "only if", "requires") that appear across 2 or more specs.
+
+   **Implicit conventions** — patterns using "always", "never", "must not", "we use", "we don't" that recur across specs without being formally declared.
+
+   For each candidate, determine proposed scope using these heuristics:
+   - Appears in any `intent.md` → scope: `intent`
+   - Appears only in `usecase.md` files → scope: `behaviour`
+   - Appears only in implementation-adjacent contexts → scope: `impl`
+   - Mixed → default to `intent`
+
+6. Filter out:
+   - Candidates already defined in `taproot/global-truths/`
+   - Candidates matching any entry in the suppression list from step 4
+
+   If no candidates remain after filtering, report:
+   > "No new truth candidates found — the hierarchy appears consistent with existing global truths."
+   Then go to Phase 5.
+
+### Phase 4 — Present Candidates
+
+7. Group remaining candidates by category. If more than 10 total, present in batches of 5. After each batch, ask: "[C] Continue to next batch  [D] Done — stop here".
+
+   For each candidate, present:
+   ```
+   Candidate: `<term or rule>`
+   Category: <recurring term | business rule | implicit convention>
+   Proposed scope: <intent | behaviour | impl>
+   Heuristic: <why this scope was proposed>
+   Evidence:
+   - `<spec path>`: "<excerpt showing the term/rule>"
+   - `<spec path>`: "<excerpt showing the term/rule>"
+
+   [P] Promote → /tr-ineed   [S] Skip   [B] Backlog   [D] Dismiss
+   ```
+
+   **Autonomous mode:** defer all candidates to backlog as "truth candidate: `<term>`" and skip to Phase 5.
+
+8. Handle each developer choice:
+
+   **Promote [P]:**
+   - Invoke `/tr-ineed` with the candidate term, proposed scope, and evidence pre-populated as context
+   - If `/tr-ineed` routes to a location other than `define-truth`, surface the routing decision:
+     > "This candidate was routed to `<location>`. [A] Accept routing  [B] Override — invoke define-truth directly"
+   - If the developer abandons `/tr-ineed` mid-flow: treat the candidate as skipped for this session (no truth file created; candidate reappears on next run)
+   - After `/tr-ineed` completes (or is abandoned), return to the candidate list
+
+   **Skip [S]:**
+   - No record written; candidate reappears on next discovery run
+
+   **Backlog [B]:**
+   - Append to `.taproot/backlog.md`: `- [YYYY-MM-DD] truth candidate: <term>`
+   - Move to next candidate
+
+   **Dismiss [D]:**
+   - Append to `.taproot/backlog.md`: `- [YYYY-MM-DD] reviewed — not a truth: <term>`
+   - This entry suppresses the candidate on all future discovery runs
+   - Move to next candidate
+
+### Phase 5 — Wrap Up
+
+9. Report:
+   > "Discovery complete — N promoted, N skipped, N backlogged, N dismissed[, N remaining]."
+   > (Include "N remaining" only if the developer ended the session early.)
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-ineed <candidate>` — promote a kept candidate now
+   [B] `/tr-status` — see current project health
+   [C] `/tr-review-all` — run a full review (includes another truth discovery pass)
+
+## Output
+
+- Zero or more truth files created in `taproot/global-truths/` (via `/tr-ineed` → define-truth)
+- `.taproot/backlog.md` updated with any backlogged or dismissed candidates
+- Summary report: N promoted, N skipped, N backlogged, N dismissed
+
+## CLI Dependencies
+
+None.
+
+## Notes
+
+- Truth files in `taproot/global-truths/` are any files that are NOT named `intent.md` or `usecase.md`. They may have any name (e.g. `glossary.md`, `pricing-rules.md`, `entity-model.md`).
+- "Recurring" means 2 or more specs — not just repeated within a single spec.
+- Skip generic language-level words ("the", "a", "is", "not") and taproot structural terms ("intent", "behaviour", "usecase", "implementation") — these are not domain truths.
+- Dismissed entries in `.taproot/backlog.md` are matched by the literal string "reviewed — not a truth: `<term>`" — the suppression logic is substring-match on the candidate term.
+- This skill is read-only on the hierarchy — it never modifies `intent.md` or `usecase.md` files directly.

package/skills/grill-me.md

@@ -46,6 +46,7 @@ Based on Matt Pocock's `grill-me` skill (MIT licensed, https://github.com/mattpo
    **What's next?**
    [A] `/tr-ineed "<clarified requirement>"` — route the sharpened requirement into the hierarchy
    [B] `/tr-behaviour <path>/` — write the spec now that the design is clear
+   [C] `/tr-backlog <deferred question>` — capture an unresolved question for later without routing it now
 
 ## Output
 

package/skills/guide.md

@@ -56,6 +56,8 @@ ineed → intent → behaviour → implement → trace → status
 | `/tr-status` | Generate a health dashboard for the hierarchy |
 | `/tr-review` | Stress-test a spec with adversarial questions |
 | `/tr-review-all` | Run review across an entire subtree |
+| `/tr-discover-truths` | Scan the hierarchy for implicit facts and promote them to global truths |
+| `/tr-define-truth` | Create or update a truth entry in `taproot/global-truths/` |
 | `/tr-browse` | Read a hierarchy document section by section in the terminal — with inline editing via `[M] Modify` |
 | `/tr-backlog` | Capture an idea or finding instantly mid-session; called with no args opens triage to discard, keep, or promote items |
 | `/tr-grill-me` | Interview the user relentlessly to sharpen a plan or design |
@@ -105,6 +107,7 @@ ineed → intent → behaviour → implement → trace → status
    **What's next?**
    [A] `/tr-ineed` — capture your first (or next) requirement
    [B] `/tr-status` — see the current project health at a glance
+   [C] `/tr-backlog` — triage captured ideas (only if `.taproot/backlog.md` is non-empty)
 
 ## Output
 

package/skills/implement.md

@@ -9,6 +9,15 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
 - `path` (required): Path to the behaviour folder containing `usecase.md` to implement.
 - `name` (optional): Slug for the implementation folder (e.g., `rest-api`, `background-job`). If omitted, derive from the implementation approach chosen.
 
+## Autonomous mode
+
+Before following any steps, check whether autonomous mode is active:
+- `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
+- `--autonomous` was passed as an argument to this skill invocation, **or**
+- `.taproot/settings.yaml` contains `autonomous: true`
+
+If any of these is true, **autonomous mode is active** — apply the autonomous notes at each step where they appear. If none is true, autonomous mode is **inactive** — show confirmation prompts as normal.
+
 ## Steps
 
 1. Read `<path>/usecase.md` thoroughly. Understand:
@@ -22,6 +31,11 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
 
 3. Walk up the hierarchy: read the parent `intent.md` to understand the broader goal. This context should inform design decisions (e.g., if the intent has a constraint about performance, that should influence implementation choices).
 
+3a. **Load applicable truths.** If `taproot/global-truths/` exists, collect truth files applicable at impl level:
+   - Include files with `_intent`, `_behaviour`, or `_impl` suffix, in an `intent/`, `behaviour/`, or `impl/` sub-folder, or with no scope signal (treat as intent-scoped; note inline: "Applied `global-truths/<file>` as intent-scoped (no explicit scope signal)")
+   - Read each applicable file; apply defined terms and conventions when choosing the implementation approach, naming, and design decisions
+   - If the implementation plan contradicts an applicable truth, surface the conflict before proceeding: "This implementation contradicts `global-truths/<file>`: `<excerpt>`. [A] update plan to align, [B] update the truth, [C] proceed with the conflict noted."
+
 4. **Pattern check + plan mode.** Before proposing the plan: if `.taproot/docs/patterns.md` exists, scan the behaviour description and any design notes for semantic matches. Match signals:
    - "applies to all implementations / cross-cutting concern" → `check-if-affected-by`
    - "enforce a rule on all future work" → `check-if-affected-by`
@@ -38,7 +52,9 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
    - Any design decisions that need to be made (with options and recommendation)
    - The implementation folder slug and path
 
-   Present the plan. Do not proceed to writing code until the user approves.
+   **Autonomous mode:** form the plan internally, record it in the `impl.md` Design Decisions section, and proceed directly to step 5 without pausing for approval.
+
+   **Interactive mode:** present the plan. Do not proceed to writing code until the user approves.
 
 5. Create the implementation folder `<path>/<impl-slug>/` and write `impl.md`:
    - **Behaviour**: relative path to `../usecase.md`
@@ -99,8 +115,15 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
    b. Write the tests — each test should be traceable to a specific UseCase step, postcondition, error condition, or alternate flow trigger. Name tests descriptively.
    c. Verify the tests pass
 
+   **Autonomous mode — if tests fail:** record the full test output in `impl.md` under a `## Notes` entry headed `Autonomous execution — test failure`, set `**State:** needs-rework`, and stop. Do not attempt to fix tests autonomously without context from the developer.
+
 8. Run `taproot dod <impl-path>` to evaluate the Definition of Done. For agent-driven conditions (`check-if-affected`, `document-current`): reason about each, apply any needed changes, then record your resolution with `taproot dod <impl-path> --resolve "<condition>" --note "<reasoning>"`. Re-run until all conditions pass. `taproot dod` marks `impl.md` state `complete` when all pass.
 
+   **Autonomous mode — DoD self-resolution:**
+   - For every `check-if-affected-by`, `check-if-affected`, `check:`, and `document-current` condition: reason through it by reading the spec and source, then record the resolution with `--resolve` and `--note` without prompting.
+   - For any `check:` condition where the answer cannot be determined from the code and spec alone: write a `<!-- autonomous: pending-review -->` comment in `## DoD Resolutions` alongside the unresolved condition entry, with the question text. Continue evaluating remaining conditions. After all conditions are processed, if any remain marked pending-review, set `**State:** in-progress` and commit — the developer will complete them on return.
+   - For `run:` conditions that exit non-zero: record the output in `impl.md`, mark `needs-rework`, and stop.
+
 9. **Implementation commit** — commit source files and `impl.md` together:
 
    Before staging:

package/skills/intent.md

@@ -20,6 +20,11 @@ Create a new business intent or refine an existing one. An intent captures the "
 
 2. Search existing intents under `taproot/` for overlap. Read each `intent.md` found. If a closely related intent exists, show it to the user and ask: "This looks related to existing intent at `<path>`. Should I refine that one, or create a separate intent for a genuinely different goal?"
 
+2a. **Load applicable truths.** If `taproot/global-truths/` exists, collect truth files applicable at intent level:
+   - Include files with `_intent` suffix, in an `intent/` sub-folder, or with no scope signal (treat as intent-scoped; note inline: "Applied `global-truths/<file>` as intent-scoped (no explicit scope signal)")
+   - Read each applicable file; note any defined terms, business rules, or conventions
+   - If the draft contradicts an applicable truth, surface the conflict before writing: "This draft uses `<term>` in a way that conflicts with `global-truths/<file>`: `<excerpt>`. [A] update spec to align, [B] update the truth, [C] proceed with the conflict noted."
+
 3. Draft the `intent.md` content:
    - Title: noun phrase capturing the desired outcome (e.g., "Password Reset Without Support", not "Password Reset Feature")
    - Stakeholders: at minimum the direct user/actor and the business/product owner; consider: ops, security, compliance, support, third-party integrators

package/skills/refine.md

@@ -35,6 +35,11 @@ Update a behaviour spec (`usecase.md`) based on what was learned during or after
    - **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
 
+2a. **Load applicable truths.** If `taproot/global-truths/` exists, collect truth files applicable at behaviour level:
+   - Include files with `_intent` or `_behaviour` suffix, in an `intent/` or `behaviour/` sub-folder, or with no scope signal (treat as intent-scoped; note inline: "Applied `global-truths/<file>` as intent-scoped (no explicit scope signal)")
+   - Read each applicable file; ensure the refined spec aligns with applicable truths
+   - If a proposed refinement contradicts an applicable truth, surface the conflict before writing: "This refinement uses `<term>` in a way that conflicts with `global-truths/<file>`: `<excerpt>`. [A] update spec to align, [B] update the truth, [C] proceed with the conflict noted."
+
 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`:

package/skills/review-all.md

@@ -66,14 +66,42 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
 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:
+8. **Truth discovery pass** — if `taproot/global-truths/` exists and the hierarchy has 3 or more readable `intent.md`/`usecase.md` files (excluding `global-truths/`):
+
+   Run the same scan as `/tr-discover-truths` (Phase 2–3 of that skill): collect candidates not already defined in `global-truths/` and not suppressed by `.taproot/backlog.md` dismissed entries.
+
+   If candidates are found, append to the report:
+
+   ```
+   ## Truth Candidates
+
+   The following implicit facts were detected in the hierarchy but are not yet captured as global truths:
+
+   - `<term>` (scope: <intent|behaviour|impl>) — found in: <spec-path>, <spec-path>
+   ...
+   ```
+
+   Then offer:
+   > "[P] Process candidates now via `/tr-discover-truths`  [D] Defer — append all to backlog"
+
+   **If [P]:** invoke `/tr-discover-truths` inline; return here when it completes.
+
+   **If [D]:** append each candidate to `.taproot/backlog.md` as `- [YYYY-MM-DD] truth candidate: <term>`.
+
+   If no candidates found (hierarchy consistent with existing truths), append to report:
+   ```
+   ## Truth Candidates
+   No new candidates — hierarchy is consistent with existing global truths.
+   ```
+
+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] `/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
+   [C] `/tr-backlog <finding>` — capture a deferred finding before routing it to the hierarchy
 
 ## Output
 

package/skills/review.md

@@ -60,6 +60,7 @@ Stress-test a single Taproot artifact — an `intent.md`, `usecase.md`, or `impl
    **What's next?**
    [A] `/tr-refine <path>` — apply the findings to the spec
    [B] `/tr-implement <path>/` — spec is clean; proceed to implementation
+   [C] `/tr-backlog <finding>` — capture an out-of-scope issue for later without routing it now
 
 ## Output
 

package/skills/status.md

@@ -78,12 +78,13 @@ Generated: <date>
      [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:
+   - **If no specific items were found** (healthy project): check whether `.taproot/backlog.md` exists and contains items. Show the generic fallback menu:
 
      **What's next?**
      [A] `/tr-plan` — pick the next behaviour to implement
-     [B] `/tr-ineed` — capture a new requirement
+     [B] `/tr-ineed` — route a new requirement into the hierarchy
      [C] `/tr-review-all` — deeper semantic review of specs
+     [D] `/tr-backlog` — triage captured ideas (only if `.taproot/backlog.md` is non-empty)
 
 ## Output