@imix-js/taproot 0.2.0

package/docs/cli.md

@@ -0,0 +1,226 @@
+# CLI Reference
+
+The Taproot CLI handles setup, validation, and reporting. It does not generate content — that's what the agent skills do. The rule of thumb: use `/tr-*` commands when you want the AI to write or update documents; use `taproot` CLI commands to validate, report, and check structural integrity.
+
+---
+
+## Setup
+
+### `taproot init`
+
+```bash
+taproot init [--with-hooks] [--with-ci github|gitlab] [--with-skills] [--agent claude|cursor|copilot|windsurf|generic|all]
+```
+
+Initializes Taproot in the current directory. Creates `taproot/` and `.taproot/settings.yaml` if they don't exist, then installs whichever integrations you request.
+
+| Option | Effect |
+|--------|--------|
+| `--with-hooks` | Installs `.git/hooks/pre-commit` running `taproot commithook` |
+| `--with-ci github` | Generates `.github/workflows/taproot.yml` with validate-structure, validate-format, and check-orphans |
+| `--with-ci gitlab` | Generates a `taproot-validate` job in `.gitlab-ci.yml` |
+| `--with-skills` | Copies skill definitions to `.taproot/skills/`. Implied by `--agent claude` — only needed if you want skills without a Claude adapter. |
+| `--agent <name>` | Generates agent adapter files (see [Agent Setup](agents.md)) |
+
+Running `taproot init` again on an existing project is safe — it skips files that already exist and reports `exists` for each.
+
+### `taproot update`
+
+```bash
+taproot update [--with-hooks]
+```
+
+Refreshes installed agent adapters and skills to the current version. Run this after upgrading the `taproot` package.
+
+The update command also:
+- Removes stale artefacts from older Taproot layouts (e.g., the pre-v0.1 `taproot/skills/` directory)
+- Refreshes `.taproot/docs/` with the current taproot documentation (patterns, architecture, security, etc.) so agent skills have up-to-date reference material
+- Runs a cross-link refresh: adds missing `## Behaviours <!-- taproot-managed -->` sections to `intent.md` files and `## Implementations <!-- taproot-managed -->` sections to `usecase.md` files, then appends any missing child links and prunes any links to non-existent files
+- Migrates old `taproot validate-structure` / `taproot validate-format` pre-commit hooks to the newer `taproot commithook` format
+
+---
+
+## Validation
+
+### `taproot validate-structure`
+
+```bash
+taproot validate-structure [--path taproot/] [--strict]
+```
+
+Verifies that the folder hierarchy follows Taproot's nesting rules:
+- Intent folders contain `intent.md` and optionally behaviour subdirectories
+- Behaviour folders contain `usecase.md` and optionally impl or sub-behaviour subdirectories
+- Implementation folders contain `impl.md` and are always leaves (no children)
+- Folder names match the allowed pattern (lowercase kebab-case)
+
+Exit 0 if valid, exit 1 with violations. Use `--strict` to treat warnings as errors.
+
+### `taproot validate-format`
+
+```bash
+taproot validate-format [--path taproot/] [--fix]
+```
+
+Validates that marker files (`intent.md`, `usecase.md`, `impl.md`) conform to their schemas — required sections present, required fields populated, state values from the allowed set. Also checks:
+
+- Every `intent.md` with child behaviour folders has a `## Behaviours <!-- taproot-managed -->` section
+- Every `usecase.md` with child impl folders has an `## Implementations <!-- taproot-managed -->` section
+- Every link in those sections resolves to an existing file (detects `STALE_LINK`)
+- `impl.md` `## Behaviour` references point to existing `usecase.md` files
+- Every `usecase.md` with child impl folders has a `## Acceptance Criteria` section (warns `MISSING_ACCEPTANCE_CRITERIA` if absent)
+- Acceptance criterion IDs (`AC-N` and `NFR-N`) are unique within their respective prefix namespace within a file (errors `DUPLICATE_CRITERION_ID` if duplicate)
+
+Use `--fix` to scaffold missing section headers automatically. This is safe to run repeatedly — it only adds what's missing, never overwrites existing content.
+
+### `taproot acceptance-check`
+
+```bash
+taproot acceptance-check [--path taproot/] [--tests <dir>] [--format json]
+```
+
+Verifies that every acceptance criterion ID (`AC-N` and `NFR-N`) defined in `## Acceptance Criteria` sections is referenced by at least one test or verification file, and that no test file references a criterion that doesn't exist in any spec.
+
+Reports three categories:
+- **Uncovered:** criterion IDs present in specs but not found in any test file (exit 1)
+- **Orphaned:** criterion IDs found in test files but not defined in any `usecase.md` (exit 1)
+- **Missing sections:** `usecase.md` files with child implementations but no `## Acceptance Criteria` section (warning only)
+
+| Option | Effect |
+|--------|--------|
+| `--path <path>` | Limit spec collection to a subtree; test files are still scanned globally |
+| `--tests <dir>` | Override test directory (repeatable; defaults to `test/`, `tests/`, `spec/`) |
+| `--format json` | Output a JSON report instead of human-readable text |
+
+Criterion ID matching is grep-based: the strings `AC-N` and `NFR-N` must appear verbatim somewhere in the test or verification file. Common patterns: `it('AC-1: ...')`, `describe('AC-3')`, `// covers AC-2`, `// NFR-1 verified by load-test/search.k6.js`. NFR-N references may point to load tests, security scan configs, or manual verification artefacts — any file containing the verbatim ID counts. Deprecated criteria (lines starting with `~~**AC-N` or `~~**NFR-N`) are excluded from the check.
+
+---
+
+## Traceability
+
+### `taproot link-commits`
+
+```bash
+taproot link-commits [--since <date|hash>] [--dry-run]
+```
+
+Scans the git log for commits matching the conventional format (`taproot(<path>): message` or `Taproot: <path>` trailer) and adds them to the `## Commits` section of the corresponding `impl.md`. Use `--dry-run` to preview changes without writing them. Use `--since` to limit the scan to recent commits.
+
+### `taproot check-orphans`
+
+```bash
+taproot check-orphans [--path taproot/] [--include-unimplemented]
+```
+
+Finds broken references across the hierarchy:
+- Source files listed in `impl.md` that no longer exist on disk
+- `## Behaviour` references in `impl.md` that point to non-existent `usecase.md` files
+- Commits in `## Commits` that are not in git history
+
+Use `--include-unimplemented` to also report behaviours with no implementations (useful for coverage gaps, not just broken links).
+
+---
+
+## Reporting
+
+### `taproot coverage`
+
+```bash
+taproot coverage [--path taproot/] [--format tree|json|markdown|context]
+```
+
+Summarizes implementation completeness across the hierarchy: how many behaviours have at least one implementation, how many are still planned. The default output is a tree view. Use `--format context` to write `taproot/CONTEXT.md` — a compact summary suitable for pasting into an agent context window.
+
+### `taproot sync-check`
+
+```bash
+taproot sync-check [--path taproot/] [--since <date>]
+```
+
+Detects staleness in two directions:
+- **Code newer than spec:** a source file in `## Source Files` has been modified more recently than the `impl.md` was last verified — the implementation may have drifted from the spec
+- **Spec newer than implementation:** a `usecase.md` was reviewed after the corresponding `impl.md` was completed — the implementation may not reflect the latest spec
+
+Run this before a release or when you suspect specs have drifted from the code.
+
+### `taproot overview`
+
+```bash
+taproot overview
+```
+
+Regenerates `taproot/OVERVIEW.md` — a compact hierarchy summary with clickable links to every intent, behaviour, and impl in the tree. The overview is the agent's entry point for orientation: agent skills read it to understand the shape of the project before drilling into individual files.
+
+### `taproot plan`
+
+```bash
+taproot plan [--format tree|json]
+```
+
+Surfaces unimplemented behaviours as work items, ordered by priority (intents with more coverage are prioritized to reach completion). Useful for sprint planning or for orienting a new contributor. The `/tr-plan` skill provides an AI-driven version with more context.
+
+---
+
+## Definition of Done
+
+### `taproot dod`
+
+```bash
+taproot dod [impl-path] [--dry-run]
+taproot dod <impl-path> --resolve <condition> --note "<text>" [--resolve <condition> --note "<text>" ...]
+```
+
+Runs all configured DoD conditions from `.taproot/settings.yaml` against the specified implementation (or all implementations if no path is given). If all conditions pass and an `impl-path` is provided, marks the impl `complete`, records the results in `## DoD Resolutions`, and automatically advances the parent `usecase.md` state from `specified` to `implemented` if it hasn't been already.
+
+Use `--resolve`/`--note` to record agent resolutions for agent-driven conditions (e.g. `document-current`, `check-if-affected`, `check-if-affected-by`). Multiple pairs can be supplied in a single invocation — conditions are paired with notes by position.
+
+See [Configuration](configuration.md) for how to define DoD conditions.
+
+---
+
+## Pre-commit Hook
+
+### `taproot commithook`
+
+```bash
+taproot commithook
+```
+
+Classifies the staged files and runs the appropriate quality gate. Installed by `taproot init --with-hooks` as the content of `.git/hooks/pre-commit` — you do not call this directly.
+
+The hook uses a three-tier classification, where the implementation tier is detected by **reverse-lookup**: the hook walks all `impl.md` files in `taproot/` and builds a map of every source file path listed in their `## Source Files` sections. Any staged file that appears in this map triggers the implementation tier. Files not tracked by any `impl.md` (e.g. `.gitignore`, CI configs) always pass as plain commits.
+
+| Staged files | Gate applied |
+|---|---|
+| Only hierarchy files (`intent.md`, `usecase.md`) | `validate-structure` + `validate-format` — hierarchy must be valid before the commit lands |
+| Only `impl.md` (no source files in map) | Definition of Ready — the parent `usecase.md` must be in `specified` state and have `## Flow` and `## Related` sections |
+| Source files found in map + `impl.md` staged | Verify only `## Status` (and `## DoD Resolutions`) changed in `impl.md`; then run DoD |
+| Source files found in map but `impl.md` NOT staged | **Blocked** — "Stage `impl.md` alongside your source files. No implementation commit should proceed without its traceability record." |
+| No tracked source files, no hierarchy or impl files | No checks; commit proceeds |
+
+The DoR gate prevents committing an implementation record before the behaviour is fully specified. The DoD gate prevents marking an implementation complete without passing the quality checks defined in `.taproot/settings.yaml`.
+
+---
+
+## Commit Convention
+
+Link commits to implementations using the conventional tag format:
+
+```
+taproot(<intent>/<behaviour>/<impl>): <message>
+```
+
+For example:
+```
+taproot(password-reset/request-reset/email-trigger): add rate limiting
+```
+
+Or use a commit trailer:
+
+```
+fix: handle missing user gracefully
+
+Taproot: password-reset/request-reset/email-trigger
+```
+
+After tagging commits, run `taproot link-commits` to update the `## Commits` section of the corresponding `impl.md` automatically. The CI integration (see [Configuration](configuration.md)) can run this on every merge.

