@deftai/directive-content 0.55.0

package/verification/integration.md

@@ -0,0 +1,76 @@
+# Integration Checking
+
+Verify that features work together as a system, not just individually.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [verification/verification.md](./verification.md) | [contracts/boundary-maps.md](../contracts/boundary-maps.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) integration-checker model.
+
+---
+
+## Core Principle
+
+Individual features can pass verification while the system is broken. A component can exist without being imported. An API can exist without being called. **Existence ≠ integration.**
+
+---
+
+## When to Check
+
+- ! After completing 2+ features that should connect
+- ! Before marking a release as done
+- ~ After any feature that produces exports consumed by other features
+- ? After single isolated features with no upstream/downstream
+
+## 4 Integration Checks
+
+### 1. Export → Import
+
+- ! For each feature's declared **produces** (from boundary maps), verify downstream features import them
+- ! Imports must be **used**, not just declared — an unused import is not integration
+- ~ Use `rg` or `ast-grep` to verify import + usage
+
+```bash
+# Check if feature 1's export is used by feature 2
+rg "import.*generateToken" src/ --type ts
+rg "generateToken" src/ --type ts | rg -v "import|export"
+```
+
+### 2. API → Consumer
+
+- ! Every API route has at least one consumer (UI component, CLI command, test, or external client)
+- ! Verify the consumer actually calls the route (fetch, axios, curl — not just a comment)
+- ⊗ Orphaned API routes — routes that exist but nothing calls them
+
+### 3. Auth Protection
+
+- ! Pages/routes requiring auth actually check auth (middleware, hooks, guards)
+- ! Protected API endpoints verify tokens/sessions before processing
+- ~ Check for redirect-on-no-auth behavior in protected UI routes
+
+### 4. E2E Flow Tracing
+
+- ~ For each user-observable flow (from demo sentences), trace the full path:
+  - UI action → API call → data operation → response → UI update
+- ! Each link in the chain must be real code, not a stub
+- ! Use verification ladder Tier 3 (behavioral) when possible
+
+---
+
+## Integration Report
+
+Record per-release in vBRIEF or `docs/integration/`:
+
+- **Connected**: export + consumer confirmed
+- **Orphaned**: export exists, no consumer found
+- **Broken**: consumer references export that doesn't exist
+
+---
+
+## Anti-Patterns
+
+- ⊗ Declaring integration complete because all features individually pass
+- ⊗ Skipping integration checks on "simple" multi-feature releases
+- ⊗ Orphaned routes/components left in codebase after feature changes
+- ⊗ Trusting boundary maps without verifying actual code

package/verification/plan-checking.md

