@imix-js/taproot 0.5.1 → 0.7.0

package/docs/patterns.md

@@ -8,10 +8,10 @@ Reusable patterns for extending and enforcing the taproot hierarchy. Each patter
 
 **Problem:** You have an architectural rule that should apply to every implementation — not just a one-time concern, but a standing requirement. Examples: every skill must include a session hygiene signal; every skill that produces output must present a **What's next?** block; every implementation must satisfy a security review checklist. Writing this rule in a README or CLAUDE.md makes it aspirational. You want it enforced automatically, at commit time, for every new implementation.
 
-**Pattern:** Define the rule as a behaviour spec (`usecase.md`), then add a `check-if-affected-by` entry to `.taproot/settings.yaml`.
+**Pattern:** Define the rule as a behaviour spec (`usecase.md`), then add a `check-if-affected-by` entry to `taproot/settings.yaml`.
 
 ```yaml
-# .taproot/settings.yaml
+# taproot/settings.yaml
 definitionOfDone:
   - check-if-affected-by: skill-architecture/context-engineering
 ```
@@ -37,7 +37,7 @@ When the DoD runner encounters this condition, it instructs the agent to:
 **How to add a new cross-cutting constraint:**
 
 1. Write the spec — `/tr-behaviour taproot/<your-intent>/ "<rule>"` — define what compliance looks like, what non-compliance looks like, and how to resolve it
-2. Add to `.taproot/settings.yaml`:
+2. Add to `taproot/settings.yaml`:
    ```yaml
    definitionOfDone:
      - check-if-affected-by: <intent-slug>/<behaviour-slug>
@@ -95,11 +95,11 @@ The agent is asked: "Does this implementation require changes to `<file>`?" If y
 
 **Problem:** You have a one-off question the agent should reason about at DoD (or DoR) time — something too project-specific to warrant a full behaviour spec, but important enough to enforce at every commit. Examples: "should this story be split?", "does this change affect the public API contract?", "is there a simpler approach we haven't considered?".
 
-**Pattern:** Add a `check:` entry to `definitionOfDone` (or `definitionOfReady`) in `.taproot/settings.yaml`.
+**Pattern:** Add a `check:` entry to `definitionOfDone` (or `definitionOfReady`) in `taproot/settings.yaml`.
 
 ```yaml
 definitionOfDone:
-  - check: "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?"
+  - check: "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?"
   - check: "does this story reveal a reusable pattern worth documenting in docs/patterns.md?"
 ```
 
@@ -114,7 +114,7 @@ The agent reads the question text, reasons whether the answer is yes, no, or not
 
 | Question | Action if yes |
 |---|---|
-| `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 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` |
 
 ---
@@ -131,7 +131,7 @@ The agent reads the question text, reasons whether the answer is yes, no, or not
 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`
+- `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.
 ```

package/docs/security.md

@@ -9,9 +9,9 @@ This document describes taproot's security model, applicable threat categories,
 Taproot has two security boundaries that must be explicitly trusted:
 
 **`settings.yaml` — Executable Configuration**
-The `definitionOfDone` and `definitionOfReady` check entries are executed as shell commands via `spawnSync(..., { shell: true })` in `dod-runner.ts` / `dor-runner.ts`. This is an intentional design — equivalent to `package.json` scripts. The trust boundary is: whoever controls `.taproot/settings.yaml` controls what shell commands run during gate evaluation.
+The `definitionOfDone` and `definitionOfReady` check entries are executed as shell commands via `spawnSync(..., { shell: true })` in `dod-runner.ts` / `dor-runner.ts`. This is an intentional design — equivalent to `package.json` scripts. The trust boundary is: whoever controls `taproot/settings.yaml` controls what shell commands run during gate evaluation.
 
-**`.taproot/skills/` — Agent Instructions**
+**`taproot/agent/skills/` — Agent Instructions**
 Skill files (`.md`) are loaded and delivered as instructions to AI agents. Whoever controls skill content controls agent behaviour. A compromised skill file is a direct agent instruction injection vector.
 
 Both boundaries are intentional; neither should be changed. Both must be consciously managed.
