@imix-js/taproot 0.2.1 → 0.4.0

package/dist/core/test-cache.js

@@ -0,0 +1,187 @@
+import { existsSync, readFileSync, writeFileSync, mkdirSync, statSync } from 'fs';
+import { join, resolve, relative, dirname } from 'path';
+import { spawn } from 'child_process';
+import { readResolutions } from './dod-runner.js';
+const DEFAULT_TEST_TIMEOUT_MS = 300_000; // 300 seconds
+const DEFAULT_MAX_AGE_MS = 60 * 60 * 1000; // 60 minutes
+/** Derive the cache path from an impl.md path.
+ *  Strips 'taproot/' prefix and '/impl.md' suffix, maps into .taproot/.test-results/.
+ *  Handles both absolute and relative implPath inputs. */
+export function deriveCachePath(implPath, cwd) {
+    const absImpl = resolve(cwd, implPath);
+    const relImpl = relative(cwd, absImpl).replace(/\\/g, '/');
+    // Strip leading 'taproot/' segment
+    const withoutRoot = relImpl.startsWith('taproot/')
+        ? relImpl.slice('taproot/'.length)
+        : relImpl;
+    // Strip trailing '/impl.md'
+    const key = withoutRoot.endsWith('/impl.md')
+        ? withoutRoot.slice(0, -'/impl.md'.length)
+        : withoutRoot;
+    return join(cwd, '.taproot', '.test-results', `${key}.json`);
+}
+/** Read a cached test result. Returns null if absent or malformed. */
+export function readCache(cachePath) {
+    if (!existsSync(cachePath))
+        return null;
+    try {
+        const raw = readFileSync(cachePath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.exitCode !== 'number' || !parsed.timestamp)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns true if the cached result is malformed JSON (exists but unparseable). */
+export function isCacheCorrupt(cachePath) {
+    if (!existsSync(cachePath))
+        return false;
+    try {
+        JSON.parse(readFileSync(cachePath, 'utf-8'));
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Check whether a cached result is stale.
+ *  Stale if: any tracked source file is newer than the cache timestamp,
+ *  or (if no source files listed) the cache is older than testResultMaxAge. */
+export function isCacheStale(cache, implPath, cwd, testResultMaxAgeMs = DEFAULT_MAX_AGE_MS) {
+    const absImpl = resolve(cwd, implPath);
+    const cacheTs = Date.parse(cache.timestamp);
+    if (isNaN(cacheTs))
+        return true;
+    // Read source files from impl.md
+    const sourceFiles = readSourceFiles(absImpl, cwd);
+    if (sourceFiles.length === 0) {
+        // Fall back to max-age check
+        return Date.now() - cacheTs > testResultMaxAgeMs;
+    }
+    // Stale if any source file is newer than the cache
+    for (const src of sourceFiles) {
+        const absSrc = resolve(cwd, src);
+        if (!existsSync(absSrc))
+            continue;
+        try {
+            const mtime = statSync(absSrc).mtimeMs;
+            if (mtime > cacheTs)
+                return true;
+        }
+        catch {
+            // ignore stat errors
+        }
+    }
+    return false;
+}
+function readSourceFiles(absImplPath, cwd) {
+    try {
+        const content = readFileSync(absImplPath, 'utf-8');
+        const match = content.match(/^## Source Files\s*\n([\s\S]*?)(?=\n## |\n$|$)/m);
+        if (!match)
+            return [];
+        const sources = [];
+        for (const m of match[1].matchAll(/`([^`]+)`/g)) {
+            sources.push(m[1]);
+        }
+        return sources;
+    }
+    catch {
+        return [];
+    }
+}
+/** Write a test result to the cache file, creating parent dirs as needed. */
+export function writeCache(cachePath, result) {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify(result, null, 2), 'utf-8');
+}
+/** Execute testsCommand, streaming output to the terminal while also capturing it.
+ *  Returns the TestResult with the last N lines as summary. */
+export async function executeTestCommand(command, cwd, timeoutMs = DEFAULT_TEST_TIMEOUT_MS) {
+    return new Promise((resolvePromise) => {
+        const timestamp = new Date().toISOString();
+        const lines = [];
+        const child = spawn(command, { shell: true, cwd });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        function handleData(chunk, stream) {
+            const text = chunk.toString();
+            stream.write(text);
+            lines.push(...text.split('\n'));
+        }
+        child.stdout?.on('data', (chunk) => handleData(chunk, process.stdout));
+        child.stderr?.on('data', (chunk) => handleData(chunk, process.stderr));
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const exitCode = timedOut ? -1 : (code ?? 1);
+            const timeoutSecs = Math.round(timeoutMs / 1000);
+            const summaryLines = timedOut
+                ? [`timed out after ${timeoutSecs}s`]
+                : lines.filter(l => l.trim()).slice(-20);
+            resolvePromise({
+                timestamp,
+                command,
+                exitCode,
+                summary: summaryLines.join('\n'),
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            resolvePromise({
+                timestamp,
+                command,
+                exitCode: 127,
+                summary: err.message,
+            });
+        });
+    });
+}
+/** Full evidence-backed tests-passing check.
+ *  Returns { passed, output, correction, warnNoCache } */
+export async function runTestsPassingWithCache(options) {
+    const { implPath, cwd, testsCommand, rerunTests } = options;
+    const testResultMaxAgeMs = options.testResultMaxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const testTimeoutMs = options.testTimeoutMs ?? DEFAULT_TEST_TIMEOUT_MS;
+    const cachePath = deriveCachePath(implPath, cwd);
+    // Warn and re-run if cache is corrupt
+    if (isCacheCorrupt(cachePath)) {
+        process.stderr.write(`Warning: Ignoring malformed cache at ${cachePath} — re-running tests.\n`);
+    }
+    let result = null;
+    if (!rerunTests) {
+        result = readCache(cachePath);
+        if (result && isCacheStale(result, implPath, cwd, testResultMaxAgeMs)) {
+            result = null; // stale — will re-execute
+        }
+    }
+    // Execute if no fresh cache
+    if (!result) {
+        result = await executeTestCommand(testsCommand, cwd, testTimeoutMs);
+        writeCache(cachePath, result);
+    }
+    if (result.exitCode === 0) {
+        return { passed: true, output: '', correction: '' };
+    }
+    if (result.exitCode === -1) {
+        const timeoutSecs = Math.round(testTimeoutMs / 1000);
+        return {
+            passed: false,
+            output: result.summary,
+            correction: `tests-passing blocked: test command timed out after ${timeoutSecs}s. Increase testTimeout in .taproot/settings.yaml if needed.`,
+        };
+    }
+    return {
+        passed: false,
+        output: result.summary,
+        correction: 'tests-passing blocked: Fix failing tests and re-run taproot dod.',
+    };
+}
+// Re-export for use in commithook staleness check
+export { readResolutions };
+//# sourceMappingURL=test-cache.js.map

package/dist/core/test-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-cache.js","sourceRoot":"","sources":["../../src/core/test-cache.ts"],"names":[],"mappings":"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"}

package/dist/validators/types.d.ts

@@ -40,6 +40,8 @@ export type DodConditionEntry = string | {
     'check-if-affected-by': string;
 } | {
     'check': string;
+} | {
+    'require-discussion-log': boolean;
 };
 export interface TaprootConfig {
     version: number;
@@ -65,4 +67,9 @@ export interface TaprootConfig {
     };
     definitionOfDone?: DodConditionEntry[];
     definitionOfReady?: DodConditionEntry[];
+    cli?: string;
+    autonomous?: boolean;
+    testsCommand?: string;
+    testResultMaxAge?: number;
+    testTimeout?: number;
 }

package/docs/agents.md

@@ -8,6 +8,7 @@ Taproot works with any AI assistant that can read files. Run `taproot init --age
 |-------|-------------|---------|---------------------|
 | Claude Code | **Tier 1** — fully supported | `taproot init --agent claude` | `.claude/commands/tr-*.md` — one file per slash command |
 | Gemini CLI | **Tier 2** — implemented & tested | `taproot init --agent gemini` | `.gemini/commands/tr-*.toml` — one file per command |
+| Aider | **Tier 2** — implemented & tested | `taproot init --agent aider` | `.aider.conf.yml` with `read:` entries + `CONVENTIONS.md` |
 | Cursor | **Tier 3** — community supported | `taproot init --agent cursor` | `.cursor/rules/taproot.md` — project-wide rules |
 | GitHub Copilot | **Tier 3** — community supported | `taproot init --agent copilot` | `.github/copilot-instructions.md` |
 | Windsurf | **Tier 3** — community supported | `taproot init --agent windsurf` | `.windsurfrules` |
@@ -69,6 +70,16 @@ This refreshes all adapter files and skill definitions to the current version. R
 
 ---
 
+## Aider
+
+The Aider adapter installs `.aider.conf.yml` with `read:` entries so every Aider session automatically loads all taproot skill definitions and `CONVENTIONS.md` as context. No extra flags needed — run `aider` in the project directory and it picks up taproot context immediately.
+
+Skills are invoked by natural language: *"implement the behaviour at taproot/my-intent/my-feature/"* rather than a slash command.
+
+If `.aider.conf.yml` already exists, `taproot init` merges the `read:` entries without removing your existing settings (model, API key, etc.). If the file contains invalid YAML, the command stops with an error rather than overwriting it.
+
+---
+
 ## Non-Claude agents
 
 For Cursor, Copilot, and Windsurf, the adapter installs a rules or instructions file. These give the agent context on the taproot hierarchy, the document formats, and the commit convention — enough to read and navigate the hierarchy, write conformant documents, and use the CLI commands correctly.

package/docs/cli.md

@@ -9,11 +9,13 @@ The Taproot CLI handles setup, validation, and reporting. It does not generate c
 ### `taproot init`
 
 ```bash
-taproot init [--with-hooks] [--with-ci github|gitlab] [--with-skills] [--agent claude|cursor|copilot|windsurf|generic|all]
+taproot init [--with-hooks] [--with-ci github|gitlab] [--with-skills] [--agent claude|cursor|copilot|windsurf|generic|all] [--template webapp|book-authoring|cli-tool] [--force]
 ```
 
 Initializes Taproot in the current directory. Creates `taproot/` and `.taproot/settings.yaml` if they don't exist, then installs whichever integrations you request.
 
+When run on an empty project (no `taproot/` directory yet), the command prompts: **"Start from a template? [y/N]"** — entering `y` presents a list of starter hierarchies to choose from.
+
 | Option | Effect |
 |--------|--------|
 | `--with-hooks` | Installs `.git/hooks/pre-commit` running `taproot commithook` |
@@ -21,6 +23,8 @@ Initializes Taproot in the current directory. Creates `taproot/` and `.taproot/s
 | `--with-ci gitlab` | Generates a `taproot-validate` job in `.gitlab-ci.yml` |
 | `--with-skills` | Copies skill definitions to `.taproot/skills/`. Implied by `--agent claude` — only needed if you want skills without a Claude adapter. |
 | `--agent <name>` | Generates agent adapter files (see [Agent Setup](agents.md)) |
+| `--template <type>` | Skip the prompt and apply a starter template directly (`webapp`, `book-authoring`, or `cli-tool`). Copies the starter's `taproot/` hierarchy and `.taproot/settings.yaml` into the project. |
+| `--force` | When used with `--template`, overwrites an existing `.taproot/settings.yaml` with the template's version. |
 
 Running `taproot init` again on an existing project is safe — it skips files that already exist and reports `exists` for each.
 
@@ -166,7 +170,7 @@ Surfaces unimplemented behaviours as work items, ordered by priority (intents wi
 ### `taproot dod`
 
 ```bash
-taproot dod [impl-path] [--dry-run]
+taproot dod [impl-path] [--dry-run] [--rerun-tests]
 taproot dod <impl-path> --resolve <condition> --note "<text>" [--resolve <condition> --note "<text>" ...]
 ```
 
@@ -174,6 +178,8 @@ Runs all configured DoD conditions from `.taproot/settings.yaml` against the spe
 
 Use `--resolve`/`--note` to record agent resolutions for agent-driven conditions (e.g. `document-current`, `check-if-affected`, `check-if-affected-by`). Multiple pairs can be supplied in a single invocation — conditions are paired with notes by position.
 
+Use `--rerun-tests` to force re-execution of `testsCommand` regardless of any cached result. Requires `<impl-path>`.
+
 See [Configuration](configuration.md) for how to define DoD conditions.
 
 ---

package/docs/configuration.md

@@ -64,7 +64,7 @@ The `definitionOfDone` list controls what `taproot dod` checks and what the pre-
 
 | Form | What it does |
 |------|-------------|
-| `tests-passing` | Built-in: runs `npm test` (or `yarn test`). Passes if exit code is 0. |
+| `tests-passing` | Built-in: runs `npm test`. When `testsCommand` is configured in `settings.yaml`, uses evidence-backed execution with a cache file — see [State Transition Guardrails](#state-transition-guardrails). |
 | `linter-clean` | Built-in: runs `npm run lint`. Passes if exit code is 0. |
 | `commit-conventions` | Built-in: runs `npm run check:commits`. Passes if exit code is 0. |
 | `document-current: <description>` | Agent-verified: the agent checks whether the described documentation is current and applies updates if needed. |
@@ -106,6 +106,50 @@ Taproot's own `.taproot/settings.yaml` ships with several `check-if-affected-by`
 
 ---
 
+## Autonomous Execution
+
+Setting `autonomous: true` in `settings.yaml` (or `TAPROOT_AUTONOMOUS=1` / `--autonomous` per invocation) puts all agent skills into non-interactive mode.
+
+```yaml
+autonomous: true   # all sessions in this repo run without confirmation prompts
+```
+
+**What autonomous mode changes:**
+- `/tr-implement` proceeds from plan to code without pausing for plan approval
+- `/tr-commit` stages and commits without asking for confirmation when nothing is pre-staged
+- DoD conditions are self-evaluated: resolvable conditions are recorded directly; unresolvable `check:` questions are marked `<!-- autonomous: pending-review -->` in `impl.md`
+- Test failures or hook rejections are recorded in `impl.md` (impl marked `needs-rework`) and the agent stops — the developer returns to a clear failure report
+
+**Three activation mechanisms (in order of scope):**
+1. `autonomous: true` in `.taproot/settings.yaml` — repo-wide, all sessions
+2. `TAPROOT_AUTONOMOUS=1` environment variable — per process invocation
+3. `--autonomous` flag on a skill invocation (e.g. `/tr-implement path/ --autonomous`) — per skill
+
+When none of these is set, confirmation prompts are shown as normal. Autonomous mode is never inferred from context.
+
+---
+
+## State Transition Guardrails
+
+When `testsCommand` is set in `settings.yaml`, the `tests-passing` condition uses evidence-backed execution: it runs the command, caches the result in `.taproot/.test-results/`, and enforces freshness at commit time.
+
+```yaml
+testsCommand: npm test        # command to run for evidence-backed tests-passing
+testResultMaxAge: 60          # minutes before a no-source-file cache is stale (default: 60)
+testTimeout: 300              # seconds before testsCommand is killed (default: 300)
+```
+
+**How it works:**
+- `taproot dod <impl-path>` runs `testsCommand`, streams output live, and writes `.taproot/.test-results/<intent>/<behaviour>/<impl>.json`
+- On subsequent runs, the cached result is used if it is not stale (no tracked source files changed since the last run)
+- `taproot dod <impl-path> --rerun-tests` forces re-execution regardless of cache
+- `--resolve "tests-passing"` is rejected when `testsCommand` is configured — evidence is required, not agent assertion
+- The pre-commit hook verifies a fresh passing result exists before allowing an implementation commit with a `complete` impl
+
+**Add `.taproot/.test-results/` to `.gitignore`** — the cache is a local execution artifact, not a committed record.
+
+---
+
 ## Definition of Ready
 
 The `definitionOfReady` list controls what the pre-commit hook checks when you make a declaration commit (committing `impl.md` without source files). All conditions must pass before the declaration commit is accepted.
@@ -139,6 +183,19 @@ When a `check:` condition is present in `definitionOfReady`, the agent reasons a
 - condition: check: is this spec complete enough? | note: yes, all flows are specified | resolved: 2026-03-20T10:00:00.000Z
 ```
 
+### `require-discussion-log`
+
+Require a `discussion.md` alongside every `impl.md` at declaration commit time. Off by default — enable for teams that want to enforce the record-decision-rationale habit:
+
+```yaml
+definitionOfReady:
+  - require-discussion-log: true
+```
+
+When enabled, the pre-commit hook checks whether `discussion.md` exists in the impl folder before accepting the declaration commit. If missing, the commit is rejected with the expected file path. The check is existence-only — content quality is not verified by the hook.
+
+See `taproot/requirements-compliance/record-decision-rationale/` for what `discussion.md` should contain and how the agent writes it.
+
 ### When DoR runs
 
 DoR runs once: when the declaration commit is made (committing `impl.md` alone, before any source code). It is enforced by the pre-commit hook's declaration tier.
@@ -240,6 +297,26 @@ Applied as a second substitution pass after the language pack (if any). Re-appli
 
 ---
 
+## CLI invocation
+
+### `cli`
+
+Controls which command agents use when executing taproot CLI steps (e.g. `taproot dod`, `taproot link-commits`). The value is injected into agent adapter files as a machine-readable block — agents read it at session start and substitute it wherever a skill step says `taproot <subcommand>`.
+
+```yaml
+cli: taproot
+```
+
+**Default:** `npx @imix-js/taproot` — works in any environment, whether or not taproot is globally installed.
+
+**Common overrides:**
+- `cli: taproot` — globally installed (`npm install -g @imix-js/taproot`)
+- `cli: ./node_modules/.bin/taproot` — local `devDependency`
+
+**Requires `taproot update`:** yes — the invocation block in agent adapter files is regenerated.
+
+---
+
 ## Validation settings
 
 ### `require_dates`

package/docs/patterns.md

@@ -116,3 +116,46 @@ The agent reads the question text, reasons whether the answer is yes, no, or not
 |---|---|
 | `does this story introduce a cross-cutting concern that warrants a new check-if-affected-by or check-if-affected entry in .taproot/settings.yaml?` | Agent adds the entry to `.taproot/settings.yaml` |
 | `does this story reveal a reusable pattern worth documenting in docs/patterns.md?` | Agent adds a pattern entry to `docs/patterns.md` |
+
+---
+
+## Autonomous mode preamble (`## Autonomous mode` section in skills)
+
+**Problem:** A skill has one or more confirmation prompts (plan approval, staging confirmation, DoD resolution prompts). You want the same skill to work in both interactive and non-interactive (CI, headless agent) contexts without maintaining two versions.
+
+**Pattern:** Add an `## Autonomous mode` section at the top of the skill file (before `## Steps`) that tells the agent to check for autonomous mode activation and apply autonomous notes throughout the steps.
+
+```markdown
+## 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.
+```
+
+Then at each confirmation step, add a conditional note:
+
+```markdown
+**Interactive mode:** ask "Should I proceed?" and wait for confirmation.
+
+**Autonomous mode:** proceed directly without waiting for confirmation.
+```
+
+**When to use it:**
+- The skill has at least one confirmation prompt that would block unattended execution
+- You want CI agents, headless runners, or `TAPROOT_AUTONOMOUS=1` users to be able to run the skill without interaction
+- The skill already exists and works correctly in interactive mode — this is an additive change
+
+**When NOT to use it:**
+- The confirmation prompt exists to prevent destructive irreversible actions (e.g. deleting data, force-pushing) — in these cases, autonomous bypass is unsafe
+- The skill is already fully automated (no prompts) — the preamble adds noise without value
+
+**Taproot's built-in uses:**
+
+| Skill | Prompt bypassed in autonomous mode |
+|---|---|
+| `skills/implement.md` | Plan approval in step 4 |
+| `skills/commit.md` | Staging confirmation in step 3 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imix-js/taproot",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "AI-driven specs, enforced at commit time. Code without traceability doesn't merge.",
   "type": "module",
   "bin": {
@@ -39,6 +39,7 @@
   "dependencies": {
     "@inquirer/checkbox": "^5.1.2",
     "@inquirer/confirm": "^6.0.10",
+    "@inquirer/select": "^5.1.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "js-yaml": "^4.1.1"

package/skills/backlog.md

@@ -0,0 +1,76 @@
+# Skill: backlog
+
+## Description
+
+Capture ideas, findings, and deferred work mid-session with a single command — without interrupting current flow. Called with an argument: captures instantly, no prompts. Called with no argument: opens triage — review each item and discard, keep, or promote to `/tr-ineed`.
+
+## Inputs
+
+- `idea` (optional): One-liner text to capture. If omitted, triage mode opens.
+
+## Steps
+
+### Capture mode (argument present)
+
+1. Detect that an argument was provided.
+2. If the argument is blank or whitespace only: warn *"Nothing to capture — provide a description."* and stop.
+3. Create `.taproot/backlog.md` if absent. Append the item:
+   `- [YYYY-MM-DD] <idea>` using today's date.
+4. Confirm in one line: *"✓ Captured: <idea>"*
+   No follow-up response required from the developer — the session continues.
+
+### Triage mode (no argument)
+
+1. Read `.taproot/backlog.md`.
+   - If absent or contains no standard items: report *"Backlog is empty. Use `/tr-backlog <idea>` to capture something."* and stop.
+
+2. Present all standard items as a numbered list (FIFO order, oldest first):
+   ```
+   Backlog — N items
+    1. [YYYY-MM-DD] item text
+    2. [YYYY-MM-DD] item text
+   ...
+   ```
+   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 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>` 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."*
+   If any non-standard lines were skipped: *"Skipped N non-standard line(s) — they remain in `.taproot/backlog.md`."*
+
+   If the developer exits without `done`: unprocessed items remain unchanged. If any actions were taken, show the summary; otherwise continue naturally.
+
+6. Present next steps (triage mode only — skip for capture mode):
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-ineed <idea>` — route a kept item into the hierarchy now
+   [B] `/tr-status` — see current project health
+
+## Output
+
+**Capture:** item written to `.taproot/backlog.md`, one-line confirmation.
+**Triage:** backlog updated in place; promoted items handed to `/tr-ineed`; completion summary shown.
+
+## CLI Dependencies
+
+None.
+
+## Notes
+
+- Capture is instant — no confirmation, no required fields, no prompts beyond the one-line acknowledgement.
+- Item format: `- [YYYY-MM-DD] <text>`. Items are presented FIFO (oldest first) during triage.
+- Items promoted via `[P]` are removed from the backlog before `/tr-ineed` is invoked. If the developer abandons the `/tr-ineed` discovery, re-capture the item with `/tr-backlog <idea>`.
+- This is a scratchpad, not a project management tool — no priority, labels, or status tracking.
+- Storage is `.taproot/backlog.md` — a committed markdown file inside the taproot config directory, versioned with the project.

package/skills/behaviour.md

@@ -82,6 +82,8 @@ Define a UseCase (observable system behaviour) under an intent or another behavi
 
 9. Create the directory `<parent>/<slug>/` and write `usecase.md`.
 
+9b. **Optionally write `discussion.md`** — if the session involved meaningful discovery dialogue (scope decisions, alternate flows surfaced, pivotal questions that changed the spec), draft a brief `discussion.md` in the behaviour folder alongside `usecase.md`. Use the same four-section template as `tr-implement` (Pivotal Questions, Alternatives Considered, Decision, Open Questions) but set `Skill: tr-behaviour`. Skip if the spec authoring was straightforward with no significant exploration.
+
 10. Update the parent document's `## Behaviours <!-- taproot-managed -->` section:
     - Read the parent `intent.md` (or parent `usecase.md` for sub-behaviours).
     - If the `## Behaviours` section does not exist, insert it immediately before `## Status` (or append at end of file if `## Status` is absent), with the heading `## Behaviours <!-- taproot-managed -->`.

package/skills/browse.md

@@ -0,0 +1,84 @@
+# Skill: browse
+
+## Description
+
+Read a taproot hierarchy document section by section in the terminal — without opening an external editor. Presents each section one at a time, offers inline editing via `[M] Modify`, and lists what's below at the end. Distinct from `/tr-review` (which is an agent-driven critique); browse is the developer reading the spec themselves.
+
+## Inputs
+
+- `path` (required): Path to a hierarchy document (`intent.md`, `usecase.md`, or `impl.md`) or the folder containing one.
+
+## Steps
+
+1. **Resolve the target document.**
+   - If `path` points directly to a file (`intent.md`, `usecase.md`, or `impl.md`): use it as-is.
+   - If `path` points to a folder: look for `intent.md`, then `usecase.md`, then `impl.md` at that exact folder level (not in subfolders). Child impl folders are children to list later — they are not the target document.
+   - If no hierarchy document is found: report *"No intent.md, usecase.md, or impl.md found at `<path>`"* and stop.
+   - If the path does not exist: report *"No file found at `<path>` — check the path and try again"* and stop.
+
+2. **Check for discussion.md.** Look for `discussion.md` in the same folder as the resolved document.
+   - If present and has substantive content (not just template headings): announce *"📝 Discussion notes found — I'll include context from them where relevant"*
+   - If absent or skeleton-only: skip silently — no announcement, no placeholder.
+
+3. **Determine the document type** (`intent.md`, `usecase.md`, or `impl.md`) and identify the section order by reading the document.
+
+4. **Present sections one at a time.** For each section:
+
+   a. Display the section heading and body, formatted to fit a terminal screen.
+
+   b. **Discussion context** — if `discussion.md` is present and substantive, insert a `> How we got here:` block at the following anchor (only once per browse session):
+      - `usecase.md`: before the `## Main Flow` section
+      - `impl.md`: alongside `## Design Decisions`
+      - `intent.md`: alongside `## Goal`
+
+   c. **Long section** — if the section body exceeds approximately 20 lines:
+      - Present the first ~20 lines, then offer: `[C] See more | [D] Done with this section`
+      - `[C]`: present the next ~20 lines; repeat until exhausted
+      - `[D]`: treat the section as complete and continue to step 4d
+
+   d. After displaying the section (or completing pagination), offer:
+
+      > `[C] Continue   [M] Modify   [S] Skip to children`
+
+5. **Handle developer choice:**
+
+   **[C] Continue** — present the next section (repeat step 4). When all sections are shown, proceed to step 6.
+
+   **[M] Modify** — ask: *"What would you like to change in this section?"*
+   - If the section is `## Commits` or `## DoD Resolutions` in an `impl.md`: first warn *"⚠ This section is managed by `taproot link-commits` / `taproot dod` — manual edits may be overwritten on the next run. Continue?"* and wait for confirmation before proceeding.
+   - Developer states the change. Apply it to the file and show the updated section.
+   - If the developer says "never mind" or equivalent: confirm *"No changes — continuing"* and return to step 4d.
+   - After applying the change, return to step 4d with the updated section displayed.
+
+   **[S] Skip to children** — skip remaining sections and proceed directly to step 6.
+
+6. **Show what's below:**
+   - **intent.md**: list child behaviours — name and relative path to each `usecase.md`
+   - **usecase.md**: list implementations — name and relative path to each `impl.md`
+   - **impl.md**: *"No children — this is a leaf implementation."*
+
+   To go deeper into any child, the developer calls `/tr-browse <child-path>`.
+
+7. 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-browse <child-path>` — go deeper into one of the listed children
+   [B] `/tr-implement <path>/` — start building (if browsing a behaviour spec)
+   [C] `/tr-review <path>` — get an agent critique of the spec
+
+## Output
+
+The developer has read the document section by section in the terminal. Any `[M]` edits are saved to the file. The developer knows what's below without opening any additional files.
+
+## CLI Dependencies
+
+None
+
+## Notes
+
+- Browse is read-and-light-edit, not a stress-test. Resist the urge to comment on spec quality — the developer is reading, not asking for a critique. Use `/tr-review` for that.
+- The ~20-line pagination threshold is a guideline. Use judgment — a section with 22 short lines may be fine to show in full; a section with 15 very long lines may need pagination.
+- The `> How we got here:` block is shown once per browse session at the designated anchor, not repeated for every section.
+- After [M] edits, the file on disk is updated but no git staging is performed — the developer commits when ready.

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