@@ -0,0 +1,85 @@
+# Plan Checking
+
+Pre-execution verification — catch bad plans before they become bad code.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [verification/verification.md](./verification.md) | [contracts/boundary-maps.md](../contracts/boundary-maps.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) plan-checker model.
+
+---
+
+## Core Principle
+
+A bad plan caught before execution is 10x cheaper than bad code caught after. Verify plans **will** achieve goals, not just that they look complete.
+
+---
+
+## When to Check
+
+- ! Before executing any multi-task plan
+- ~ Before executing single-task plans for high-risk features
+- ? Skip for trivial tasks (single file, obvious change)
+
+## 4 Verification Dimensions
+
+### 1. Coverage — Every requirement has task(s)
+
+- ! Extract requirements from the spec/PRD
+- ! Verify each requirement maps to at least one task
+- ! Flag requirements with zero coverage
+- ⊗ One vague task covering multiple requirements ("implement auth" for login + logout + sessions)
+
+### 2. Completeness — Every task has acceptance criteria + verify command
+
+- ! Every task has observable acceptance criteria (truths, artifacts, key links)
+- ! Every task producing code has a **verify command** — a specific command that proves it works
+- ⊗ Tasks with only steps and no acceptance criteria
+- ⊗ Tasks where "verify" is just "review the code"
+
+**Verify command examples:**
+```
+verify: pytest tests/test_auth.py -v
+verify: curl -s localhost:3000/api/health | jq .status
+verify: task test:coverage  # must show ≥85%
+```
+
+### 3. Wiring — Artifacts are connected, not just created
+
+- ! Check that planned artifacts import/consume each other
+- ! Planned API routes have planned consumers (UI, CLI, tests)
+- ! Planned components are imported in planned pages/routes
+- ⊗ Isolated artifacts — a file that exists but nothing references it
+
+### 4. Scope — Plan fits in context budget
+
+- ~ **2–3 tasks per plan** is ideal
+- ! **5+ tasks** in a single plan is a blocker — split it
+- ~ **5–8 files** modified per plan is ideal
+- ! **15+ files** in a single plan is a blocker — split it
+- ! Complex work (auth, payments, data migrations) gets its own plan, not a subtask
+
+---
+
+## Plan Check Output
+
+Record in `./vbrief/plan.vbrief.json` as a narrative on the plan item:
+
+```
+Coverage:    4/4 requirements covered ✓
+Completeness: 3/3 tasks have verify commands ✓
+Wiring:      2 key links verified ✓
+Scope:       3 tasks, 7 files ✓
+```
+
+If any dimension fails: revise plan before execution.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Executing a plan that failed any dimension
+- ⊗ Plans without verify commands ("we'll test it later")
+- ⊗ One mega-plan for an entire feature (split into per-feature plans)
+- ⊗ Checking plans after execution (defeats the purpose)

package/verification/uat.md

@@ -0,0 +1,60 @@
+# User Acceptance Testing (UAT)
+
+Auto-generated, human-readable verification scripts for completed work units.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [verification/verification.md](./verification.md) | [coding/testing.md](../coding/testing.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) UAT model.
+
+---
+
+## Core Principle
+
+When the agent says "done," the user needs a way to **see it with their own eyes** — without reading code.
+
+---
+
+## When to Generate
+
+- ! Generate a UAT script when a feature completes
+- ~ Generate on release completion as a rollup
+- ? Generate per-task for high-risk changes
+
+## UAT Script Format
+
+```markdown
+## UAT: [Feature Name]
+Date: YYYY-MM-DD
+
+### Test 1: [Scenario Title]
+**Do:**
+1. [Specific action — copy-pasteable command or UI step]
+2. [Next action]
+
+**Expected:**
+- [Exact observable outcome — specific text, URL, behavior]
+- [What success looks like, not "it should work"]
+```
+
+## Guidelines
+
+- ! Every step is a **specific action** — copy-pasteable command or precise UI instruction
+- ! Every expected result describes **what you see** — exact text, URL, behavior
+- ! Derive tests from the feature's acceptance criteria and demo sentence
+- ⊗ Include implementation details the user doesn't need ("verify JWT is valid")
+- ⊗ Use vague expectations ("it should work", "page loads correctly")
+- ~ Cross-reference against task summaries for what was actually built
+
+## Workflow
+
+- ! UAT generation is **non-blocking** — agent writes the script and moves on
+- ~ User tests when convenient (between features, end of release, whenever)
+- ! If UAT reveals issues, create fix tasks — don't block the pipeline
+- ~ Keep UAT scripts in `docs/uat/` or alongside the feature artifacts
+
+## vBRIEF Integration
+
+- ~ Reference UAT script path in the vBRIEF feature/release summary narrative
+- ~ On UAT failure, create vBRIEF fix items with `blocked` status and failure narrative

package/verification/verification.md