@@ -67,14 +67,14 @@ Recommended controls for taproot's own CI and for projects using taproot:
 
 ## Skill Security Guidelines
 
-All skill files (`.taproot/skills/*.md`, `skills/*.md`) must follow these rules:
+All skill files (`taproot/agent/skills/*.md`, `skills/*.md`) must follow these rules:
 
 1. **No shell execution without validation** — do not instruct agents to run shell commands unless the input is validated or the command is fully static
 2. **No hardcoded credentials or tokens** — skill files are committed to version control and distributed via npm; credentials in skills are a public disclosure
 3. **Least-privilege for agent instructions** — request only the permissions and actions the skill genuinely needs; avoid open-ended "do whatever is needed" patterns
 4. **No sensitive data in output** — do not instruct agents to echo or log content from `settings.yaml` commands (raw command strings, exit output)
 
-Every change to a skill file triggers the DoD skill review condition (see `.taproot/settings.yaml`).
+Every change to a skill file triggers the DoD skill review condition (see `taproot/settings.yaml`).
 
 ---
 

package/docs/workflows.md

@@ -144,7 +144,7 @@ After building up several specs, some domain terms and business rules will recur
 /tr-discover-truths
 ```
 
-The skill scans all `intent.md` and `usecase.md` files, identifies recurring terms, business rules, and conventions not yet defined in `taproot/global-truths/`, and presents them as candidates. For each candidate you choose: **promote** (routes to `/tr-ineed` → define-truth), **backlog** (saves to `.taproot/backlog.md` for later), **skip** (reappears next run), or **dismiss** (permanently suppressed).
+The skill scans all `intent.md` and `usecase.md` files, identifies recurring terms, business rules, and conventions not yet defined in `taproot/global-truths/`, and presents them as candidates. For each candidate you choose: **promote** (routes to `/tr-ineed` → define-truth), **backlog** (saves to `taproot/agent/backlog.md` for later), **skip** (reappears next run), or **dismiss** (permanently suppressed).
 
 Truth discovery also runs as a final pass inside `/tr-review-all`, appending a `## Truth Candidates` section to the review report.
 

package/package.json

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

package/skills/backlog.md

@@ -14,14 +14,14 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 
 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:
+3. Create `taproot/agent/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`.
+1. Read `taproot/agent/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):
@@ -36,8 +36,8 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 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.
+   - **`D <n>`** — remove item n from `taproot/agent/backlog.md`. Confirm: *"✓ Discarded #n"*. Redisplay the updated numbered list.
+   - **`P <n>` promote to /tr-ineed** — remove item n from `taproot/agent/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**
@@ -46,7 +46,7 @@ Capture ideas, findings, and deferred work mid-session with a single command —
    - **`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 any non-standard lines were skipped: *"Skipped N non-standard line(s) — they remain in `taproot/agent/backlog.md`."*
 
    If the developer exits without `done`: unprocessed items remain unchanged. If any actions were taken, show the summary; otherwise continue naturally.
 
@@ -60,7 +60,7 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 
 ## Output
 
-**Capture:** item written to `.taproot/backlog.md`, one-line confirmation.
+**Capture:** item written to `taproot/agent/backlog.md`, one-line confirmation.
 **Triage:** backlog updated in place; promoted items handed to `/tr-ineed`; completion summary shown.
 
 ## CLI Dependencies
@@ -73,4 +73,4 @@ None.
 - 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.
+- Storage is `taproot/agent/backlog.md` — a committed markdown file inside the taproot config directory, versioned with the project.

package/skills/behaviour.md

@@ -15,14 +15,14 @@ Define a UseCase (observable system behaviour) under an intent or another behavi
    - If `parent` contains `intent.md`: read the intent to understand the goal and success criteria.
    - If `parent` contains `usecase.md`: read the parent behaviour — this new behaviour is a sub-behaviour.
 
-1a. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the behaviour description for semantic matches. Match signals:
+1a. **Pattern check** — If `taproot/agent/docs/patterns.md` exists, scan the behaviour description for semantic matches. Match signals:
    - "apply to all / every implementation / every skill" → `check-if-affected-by`
    - "enforce a rule / architectural constraint / agents should follow" → `check-if-affected-by`
    - "keep docs current / enforce documentation quality" → `document-current`
    - "every new feature must update X" → `check-if-affected: X`
 
    If a match is found, **interrupt before asking clarifying questions**:
-   > "Before I write this spec — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md`."
+   > "Before I write this spec — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/docs/patterns.md`."
    > **[A] Use this pattern now** — I'll guide you through applying it instead of writing a spec
    > **[B] Continue writing the spec** — the spec is distinct from the pattern
 

