@imix-js/taproot 0.2.0

package/dist/validators/format-rules.js

@@ -0,0 +1,238 @@
+import { existsSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { getLocalizedRequiredSections } from '../core/language.js';
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const STATE_LINE = /^\s*[-*]?\s*\*\*State:\*\*\s*(.+)$/m;
+const DATE_LINE = /^\s*[-*]?\s*\*\*(?:Created|Last reviewed|Last verified):\*\*\s*(.+)$/gm;
+export function checkRequiredSections(doc, markerType, pack) {
+    const required = getLocalizedRequiredSections(markerType, pack ?? null);
+    return required
+        .filter(section => !doc.sections.has(section))
+        .map(section => ({
+        type: 'error',
+        filePath: doc.filePath,
+        code: 'MISSING_SECTION',
+        message: `Required section "## ${titleCase(section)}" is missing`,
+    }));
+}
+export function checkStatusValue(doc, markerType, config) {
+    if (!config.validation.requireStatus)
+        return [];
+    const statusSection = doc.sections.get('status');
+    if (!statusSection)
+        return []; // Caught by checkRequiredSections
+    const match = STATE_LINE.exec(statusSection.rawBody);
+    if (!match) {
+        return [{
+                type: 'error',
+                filePath: doc.filePath,
+                line: statusSection.startLine,
+                code: 'MISSING_STATE_LINE',
+                message: 'Status section is missing the "**State:**" line',
+            }];
+    }
+    const value = (match[1] ?? '').trim();
+    if (markerType === 'intent' && value === 'deferred') {
+        const bodyLines = statusSection.bodyLines;
+        const stateLine = bodyLines.findIndex(l => /\*\*State:\*\*/.test(l));
+        const lineNumber = statusSection.startLine + (stateLine >= 0 ? stateLine + 1 : 0);
+        return [{
+                type: 'error',
+                filePath: doc.filePath,
+                line: lineNumber,
+                code: 'INVALID_STATUS_VALUE',
+                message: 'deferred is not a valid state for intent.md — use deprecated instead',
+            }];
+    }
+    const allowed = markerType === 'intent' ? config.validation.allowedIntentStates :
+        markerType === 'behaviour' ? config.validation.allowedBehaviourStates :
+            config.validation.allowedImplStates;
+    if (!allowed.includes(value)) {
+        const bodyLines = statusSection.bodyLines;
+        const stateLine = bodyLines.findIndex(l => /\*\*State:\*\*/.test(l));
+        const lineNumber = statusSection.startLine + (stateLine >= 0 ? stateLine + 1 : 0);
+        return [{
+                type: 'error',
+                filePath: doc.filePath,
+                line: lineNumber,
+                code: 'INVALID_STATUS_VALUE',
+                message: `Invalid state "${value}" for ${markerType}. Allowed: ${allowed.join(', ')}`,
+            }];
+    }
+    return [];
+}
+export function checkDateFormat(doc, config) {
+    if (!config.validation.requireDates)
+        return [];
+    const statusSection = doc.sections.get('status');
+    if (!statusSection)
+        return [];
+    const violations = [];
+    let match;
+    const regex = new RegExp(DATE_LINE.source, 'gm');
+    while ((match = regex.exec(statusSection.rawBody)) !== null) {
+        const value = (match[1] ?? '').trim();
+        if (!ISO_DATE.test(value)) {
+            const matchLine = statusSection.rawBody
+                .substring(0, match.index)
+                .split('\n').length;
+            violations.push({
+                type: 'error',
+                filePath: doc.filePath,
+                line: statusSection.startLine + matchLine,
+                code: 'INVALID_DATE_FORMAT',
+                message: `Date "${value}" is not in ISO 8601 format (YYYY-MM-DD)`,
+            });
+        }
+    }
+    return violations;
+}
+export function checkBehaviourReference(doc, implFilePath) {
+    const behaviourSection = doc.sections.get('behaviour');
+    if (!behaviourSection)
+        return []; // Caught by checkRequiredSections
+    const refLine = behaviourSection.bodyLines.find(l => l.trim().length > 0);
+    if (!refLine) {
+        return [{
+                type: 'error',
+                filePath: doc.filePath,
+                line: behaviourSection.startLine + 1,
+                code: 'MISSING_BEHAVIOUR_REFERENCE',
+                message: 'Behaviour section is empty — expected a relative path to usecase.md',
+            }];
+    }
+    const ref = refLine.trim();
+    const resolvedPath = resolve(dirname(implFilePath), ref);
+    if (!existsSync(resolvedPath)) {
+        const lineNumber = behaviourSection.startLine +
+            behaviourSection.bodyLines.indexOf(refLine) + 1;
+        return [{
+                type: 'error',
+                filePath: doc.filePath,
+                line: lineNumber,
+                code: 'INVALID_BEHAVIOUR_REFERENCE',
+                message: `Behaviour reference "${ref}" does not resolve to an existing file`,
+            }];
+    }
+    return [];
+}
+export function checkDiagramSection(doc) {
+    const diagramSection = doc.sections.get('diagram');
+    if (!diagramSection)
+        return [];
+    const hasMermaidFence = /```mermaid/i.test(diagramSection.rawBody);
+    if (!hasMermaidFence) {
+        return [{
+                type: 'warning',
+                filePath: doc.filePath,
+                line: diagramSection.startLine,
+                code: 'DIAGRAM_MISSING_MERMAID_FENCE',
+                message: 'Diagram section exists but contains no mermaid code fence (```mermaid)',
+            }];
+    }
+    return [];
+}
+export function checkLinkSection(doc, node) {
+    if (node.marker === 'intent') {
+        const hasBehaviourChildren = node.children.some(c => c.marker === 'behaviour');
+        return checkManagedSection(doc, 'behaviours', 'Behaviours', hasBehaviourChildren);
+    }
+    if (node.marker === 'behaviour') {
+        const hasImplChildren = node.children.some(c => c.marker === 'impl');
+        return checkManagedSection(doc, 'implementations', 'Implementations', hasImplChildren);
+    }
+    return [];
+}
+function findSectionByPrefix(doc, prefix) {
+    for (const [key, value] of doc.sections) {
+        if (key === prefix || key.startsWith(prefix + ' '))
+            return value;
+    }
+    return undefined;
+}
+function checkManagedSection(doc, sectionKey, sectionTitle, hasChildren) {
+    const violations = [];
+    const section = findSectionByPrefix(doc, sectionKey);
+    if (hasChildren && !section) {
+        violations.push({
+            type: 'error',
+            filePath: doc.filePath,
+            code: 'MISSING_LINK_SECTION',
+            message: `Missing "## ${sectionTitle}" section — run \`taproot update\` to generate it`,
+        });
+        return violations;
+    }
+    if (!section)
+        return [];
+    const linkPattern = /\[.*?\]\((.+?)\)/g;
+    let m;
+    while ((m = linkPattern.exec(section.rawBody)) !== null) {
+        const linkTarget = m[1];
+        const resolved = resolve(dirname(doc.filePath), linkTarget);
+        if (!existsSync(resolved)) {
+            violations.push({
+                type: 'error',
+                filePath: doc.filePath,
+                code: 'STALE_LINK',
+                message: `STALE_LINK — link in ## ${sectionTitle} points to non-existent file: ${linkTarget}`,
+            });
+        }
+    }
+    return violations;
+}
+export function checkAcceptanceCriteria(doc, node, pack) {
+    const hasImplChildren = node.children.some(c => c.marker === 'impl');
+    const acKey = pack ? (pack['Acceptance Criteria']?.toLowerCase() ?? 'acceptance criteria') : 'acceptance criteria';
+    const criteriaSection = doc.sections.get(acKey);
+    if (hasImplChildren && !criteriaSection) {
+        return [{
+                type: 'warning',
+                filePath: doc.filePath,
+                code: 'MISSING_ACCEPTANCE_CRITERIA',
+                message: 'usecase.md has implementations but no "## Acceptance Criteria" section',
+            }];
+    }
+    if (!criteriaSection)
+        return [];
+    const violations = [];
+    const idPattern = /^\*\*(AC|NFR)-(\d+):/gm;
+    const seen = new Set();
+    let m;
+    while ((m = idPattern.exec(criteriaSection.rawBody)) !== null) {
+        const id = `${m[1]}-${m[2]}`;
+        if (seen.has(id)) {
+            const linesBefore = criteriaSection.rawBody.substring(0, m.index).split('\n').length;
+            violations.push({
+                type: 'error',
+                filePath: doc.filePath,
+                line: criteriaSection.startLine + linesBefore,
+                code: 'DUPLICATE_CRITERION_ID',
+                message: `Duplicate acceptance criterion ID "${id}" — each AC-N / NFR-N must be unique within the file`,
+            });
+        }
+        seen.add(id);
+    }
+    return violations;
+}
+export function validateFormat(doc, markerType, config, node, pack) {
+    const violations = [];
+    violations.push(...checkRequiredSections(doc, markerType, pack));
+    violations.push(...checkStatusValue(doc, markerType, config));
+    violations.push(...checkDateFormat(doc, config));
+    if (markerType === 'impl') {
+        violations.push(...checkBehaviourReference(doc, doc.filePath));
+    }
+    if (markerType === 'behaviour') {
+        violations.push(...checkDiagramSection(doc));
+        if (node)
+            violations.push(...checkAcceptanceCriteria(doc, node, pack));
+    }
+    if (node) {
+        violations.push(...checkLinkSection(doc, node));
+    }
+    return violations;
+}
+function titleCase(s) {
+    return s.replace(/\b\w/g, c => c.toUpperCase());
+}
+//# sourceMappingURL=format-rules.js.map