@@ -0,0 +1,117 @@
+# Agent Work Verification
+
+Goal-backward verification of agent output — check outcomes, not checklists.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [coding/testing.md](../coding/testing.md) | [verification/uat.md](./uat.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) verification model.
+
+---
+
+## Core Principle
+
+"All steps done" is **not** verification. Checking actual outcomes is.
+
+- ! Verify **observable results**, not process completion
+- ⊗ Mark a task done because its steps were followed
+- ! Every task defines **acceptance criteria** before work begins
+
+---
+
+## Acceptance Criteria
+
+Three subcategories of verifiable outcomes:
+
+### Truths (Behavioral)
+
+Observable behaviors that must be true after task completion.
+
+- ! State as testable assertions: "User can sign up with email and password"
+- ! Require running commands, checking output, or observing behavior to confirm
+- ~ Persist truths in the task's vBRIEF item narrative
+
+### Artifacts (Files)
+
+Files that must exist with real implementation.
+
+- ! Specify: path, minimum substance (e.g., line count), required exports
+- ⊗ Accept "file exists" alone — verify it has real content
+- ! Check exports match what was promised
+
+### Key Links (Wiring)
+
+Connections between artifacts that must be present.
+
+- ! Verify imports: `route.ts` imports `generateToken` from `auth.ts`
+- ! Verify exports: modules expose what downstream consumers need
+- ~ Check that wiring is functional, not just syntactically present
+
+---
+
+## Stub Detection
+
+- ! Scan for incomplete implementations before marking done:
+  - `TODO`, `FIXME`, `HACK`, `XXX` comments
+  - `return null`, `return {}`, `return []`, `return ""` placeholders
+  - `console.log` / `print` placeholders standing in for real logic
+  - `pass` (Python), `unimplemented!()` (Rust), `panic("not implemented")` (Go)
+  - Functions under ~8 lines that return hardcoded/empty values
+- ⊗ Accept stubs as completed work
+
+## Legacy and Deprecated Code Detection
+
+- ~ When reviewing or modifying any file, scan for legacy indicators and file a hygiene task if found:
+  - Comments: `LEGACY`, `COMPAT`, `OLD_`, `# old way`, `// deprecated`, `TODO: remove`
+  - Commented-out code blocks (more than 1 line)
+  - Feature flag branches where the flag is hardcoded to always-on or always-off
+  - Parallel implementations: old and new approach coexisting without a documented migration path
+- ⊗ Leave legacy markers in place after a migration is complete; remove them in the same commit as the migration
+- ~ See [coding/hygiene.md](../coding/hygiene.md) for the full legacy removal protocol
+
+---
+
+## Verification Ladder (4 Tiers)
+
+Pick the **strongest tier reachable** for each task.
+
+### Tier 1 — Static
+
+- Files exist, line counts met, exports present, imports wired, no stubs
+- ! Always perform static verification — it is the minimum
+
+### Tier 2 — Command
+
+- Tests pass, build succeeds, lint clean
+- ~ Prefer this tier for any task that produces executable code
+
+### Tier 3 — Behavioral
+
+- Browser flows work, API responses correct, CLI output matches spec
+- ~ Use for user-facing features; run `curl`, browser checks, or CLI invocations
+
+### Tier 4 — Human
+
+- User manually verifies (see [uat.md](./uat.md))
+- ! Use **only** when tiers 1–3 cannot confirm the outcome
+- ⊗ Ask a human to verify what a `curl` or test command can check
+
+---
+
+## vBRIEF Integration
+
+- ~ Record acceptance criteria in `./vbrief/plan.vbrief.json` task narrative before execution
+- ~ Record verification tier reached in `./vbrief/plan.vbrief.json` task status/metadata
+- ~ On verification failure, set task status to `blocked` in `./vbrief/plan.vbrief.json` with failure narrative
+- ? Allow stubs only if explicitly marked as intentional scope deferral in `./vbrief/plan.vbrief.json`
+
+---
+
+## Anti-Patterns
+
+- ⊗ Marking a task done because all code was written (verify outcomes)
+- ⊗ Skipping static verification
+- ⊗ Accepting stubs as complete
+- ⊗ Asking a human to check what the agent can verify itself
+- ⊗ Verifying process ("I did steps 1–5") instead of outcomes ("user can log in")