package/skills/bug.md

@@ -35,10 +35,10 @@ Diagnose a defect through structured root cause analysis (5-Why) and delegate to
 
    - **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`
+     - 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.
+   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.
 

package/skills/commit.md

@@ -5,7 +5,7 @@
 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`
+- `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.
 
@@ -35,7 +35,7 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
    **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.
+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.
 
 5. Execute the sub-flow matching the commit type:
 
@@ -60,13 +60,25 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
 3. If a `check:` condition requires action you cannot take (e.g. failing tests), report: "Cannot commit — `<condition>` is unresolved and requires: `<correction hint>`." Stop and wait.
 
-4. Stage source files + all matched impl.md files and commit with a concise one-line message.
+4. **Truth consistency check** — if `taproot/global-truths/` exists:
+   a. Collect all truth files applicable at impl level: intent-scoped truths (always), behaviour-scoped truths, and impl-scoped truths.
+   b. Read each applicable truth file. If a file is unreadable, note it and skip.
+   c. Check the staged impl.md and source changes for consistency with applicable truths:
+      - Are defined architectural patterns and project conventions being followed?
+      - Are implementation-level rules respected?
+      - Are domain terms used consistently with their definitions?
+   d. If a conflict is found, surface it before proceeding:
+      > "Truth conflict: `<excerpt>` in staged changes conflicts with `global-truths/<file>`: `<truth excerpt>`. [A] Fix the implementation | [B] Update the truth | [C] Proceed with conflict noted"
+      Wait for the developer's choice. Do not proceed to step 5 until resolved.
+   e. If no conflicts (or all resolved): run `taproot truth-sign` to record the session marker the hook validates.
+
+5. Stage source files + all matched impl.md files and commit with a concise one-line message.
 
 ### Declaration commit
 
 1. Verify parent `usecase.md` is in `specified`, `implemented`, or `complete` state. If it is in `draft` or `proposed` state, report: "Cannot declare implementation — parent `usecase.md` is in `<state>` state. Run `/tr-refine <usecase-path>` to complete the spec first." Stop.
 
-2. Read `.taproot/settings.yaml` `definitionOfReady` entries. For each `check-if-affected-by` or `check:` condition, write an entry directly into `## DoR Resolutions` in the impl.md. There is no `taproot dor` CLI — write entries by hand:
+2. Read `taproot/settings.yaml` `definitionOfReady` entries. For each `check-if-affected-by` or `check:` condition, write an entry directly into `## DoR Resolutions` in the impl.md. There is no `taproot dor` CLI — write entries by hand:
    ```
    condition: <name> | note: <reasoning> | resolved: <date>
    ```

package/skills/define-truth.md

@@ -38,9 +38,25 @@ Create or update a truth entry in `taproot/global-truths/` — a fact, business
 
    Wait for the developer's choice.
 
-### Phase 3 — Choose Convention
+### Phase 3 — Name the File
 