package/dist/validators/format-rules.js.map

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

package/dist/validators/structure-rules.d.ts

@@ -0,0 +1,10 @@
+import type { FolderNode, Violation } from './types.js';
+export declare function checkDuplicateMarkers(node: FolderNode): Violation[];
+export declare function checkKebabCase(node: FolderNode): Violation[];
+export declare function checkBehaviourParent(node: FolderNode): Violation[];
+export declare function checkImplParent(node: FolderNode): Violation[];
+export declare function checkOrphanFolder(node: FolderNode): Violation[];
+export declare function checkEmptyFolder(node: FolderNode): Violation[];
+export declare function validateStructure(root: FolderNode, options: {
+    strict: boolean;
+}): Violation[];

package/dist/validators/structure-rules.js

@@ -0,0 +1,94 @@
+import { join } from 'path';
+import { flattenTree } from '../core/fs-walker.js';
+const KEBAB_CASE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function checkDuplicateMarkers(node) {
+    if (node.markerFiles.length <= 1)
+        return [];
+    return [{
+            type: 'error',
+            filePath: node.absolutePath,
+            code: 'DUPLICATE_MARKERS',
+            message: `Folder contains multiple marker files: ${node.markerFiles.join(', ')}`,
+        }];
+}
+export function checkKebabCase(node) {
+    if (KEBAB_CASE.test(node.name))
+        return [];
+    return [{
+            type: 'error',
+            filePath: node.absolutePath,
+            code: 'INVALID_FOLDER_NAME',
+            message: `Folder name "${node.name}" does not match kebab-case pattern (^[a-z0-9]+(-[a-z0-9]+)*$)`,
+        }];
+}
+export function checkBehaviourParent(node) {
+    if (node.marker !== 'behaviour')
+        return [];
+    const parentMarker = node.parent?.marker ?? null;
+    if (parentMarker === 'intent' || parentMarker === 'behaviour')
+        return [];
+    return [{
+            type: 'error',
+            filePath: join(node.absolutePath, 'usecase.md'),
+            code: 'BEHAVIOUR_PARENT_INVALID',
+            message: `Behaviour folder "${node.name}" must be a child of an intent or behaviour folder, but parent is ${parentMarker === null ? 'the root or an unmarked folder' : `a "${parentMarker}" folder`}`,
+        }];
+}
+export function checkImplParent(node) {
+    if (node.marker !== 'impl')
+        return [];
+    if (node.parent?.marker === 'behaviour')
+        return [];
+    return [{
+            type: 'error',
+            filePath: join(node.absolutePath, 'impl.md'),
+            code: 'IMPL_PARENT_INVALID',
+            message: `Implementation folder "${node.name}" must be a child of a behaviour folder, but parent is ${node.parent?.marker === null ? 'an unmarked folder' : `a "${node.parent?.marker ?? 'root'}" folder`}`,
+        }];
+}
+export function checkOrphanFolder(node) {
+    if (node.marker !== null)
+        return [];
+    if (node.hasDescendantWithMarker)
+        return [];
+    // The taproot root itself (depth 0) is allowed to be empty initially
+    if (node.depth === 0)
+        return [];
+    return [{
+            type: 'error',
+            filePath: node.absolutePath,
+            code: 'ORPHAN_FOLDER',
+            message: `Folder "${node.name}" contains no marker file and has no descendant with a marker file`,
+        }];
+}
+export function checkEmptyFolder(node) {
+    if (node.marker === null)
+        return [];
+    if (node.children.length > 0)
+        return [];
+    // impl folders are leaf nodes by design — not empty warnings
+    if (node.marker === 'impl')
+        return [];
+    return [{
+            type: 'warning',
+            filePath: node.absolutePath,
+            code: 'EMPTY_FOLDER',
+            message: `${node.marker} folder "${node.name}" has no child folders`,
+        }];
+}
+export function validateStructure(root, options) {
+    const violations = [];
+    const nodes = flattenTree(root);
+    for (const node of nodes) {
+        violations.push(...checkDuplicateMarkers(node));
+        if (node !== root)
+            violations.push(...checkKebabCase(node));
+        violations.push(...checkBehaviourParent(node));
+        violations.push(...checkImplParent(node));
+        violations.push(...checkOrphanFolder(node));
+        if (options.strict)
+            violations.push(...checkEmptyFolder(node));
+    }
+    return violations;
+}
+//# sourceMappingURL=structure-rules.js.map