package/docs/concepts.md

@@ -0,0 +1,268 @@
+# Document Types
+
+Taproot uses three layers, each represented by a markdown file. Every layer answers a different question:
+
+| Layer | File | Question |
+|-------|------|----------|
+| Intent | `intent.md` | *Why* does this feature exist, and for whom? |
+| Behaviour | `usecase.md` | *What* does the system do — observable, testable actions? |
+| Implementation | `impl.md` | *How* is this built — code, tests, design decisions? |
+
+This separation matters because the layers evolve at different rates. Business goals (intents) are stable. Specific use cases (behaviours) change when users give feedback. Implementations change every sprint. Keeping them separate means a code refactor doesn't invalidate a behaviour spec, and a scope change doesn't orphan an implementation.
+
+---
+
+## Intent (`intent.md`)
+
+An intent captures a business goal — the *why* behind a feature. It is written from a business perspective, not a technical one. The question it answers is: "Why are we building this at all, and how will we know it's done?"
+
+An intent contains:
+
+- **Goal** — one or two sentences on what outcome the feature delivers for the business or user
+- **Stakeholders** — who cares about this and why; their priorities often conflict, and naming them makes trade-offs explicit
+- **Success Criteria** — concrete, checkable statements; these become the acceptance criteria for the entire feature tree below this intent
+- **Constraints** — scope boundaries: things this feature must not do, or must be compatible with. Constraints are not the same as NFR criteria — they define the intent's boundaries, not quality thresholds on specific behaviours (e.g. "must not reveal whether an email is registered" is a constraint; "all endpoints must respond within 500ms" is a cross-cutting NFR and belongs in `quality-gates/`)
+- **Behaviours** — auto-maintained list of child behaviour specs (managed by `taproot update`)
+- **Status** — lifecycle state: `draft` → `active` → `achieved` → `deprecated`
+
+```markdown
+# Intent: Password Reset Without Support Contact
+
+## Goal
+Enable users to reset their password without contacting support,
+while preventing unauthorized account access.
+
+## Stakeholders
+- Product: Jane — reduce support ticket volume by 30%
+- Security: team — prevent account takeover via reset flow
+
+## Success Criteria
+- [ ] Users can request a reset link via email
+- [ ] Reset links expire after 15 minutes
+- [ ] Failed attempts are rate-limited to prevent brute force
+
+## Constraints
+- Must not reveal whether an email address is registered (prevent enumeration)
+
+## Behaviours <!-- taproot-managed -->
+- [Request Password Reset](./request-reset/usecase.md)
+- [Validate Reset Token](./validate-token/usecase.md)
+
+## Status
+- **State:** active
+- **Created:** 2024-01-15
+```
+
+---
+
+## Behaviour (`usecase.md`)
+
+A behaviour is one observable thing the system does — from the perspective of an actor trying to accomplish something. It is written in UseCase format: preconditions, main flow, alternate flows, postconditions.
+
+A behaviour spec is the contract between the intent (business goals) and the implementation (code). If you write the spec well, you can implement it without asking the product owner any more questions. If you write the code first and add a spec later, it reveals whether the code actually does what was intended.
+
+A behaviour contains:
+
+- **Actor** — who or what triggers this behaviour (a user, a scheduled job, another service)
+- **Preconditions** — what must be true before this can happen
+- **Main Flow** — the steps in the happy path, written as active-voice actions (subject + verb + object)
+- **Alternate Flows** — named variations: what if the user cancels? what if a network call fails?
+- **Postconditions** — what is true after successful completion (these should map to success criteria in the parent intent)
+- **Error Conditions** — unrecoverable failures with specific triggers and specific system responses
+- **Flow** — a Mermaid diagram of the main flow; the human-readable visual contract
+- **Related** — other behaviours that share an actor, have precondition overlap, or must precede/follow this one
+- **Implementations** — auto-maintained list of child impl records (managed by `taproot update`)
+- **Status** — lifecycle state: `proposed` → `specified` → `implemented` → `tested` → `deprecated` (or `deferred` to park without deleting)
+
+```markdown
+# Behaviour: Request Password Reset
+
+## Actor
+Registered user who has forgotten their password
+
+## Preconditions
+- User account exists and is not locked
+- User is not currently logged in
+
+## Main Flow
+1. User navigates to the login page and clicks "Forgot password"
+2. User enters their email address and submits
+3. System validates the email address format
+4. System checks whether the email exists in the database
+5. System generates a time-limited reset token and sends an email
+6. System displays a "Check your email" confirmation page
+
+## Alternate Flows
+
+### Email not registered
+- **Trigger:** Email address not found in the database at step 4
+- **Steps:**
+  1. System displays the same "Check your email" confirmation (prevent enumeration)
+  2. No email is sent
+
+### Rate limit exceeded
+- **Trigger:** More than 3 reset requests from the same email within an hour
+- **Steps:**
+  1. System returns 429 and displays a "Try again later" message
+
+## Postconditions
+- A reset token exists in the database, expiring in 15 minutes
+- A reset email has been sent to the provided address (if the account existed)
+
+## Error Conditions
+- **Email service unavailable:** System shows an inline error, does not expose service details, preserves the form so the user can retry
+
+## Flow
+```mermaid
+sequenceDiagram
+    User->>LoginPage: clicks "Forgot password"
+    User->>System: submits email address
+    System->>DB: check email exists
+    alt email found
+        System->>EmailService: send reset token
+        System-->>User: "Check your email"
+    else email not found
+        System-->>User: "Check your email" (same message)
+    end
+```
+
+## Related
+- `./validate-token/usecase.md` — must follow this flow; consumes the token generated here
+
+## Acceptance Criteria
+
+**AC-1: Reset email sent**
+- Given the user has a registered account and is not logged in
+- When they submit their email address on the forgot-password form
+- Then the system sends a reset email and displays "Check your email"
+
+**AC-2: Unregistered email — same confirmation shown**
+- Given the email address is not registered
+- When the user submits it on the forgot-password form
+- Then the system displays "Check your email" without sending an email
+
+**AC-3: Rate limit exceeded**
+- Given the user has already requested 3 resets in the last hour
+- When they submit the form again
+- Then the system returns a 429 response and displays "Try again later"
+
+**NFR-1: Reset email delivery time**
+- Given normal mail service conditions
+- When the system sends a password reset email
+- Then the email is delivered within 60 seconds (p95)
+```
+
+NFR criteria (`**NFR-N:**`) express *how well* the system must perform a behaviour — quality constraints with measurable thresholds. They live in the same `## Acceptance Criteria` section, after the functional ACs. The `NFR-` prefix is distinct from `AC-` so IDs never collide.
+
+A measurable threshold is one of:
+- A number with a unit (`200ms`, `60%`, `500 concurrent users`)
+- A named standard (`WCAG 2.1 AA`, `PCI DSS 4.0`)
+- A testable boolean condition (`account is locked`, `notification email is sent`)
+
+ISO 25010 provides a useful taxonomy for NFR categories: **performance efficiency**, **reliability**, **security**, **maintainability**, **portability**, **compatibility**, **interaction capability**. Teams are not required to use these names — any consistent label works.
+
+```markdown
+## Implementations <!-- taproot-managed -->
+- [Email Trigger](./email-trigger/impl.md)
+
+## Status
+- **State:** implemented
+- **Created:** 2024-01-20
+- **Last reviewed:** 2024-03-01
+```
+
+---
+
+## Implementation (`impl.md`)
+
+An implementation record is the traceability bridge between a behaviour spec and actual code. It is not a technical spec — that belongs in code comments or ADRs. Instead it answers: "Where in the codebase does this behaviour live, what decisions were made, and is it still current?"
+
+An implementation contains:
+
+- **Behaviour** — relative path to the parent `usecase.md`
+- **Design Decisions** — choices made during implementation that aren't obvious from the code; the *why* behind architectural choices
+- **Source Files** — the files that constitute this implementation; used by `sync-check` to detect staleness
+- **Commits** — linked by `taproot link-commits` automatically from conventional commit messages
+- **Tests** — test files that verify this behaviour; used by DoD checks
+- **DoD Resolutions** — recorded outcomes of Definition of Done checks
+- **Status** — lifecycle state: `planned` → `in-progress` → `complete` → `needs-rework`
+
+```markdown
+# Implementation: Email Trigger
+
+## Behaviour
+../usecase.md
+
+## Design Decisions
+- Generic error message regardless of email existence (prevent enumeration attacks)
+- Rate limit: 3 requests per email per hour, enforced via Redis with TTL
+- Token stored as a bcrypt hash — raw token only in the email, never logged
+
+## Source Files
+- `src/auth/password-reset.ts`
+- `src/auth/password-reset-email.ts`
+- `src/auth/reset-token.ts`
+
+## Commits
+- `a1b2c3d` — Add password reset request endpoint
+- `f4e5d6c` — Add rate limiting to reset requests
+
+## Tests
+- `test/auth/password-reset.test.ts`
+- `test/auth/reset-token.test.ts`
+
+## Status
+- **State:** complete
+- **Created:** 2024-02-01
+- **Last verified:** 2024-03-01
+```
+
+---
+
+## Nesting
+
+Behaviours can contain sub-behaviours. Use sub-behaviours when a single UseCase has distinct phases with different actors, different preconditions, or enough complexity to warrant separate testing. Sub-behaviours are still leaves relative to their parent behaviour but can have their own implementations.
+
+Implementations are always leaves — they never contain child folders.
+
+```
+taproot/
+└── password-reset/
+    ├── intent.md
+    ├── request-reset/
+    │   ├── usecase.md
+    │   └── email-trigger/
+    │       └── impl.md
+    └── validate-token/
+        ├── usecase.md
+        ├── token-validation/
+        │   └── impl.md
+        └── rate-limit-check/      ← sub-behaviour
+            ├── usecase.md
+            └── redis-check/
+                └── impl.md
+```
+
+## Document States
+
+Each document has a `State` field that tracks its lifecycle. States are validated by `taproot validate-format` and enforced by the pre-commit hook.
+
+| State | Intent | Behaviour | Implementation |
+|-------|--------|-----------|----------------|
+| `draft` | Being written, not ready for dev | — | — |
+| `active` | Feature in progress | — | — |
+| `proposed` | — | Idea, not yet specified | — |
+| `specified` | — | Fully specced, ready to implement | — |
+| `implemented` | — | Code exists | — |
+| `tested` | — | Tests passing and reviewed | — |
+| `planned` | — | — | Scoped, not started |
+| `in-progress` | — | — | Being implemented |
+| `complete` | — | — | Done; DoD passed |
+| `needs-rework` | — | — | Implementation failed DoD |
+| `achieved` | All behaviours complete | — | — |
+| `deprecated` | No longer relevant | No longer relevant | — |
+| `deferred` | — | Not pursuing for now | Not pursuing for now |
+
+The pre-commit hook uses state transitions to enforce workflow gates: you cannot declare an implementation without the parent behaviour being in `specified` state, and you cannot mark an implementation complete without passing Definition of Done checks.
+
+**Deferred items** are consciously parked — `deferred` is not a synonym for `proposed` (not started) or `needs-rework` (broken). It means "we explored or attempted this and decided to stop for now." Deferred behaviours are excluded from `taproot plan` candidates, and deferred implementations are excluded from `check-orphans` errors (missing source files, missing test files). Both are reported in a separate Parked section by `tr-status`. Use `deprecated` (not `deferred`) on intents.