-4. Ask which storage convention to use:
+4. Propose a category-level name for the file — one that can hold multiple related truths, not the specific term being captured now:
+
+   > "What should the file be called? Pick a category name so related truths can live together:
+   >
+   > Suggested names by scope:
+   > - **intent**: `glossary` · `principles` · `ux-principles` · `domain-model` · `system-context`
+   > - **behaviour**: `principles` · `guarantees` · `rules`
+   > - **impl**: `architecture` · `tech-choices` · `patterns`
+   >
+   > (Or enter your own name — keep it generic enough to hold future truths of the same kind.)"
+
+   If a file with that name already exists at the target path, note it:
+   > "A file `<name>_<scope>.md` already exists — I'll append to it rather than create a new one."
+
+### Phase 4 — Choose Convention
+
+5. 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`)
@@ -50,25 +66,25 @@ Create or update a truth entry in `taproot/global-truths/` — a fact, business
    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
+### Phase 5 — Write the File
 
-5. Determine the file path:
+6. 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:
+7. 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:
+8. 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:
+9. **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:
+10. **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.

package/skills/discover-truths.md

@@ -13,9 +13,9 @@ Scan the taproot hierarchy for implicit facts — recurring terms, business rule
 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`
+- `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.
+If any of these is true, **autonomous mode is active** — skip interactive prompts and defer all candidates to `taproot/agent/backlog.md` as "truth candidate: `<term>`" entries, then report the summary.
 
 ## Steps
 
@@ -31,7 +31,7 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 
 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.
+4. Read `taproot/agent/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
 
@@ -89,11 +89,11 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
    - No record written; candidate reappears on next discovery run
 
    **Backlog [B]:**
-   - Append to `.taproot/backlog.md`: `- [YYYY-MM-DD] truth candidate: <term>`
+   - Append to `taproot/agent/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>`
+   - Append to `taproot/agent/backlog.md`: `- [YYYY-MM-DD] reviewed — not a truth: <term>`
    - This entry suppresses the candidate on all future discovery runs
    - Move to next candidate
 
@@ -113,7 +113,7 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 ## 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
+- `taproot/agent/backlog.md` updated with any backlogged or dismissed candidates
 - Summary report: N promoted, N skipped, N backlogged, N dismissed
 
 ## CLI Dependencies
@@ -125,5 +125,5 @@ None.
 - 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.
+- Dismissed entries in `taproot/agent/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/guide.md

@@ -107,7 +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)
+   [C] `/tr-backlog` — triage captured ideas (only if `taproot/agent/backlog.md` is non-empty)
 
 ## Output
 

package/skills/implement.md

@@ -14,7 +14,7 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
 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`
+- `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.
 
@@ -36,14 +36,14 @@ If any of these is true, **autonomous mode is active** — apply the autonomous
    - 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:
+4. **Pattern check + plan mode.** Before proposing the plan: if `taproot/agent/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`
    - "keep a file in sync / update X on every change" → `check-if-affected: X`
 
    If a match is found, surface it before the plan:
-   > "Before the plan — this looks like it could use the **`<pattern-name>`** pattern rather than a custom implementation. See `.taproot/docs/patterns.md`."
-   > **[A] Use the pattern** — apply it via `.taproot/settings.yaml` instead of writing source code
+   > "Before the plan — this looks like it could use the **`<pattern-name>`** pattern rather than a custom implementation. See `taproot/agent/docs/patterns.md`."
+   > **[A] Use the pattern** — apply it via `taproot/settings.yaml` instead of writing source code
    > **[B] Continue with implementation** — the custom implementation is intentional
 
    Then **propose the implementation plan:**
@@ -102,7 +102,7 @@ If any of these is true, **autonomous mode is active** — apply the autonomous
 6. **Declaration commit** — commit `impl.md`, `discussion.md` (if written), and any `usecase.md` link-section update together (no source files):
 
    Before committing:
-   - Read `.taproot/settings.yaml` and note the `definitionOfReady` conditions — these are the checks the hook will run. If the file has no `definitionOfReady` section, only baseline DoR checks run.
+   - Read `taproot/settings.yaml` and note the `definitionOfReady` conditions — these are the checks the hook will run. If the file has no `definitionOfReady` section, only baseline DoR checks run.
    - There is no standalone `taproot dor` command — DoR runs automatically via the pre-commit hook when impl.md is staged without source files (this is a **declaration commit**). Resolve any agent-driven DoR conditions (e.g. `check-if-affected-by`) in impl.md under `## DoR Resolutions` before staging.
 
    ```

package/skills/ineed.md

@@ -10,7 +10,24 @@ Route a natural language requirement to the right place in the taproot hierarchy
 
 ## Steps
 
-0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
+0. **Global truth check** — Before anything else, determine if the requirement is a **principle, fact, or rule to capture** rather than a feature to build or enforce.
+
+   Global truth signals:
+   - User explicitly says "as a global truth", "add this as a truth", "capture this as a principle"
+   - The requirement is a design principle or quality attribute with no concrete actor or user-visible action (e.g. "fail early", "discoverable by default", "no surprises")
+   - The requirement describes how the system *should be* rather than what it *should do*
+
+   If a global truth signal is present, **interrupt before proceeding**:
+   > "That sounds like a **global truth** — a design principle to capture in `taproot/global-truths/`, not a feature to build. Should I route it there, or is this something that should actively enforce on every implementation via a DoD gate?
+   > **[A]** Global truth → route to `/tr-define-truth`
+   > **[B]** Enforcement gate → apply `check-if-affected-by` pattern
+   > **[C]** New requirement → continue with normal routing"
+
+   - **[A]**: call `/tr-define-truth` with the principle. Stop — do not continue routing.
+   - **[B]**: proceed to pattern check below.
+   - **[C]** or no global truth signal: proceed to pattern check below.
+
+0a. **Pattern check** — If `taproot/agent/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
    - "apply to all / every implementation / every skill / everywhere" → `check-if-affected-by`
    - "guide agents / architecture rules / agents should follow / enforce a rule" → `check-if-affected-by`
    - "enforce documentation / docs must stay current / keep docs accurate" → `document-current`