package/dist/validators/structure-rules.js.map

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

package/dist/validators/types.d.ts

@@ -0,0 +1,68 @@
+export type MarkerType = 'intent' | 'behaviour' | 'impl';
+export interface FolderNode {
+    absolutePath: string;
+    relativePath: string;
+    name: string;
+    marker: MarkerType | null;
+    markerFiles: string[];
+    children: FolderNode[];
+    parent: FolderNode | null;
+    depth: number;
+    hasDescendantWithMarker: boolean;
+}
+export interface SectionContent {
+    heading: string;
+    startLine: number;
+    bodyLines: string[];
+    rawBody: string;
+}
+export interface ParsedMarkdown {
+    filePath: string;
+    sections: Map<string, SectionContent>;
+    rawLines: string[];
+}
+export interface Violation {
+    type: 'error' | 'warning';
+    filePath: string;
+    line?: number;
+    code: string;
+    message: string;
+}
+export type DodConditionEntry = string | {
+    run: string;
+    name?: string;
+    correction?: string;
+} | {
+    'document-current': string;
+} | {
+    'check-if-affected': string;
+} | {
+    'check-if-affected-by': string;
+} | {
+    'check': string;
+};
+export interface TaprootConfig {
+    version: number;
+    root: string;
+    commitPattern: string;
+    commitTrailer: string;
+    agents: string[];
+    language?: string;
+    vocabulary?: Record<string, string>;
+    validation: {
+        requireDates: boolean;
+        requireStatus: boolean;
+        allowedIntentStates: string[];
+        allowedBehaviourStates: string[];
+        allowedImplStates: string[];
+    };
+    hooks: {
+        preCommit: string[];
+    };
+    ci: {
+        onPr: string[];
+        onMerge: string[];
+    };
+    definitionOfDone?: DodConditionEntry[];
+    definitionOfReady?: DodConditionEntry[];
+}

