@imix-js/taproot 0.2.0

package/docs/configuration.md

@@ -0,0 +1,255 @@
+# Configuration
+
+## Quick discovery
+
+- **In your project:** `.taproot/CONFIGURATION.md` — installed and refreshed by `taproot update`, documents all `settings.yaml` options with examples and whether each requires re-running `taproot update`
+- **From the CLI:** `taproot --help` includes a footer pointing to `.taproot/settings.yaml` and `.taproot/CONFIGURATION.md`
+- **Full reference:** this document
+
+## `.taproot/settings.yaml`
+
+Created by `taproot init`. All settings have defaults — you only need to add what you want to override.
+
+```yaml
+version: 1
+root: taproot/
+
+# Language pack for localising section headers, Gherkin keywords, and state values.
+# Supported codes: de, fr, es, ja, pt (omit for English).
+# Applied at `taproot update` time — skill files and agent adapters are regenerated
+# with translated structural vocabulary. Validators and the commit hook also accept
+# the localised section names when this is set.
+language: de
+
+# Domain vocabulary overrides — replace dev-specific terms with domain-appropriate equivalents.
+# Applied as a second pass after the language pack. Re-applied on each `taproot update`.
+vocabulary:
+  tests: manuscript reviews
+  source files: chapters
+  build: compile draft
+
+# Commit message format for linking commits to impl.md records.
+# The default matches: taproot(path/to/impl): message
+commit_pattern: "taproot\\(([^)]+)\\):"
+commit_trailer: "Taproot"
+
+# Which agent adapters to keep current when running taproot update.
+# Adapters not in this list are not regenerated on update.
+agents: [claude, cursor, generic]
+
+# Validation strictness — controls what validate-format accepts.
+validation:
+  require_dates: true           # intent.md and impl.md must have Created: dates
+  require_status: true          # all marker files must have a ## Status section
+  allowed_intent_states: [draft, active, achieved, deprecated]
+  allowed_behaviour_states: [proposed, specified, implemented, tested, deprecated, deferred]
+  allowed_impl_states: [planned, in-progress, complete, needs-rework, deferred]
+
+# Definition of Done — conditions checked before taproot dod marks an impl complete.
+definitionOfDone:
+  - tests-passing
+  - linter-clean
+  - document-current: ensure all sections in readme.md are up to date
+  - run: npm run check:commits
+    name: commit-conventions
+```
+
+---
+
+## Definition of Done
+
+The `definitionOfDone` list controls what `taproot dod` checks and what the pre-commit hook enforces when you commit source code alongside an `impl.md`. Each condition must pass before an implementation can be marked `complete`.
+
+### Condition syntax
+
+| Form | What it does |
+|------|-------------|
+| `tests-passing` | Built-in: runs `npm test` (or `yarn test`). Passes if exit code is 0. |
+| `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. |
+| `check-if-affected: <file>` | Agent-verified: the agent reviews whether the given file needed updating as a result of this implementation and applies changes if needed. |
+| `check-if-affected-by: <behaviour-path>` | Agent-verified: the agent reads the referenced behaviour spec and determines whether it applies to this implementation — verifying compliance if it does, recording "not applicable" if it does not. Use for cross-cutting requirements that every implementation of a given type must satisfy (e.g. every new skill must satisfy `human-integration/contextual-next-steps`). |
+| `check: <free-form question>` | Agent-verified: the agent reads the question, reasons whether the answer is yes, no, or not applicable for this specific implementation, and takes any indicated action (e.g. adds an entry to `.taproot/settings.yaml`, documents a new pattern). The two default entries in `.taproot/settings.yaml` cover the most common meta-questions. |
+| `run: <command>` | Custom shell command. Exit 0 = pass, any other exit code = fail. |
+
+You can give any condition a custom name with `name: <label>`, which is used in DoD reports:
+
+```yaml
+definitionOfDone:
+  - run: ./scripts/check-migrations.sh
+    name: migration-safety
+```
+
+### When DoD runs
+
+DoD runs in two places:
+
+1. **`taproot dod [impl-path]`** — manually, or in CI. Pass an `impl-path` to mark the impl `complete` if all conditions pass; omit it to check all impls without writing changes.
+2. **Pre-commit hook (implementation tier)** — when you commit source files alongside an `impl.md`. The hook checks DoD in dry-run mode; if any condition fails, the commit is blocked.
+
+Results are recorded in the `## DoD Resolutions` section of `impl.md`. The section is maintained by `taproot dod` — do not edit it manually.
+
+### Built-in cross-cutting DoD conditions
+
+Taproot's own `.taproot/settings.yaml` ships with several `check-if-affected-by` conditions that enforce project-wide quality rules. These serve as reference examples:
+
+| Condition | What it enforces |
+|-----------|-----------------|
+| `check-if-affected-by: agent-integration/agent-agnostic-language` | Shared skill/spec files use generic agent language — no implicit Claude assumptions, no `@{project-root}` syntax outside adapter files |
+| `check-if-affected-by: human-integration/contextual-next-steps` | Every skill that produces output ends with a **What's next?** block |
+| `check-if-affected-by: human-integration/pause-and-confirm` | Skills that write multiple documents pause for developer confirmation between each |
+| `check-if-affected-by: skill-architecture/context-engineering` | Skill files meet context-efficiency constraints |
+| `check-if-affected-by: skill-architecture/commit-awareness` | Skills with git commit steps load the full commit skill rather than inventing ad-hoc git flows |
+| `check-if-affected-by: human-integration/pattern-hints` | Skills that receive natural language intent check `docs/patterns.md` for pattern matches |
+| `check-if-affected-by: quality-gates/architecture-compliance` | Implementations comply with `docs/architecture.md` constraints |
+
+---
+
+## 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.
+
+### Condition syntax
+
+The `definitionOfReady` conditions use the same syntax as `definitionOfDone` — bare built-in names, `run:` shell commands, `check:` agent questions, and `check-if-affected-by:` behaviour spec references. The baseline checks (usecase exists, state=specified, Flow diagram, Related section) always run regardless of what's configured here.
+
+### `check-if-affected-by:` at DoR time
+
+Use `check-if-affected-by` in `definitionOfReady` to enforce pre-implementation architecture compliance. The agent reads the referenced behaviour spec and determines whether the proposed implementation's design decisions comply before any code is written.
+
+Two built-in gates ship with taproot's default configuration:
+
+```yaml
+definitionOfReady:
+  - check-if-affected-by: quality-gates/architecture-compliance
+  - check-if-affected-by: quality-gates/nfr-measurability
+```
+
+**`quality-gates/architecture-compliance`** — requires every `impl.md` declaration to be checked against `docs/architecture.md` before implementation begins. See `docs/architecture.md` for the project's architectural decisions and constraints.
+
+**`quality-gates/nfr-measurability`** — requires every `impl.md` declaration to verify that all `**NFR-N:**` entries in the parent `usecase.md` have measurable `Then` clauses (number+unit, named standard, or testable boolean). Vague qualifiers ("fast", "secure", "reasonable") block the declaration commit. If the `usecase.md` has no `**NFR-N:**` entries, the check passes as not applicable.
+
+### `check:` at DoR time
+
+When a `check:` condition is present in `definitionOfReady`, the agent reasons about the question before making the declaration commit. The resolution is written directly into the new `impl.md` under `## DoR Resolutions`:
+
+```markdown
+## DoR Resolutions
+- condition: check: is this spec complete enough? | note: yes, all flows are specified | resolved: 2026-03-20T10:00:00.000Z
+```
+
+### 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.
+
+---
+
+## CI Integration
+
+Taproot validation runs fast (seconds) and has no external dependencies beyond Node. Adding it to CI ensures the hierarchy stays valid on every merge.
+
+### GitHub Actions
+
+```bash
+taproot init --with-ci github
+```
+
+Generates `.github/workflows/taproot.yml` that runs on every PR and push to main:
+
+```yaml
+- run: taproot validate-structure
+- run: taproot validate-format
+- run: taproot check-orphans
+```
+
+### GitLab CI
+
+```bash
+taproot init --with-ci gitlab
+```
+
+Generates a `taproot-validate` job in `.gitlab-ci.yml`. If `.gitlab-ci.yml` already exists, the job is appended — existing CI is not modified.
+
+### Keeping CONTEXT.md current on merge
+
+`taproot/CONTEXT.md` is a compact hierarchy summary for agent consumption (generated by `taproot coverage --format context`). If your agents use it for project orientation, keep it current by adding this to your post-merge pipeline:
+
+```bash
+taproot link-commits
+taproot coverage --format context
+git add taproot/CONTEXT.md && git commit -m "chore: update taproot context" || true
+```
+
+---
+
+## Language
+
+### `language`
+
+Set to a BCP-47 language code to localise taproot's structural vocabulary for non-English teams.
+
+```yaml
+language: de   # German
+```
+
+**Supported codes:** `de` (German), `fr` (French), `es` (Spanish), `ja` (Japanese), `pt` (Portuguese). Omit the field entirely for English (default).
+
+**What gets localised:**
+
+| Element | Example (de) |
+|---------|-------------|
+| Section headers in skill files | `## Actor` → `## Akteur` |
+| Gherkin keywords | `Given / When / Then` → `Gegeben / Wenn / Dann` |
+| State values | `specified / complete` → `spezifiziert / vollständig` |
+
+Localisation is applied at **`taproot update`** time — skill files and agent adapter files are regenerated with the translated vocabulary. The `validate-format` command and the pre-commit commit hook also accept the localised section names when `language` is set, so German (or French, etc.) usecase.md files pass validation without needing English headers.
+
+`impl.md` traceability fields (`## Behaviour`, `## Commits`, `## Tests`) are intentionally kept in English — they are structural links, not prose, and must remain machine-readable regardless of language setting.
+
+**Unknown language code:** `taproot update` will abort with an error listing the supported codes and make no file changes.
+
+---
+
+## Vocabulary
+
+### `vocabulary`
+
+Replace dev-specific terms in installed skill files with domain-appropriate equivalents. Useful for non-development projects (book authoring, financial reporting, legal review) where terms like "tests", "source files", or "build" don't map to project reality.
+
+```yaml
+vocabulary:
+  tests: manuscript reviews
+  source files: chapters
+  build: compile draft
+  implementation: writing
+```
+
+Applied as a second substitution pass after the language pack (if any). Re-applied on each `taproot update` run, so overrides survive skill upgrades.
+
+**Substitution semantics:**
+
+- **Declaration-order**: keys are processed in the order they appear in `settings.yaml`. Once a token is substituted, the result is not re-scanned — this prevents chained substitution.
+- **Case-sensitive**: `tests` matches `tests` but not `Tests` or `TESTS`. Use multiple keys if case variants need covering.
+- **Structural keywords protected**: keys matching section headers, Gherkin keywords, or state values (from the active language pack, or English defaults) are skipped with a warning. This prevents accidentally overriding structural vocabulary that validators depend on.
+
+**Error conditions:**
+
+- If any vocabulary key maps to an empty string, `taproot update` aborts with an error message and makes no file changes.
+- If a vocabulary key conflicts with a structural keyword, `taproot update` logs a warning for that key, skips it, and applies all non-conflicting overrides.
+
+---
+
+## Validation settings
+
+### `require_dates`
+
+When `true`, `validate-format` requires a `Created:` date in `intent.md` and `impl.md`. Useful for auditing when features were introduced. Disable in projects where historical intents were backfilled without dates.
+
+### `require_status`
+
+When `true`, all marker files must have a `## Status` section. Disable during initial migration of a large codebase where some documents are incomplete.
+
+### State lists
+
+The `allowed_*_states` lists control what values are accepted in the `State:` field of each document type. You can add custom states if your workflow requires them (e.g., `approved` between `specified` and `implemented`), but the pre-commit hook's DoR gate always checks for `specified` specifically before allowing a declaration commit — custom intermediate states will block the hook unless you adjust the DoR configuration.