@@ -18,14 +35,14 @@ Route a natural language requirement to the right place in the taproot hierarchy
    - "research before building / check if a library exists / look up how to implement" → research-first (`/tr-research`)
 
    If a match is found, **interrupt before proceeding**:
-   > "Before I route this — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md` for how to use it."
+   > "Before I route this — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/docs/patterns.md` for how to use it."
    > **[A] Use this pattern now** — I'll guide you through applying it
    > **[B] Continue as a new requirement** — route and spec it normally
 
-   - **[A]**: read the relevant section of `.taproot/docs/patterns.md` and guide the user through applying the pattern directly. Do not create a new hierarchy entry.
+   - **[A]**: read the relevant section of `taproot/agent/docs/patterns.md` and guide the user through applying the pattern directly. Do not create a new hierarchy entry.
    - **[B]** or no match: proceed to step 1.
 
-   If multiple patterns match, list all before asking. If `.taproot/docs/patterns.md` is absent, skip silently.
+   If multiple patterns match, list all before asking. If `taproot/agent/docs/patterns.md` is absent, skip silently.
 
 1. **Classify the requirement** — Load `taproot/OVERVIEW.md` if it exists; if not, walk `taproot/` and read each `intent.md`. Use this hierarchy map to decide which path to take:
 

package/skills/refine.md

@@ -11,14 +11,14 @@ Update a behaviour spec (`usecase.md`) based on what was learned during or after
 
 ## Steps
 
-0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the `finding` input for semantic matches. Match signals:
+0. **Pattern check** — If `taproot/agent/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
+   > "Before I refine this — that finding sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/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`.

package/skills/review-all.md

@@ -68,7 +68,7 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
 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.
+   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/agent/backlog.md` dismissed entries.
 
    If candidates are found, append to the report:
 
@@ -86,7 +86,7 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
    **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 [D]:** append each candidate to `taproot/agent/backlog.md` as `- [YYYY-MM-DD] truth candidate: <term>`.
 
    If no candidates found (hierarchy consistent with existing truths), append to report:
    ```

package/skills/status.md

@@ -78,13 +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): check whether `.taproot/backlog.md` exists and contains items. Show the generic fallback menu:
+   - **If no specific items were found** (healthy project): check whether `taproot/agent/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` — 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)
+     [D] `/tr-backlog` — triage captured ideas (only if `taproot/agent/backlog.md` is non-empty)
 
 ## Output