package/dist/validators/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/validators/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/validators/types.ts"],"names":[],"mappings":""}

package/docs/agents.md

@@ -0,0 +1,88 @@
+# Agent Setup
+
+Taproot works with any AI assistant that can read files. Run `taproot init --agent <name>` to generate the adapter for your assistant. The adapter installs the agent-specific integration files (slash commands, rules, or instruction files) that teach the agent how to use Taproot.
+
+## Supported Agents
+
+| Agent | Support Tier | Command | What gets installed |
+|-------|-------------|---------|---------------------|
+| 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 |
+| 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` |
+| Any agent | **Tier 3** — community supported | `taproot init --agent generic` | `AGENTS.md` — agent-agnostic instructions |
+| All agents | — | `taproot init --agent all` | All of the above |
+
+**Tier 1** agents are fully tested with all features supported and covered in CI. **Tier 2** agents have working adapters with basic end-to-end validation. **Tier 3** agents are community-supported — adapters are generated but not officially validated end-to-end. Feedback and fixes welcome.
+
+You can install multiple adapters in the same project. If your team uses Cursor and you use Claude Code, run `taproot init --agent all`.
+
+When Taproot is updated, run `taproot update` to refresh the adapter files to the current version. The update command also removes stale files from older layouts.
+
+---
+
+## Skills (Claude Code)
+
+Claude Code skills are the richest integration. Each skill is a self-contained markdown file that defines a complete interactive workflow — inputs, steps, output format, and CLI dependencies. The agent reads the skill file when you invoke the command and follows it precisely.
+
+After `taproot init --agent claude --with-skills`, skills are available as `/tr-*` slash commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/tr-guide` | Onboarding walkthrough — explains the hierarchy, lists commands, tailors the guide to whether your project already has intents |
+| `/tr-ineed` | Route a natural language requirement to the right place; runs structured discovery for vague requirements before placement |
+| `/tr-intent` | Create or refine a business intent document with stakeholders and success criteria |
+| `/tr-behaviour` | Define a UseCase under an intent or another behaviour; walks alternate flows and error conditions proactively |
+| `/tr-decompose` | Break an intent into the set of behaviours needed to fulfil it |
+| `/tr-implement` | Implement a behaviour: write code, write tests, create `impl.md`, commit with conventional tag |
+| `/tr-trace` | Navigate the hierarchy in any direction — file to intent (bottom-up), intent to code (top-down), or across siblings |
+| `/tr-status` | Coverage dashboard: shows what's implemented, what's planned, what's stale, and what to do next |
+| `/tr-review` | Stress-test a single artifact — challenges assumptions, identifies gaps, asks adversarial questions |
+| `/tr-review-all` | Comprehensive review of an entire subtree — structural checks, cross-cutting analysis, per-artifact findings |
+| `/tr-refine` | Update a behaviour spec based on post-implementation learnings |
+| `/tr-promote` | Escalate a finding from implementation or behaviour level up to the intent |
+| `/tr-analyse-change` | Impact analysis before editing an existing artifact — identifies downstream breakage and related behaviours |
+| `/tr-plan` | Surface the next independently-implementable work item from the hierarchy |
+| `/tr-discover` | Reverse-engineer an existing codebase into a taproot hierarchy through structured, interactive discovery |
+| `/tr-grill-me` | Interview you relentlessly about a plan or design — one decision branch at a time, recommended answer first |
+| `/tr-research` | Research a domain or technical subject before speccing — scans local resources, searches the web, optionally grills domain experts |
+| `/tr-sweep` | Apply a uniform task to a filtered set of hierarchy files — enumerate, confirm, then call `taproot apply` per file |
+
+### How skills work
+
+Skills are portable markdown files installed to `.taproot/skills/`. They are not IDE plugins or extensions — any agent that can read files can follow a skill. The Claude Code adapter generates `.claude/commands/tr-*.md` files that reference the skills; invoking `/tr-intent` tells Claude to load and follow `skills/intent.md`.
+
+This means:
+- Skills work even if the Claude Code extension is updated or changed
+- You can read any skill file to understand exactly what the agent will do
+- You can customise a skill by editing its file in `.taproot/skills/`
+- Skills stay in sync with Taproot via `taproot update`
+
+### Updating skills
+
+```bash
+taproot update
+```
+
+This refreshes all adapter files and skill definitions to the current version. Run it after upgrading the `taproot` package.
+
+---
+
+## 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.
+
+These adapters do not provide slash commands. Instead, refer to the relevant document or hierarchy path in your prompt:
+
+```
+Look at taproot/password-reset/request-reset/usecase.md and implement the rate limiting behaviour.
+```
+
+Or ask the agent to run CLI commands directly:
+
+```
+Run taproot validate-format and fix any violations in the hierarchy.
+```
+
+The `AGENTS.md` generic adapter works with any agent and can also be used as documentation for team members who are new to Taproot.