package/docs/demo.svg

@@ -0,0 +1,111 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 700 420" width="700" height="420">
+  <defs>
+    <style>
+      .terminal { font-family: 'Menlo', 'Monaco', 'Consolas', 'Courier New', monospace; font-size: 13px; }
+
+      /* cursor blink */
+      @keyframes blink { 0%,49%{opacity:1} 50%,100%{opacity:0} }
+      .cursor { fill: #e8e8e8; animation: blink 1s step-start infinite; }
+
+      /* fade in blocks */
+      @keyframes fadeIn { from{opacity:0} to{opacity:1} }
+
+      .clip1  { animation: fadeIn 0.01s 0.5s  both; opacity:0; }
+      .clip2  { animation: fadeIn 0.01s 2.2s  both; opacity:0; }
+      .clip3  { animation: fadeIn 0.01s 3.0s  both; opacity:0; }
+      .clip4  { animation: fadeIn 0.01s 3.6s  both; opacity:0; }
+      .clip5  { animation: fadeIn 0.01s 5.0s  both; opacity:0; }
+      .clip6  { animation: fadeIn 0.01s 5.8s  both; opacity:0; }
+      .clip7  { animation: fadeIn 0.01s 6.4s  both; opacity:0; }
+      .clip8  { animation: fadeIn 0.01s 7.2s  both; opacity:0; }
+      .clip9  { animation: fadeIn 0.01s 8.0s  both; opacity:0; }
+      .clip10 { animation: fadeIn 0.01s 8.6s  both; opacity:0; }
+      .clip11 { animation: fadeIn 0.01s 9.2s  both; opacity:0; }
+      .clip12 { animation: fadeIn 0.01s 9.8s  both; opacity:0; }
+      .clip13 { animation: fadeIn 0.01s 10.4s both; opacity:0; }
+      .clip14 { animation: fadeIn 0.01s 11.0s both; opacity:0; }
+      .clip15 { animation: fadeIn 0.01s 11.6s both; opacity:0; }
+      .clip16 { animation: fadeIn 0.01s 12.2s both; opacity:0; }
+
+      /* full reset loop */
+      @keyframes loopReset { 0%{opacity:1} 97%{opacity:1} 99%{opacity:0} 100%{opacity:0} }
+      .looping { animation: loopReset 14s linear infinite; }
+    </style>
+  </defs>
+
+  <!-- window chrome -->
+  <rect width="700" height="420" rx="10" fill="#1e1e1e"/>
+  <rect width="700" height="34" rx="10" fill="#2d2d2d"/>
+  <rect y="24" width="700" height="10" fill="#2d2d2d"/>
+  <circle cx="20" cy="17" r="6" fill="#ff5f57"/>
+  <circle cx="40" cy="17" r="6" fill="#febc2e"/>
+  <circle cx="60" cy="17" r="6" fill="#28c840"/>
+  <text x="350" y="22" text-anchor="middle" font-family="Menlo,monospace" font-size="12" fill="#888">taproot demo</text>
+
+  <g class="looping">
+  <g class="terminal" transform="translate(24, 60)">
+
+    <!-- npx taproot init -->
+    <g class="clip1">
+      <text><tspan fill="#7eca5c">~/myproject</tspan><tspan fill="#666"> $ </tspan><tspan fill="#e8e8e8">npx taproot init --agent claude --with-hooks</tspan></text>
+    </g>
+    <g class="clip2" transform="translate(0,22)">
+      <text><tspan fill="#7eca5c">created </tspan><tspan fill="#888"> .taproot/skills/  (18 skills)</tspan></text>
+    </g>
+    <g class="clip3" transform="translate(0,40)">
+      <text><tspan fill="#7eca5c">created </tspan><tspan fill="#888"> .taproot/settings.yaml</tspan></text>
+    </g>
+    <g class="clip4" transform="translate(0,58)">
+      <text><tspan fill="#7eca5c">installed</tspan><tspan fill="#888"> .claude/commands/  (Claude adapter)</tspan></text>
+    </g>
+    <g class="clip5" transform="translate(0,76)">
+      <text><tspan fill="#7eca5c">installed</tspan><tspan fill="#888"> .git/hooks/pre-commit</tspan></text>
+    </g>
+
+    <!-- divider -->
+    <g class="clip6" transform="translate(0,104)">
+      <text fill="#444">──────────────────────────────────────────────</text>
+    </g>
+
+    <!-- /tr-ineed -->
+    <g class="clip7" transform="translate(0,126)">
+      <text><tspan fill="#7eca5c">claude</tspan><tspan fill="#666"> › </tspan><tspan fill="#e8e8e8">/tr-ineed user authentication</tspan></text>
+    </g>
+    <g class="clip8" transform="translate(0,148)">
+      <text><tspan fill="#569cd6">Actor:  </tspan><tspan fill="#e8e8e8">Developer signing in for the first time</tspan></text>
+    </g>
+    <g class="clip9" transform="translate(0,166)">
+      <text><tspan fill="#569cd6">Need:   </tspan><tspan fill="#e8e8e8">Verify identity before accessing the app</tspan></text>
+    </g>
+    <g class="clip10" transform="translate(0,184)">
+      <text><tspan fill="#7eca5c">written </tspan><tspan fill="#888"> taproot/auth/login/usecase.md</tspan></text>
+    </g>
+
+    <!-- divider -->
+    <g class="clip11" transform="translate(0,210)">
+      <text fill="#444">──────────────────────────────────────────────</text>
+    </g>
+
+    <!-- taproot dod -->
+    <g class="clip12" transform="translate(0,232)">
+      <text><tspan fill="#7eca5c">~/myproject</tspan><tspan fill="#666"> $ </tspan><tspan fill="#e8e8e8">taproot dod taproot/auth/login/impl.md</tspan></text>
+    </g>
+    <g class="clip13" transform="translate(0,254)">
+      <text><tspan fill="#7eca5c">  ✓  </tspan><tspan fill="#888">baseline-validate-format</tspan></text>
+    </g>
+    <g class="clip14" transform="translate(0,272)">
+      <text><tspan fill="#7eca5c">  ✓  </tspan><tspan fill="#888">tests-passing</tspan></text>
+    </g>
+    <g class="clip15" transform="translate(0,290)">
+      <text><tspan fill="#7eca5c">  ✓  All checks passed. Marked </tspan><tspan fill="#4ec9b0">impl.md</tspan><tspan fill="#7eca5c"> complete.</tspan></text>
+    </g>
+
+    <!-- cursor prompt — appears after last line -->
+    <g class="clip16" transform="translate(0,315)">
+      <text><tspan fill="#7eca5c">~/myproject</tspan><tspan fill="#666"> $ </tspan></text>
+      <rect class="cursor" x="124" y="-13" width="8" height="15"/>
+    </g>
+
+  </g>
+  </g>
+</svg>

package/docs/patterns.md

@@ -0,0 +1,118 @@
+# Patterns
+
+Reusable patterns for extending and enforcing the taproot hierarchy. Each pattern solves a recurring problem — use them as building blocks rather than reinventing them.
+
+---
+
+## Cross-cutting constraint enforcement (`check-if-affected-by`)
+
+**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`.
+
+```yaml
+# .taproot/settings.yaml
+definitionOfDone:
+  - check-if-affected-by: skill-architecture/context-engineering
+```
+
+When the DoD runner encounters this condition, it instructs the agent to:
+1. Read `taproot/skill-architecture/context-engineering/usecase.md`
+2. Determine whether the current implementation is affected
+3. If yes — verify compliance and apply corrections; if no — record "not applicable" with a reason
+
+**When to use it:**
+- The rule is architectural (applies across many implementations, not one)
+- Compliance is agent-verifiable (the rule can be checked by reading the spec and the impl)
+- The rule governs *how something is built*, not *what is built*
+
+**Taproot's built-in uses:**
+
+| Condition | Spec | What it enforces |
+|---|---|---|
+| `check-if-affected-by: human-integration/contextual-next-steps` | `taproot/human-integration/contextual-next-steps/usecase.md` | Every skill that produces output ends with a **What's next?** block |
+| `check-if-affected-by: human-integration/pause-and-confirm` | `taproot/human-integration/pause-and-confirm/usecase.md` | Skills that write multiple documents pause for developer confirmation between each |
+| `check-if-affected-by: skill-architecture/context-engineering` | `taproot/skill-architecture/context-engineering/usecase.md` | Skill files meet context-efficiency constraints (description ≤50 tokens, on-demand loading, `/compact` signal) |
+
+**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`:
+   ```yaml
+   definitionOfDone:
+     - check-if-affected-by: <intent-slug>/<behaviour-slug>
+   ```
+3. On the next implementation commit, the agent reads the spec and evaluates compliance automatically
+
+**Note:** All existing `impl.md` files that were completed before the condition was added will show the condition as unresolved the next time their source files are committed. This is intentional — it backfills compliance on the next touch.
+
+---
+
+## Specific file impact tracking (`check-if-affected`)
+
+**Problem:** Certain files need manual review whenever the codebase changes — a docs index, a CLI help text, a skill guide. You want the DoD to prompt the implementer to check them, without making the check fully automated.
+
+**Pattern:** Add a `check-if-affected` entry pointing to the file.
+
+```yaml
+definitionOfDone:
+  - check-if-affected: src/commands/update.ts
+  - check-if-affected: skills/guide.md
+```
+
+The agent is asked: "Does this implementation require changes to `<file>`?" If yes, it makes the changes. If no, it records why not.
+
+**When to use it:**
+- A specific file is a known integration point that frequently needs updating
+- The check is simpler than a full behaviour spec (no complex compliance criteria)
+- Use `check-if-affected-by` when the rule is architectural; use `check-if-affected` when the concern is a specific file
+
+---
+
+## Research before speccing (`/tr-research`)
+
+**Problem:** A requirement touches an unfamiliar domain — an algorithm, a third-party protocol, an existing library ecosystem. Writing a behaviour spec without domain knowledge produces vague, incorrect, or redundant requirements.
+
+**Pattern:** Run `/tr-research <topic>` before `/tr-behaviour`. The research skill scans local resources, searches the web, and optionally grills a domain expert. It produces a structured synthesis (local sources, web sources, key conclusions, open questions, references) that can be saved as a citable document or fed directly into a spec.
+
+```
+/tr-research "satellite tracking algorithms"
+→ scan local docs, web search, expert grilling
+→ save as research/satellite-tracking-algorithms.md
+→ /tr-behaviour taproot/navigation/ "satellite tracking" (with research context)
+```
+
+`/tr-ineed` triggers research automatically when it detects a knowledge-intensive domain — so you often get this for free.
+
+**When to use it:**
+- The domain is unfamiliar (new algorithm, new protocol, new library)
+- Existing libraries may already solve the problem (avoid reinventing the wheel)
+- The spec author is not a domain expert and an expert is available to grill
+
+---
+
+## Open-ended agent questions (`check:`)
+
+**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`.
+
+```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 reveal a reusable pattern worth documenting in docs/patterns.md?"
+```
+
+The agent reads the question text, reasons whether the answer is yes, no, or not applicable for the current implementation, and calls `taproot dod --resolve "check: <text>" "<what was done or why it does not apply>"`.
+
+**When to use it:**
+- The question is project-specific (not architectural enough to justify a full spec)
+- The question has an action: if yes, the agent *does something* (adds to config, updates docs, flags a concern)
+- Use `check-if-affected-by` when the rule applies to many implementations; use `check:` for one-off reasoning prompts
+
+**Taproot's built-in defaults:**
+
+| 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 reveal a reusable pattern worth documenting in docs/patterns.md?` | Agent adds a pattern entry to `docs/patterns.md` |

package/docs/security.md

@@ -0,0 +1,95 @@
+# Security Posture
+
+This document describes taproot's security model, applicable threat categories, and recommended controls. It is derived from `research/owasp-cli-and-agentic-applicability.md` and is the authoritative reference for security decisions.
+
+---
+
+## Trust Model
+
+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.
+
+**`.taproot/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.
+
+---
+
+## OWASP Top 10 (2021) — Applicability
+
+| Category | Verdict | Rationale |
+|---|---|---|
+| A01 Broken Access Control | Not applicable | No application-level access control; OS filesystem permissions are the control |
+| A02 Cryptographic Failures | Not applicable | No passwords, tokens, or personal data stored or transmitted |
+| **A03 Injection** | **Applicable** | `shell: true` in dod/dor-runner with `settings.yaml` commands; intentional trust model — document the boundary |
+| **A04 Insecure Design** | **Applicable** | Trust model must be explicitly documented and threat-modelled |
+| **A05 Security Misconfiguration** | **Applicable** | Shipped skill files must not contain insecure defaults; reviewed before publish |
+| **A06 Vulnerable Components** | **Applicable** | npm dependencies may carry CVEs; controls: `npm audit` + lockfile + Syft + Grype in CI |
+| A07 Authentication Failures | Not applicable | No authentication — local CLI tool with no user accounts or sessions |
+| **A08 Integrity Failures** | **Applicable** | npm package integrity (provenance attestation); skill files as trusted instruction delivery |
+| **A09 Logging Failures** | **Applicable (marginal)** | DoD/DoR error output must not reproduce raw command strings from `settings.yaml` |
+| A10 SSRF | Not applicable | No HTTP requests made by taproot |
+
+---
+
+## Agentic Security Highlights
+
+These categories are Critical for taproot as an agent instruction delivery system.
+
+**LLM01 / ASI01 — Prompt Injection / Agent Goal Hijack**
+Skill files are instructions agents execute without sanitisation. A compromised or malicious skill file is a direct prompt injection and agent goal hijack vector. Controls: human review of all skill changes; DoD skill review condition (see below).
+
+**LLM03 / ASI04 — Supply Chain**
+npm is the delivery vector for skill files. A compromised npm package delivers malicious agent instructions to every user. Controls: lockfile enforcement, provenance attestation, Syft SBOM + Grype vulnerability scan in CI.
+
+**LLM05 / ASI05 — Improper Output Handling / Unexpected Code Execution**
+Taproot output (skill files, adapters) is consumed by agents as trusted input. Skills that instruct agents to execute shell commands without validation are a direct RCE vector. Controls: no shell command execution in skills without explicit validation; least-privilege principle for all agent instructions.
+
+**LLM06 — Excessive Agency**
+Skills instruct agents to take consequential actions (commit, write files, invoke commands). Every skill must follow least-privilege: request only the permissions and actions genuinely required. Over-broad instructions create an excessive agency risk.
+
+---
+
+## Supply Chain Controls
+
+Recommended controls for taproot's own CI and for projects using taproot:
+
+- **`npm audit --audit-level=high`** — fail CI on high/critical CVEs in the dependency tree
+- **Lockfile** — `package-lock.json` committed and verified; reject installs without a lockfile
+- **Syft** — generate an SBOM (Software Bill of Materials) on every release build
+- **Grype** — scan the SBOM for known vulnerabilities; fail on high/critical findings
+- **npm provenance attestation** — publish with `--provenance` so package integrity can be verified against the build pipeline
+
+---
+
+## Skill Security Guidelines
+
+All skill files (`.taproot/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`).
+
+---
+
+## Non-Applicable Categories
+
+| Category | Reason |
+|---|---|
+| A01 Broken Access Control | No application-level access control layer |
+| A02 Cryptographic Failures | No secrets, credentials, or personal data in scope |
+| A07 Authentication Failures | No user accounts or sessions |
+| A10 SSRF | No outbound HTTP requests |
+| LLM08 Vector/Embedding Weaknesses | No RAG or embedding systems |
+| LLM10 Unbounded Consumption | No LLM inference; no resource consumption risk |
+| ASI07 Insecure Inter-Agent Communication | Inter-agent orchestration is out of taproot's scope |
+
+---
+
+*See `research/owasp-cli-and-agentic-applicability.md` for the full applicability matrices and open questions.*