@deftai/directive-content 0.55.0

package/skills/deft-directive-build/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: deft-directive-build
+description: >-
+  Build a project from scope vBRIEFs following Deft Directive framework
+  standards. Use after deft-directive-setup has generated the project
+  definition, or when the user has story vBRIEFs in vbrief/active/ ready to
+  implement. Handles scaffolding, implementation, testing, and quality checks
+  phase by phase.
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Build
+
+Implements a project from its scope vBRIEFs following Deft Directive standards.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## When to Use
+
+- After `deft-directive-setup` completes and generates `PROJECT-DEFINITION.vbrief.json`
+- User says "build this", "implement the spec", or "start building"
+- Resuming a partially-built project that has story vBRIEFs in `vbrief/active/`
+
+## Step 0 -- Implementation Preflight (#810)
+
+- ! Before starting any new implementation story or switching from one story to another, MUST run `git status --short --branch`.
+- ! If the working tree is dirty, MUST stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the target story. Ask the operator to choose one path: commit existing work, stash existing work, include existing work in the current story, or stop.
+- ⊗ Begin a new story while unrelated dirty work is present without explicit operator approval.
+- ! Resolve exactly one target story vBRIEF path by default. One story is the default implementation unit for this skill; if the user asks for a phase/epic, decompose or ask which story to start.
+- ! Batching multiple stories in one branch/PR requires explicit operator approval and a short rationale recorded in the handoff.
+- ! **Swarm-cohort dispatch carve-out**: when this skill is invoked as part of a swarm cohort allocated by `skills/deft-directive-swarm/SKILL.md`, the approved Phase 5 allocation plan satisfies the "explicit operator approval and short rationale recorded in the handoff" requirement above -- the dispatched vBRIEF paths and allocation rationale ARE the consent token. Process each assigned story sequentially under the checkpoint-commit + `task scope:complete` discipline below. Do NOT re-prompt the parent for batching approval mid-cohort -- the all-or-nothing dispatch envelope rule (`AGENTS.md` `## Multi-agent orchestration discipline (#954)`) forbids mid-scope user-approval gates.
+- ! **Structured consent-token recognition (#1378)**: the canonical recognition path for the carve-out above is the structured `## Allocation context` section of the dispatch envelope (the frozen schema in `templates/agent-prompt-preamble.md`, Story A of #1378). When that section reports `dispatch_kind: swarm-cohort` with a non-null `allocation_plan_id` AND a non-null `batching_rationale`, the consent token is satisfied mechanically -- read `cohort_vbriefs` as the authoritative file boundary and process each entry sequentially under the checkpoint-commit + `task scope:complete` discipline below, without re-prompting the parent for batching approval mid-cohort. When the `## Allocation context` section is ABSENT (pre-#1378 dispatches, solo-interactive sessions), fall back to the #1371 prose carve-out immediately above -- the prose carve-out remains the recognition path of record for un-elevated envelopes.
+- ! **Within a cohort, between stories**: the working tree MUST be clean after each story's checkpoint commit + `task scope:complete`. If `git status --short` shows uncommitted state between stories (e.g. a missed `task scope:complete` move, an unstaged file from the prior story), checkpoint-commit it and proceed -- do NOT pause to ask the operator. The dirty-tree "ask the operator" branch above applies only at the FIRST story-start of a fresh branch, where uncommitted operator work might legitimately exist.
+- ! If the target story is in `vbrief/proposed/`, run `task scope:promote -- <path>` first; if it is in `vbrief/pending/`, run `task scope:activate -- <path>`. After activation, update the path to the active-file location before preflight.
+- ! Before any code-writing tool call -- the first scaffold edit, the first `task` invocation that mutates files, or any `start_agent` dispatch that will implement scope -- MUST run `task vbrief:preflight -- <active-story-path>` (the structural intent gate; wraps `scripts/preflight_implementation.py` so the same invocation works whether deft is the project root or installed as a `deft/` subdirectory).
+
+The gate exits 0 only when the candidate vBRIEF lives in `vbrief/active/` AND `plan.status == "running"`. Any other state (pending/, proposed/, completed/, active/-with-non-running-status, malformed JSON, missing keys) exits 1 with an actionable redirect to `task vbrief:activate <path>`.
+
+- ! A non-zero exit MUST halt the skill. Surface the helper's stderr message verbatim to the user; do NOT proceed to USER.md Gate, File Reading, or any later phase.
+- ! Use canonical lifecycle tasks to satisfy this gate: `task scope:promote -- <path>` for proposed stories, `task scope:activate -- <path>` for pending stories, and the helper's idempotent companion `task vbrief:activate <path>` only when following the preflight redirect directly. Manual lifecycle moves bypass the activation contract -- use the task.
+- ⊗ Infer implementation intent from lifecycle vocabulary ("do the full PR process", "start the work", "poller agents"), branching language, or workflow shape. Workflow-shape vocabulary is NOT authorization to spawn an implementation agent (#810 surfacing event).
+- ⊗ Skip this preflight because the user said "yes", "go", or "proceed" -- affirmative continuation phrases are NOT implementation authorization unless the prior turn explicitly proposed implementation. When intent is ambiguous, ask one targeted question before invoking the gate.
+
+## Platform Detection
+
+! Before resolving any config paths, detect the host OS from your environment context:
+
+| Platform           | USER.md default path                                              |
+|--------------------|-------------------------------------------------------------------|
+| Windows            | `%APPDATA%\deft\USER.md` (e.g. `C:\Users\{user}\AppData\Roaming\deft\USER.md`) |
+| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |
+
+- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform
+
+## Pre-Cutover Detection Guard
+
+! Before proceeding with any build step, detect whether the project uses the pre-v0.20 document model **or was generated by a strategy that emitted non-conformant v0.20 output shape** (the root cause of most "build fails immediately after spec" complaints in #1166). Redirect or block with the precise remediation.
+
+### Detection Criteria
+
+A project is **pre-cutover** if ANY of the following are true. This prose mirrors the executable helper in `scripts/_precutover.py`; when in doubt, the helper is canonical.
+
+1. `SPECIFICATION.md` exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: vbrief/specification.vbrief.json -->`, and `vbrief/specification.vbrief.json` plus all five lifecycle folders exist.
+2. `PROJECT.md` exists and contains neither the legacy `<!-- deft:deprecated-redirect -->` sentinel NOR the current `Purpose: deprecation redirect` canonical-banner marker (real content, not a deprecation redirect)
+3. `vbrief/specification.vbrief.json` exists but the lifecycle folders (`vbrief/proposed/`, `vbrief/pending/`, `vbrief/active/`, `vbrief/completed/`, `vbrief/cancelled/`) do NOT exist
+4. Strategy output shape violations (run `task verify-strategy-output` -- the canonical gate -- or the direct form `python .deft/core/scripts/validate_strategy_output.py --project-root <path>` after `deft` install):
+   - Any scope vBRIEF under `vbrief/proposed/` (or other lifecycle dirs) lacks the required `YYYY-MM-DD-` date prefix in its filename (e.g. bare `scaffold.vbrief.json`).
+   - `vbrief/PROJECT-DEFINITION.vbrief.json` is missing.
+   - `vbrief/specification.vbrief.json` exists as a legacy dual-write in a user-generated project. This is tolerated only for the framework source tree or a complete post-cutover full-spec consumer where all lifecycle folders exist and `SPECIFICATION.md` is rendered from `vbrief/specification.vbrief.json`.
+
+### Action on Detection
+
+! If pre-cutover or strategy-nonconformant state is detected, **stop immediately** and display an actionable message that cites the exact validator:
+
+> "This project was generated with pre-v0.20 or non-conformant strategy output. Run the deterministic validator and follow its remediation: `task verify-strategy-output` (works in source and after `deft` package install) or `python .deft/core/scripts/validate_strategy_output.py --project-root .` . Then `task migrate:vbrief` / `task project:render` / strategy re-run as indicated."
+
+! Include specific details about what was detected (the validator output is authoritative):
+
+- Legacy specification.vbrief.json or missing lifecycle folders: "Run `task migrate:vbrief` to create the lifecycle folder structure and remove legacy dual-writes"
+- Non-date-prefixed vBRIEFs: "Re-run the emitting strategy after the v0.20 migrations (#1166 s1+s2+...) or manually rename files to `YYYY-MM-DD-<slug>.vbrief.json` and `task scope:promote`"
+- Missing `PROJECT-DEFINITION.vbrief.json`: "Run `task project:render` to generate the project definition"
+- `SPECIFICATION.md` / `PROJECT.md` without sentinel: the classic pre-cutover messages
+- Scope vBRIEF in wrong folder: "Status is '{status}' but file is in {folder}/ -- run `task scope:activate <file>` to fix"
+
+! After the validator reports clean, re-run this guard before continuing.
+
+⊗ Proceed with build when pre-cutover or strategy-nonconformant artifacts are detected -- always redirect to migration first (or run the validator) and surface the exact remediation.
+⊗ Silently ignore these artifacts or guess at fixes -- the validator (wired into `task check` and this guard) is the deterministic gate.
+
+## USER.md Gate
+
+! Before proceeding, verify USER.md exists at the platform-appropriate path
+(resolved via Platform Detection above, or `$DEFT_USER_PATH` if set).
+
+- ! If USER.md is not found: inform the user and redirect to `deft-directive-setup`
+  Phase 1 before continuing -- do not proceed without user preferences
+- ! Once USER.md exists, continue with the Cost Phase Gate below
+
+## Cost Phase Gate (#739)
+
+! Before proceeding to File Reading, verify the project has gone through the
+pre-build cost & budget transparency phase from `skills/deft-directive-cost/SKILL.md`.
+This closes the adoption-blocker surfaced by issue #739 (refs #151 umbrella) where
+users finished the spec flow and stopped at build because deft offered no cost
+signal.
+
+### Detection
+
+- ! Check for `COST-ESTIMATE.md` in the project root.
+- ! Check that the file contains a recorded decision (the **Decision recorded**
+  block populated with one of: `build`, `rescope`, `no-build`, `skip`).
+- ! For `skip`, `rescope`, or `no-build` decisions: the **Reason** field MUST be
+  populated (one or two sentences in plain language). A skip with no reason
+  recorded is treated the same as no decision.
+
+### Action
+
+- ! If `COST-ESTIMATE.md` is missing OR the **Decision recorded** block is
+  unpopulated OR a `skip`/`rescope`/`no-build` decision has no reason recorded:
+  stop immediately and redirect the user:
+
+  > "This project has not gone through the pre-build cost & budget transparency
+  > phase. Run `skills/deft-directive-cost/SKILL.md` to produce a plain-English
+  > `COST-ESTIMATE.md`, then re-run the build skill once the user has chosen
+  > build / rescope / no-build / skip(+reason)."
+
+- ! On a `build` or `skip` decision: continue with File Reading below.
+- ! On a `rescope` decision: stop and redirect the user back to spec edits
+  (chain to `skills/deft-directive-refinement/SKILL.md` to pull spec scope
+  back, or the interview), then re-run `skills/deft-directive-cost/SKILL.md`
+  before re-attempting build.
+- ! On a `no-build` decision: stop and exit; do NOT proceed to File Reading.
+  The user has explicitly stopped the project at the cost phase.
+- ⊗ Proceed to File Reading or any subsequent phase when `COST-ESTIMATE.md` is
+  missing, when the decision is unpopulated, or when a skip / rescope / no-build
+  decision has no reason recorded.
+- ⊗ Treat a `rescope` or `no-build` decision as if it were a `build` -- the
+  build skill MUST honor the recorded decision.
+
+## File Reading
+
+- ! Read in order, lazy load:
+  1. `./vbrief/active/` -- scope vBRIEFs for work items to build (required)
+  2. `./vbrief/PROJECT-DEFINITION.vbrief.json` -- project identity, tech stack, architecture
+  3. `./.planning/codebase/MAP.md` -- generated codebase orientation projection, if present (advisory)
+  4. USER.md at the platform-appropriate path (see Platform Detection) -- Personal section is highest precedence; Defaults are fallback
+  5. `deft/main.md` -- framework guidelines
+  6. `deft/coding/coding.md` -- coding standards
+  7. `deft/coding/testing.md` -- testing requirements
+  8. `deft/coding/toolchain.md` -- toolchain validation rules
+  9. `deft/languages/{language}.md` -- only for languages this project uses
+- ~ If the MAP is absent or may be stale and the current scope needs broad codebase orientation, run `task codebase:map` and `task verify:codebase-map-fresh` when those commands resolve. Treat absence/staleness as advisory unless the task edits `plan.architecture.codeStructure`, a configured provider artifact, or the generated MAP itself.
+- ! Treat `plan.architecture.codeStructure` and selected provider artifacts as authoritative. The MAP is a generated projection.
+- ⊗ Read all language/interface/tool files upfront
+- ⊗ Hand-edit `.planning/codebase/MAP.md` or block unrelated implementation solely because the MAP is stale or absent
+
+## Rule Precedence
+
+```
+USER.md Personal                  <- HIGHEST (name, custom rules -- always wins)
+PROJECT-DEFINITION.vbrief.json   <- Project-specific (tech stack, architecture, config)
+USER.md Defaults                  <- Fallback defaults (used when PROJECT-DEFINITION doesn't specify)
+{language}.md                     <- Language standards
+coding.md                         <- General coding
+main.md                           <- Framework defaults
+Scope vBRIEFs                     <- LOWEST
+```
+
+- ! USER.md Personal section always wins over any other file
+- ! For project-scoped settings, PROJECT-DEFINITION.vbrief.json overrides USER.md Defaults
+
+## Change Lifecycle Gate
+
+! Before any implementation that touches 3+ files, verify that a `/deft:change <name>` proposal exists and has been confirmed by the user:
+
+- ! Check `history/changes/` for an active `proposal.vbrief.json` matching this work
+- ! If no proposal exists: propose `/deft:change <name>` and present the change name for explicit confirmation (e.g. "Confirm? yes/no")
+- ! The user must reply with an affirmative (`yes`, `confirmed`, `approve`) — a general 'proceed', 'do it', or 'go ahead' does NOT satisfy this gate
+- ? For solo projects: this gate is RECOMMENDED but not mandatory for changes fully covered by `task check`; it remains mandatory for cross-cutting, architectural, or high-risk changes
+- ⊗ Skip this gate because the user has already said "proceed" or "go ahead"
+
+## Build Process
+
+All vBRIEFs (including those read from `vbrief/active/` and any new vBRIEFs this skill emits) MUST use `"vBRIEFInfo": { "version": "0.6" }`. The validator rejects any other version (see [`../../conventions/references.md`](../../conventions/references.md)).
+
+### Step 1: Understand the Scope
+
+- ! Read story vBRIEFs from `vbrief/active/` and `PROJECT-DEFINITION.vbrief.json`
+- ! Identify phases, dependencies, starting point from scope vBRIEF acceptance criteria
+- ~ Use `.planning/codebase/MAP.md`, when present, to orient broad codebase scanning. If the MAP conflicts with current code or canonical metadata, surface the drift and trust `plan.architecture.codeStructure` / provider artifacts plus the working tree over generated prose.
+- ! When scanning the existing codebase during scope understanding, MUST surface any contradicting patterns (two error-handling shapes, two state-management approaches, two naming conventions, etc.) before implementation begins -- apply `coding/hygiene.md` `## Surface Conflicts: Pick One, Explain, Flag the Other (#1005)` and choose ONE pattern (more recent OR more tested), explain the choice in the scope summary, and flag the other for cleanup
+- ⊗ Begin implementation against an averaged blend of two contradicting patterns -- "average code that satisfies both rules is the worst code" (#1005)
+- ! Present brief summary to user:
+
+> "Here's what I see: {N} story vBRIEFs in active/. I'll start with {name}. Ready?"
+
+### Step 2: Verify Toolchain
+
+- ! Before any implementation, verify all tools required by this project are installed and functional — see `deft/coding/toolchain.md` for full rules
+- ! At minimum: confirm task runner (`task --version`), language compiler/runtime, and platform SDK (if applicable) are available
+- ! If any required tool is missing, stop and report — do not proceed to Step 3
+- ⊗ Assume tools are available because the spec references them
+
+### Step 3: Build Phase by Phase
+
+For each phase:
+
+1. ! **Scaffold** — file structure, dependencies, config
+2. ! **Test first** — write tests before implementation (TDD)
+3. ! **Implement** — make tests pass, following deft coding standards
+4. ! **Verify** — run `task check`, fix any issues
+5. ! **Checkpoint** — tell user what's done, what's next
+
+- ⊗ Move to next phase until current phase passes all checks
+
+### Step 4: Quality Gates
+
+After EVERY phase:
+
+```bash
+task check          # Format, lint, type check, test, coverage
+task test:coverage  # >=85% or PROJECT-DEFINITION.vbrief.json override
+```
+
+- ! Phase is NOT done until `task check` passes
+- ⊗ Skip quality gates or claim they passed without running
+
+## Coding Standards (Summary)
+
+Read full files when you need detail:
+
+- ! TDD: write tests first — implementation incomplete without passing tests
+- ! Coverage: ≥85% lines, functions, branches, statements
+- ~ Files: <300 lines ideal, <500 recommended, ! <1000 max
+- ~ Naming: hyphens for filenames unless language idiom dictates otherwise
+- ! Contracts first: define interfaces/types before implementation
+- ! Secrets: in `secrets/` dir with `.example` templates; ⊗ secrets in code
+- ! Commits: Conventional Commits format; ! run `task check` before every commit
+
+See `deft/coding/coding.md` and `deft/coding/testing.md` for full rules.
+
+## Pre-Commit File Review
+
+! Before every commit, re-read ALL modified files and explicitly check for:
+
+1. ! **Encoding errors** -- em-dashes corrupted to replacement characters, BOM artifacts, mojibake from round-trip read/write
+2. ! **Unintended duplication** -- accidental double entries in CHANGELOG.md, scope vBRIEF files, or structured data files
+3. ! **Structural issues** -- malformed CHANGELOG entries, broken table rows, mismatched index entries, invalid JSON/YAML
+4. ! **Semantic accuracy** -- verify that counts, claims, and summaries in CHANGELOG entries and ROADMAP changelog lines match the actual data in the commit (e.g. "triaged 4 issues" must match the number actually triaged, issue numbers cited must match the issues actually added)
+5. ! **Semantic contradictions** -- when adding a `!` or `⊗` rule that prohibits a specific command, pattern, or behavior, search the same file for any `~`, `≉`, or prose that recommends or permits the same command/pattern -- resolve all contradictions in the same commit before pushing
+6. ! **Strength duplicates** -- when strengthening a rule (e.g. upgrading `~` to `!`), grep for the term in the full file and verify no weaker-strength duplicate remains
+7. ! **Forward test coverage** -- for each new source file in this PR (`scripts/`, `src/`, `cmd/`, `*.py`, `*.go`), verify a corresponding test file exists in the same PR; running existing tests is not sufficient for new code
+
+⊗ Commit without re-reading all modified files first.
+
+## Commit Strategy
+
+- ! Default to one story per branch/PR. Batching multiple stories in one branch requires explicit operator approval and a short rationale.
+- ! Create a checkpoint commit after each completed story before beginning another story.
+- ! Run `task check` before committing
+- ⊗ Claim checks passed without running them
+
+```
+feat(phase-1): scaffold project structure
+feat(phase-1): implement core data models with tests
+feat(phase-2): add REST API endpoints with integration tests
+```
+
+## Error Recovery
+
+- ! Tests fail → fix them; ⊗ skip or weaken assertions
+- ! Coverage drops → write more tests; ⊗ exclude files
+- ! Lint/type errors → fix them; ≉ add ignore comments without documented reason
+- ! Scope vBRIEF ambiguous -> ask user; ⊗ guess
+- ! Scope needs changes -> propose, get approval, update the scope vBRIEF first
+
+## Completion
+
+- ! When all phases pass and `task check` is green, complete each implemented story via `task scope:complete -- <active-story-path>` before final PR handoff.
+
+> "The project is built and all quality checks pass. Describe any new features you'd like to add — I'll follow the deft standards we've set up."
+
+## Anti-Patterns
+
+- ⊗ Skip tests or write them after implementation
+- ⊗ Ignore `task check` failures
+- ⊗ Implement things not in scope vBRIEF without asking
+- ⊗ Read every deft file upfront
+- ⊗ Move to next phase before current passes checks
+- ⊗ Make commits without running `task check`
+- ⊗ Proceed without USER.md -- always run the USER.md Gate first
+- ⊗ Spawn an implementation agent or invoke a code-writing tool against a vBRIEF that has not passed `task vbrief:preflight` (which wraps `scripts/preflight_implementation.py`) -- always run the Step 0 Implementation Preflight (#810) first; satisfy via `task vbrief:activate <path>`
+- ⊗ Proceed without `COST-ESTIMATE.md` and a recorded build / rescope / no-build / skip(+reason) decision -- always run the Cost Phase Gate (#739) first
+- ⊗ Proceed with implementation when the build or test toolchain is unavailable -- always run the Toolchain Gate (Step 2) first
+- ⊗ Proceed to next task or phase without tests passing -- testing is a hard gate, not a cleanup step
+- ⊗ Skip the Change Lifecycle Gate because the user said "proceed" -- broad approval does not satisfy the confirmation gate
+- ⊗ Commit or push directly to the default branch -- always create a feature branch first. Exception: user explicitly instructs a direct commit, or `PROJECT-DEFINITION.vbrief.json` narratives contain `Allow direct commits to master: true`
+- ⊗ Add a prohibition (`!` or `⊗`) without scanning the same file for conflicting softer-strength rules (`~`, `≉`) that reference the same term

package/skills/deft-directive-cost/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: deft-directive-cost
+description: >-
+  Pre-build cost & budget transparency phase. Use after the project
+  SPECIFICATION is approved and before the build skill kicks off, to produce a
+  plain-English COST-ESTIMATE.md the user can read, react to, and explicitly
+  accept, rescope, no-build, or skip with a recorded reason. Audience is non-
+  technical users; voice is dollars and whole-number bands, not spreadsheets.
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Cost
+
+Plain-English cost & budget transparency phase between SPECIFICATION
+approval and build kickoff. Closes the adoption-blocker surfaced by
+issue #739 (and issue #151 umbrella) where users finished the spec
+flow and stopped at build because deft offered no cost signal.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+## When to Use
+
+- After `skills/deft-directive-setup/SKILL.md` Phase 3 has produced an
+  approved `vbrief/specification.vbrief.json` (status `approved`)
+- Before `skills/deft-directive-build/SKILL.md` kicks off
+- When the user says "cost", "budget", "pre-build cost", "how much will
+  this cost", or asks to estimate cost before building
+
+## Audience & Voice
+
+- ! Non-technical users. Voice is plain English, dollars, and whole
+  numbers. No spreadsheets, no scientific notation, no industry jargon.
+- ! Loose ranges, not single point estimates. Express bands as **low /
+  typical / high**.
+- ⊗ Use jargon like "TCO", "burn rate", "p50", "OPEX vs CAPEX",
+  "amortised", "blended rate", "unit economics", "FTE", or any other
+  term a non-technical user is unlikely to know.
+
+Methodology lives in `references/cost-models.md`. The canonical body of
+the artifact lives in `templates/COST-ESTIMATE.md`.
+
+## Platform Detection
+
+! Before resolving any config paths, detect the host OS from your
+environment context and resolve the `USER.md` path:
+
+| Platform           | USER.md default path                                              |
+|--------------------|-------------------------------------------------------------------|
+| Windows            | `%APPDATA%\deft\USER.md` (e.g. `C:\Users\{user}\AppData\Roaming\deft\USER.md`) |
+| Unix (macOS/Linux) | `~/.config/deft/USER.md`                                          |
+
+- ! If `$DEFT_USER_PATH` is set, it takes precedence on any platform.
+
+Path resolution mirrors `skills/deft-directive-build/SKILL.md` so the
+two skills agree on the user's preferences file.
+
+## Inputs
+
+- ! `vbrief/specification.vbrief.json` MUST exist with `plan.status =
+  "approved"`. If the spec is not yet approved, stop and redirect to
+  `skills/deft-directive-setup/SKILL.md` Phase 3 / the spec approval
+  gate.
+- ~ `vbrief/PROJECT-DEFINITION.vbrief.json` (for tech-stack and
+  architecture narratives). Optional but improves the estimate.
+- ~ `templates/COST-ESTIMATE.md` (canonical artifact body).
+- ~ `references/cost-models.md` (methodology).
+
+## Phases
+
+### Phase 1 -- Read the spec & detect categories
+
+- ! Read the approved spec and the project definition.
+- ! Walk the spec and identify which cost categories apply for this
+  project: hosting / infrastructure, API / third-party fees, pre-flight
+  account sign-ups, build & maintenance time. Drop categories that do
+  not apply.
+- ~ State each category's relevance to the user in one sentence (e.g.
+  "Because the spec says we will use an LLM, the AI / LLM row applies
+  and is usually the largest swing factor").
+
+### Phase 2 -- Draft `COST-ESTIMATE.md`
+
+- ! Copy `templates/COST-ESTIMATE.md` into the project root as
+  `COST-ESTIMATE.md`.
+- ! Fill in each category with a **low - typical - high** plain-English
+  band. Use whole numbers where the precision does not matter.
+- ! State the **scale assumption** beside the typical band (e.g. "About
+  100 active users per day, each doing 5 main actions"). The same
+  project shape can be \$10 / month or \$10,000 / month depending on
+  traffic, so the assumption is required.
+- ! Roll up into a **monthly band** (low / typical / high). Keep the
+  roll-up loose -- adding a range to a range gives a range; do NOT
+  collapse to a single number.
+- ! When the high band is more than ~10x the typical band, surface a
+  **scale considerations** note explaining what would push the project
+  from typical to high (e.g. "media-heavy traffic blows up egress").
+- ! USD-only first pass. The artifact MUST say "USD" up top so
+  international users know to convert.
+- ⊗ Quote single-point estimates ("this will cost $47.12 / month").
+- ⊗ Cite live vendor pricing as if it were a guarantee. The artifact is
+  a snapshot; vendor pricing changes.
+
+### Phase 3 -- Read it back to the user
+
+- ! Show the user the **TL;DR**, the **monthly band** (low / typical /
+  high), and the **scale considerations** note (if present).
+- ~ Offer to read any other section in full on request.
+- ! Surface the explicit **decision point** menu in Phase 4.
+
+### Phase 4 -- Decision point (build kickoff confirmation menu)
+
+! Present the user with this exact, numbered menu. Per the framework
+menu rule (#767), `Discuss` and `Back` MUST be the final two numbered
+options. The four substantive choices come first.
+
+```
+This is your project's cost estimate. Pick one.
+
+1. Build              -- accept the cost and start the build phase
+2. Rescope            -- keep building but reduce cost first
+3. No-build           -- stop here; record the reason
+4. Skip               -- skip the cost phase; record a short reason
+5. Discuss            -- ask follow-up questions before deciding
+6. Back               -- return to the previous step (e.g. spec edits)
+```
+
+- ! `Discuss` MUST be option 5 and `Back` MUST be option 6 (the final
+  two numbered options) per the #767 framework rule.
+- ! The decision MUST be recorded in `COST-ESTIMATE.md` under
+  **Decision recorded** (decision, date, recorded-by, reason). The
+  reason field is REQUIRED for `rescope`, `no-build`, and `skip` (so
+  that the artifact's existence is auditable). The reason field is
+  optional for `build`.
+- ! On `Rescope`, return the user to spec edits (chain back to
+  `skills/deft-directive-refinement/SKILL.md` to pull spec scope back,
+  or the interview), then re-run this skill from Phase 1.
+- ! On `No-build`, write the decision to `COST-ESTIMATE.md`, mark the
+  spec scope vBRIEF accordingly, exit, and do NOT chain into the build
+  skill.
+- ! On `Skip`, write the decision and skip reason to `COST-ESTIMATE.md`
+  and proceed to the build kickoff.
+- ! On `Build`, write the decision to `COST-ESTIMATE.md` and proceed
+  to the build kickoff.
+- ! On `Discuss`, take questions and re-show the same menu. Do NOT
+  proceed without an explicit choice from options 1-4.
+- ! On `Back`, return to the spec / setup phase. Do NOT proceed without
+  re-running this skill.
+- ⊗ Proceed to the build skill silently without surfacing the decision
+  point to the user.
+
+## Output Targets
+
+- ! `COST-ESTIMATE.md` (in the project root). Created by Phase 2 and
+  finalised in Phase 4 with the recorded decision.
+- ~ Reference the artifact from `vbrief/PROJECT-DEFINITION.vbrief.json`
+  via a `references` entry of type `x-vbrief/spec-section` so future
+  agents discover the cost decision when re-reading the project
+  definition.
+
+## Anti-Patterns
+
+- ⊗ Quote single-point cost estimates -- always use loose plain-English
+  bands.
+- ⊗ Use industry jargon (TCO, p50, FTE, OPEX vs CAPEX, etc.) in the
+  artifact or skill prose -- the audience is non-technical.
+- ⊗ Skip the decision point -- the build skill MUST refuse kickoff
+  until the user has explicitly chosen build / rescope / no-build /
+  skip(+reason).
+- ⊗ Hide the `Discuss` and `Back` options or place them at the top of
+  the menu -- they MUST be the final two numbered options per #767.
+- ⊗ Generate `COST-ESTIMATE.md` and chain into build silently without
+  surfacing the decision point.
+- ⊗ Skip the `Skip` reason -- if the user opts to skip the cost phase,
+  the reason MUST be recorded so the artifact's existence is auditable.
+- ⊗ Cite live vendor pricing as a guarantee -- the artifact is a
+  snapshot; pricing changes over time.
+- ⊗ Localise to non-USD currency in the first pass -- USD-only is the
+  contract; international users convert manually.
+- ⊗ Promise a project will "definitely" stay within a band -- always
+  say "expected", "typical", or "in our estimate".
+
+## EXIT
+
+When the user makes a decision in Phase 4 and the decision is recorded
+in `COST-ESTIMATE.md`:
+
+- ! Confirm exit explicitly: `deft-directive-cost complete -- exiting skill.`
+- ! State the next step based on the decision:
+  - `Build` or `Skip` -> chain into `skills/deft-directive-build/SKILL.md`
+  - `Rescope` -> chain into `skills/deft-directive-refinement/SKILL.md`
+    for targeted spec edits, then re-run this skill
+  - `No-build` -> exit; do NOT chain into build
+  - `Discuss` -> remain in this skill until the user picks 1-4
+  - `Back` -> chain back to the previous skill (spec / setup)
+
+⊗ Exit this skill silently without confirming completion or providing
+next-step instructions.

package/skills/deft-directive-debug/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: deft-directive-debug
+description: >-
+  Systematic, evidence-based root-cause investigation. Use when the user asks
+  "why did X break / slow down / regress?", wants to debug a failure, run a
+  forensic investigation, or find the root cause of a bug -- to enter a
+  sustained investigation MODE with a claim ledger, mandatory falsification
+  before any conclusion, a chat answer-embargo until evidence closes, and a
+  deterministic validator gate. Triggers: "debug", "root cause",
+  "investigate", "why did X break", "why is X slow", "systematic debugging",
+  "forensic".
+---
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered skill -->
+<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
+
+# Deft Directive Debug
+
+Turns "why did X break / slow down?" into a disciplined investigation rather
+than a guess-and-check loop. The coding standard this skill operationalizes is
+`coding/debugging.md` (the Iron Law, four phases, evidence discipline). This
+skill adds the sustained MODE, the claim ledger, falsification waves, and the
+deterministic close gate.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+The concrete reference design is vendored read-only under
+`docs/reference/forensic-research/` -- read it for extended detail (orchestrator
+protocol, sub-agent prompts, question framing, domain packs). This skill is the
+directive-native, freshly-authored workflow; do not repurpose the vendored copy
+as the live skill.
+
+## When to Use
+
+- The user asks "why did X break / regress / slow down?" and the cause is not
+  yet known with evidence.
+- A bug needs root-cause analysis before a fix is written.
+- An incident or production anomaly needs a disciplined, auditable investigation.
+- ⊗ Do NOT use for known, trivially-fixed issues where the cause is already
+  proven -- the four-phase loop in `coding/debugging.md` suffices.
+
+## The Iron Law
+
+```
+NO CONCLUSIONS WITHOUT EVIDENCE THAT CLOSES
+```
+
+- ! MUST NOT state a root cause in chat until the evidence supporting it closes
+  and the cheapest disproof has been attempted (the chat answer-embargo).
+- ! Every factual claim cites evidence (file:line / log / metric / reproduction).
+  An uncited claim is a `[HYPOTHESIS]`, not a finding. See `coding/debugging.md`
+  `## Evidence Discipline`.
+
+## Forensic MODE Contract
+
+The investigation is a sustained posture across turns, not a one-shot answer.
+
+- ! On entry, create an investigation directory `.tmp/investigations/<id>/`
+  (gitignored, ephemeral) and write the ledger `investigation.vbrief.json` from
+  `docs/reference/forensic-research/templates/investigation.vbrief.json`. Stamp
+  `plan.status = "running"`.
+- ! While MODE is active, every turn appends evidence to the ledger before any
+  narrative. The ledger is the source of truth; chat is a view of it.
+- ! On exit, the ledger MUST pass `task verify:investigation -- --ledger <path>`
+  (the close gate) BEFORE any root-cause conclusion is delivered. Set
+  `plan.status` to `completed` / `failed` and record the Outcome.
+- ⊗ MUST NOT deliver a conclusion while `plan.status == "running"` or while the
+  validator reports hard failures.
+
+## The Claim Ledger
+
+The ledger is a thin vBRIEF 0.6 profile (`forensic-research-v1`):
+
+- ! Top-level `plan.items[]` are **branches** (competing theories). Each branch's
+  child `items[]` are **claims** (testable assertions).
+- ! Each claim carries `metadata.x-claim` with `evidenceRefs[]` (ids into
+  `plan.references[]`) and, when ruled out, a `ruledOutReason`.
+- ! `plan.edges[]` of type `invalidates` link a falsified claim to the branch it
+  rules out -- a branch is ruled out ONLY by a falsified child claim, never by
+  "no evidence found".
+- ! `metadata.x-investigation.wavesCompleted` records which waves ran.
+
+## Investigation Waves
+
+Run the waves in order. Each works solo (one agent) or parallel (sub-agents per
+`docs/reference/forensic-research/references/orchestrator-protocol.md`).
+
+1. ! **Frame** -- parse the operator question; split dual questions ("why slow AND
+   why errored") into separate branches. Reproduce the failure. Seed branches.
+2. ! **Investigate branches** -- gather evidence at component boundaries; trace
+   data flow backward from the symptom. Promote claims with `evidenceRefs`.
+3. ! **Falsify** -- for the leading theory, attempt the cheapest test that would
+   disprove it. A theory that survives a real disproof attempt is stronger than
+   one merely asserted. Record `wavesCompleted["3"] = true`.
+4. ! **Red-team** -- adversarially review the surviving theory: config-is-not-code
+   checks, tautology checks, alternative mechanisms. Record
+   `wavesCompleted["4"] = true`.
+5. ! **Synthesize** -- only after the close gate passes, write the Outcome.
+
+- ⊗ MUST NOT skip waves 3 + 4. Skipping falsification + red-team is the #1
+  forensic-discipline failure; the close gate fails closed when either is missing.
+
+## Fact vs Hypothesis Labeling
+
+- ! Every finding is labeled **Fact** (observable, evidence-cited) or
+  **Hypothesis** (an interpretation that could be wrong). This is the
+  debugging-side adoption of the shared findings vocabulary owned by #1580.
+
+## Outcome
+
+When the close gate passes, write the Outcome from
+`docs/reference/forensic-research/references/outcome-template.md`. It MUST include:
+
+- ! The root-cause **mechanism** (not a tautology -- "slow because phase X took N
+  minutes" is not a mechanism; name *why* phase X took N minutes).
+- ! For "why slow?" investigations, a "Why it was slow" section naming the
+  mechanism.
+- ! An **Observability gaps** section: when the cause was reached by inference,
+  state what could not be measured and what to log/measure next time.
+
+## Skill Completion Gate
+
+! When the Outcome is delivered and the ledger has passed the close gate, confirm
+exit unambiguously: "deft-directive-debug complete -- exiting skill." Then state
+the next step (e.g. open a fix vBRIEF for the proven cause, or chain into
+`skills/deft-directive-build/SKILL.md` to implement the fix).
+
+⊗ Exit silently without confirming completion.
+
+## Anti-Patterns
+
+- ⊗ Delivering a conclusion before the close gate passes (breaks the answer-embargo)
+- ⊗ Fixing before reproducing the failure
+- ⊗ Marking a branch "ruled out" without an `invalidates` edge from a falsified claim
+- ⊗ Presenting a duration or exit status as a root cause (tautology)
+- ⊗ Inferring a runtime/config value from source code instead of proving it at runtime
+- ⊗ Skipping the Falsify or Red-team wave under time pressure
+- ⊗ Treating "no evidence found" as "ruled out" -- it resolves to `unknown`