package/docs/architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+Architectural decisions, constraints, and patterns for the taproot codebase. Every implementation must be checked against these before coding begins (enforced via `definitionOfReady`).
+
+---
+
+## Principles
+
+**Filesystem as data model** — No external database or service. All hierarchy state lives in git-versioned markdown files under `taproot/`. No runtime state is persisted outside the filesystem.
+
+**Immutable config after load** — `loadConfig()` is called once at command entry; the resolved config object is passed down. Commands never re-read the config file mid-execution.
+
+**External I/O only at command boundaries** — File reads/writes, git invocations, and process spawns happen in command handlers (`src/commands/`), not in core logic (`src/core/`). Core modules receive data, not file paths, wherever practical.
+
+**Stateless CLI commands** — Each CLI invocation is independent. No daemon, no persistent process, no shared mutable state between invocations.
+
+**Agent-agnostic output** — Skill files and adapter files must be plain markdown/text. No agent-specific syntax in the hierarchy documents themselves.
+
+---
+
+## Constraints
+
+**No global mutable state** — No module-level variables that accumulate state across calls. Functions that need shared state receive it as parameters.
+
+**`taproot/` contains only requirement documents** — Skills, config, and framework files live in `.taproot/`. Never mix framework files into the requirements hierarchy.
+
+**`taproot/_sessions/` is the scratch space for agent session state** — Skills that persist resumable session data (phase progress, confirmed items, open questions) write to `taproot/_sessions/<skill-name>-status.md`. This folder is not a formal hierarchy document and is excluded from `taproot validate-structure`. Use `_sessions/`, not `_brainstorms/` — the latter implies ideation rather than structured state.
+
+**Markdown is the schema** — All hierarchy documents (intent.md, usecase.md, impl.md) must be valid CommonMark. No proprietary extensions.
+
+**Error messages must be actionable** — Every error surface (CLI output, DoD/DoR failures, validate-format output) must include a correction hint, not just a description of what failed.
+
+**No raw exceptions to the user** — The CLI top-level handler catches all thrown errors and prints only the message, never a stack trace or Node.js exception dump. `process.exitCode = 1` is set; the process exits cleanly. Stack traces are for tests and debugging only.
+
+---
+
+## Module boundaries
+
+| Layer | Path | Responsibility |
+|---|---|---|
+| Commands | `src/commands/` | CLI registration, I/O, orchestration |
+| Core | `src/core/` | Pure logic: parsing, validation, config, runners |
+| Validators | `src/validators/` | Types and structural validation rules |
+| Adapters | `src/adapters/` | Agent-specific adapter/skill generation |
+| Templates | `src/templates/` | Document scaffolding strings |
+
+Core modules must not import from commands. Commands may import from core, validators, adapters, and templates.
+
+---
+
+## Testing
+
+Integration tests use real temporary directories (`mkdtempSync`) — no mocking the filesystem. Config in tests must be written to `.taproot/settings.yaml` (not `.taproot/settings.yaml`).