@deftai/directive-content 0.55.0

package/strategies/map.md

@@ -0,0 +1,179 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered strategy -->
+<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every strategy: task packs:slice strategies by-trigger --trigger <kw> (or list) -->
+
+# Map Strategy
+
+Structured analysis of an existing codebase before adding features.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [core/glossary.md](../glossary.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) map-codebase workflow.
+
+---
+
+## When to Use
+
+- ! When adding features to an existing codebase the agent hasn't seen before
+- ~ When onboarding to a project with unknown conventions
+- ! When exploring an unfamiliar codebase before deciding what to build
+- ? Skip if the codebase is small (<10 files) or the agent already has context
+
+## Invocation Modes
+
+Map supports two modes, determined automatically by context:
+
+- **Standalone** -- invoked directly via `/deft:run:map` with no active interview or
+  spec workflow. Runs mapping, presents artifacts, and offers next-step options.
+- **Chained** -- invoked from the [chaining gate](./interview.md#chaining-gate) during
+  an active interview/spec workflow. Runs mapping, registers artifacts, and returns to
+  the chaining gate.
+
+The mapping workflow and artifact format are identical in both modes. Only the
+completion behavior differs (see [Completion](#completion) below).
+
+## Workflow
+
+```
+Map Codebase → Review Artifacts → Next Steps
+```
+
+Mapping produces artifacts that feed into planning so the agent **follows existing conventions** instead of inventing new ones.
+
+---
+
+## Mapping Artifacts
+
+! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
+
+Produce a single `vbrief/proposed/{project}-codebase-map.vbrief.json` with four narratives:
+
+! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+
+### `Stack` narrative -- Technology inventory
+
+- ! Languages, versions, runtimes
+- ! Frameworks and key dependencies
+- ! Build tools and package managers
+- ~ Environment configuration approach
+
+### `Architecture` narrative -- System design
+
+- ! Layers/components and their responsibilities
+- ! Data flow between components
+- ! Entry points (API routes, CLI, server start)
+- ~ Error handling strategy
+
+### `Conventions` narrative -- How code is written here
+
+- ! Naming conventions (files, functions, variables)
+- ! Import patterns and module organization
+- ! Testing patterns (framework, file naming, assertion style)
+- ! **Be prescriptive**: "Use camelCase for functions" not "some functions use camelCase"
+
+### `Concerns` narrative -- Technical debt and risks
+
+- ~ TODO/FIXME/HACK inventory with file paths
+- ~ Large files (>500 lines) that may need splitting
+- ~ Stubs and placeholder implementations
+- ~ Missing test coverage areas
+
+---
+
+## Mapping Rules
+
+- ! Include **file paths** with backticks — vague descriptions are not actionable
+- ! Write **current state only** — never what was or what you considered
+- ! Be **prescriptive** — "Use X pattern" guides future work; "X pattern is used" doesn't
+- ! Answer **"where do I put new code?"** — not just what exists
+- ⊗ Read `.env` contents or expose secrets — note existence only
+- ~ Keep each artifact under 200 lines — detail over brevity, but focused
+
+## How Artifacts Feed Downstream
+
+- ! **Planning** loads relevant mapping narratives based on feature type
+- ! **Execution** references `Conventions` narrative to match existing patterns
+- ! **Verification** uses `Concerns` narrative to avoid introducing more debt
+
+---
+
+## Completion
+
+### Artifact Registration (both modes)
+
+- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
+  - Update `completedStrategies`: increment `runCount` for `"map"`,
+    append artifact path (`vbrief/proposed/{project}-codebase-map.vbrief.json`)
+  - Append the path to the flat `artifacts` array
+- ! The mapping narratives MUST inform subsequent strategies and spec generation:
+  - `Conventions` -> implementation constraints
+  - `Architecture` -> where new code fits
+  - `Concerns` -> things to avoid or fix
+
+### Chained Mode (invoked from chaining gate)
+
+- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
+- ⊗ End the session after mapping without returning to the chaining gate
+
+### Standalone Mode (invoked directly)
+
+After presenting the mapping narratives to the user, offer next steps:
+
+```
+Mapping complete. Here's what I found:
+  - Stack: [brief summary]
+  - Architecture: [brief summary]
+  - Conventions: [brief summary]
+  - Concerns: [brief summary]
+
+Artifact: vbrief/proposed/{project}-codebase-map.vbrief.json
+
+What would you like to do next?
+
+1. Start an interview — build a specification informed by this analysis
+2. Run a discuss phase — lock key decisions using Feynman technique
+3. Run a research phase — investigate libraries, alternatives, pitfalls
+4. Done for now — review the artifact and come back later
+```
+
+- ! Present the narrative summary before offering options
+- ! If the user chooses a strategy, invoke it (the artifact persists in `vbrief/proposed/`)
+- ! If the user chooses "done", confirm the artifact location and exit cleanly
+- ~ Recommend option 1 (interview) when the user's goal is to build or extend
+- ~ Recommend option 4 (done) when the user's goal is exploration or onboarding
+
+**Handoff rule for chained strategies:** When invoking discuss or research from
+standalone map, the chaining gate does not exist. On completion of the invoked
+strategy, the agent MUST return to this standalone next-step menu instead of
+looking for `interview.md`'s chaining gate.
+
+- ! Tell the invoked strategy that the return target is the standalone map menu
+- ! After the invoked strategy completes and registers its artifacts, re-present
+  the standalone next-step options above (with updated run counts)
+
+---
+
+## Invoking This Strategy
+
+```
+/deft:run:map
+```
+
+Standalone — explore a codebase without starting an interview:
+```
+Map this codebase so I can understand it.
+```
+
+Before an interview — analysis-first, then spec:
+```
+Map this codebase, then use the interview strategy to plan [feature].
+```
+
+Or set in PROJECT-DEFINITION.vbrief.json narratives:
+```json
+"Strategy": "strategies/map.md"
+```

package/strategies/probe.md

@@ -0,0 +1,151 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered strategy -->
+<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every strategy: task packs:slice strategies by-trigger --trigger <kw> (or list) -->
+
+# Probe Strategy
+
+Stress-test a plan before committing to it — relentless interrogation until every branch of the decision tree is resolved.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/discuss.md](./discuss.md) | [strategies/interview.md](./interview.md) | [core/glossary.md](../glossary.md)
+
+> Inspired by [grill-me](https://github.com/mattpocock/skills/tree/main/grill-me) from [mattpocock/skills](https://github.com/mattpocock/skills). Adapted to directive's preparatory strategy pattern.
+
+---
+
+## When to Use
+
+- ~ Before committing to any significant design decision or architecture choice
+- ~ When a plan has been drafted but not yet stress-tested
+- ! When the user explicitly asks to be probed or challenged on their plan
+- ? Skip when the path forward is unambiguous and small in scope
+
+## Core Principle
+
+The goal is not alignment — that's `discuss`. Probe is adversarial discovery. It assumes the plan has holes and sets out to find them. Every assumption is challenged, every edge case explored, every dependency branch walked until nothing is unresolved. Where `discuss` builds consensus, `probe` finds what's missing.
+
+---
+
+## Workflow
+
+### Step 1: Establish the plan
+
+- ! Read whatever plan, design, or spec exists in the conversation context
+- ~ If no plan is in context, ask ONE question: "What's the plan you want me to probe?"
+- ~ If codebase context is relevant, explore it to answer what you can before asking
+- ⊗ Ask follow-up questions before reading available context
+
+### Step 2: Interrogate relentlessly
+
+Walk the decision tree depth-first. For each unresolved branch:
+
+- ! Ask **ONE** focused question per message
+- ! For each question, provide your recommended answer with brief reasoning
+- ! If the codebase can answer a question, explore it instead of asking the user
+- ~ Follow the thread — if an answer opens new branches, pursue them before moving on
+- ⊗ Ask multiple questions at once
+- ⊗ Accept vague answers — push back: "What does that mean concretely?"
+- ⊗ Move to the next branch before the current one is fully resolved
+
+### Question focus areas
+
+- ! **Assumptions** — "This assumes X is guaranteed — is it?"
+- ! **Edge cases** — "What happens when Y is empty / null / at the limit?"
+- ! **Dependencies** — "This requires Z to exist — what if it doesn't?"
+- ! **Failure modes** — "How does this fail? How is that surfaced to the user?"
+- ! **Scaling** — "Does this hold at 10× the expected volume?"
+- ~ **Security surface** — "Who can reach this? What's the blast radius if it's wrong?"
+- ~ **Reversibility** — "Can this decision be changed later? What's the migration cost?"
+
+### Transition criteria (probe complete)
+
+- ! All major decision branches have been resolved
+- ! No open assumptions remain
+- ~ User has acknowledged the risks of any deliberately deferred decisions
+- ~ No new branches are surfaced by the last 2–3 questions
+
+---
+
+## Output
+
+! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
+
+### Mechanical guard (`scripts/probe_session.py`)
+
+Probe completion is enforced mechanically — not by prose alone. A per-clone
+session file at `.deft/probe-session.json` records whether the session is still
+`interrogate` or `complete`, plus the probe `target`, `currentBranch`, and
+`resolvedDecisions`.
+
+- ! At probe start, record the session:
+  `uv run python scripts/probe_session.py start --target <scope>`
+- ! While interrogating, record locked/deferred/risk-accepted decisions and
+  branch focus with `record` / `set-branch` subcommands as branches resolve
+- ! Before writing probe output or registering `completedStrategies.probe`,
+  mark the session complete:
+  `uv run python scripts/probe_session.py complete`
+- ! Immediately before artifact or plan registration, run the guard:
+  - `uv run python scripts/probe_session.py guard-artifact --path vbrief/proposed/{scope}-probe.vbrief.json`
+  - `uv run python scripts/probe_session.py guard-plan-registration`
+- ⊗ Write probe artifacts or update `completedStrategies.probe` while the
+  session state is still `interrogate` — the guard exits non-zero with an
+  actionable recovery message
+
+**Recovery when the guard blocks handoff:** continue interrogation until the
+[transition criteria](#transition-criteria-probe-complete) are met, record
+decisions with `probe_session.py record`, run `probe_session.py complete`,
+then retry the guard before writing artifacts or updating `plan.vbrief.json`.
+
+`{scope}` is the project name from `PROJECT-DEFINITION.vbrief.json`, or the
+feature/component name if probing a sub-scope. Use the same value consistently
+throughout the session. Examples: `my-app-probe`, `auth-probe`.
+
+- ! Produce a `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF with three mandatory narratives:
+  - `LockedDecisions` — what was resolved and why
+  - `SurfacedRisks` — concerns raised, even if not fully resolved
+  - `DeferredDecisions` — explicitly acknowledged items with justification
+- ! Each entry in a narrative includes: **question asked**, **answer given**, **status** (locked / deferred / risk-accepted)
+- ! This vBRIEF is injected into all downstream work: planning, execution, verification
+- ! Persist significant decisions as vBRIEF narratives on the relevant plan items
+- ⊗ Write probe output to a hand-authored markdown file — use vBRIEF narratives for token-efficient, machine-consumable agent consumption (mirrors the [discuss](./discuss.md) and [research](./research.md) output contracts so the chaining-gate flow-through guarantee is mechanical, not aspirational)
+
+! After emitting the probe scope vBRIEF to `vbrief/proposed/`, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+
+---
+
+## Then: Chaining Gate
+
+After the probe is complete and `vbrief/proposed/{scope}-probe.vbrief.json` is
+written, return to the [chaining gate](./interview.md#chaining-gate).
+
+- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
+  - Update `completedStrategies`: increment `runCount` for `"probe"`,
+    append artifact path (`vbrief/proposed/{scope}-probe.vbrief.json`)
+  - Append the path to the flat `artifacts` array
+- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
+- ! The `LockedDecisions`, `SurfacedRisks`, and `DeferredDecisions` narratives from `vbrief/proposed/{scope}-probe.vbrief.json` MUST flow
+  into subsequent strategies and spec generation:
+  - Locked decisions become constraints in the specification
+  - Surfaced risks become NFRs or explicit acceptance criteria
+  - Deferred decisions appear as open questions in the spec
+- ⊗ End the session after probe without returning to the chaining gate
+  or the invoking strategy's next-step menu
+
+! **Standalone context:** If invoked from a standalone strategy (e.g. map's
+  standalone next-step menu) rather than from the interview chaining gate,
+  return to the invoking strategy's menu instead.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Accepting "we'll figure it out later" without marking it as explicitly deferred
+- ⊗ Asking generic checklist questions instead of following the decision tree
+- ⊗ Letting vague answers pass without pushing for concrete specifics
+- ⊗ Using codebase exploration as a substitute for asking the user about deliberate design choices
+- ⊗ Stopping when the conversation feels comfortable — stop when no new branches emerge
+- ⊗ Ending after probe without chaining back to the gate (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))
+- ⊗ Writing probe output to a plain markdown file (`{scope}-probe.md`) instead of the canonical `vbrief/proposed/{scope}-probe.vbrief.json` scope vBRIEF — plain markdown bypasses the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light) and breaks the downstream-consumer flow-through guarantee

package/strategies/rapid.md

@@ -0,0 +1,155 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered strategy -->
+<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every strategy: task packs:slice strategies by-trigger --trigger <kw> (or list) -->
+
+# Rapid Strategy
+
+Quick prototyping workflow -- v0.20 date-prefixed story vBRIEF output with minimal gates and fast iteration.
+
+**v0.20 note (s5-migrate-speckit-rapid-enterprise / #1166):** Rapid now emits only the canonical v0.20 shape (date-prefixed story vBRIEFs in proposed/, full PROJECT-DEFINITION.vbrief.json via task project:render, seeded lifecycle folders, no legacy specification.vbrief.json). See the dedicated ## v0.20 Output Shape section and the canonical contract `strategies/v0-20-contract.md` (s1-contract of #1166).
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/yolo.md](./yolo.md) | [strategies/README.md](./README.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [artifact-guards.md](./artifact-guards.md)
+
+> Ship a throwaway prototype fast. Skip the PRD, skip approval gates, produce a
+> date-prefixed vBRIEF in proposed/ + PROJECT-DEFINITION and start building. Suited for spikes, proof-of-concepts, and
+> disposable experiments where learning speed matters more than long-term quality.
+
+---
+
+## When to Use
+
+- ~ Throwaway prototypes, spikes, and proof-of-concept experiments
+- ~ Validating a technical approach before committing to a full spec cycle
+- ~ Solo explorations where the cost of rework is low
+- ? Time-boxed experiments (e.g. "spend 2 hours proving this works")
+- ⊗ Production features, shared libraries, or anything with downstream consumers
+
+---
+
+## Workflow
+
+### Step 1: State the Goal
+
+! Describe the prototype goal in one sentence: what are you trying to learn or prove?
+
+- ! Record the goal in a new date-prefixed story vBRIEF written to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (e.g. as the plan title or a brief narrative in the v0.6 schema). Use today's date for the prefix and a descriptive slug.
+- ~ Include a time-box if applicable (e.g. "4-hour spike")
+- ⊗ Skip this step -- even throwaway work needs a clear objective
+
+### Step 2: Minimal Interview
+
+! Ask only the questions needed to unblock implementation. Skip sizing gate, skip PRD.
+
+- ! Identify: target platform, primary language, key dependency or API
+- ~ 3-5 questions maximum -- bias toward defaults and moving fast
+- ⊗ Run the full interview questionnaire -- that defeats the purpose of rapid
+
+### Step 3: Generate date-prefixed vBRIEF in proposed/ (Forced-Light Path)
+
+! Before writing output artifacts, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for proposed/ scope items; Spec-Generating Guard for PROJECT-DEFINITION).
+
+! Write a slim story scope vBRIEF to `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` -- no PRD, no approval gate. Decompose the rapid plan into one or more focused, buildable story vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
+
+- ! Use the Light path from [interview.md](./interview.md) unconditionally
+- ! Mark `plan.status` as `draft` (not `approved`) to signal prototype quality
+- ! After the proposed/ vBRIEF(s) are written, invoke `task project:render` (from repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json`
+- ~ Keep tasks coarse-grained -- 3-5 tasks is typical for a spike
+- ⊗ Generate a PRD or require approval -- rapid skips both
+- ⊗ Hand-author `SPECIFICATION.md` directly -- it is a rendered derivative only (see v0.20 Output Shape)
+
+! After emitting the proposed/ story vBRIEF(s), surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+
+### Step 4: Build
+
+! Implement against the spec. Quality gates are relaxed but not absent.
+
+- ! Tests are still required, but coverage gate is relaxed to ≥50%
+- ~ Favour working code over clean code -- refactor later if the prototype graduates
+- ! `task check` must still pass (lint + fmt + tests)
+- ⊗ Skip `task check` entirely -- even prototypes must compile and pass basic checks
+
+### Step 5: Evaluate
+
+! At the end of the time-box (or when the prototype is done), decide next steps.
+
+- ! Record findings: what worked, what didn't, what surprised you
+- ~ Options: discard, iterate, or graduate to a full spec cycle via [interview.md](./interview.md)
+- ! If graduating: start a fresh interview -- do not carry forward the rapid spec as-is
+
+---
+
+## Output Artifacts
+
+- `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) -- lightweight story scope vBRIEF(s) with `draft` status (primary artifact; date-prefixed per v0.20 contract)
+- `vbrief/PROJECT-DEFINITION.vbrief.json` -- complete project gestalt + items registry (via `task project:render` invoked by Rapid)
+- `vbrief/{proposed,pending,active,completed,cancelled}/` -- all five lifecycle folders seeded
+- (optional derivative) `SPECIFICATION.md` -- read-only human-readable export (includes deprecated-redirect sentinel; via `task spec:render` if invoked)
+- Prototype code (may be discarded)
+- Findings summary (inline in the proposed/ vBRIEF or as a separate note)
+
+---
+
+## Fits into Chaining Gate
+
+Rapid is a **spec-generating** strategy. Selecting it at the chaining gate produces date-prefixed story vBRIEF(s) in `vbrief/proposed/` (and refreshes `vbrief/PROJECT-DEFINITION.vbrief.json` via `task project:render`) and moves directly to implementation. There is no chaining back to preparatory strategies. See the v0.20 Output Shape section below for the exact contract.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Using rapid for production features -- rapid output is explicitly throwaway
+- ⊗ Graduating a rapid prototype without a fresh spec cycle -- the shortcuts compound
+- ⊗ Running the full interview or PRD path -- that's interview strategy, not rapid
+- ⊗ Skipping `task check` -- even prototypes must pass basic quality checks
+- ⊗ Omitting the goal statement -- undirected spikes waste time
+- ⊗ Emitting the legacy singular specification artifact or bare-named vBRIEFs -- violates the v0.20 contract (see strategies/v0-20-contract.md)
+
+---
+
+## v0.20 Output Shape (s5-migrate-speckit-rapid-enterprise / #1166)
+
+This strategy has been migrated to the full v0.20 output shape so rapid-generated projects are accepted by the build skill Pre-Cutover Detection Guard with zero errors on first attempt (resolves the rapid row from the #1166 inconsistency table and the s5 story acceptance criteria).
+
+- ! Seed the five lifecycle folders under `vbrief/` if any are missing: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`.
+- ! Emit story scope items exclusively as date-prefixed scope vBRIEFs: `vbrief/proposed/YYYY-MM-DD-<kebab-slug>.vbrief.json` (use the run's creation date for the prefix; choose descriptive slugs). Decompose the rapid plan into one or more focused, buildable story vBRIEFs (v0.6 schema) rather than a monolithic legacy spec.
+- ! After the proposed/ stories are written, invoke `task project:render` (run from the repo root) to generate/refresh the complete `vbrief/PROJECT-DEFINITION.vbrief.json` (items registry is derived from the lifecycle folders).
+- ⊗ Never emit `vbrief/specification.vbrief.json` (or any legacy dual-write).
+- ~ `SPECIFICATION.md` at the project root, if produced at all, must be only a read-only derivative (e.g. via `task spec:render` after the vbriefs exist) that includes the v0.20 deprecated-redirect sentinel. The source of truth is the vbrief/ lifecycle stories + PROJECT-DEFINITION.
+- ! Before writing any proposed/ stories or PROJECT-DEFINITION, follow the guards in [artifact-guards.md](./artifact-guards.md) (Preparatory Guard for scope items in proposed/; Spec-Generating Guard for PROJECT-DEFINITION).
+- ! Final output tree must pass the deterministic v0.20 strategy output validation gate (s2-deterministic-gate) and the build Pre-Cutover Detection Guard with zero warnings/errors. See full acceptance in the s5 vBRIEF and the 1166 decomposition.
+- ! Cite the canonical contract `strategies/v0-20-contract.md` (s1-contract) for the exact shape and the per-strategy table row.
+
+---
+
+## Artifacts Summary (v0.20)
+
+**Rapid (Forced-Light path):**
+
+| Artifact | Purpose | Created By |
+|----------|---------|------------|
+| `vbrief/proposed/YYYY-MM-DD-*.vbrief.json` (one or more) | Focused story scope items (date-prefixed per vbrief convention and v0.20 contract) | Rapid |
+| `vbrief/PROJECT-DEFINITION.vbrief.json` | Project identity gestalt + complete scope items registry | `task project:render` (invoked by Rapid) |
+| `vbrief/{proposed,pending,active,completed,cancelled}/` | All five lifecycle folders seeded | Rapid |
+| (optional derivative) `SPECIFICATION.md` | Human-readable plan (includes deprecated-redirect sentinel) | `task spec:render` (if invoked) |
+
+**Pre-v0.20 / legacy artifacts that MUST NOT be produced by this strategy:**
+
+- `vbrief/specification.vbrief.json`
+- Primary handoff `SPECIFICATION.md` at project root (without sentinel)
+- Bare-named vBRIEFs in proposed/
+
+See the full table and rules in `strategies/v0-20-contract.md` (rapid row: Must Create Lifecycle Folders: Yes; Must Write PROJECT-DEFINITION: Yes; Scope vBRIEFs Location: proposed/YYYY-MM-DD-*.vbrief.json only; specification.vbrief.json: Never; SPECIFICATION.md / PROJECT.md: Omit or deprecation redirect only).
+
+---
+
+## Invoking This Strategy
+
+```
+ /deft:run:rapid [project name]
+```
+
+Or explicitly:

package/strategies/research.md

@@ -0,0 +1,155 @@
+<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
+<!-- Purpose: rendered strategy -->
+<!-- Source of truth: packs/strategies/strategies-pack-0.1.json -->
+<!-- Regenerate with: task packs:render -->
+<!-- Edit the source, not this file. Slice instead of loading every strategy: task packs:slice strategies by-trigger --trigger <kw> (or list) -->
+
+# Research Strategy
+
+Look before you leap — investigate the domain before planning.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/interview.md](./interview.md) | [strategies/discuss.md](./discuss.md) | [strategies/map.md](./map.md)
+
+> Adapted from [GSD](https://github.com/gsd-build/get-shit-done) research phase.
+
+---
+
+## When to Use
+
+- ~ Before planning a feature in an unfamiliar domain (auth, payments, real-time, etc.)
+- ~ When the feature involves libraries or APIs the agent hasn't used in this project
+- ? Skip for well-understood domains where the agent has strong existing context
+
+## Output
+
+! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
+
+Produce `vbrief/proposed/{feature}-research.vbrief.json` with two mandatory narratives:
+
+! After emitting this scope vBRIEF, surface the GitHub-issue tracking hint from [emit-hints.md](./emit-hints.md) — name all three patterns (none / `--umbrella` / `--per-vbrief`).
+
+### `DontHandRoll` narrative
+
+Problems that look simple but have existing, battle-tested solutions.
+
+- ! For each problem area, specify: **problem**, **recommended library/tool**, **why not hand-roll**
+- ! Check the project's existing dependencies first -- don't add a library when one is already available
+- ~ Consult official docs for the recommended library (use Context7 or equivalent)
+
+**Example narrative content:**
+```
+Problem: JWT validation
+Use: jose
+Rationale: Edge cases in token expiry, key rotation, algorithm confusion
+
+Problem: Email templates
+Use: react-email
+Rationale: HTML email rendering is notoriously broken across clients
+
+Problem: Rate limiting
+Use: express-rate-limit
+Rationale: IP spoofing, distributed state, Redis integration
+```
+
+### `CommonPitfalls` narrative
+
+What goes wrong in this domain, why, and how to avoid it.
+
+- ! For each pitfall: **what happens**, **why it happens**, **how to avoid it**, **warning signs**
+- ~ Informed by library docs, codebase patterns, and known failure modes
+- ~ Prioritize pitfalls that agents specifically tend to hit (stubs, missing error handling, hardcoded values)
+
+**Example narrative content:**
+```
+Pitfall: Storing plain-text passwords
+What: User passwords saved without hashing
+Why: Agent implements the happy path and forgets security
+Avoid: Use bcrypt/argon2, never store raw passwords
+Warning signs: No crypto import in auth module, password field stored as-is
+```
+
+### `IPRisk` narrative (#738)
+
+! When the project description, the `Don't Hand-Roll` survey, or the
+research notes reference third-party intellectual property (IP), the
+research phase MUST run the IP-risk heuristic from
+[`../references/ip-risk.md`](../references/ip-risk.md) -- canonical
+implementation `scripts/ip_risk.py:detect_ip_terms` -- and persist a
+plain-English `IPRisk` narrative on the research vBRIEF.
+
+The heuristic is permissive on purpose: recognizable IP names (Magic:
+The Gathering, Pokemon, etc.), fictional-universe terms (Hogwarts,
+Tatooine), branded characters, sports leagues, and trademarked products
+all trigger a hit.
+
+- ! When `detect_ip_terms` returns at least one hit, the research output
+  MUST: (1) ask the explicit monetization-intent question (personal vs
+  commercial); (2) emit `plain_risk_summary(hits, intent)` into the
+  `IPRisk` narrative; (3) plan to inject the protection scope items
+  (`ip_risk_scope_items(intent)`) at SPECIFICATION-generation time.
+- ! On `commercial` intent, surface the **non-optional** lawyer-
+  consultation recommendation in the research output -- this carries
+  forward into the interview output and the SPECIFICATION via the
+  `IPRisk` narrative.
+- ⊗ Treat the absence of detected terms as proof that the project is
+  IP-free. The heuristic only knows about the curated lists; when the
+  research scope is vague, ask the user directly whether the project is
+  based on a game / film / sports league / brand.
+- ⊗ Provide legal advice -- Deft is not a law firm. The only
+  recommendation it makes is **consult a lawyer**.
+
+---
+
+## How Research Feeds Downstream
+
+- ! **Planning** reads research before task decomposition — acceptance criteria account for pitfalls
+- ! **Execution** references "Don't Hand-Roll" — agent uses recommended libraries, not custom code
+- ~ **Verification** checks for pitfall warning signs during stub detection
+
+## Research Scope Rules
+
+- ! Research the **current feature only** — not the entire project
+- ! Time-box research — if it takes longer than the feature, scope is wrong
+- ⊗ Research as a reason to delay execution indefinitely
+- ~ Research persists as a vBRIEF in `vbrief/proposed/`
+
+---
+
+## Then: Chaining Gate
+
+After research is complete, return to the [chaining gate](./interview.md#chaining-gate)
+so the user can run additional preparatory strategies or proceed to spec generation.
+
+- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
+  - Update `completedStrategies`: increment `runCount` for `"research"`,
+    append artifact path (`vbrief/proposed/{feature}-research.vbrief.json`)
+  - Append the path to the flat `artifacts` array
+- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
+- ! The research findings MUST inform subsequent strategies and spec generation:
+  - "Don't Hand-Roll" items become constraints in the specification
+  - "Common Pitfalls" become acceptance criteria or NFRs
+- ⊗ End the session after research without returning to the chaining gate
+  or the invoking strategy's next-step menu
+
+! **Standalone context:** If invoked from a standalone strategy (e.g. map's
+  standalone next-step menu) rather than from the interview chaining gate,
+  return to the invoking strategy's menu instead.
+
+---
+
+## Workflow
+
+1. **Scope** -- Identify the domain and feature boundaries for research
+2. **Survey** -- Check existing project dependencies, official docs, and known pitfalls
+3. **Document** -- Produce `vbrief/proposed/{feature}-research.vbrief.json` with `DontHandRoll` and `CommonPitfalls` narratives
+4. **Chain** -- Return to [interview.md Chaining Gate](./interview.md#chaining-gate), or -- if invoked from a standalone strategy (e.g. map's standalone next-step menu) -- return to the invoking strategy's menu per the [standalone-context rule](#then-chaining-gate) above
+
+## Anti-Patterns
+
+- ⊗ Building custom solutions for solved problems
+- ⊗ Skipping research for unfamiliar domains ("how hard can auth be?")
+- ⊗ Research that produces a reading list instead of actionable guidance
+- ⊗ Research that doesn't flow into planning (written and never referenced)
+- ⊗ Ending after research without chaining into specification generation (chained mode; in standalone context, returning to the invoking strategy's menu satisfies the completion requirement per the [standalone-context rule](#then-chaining-gate))

package/strategies/roadmap.md

@@ -0,0 +1,9 @@
+# Roadmap Maintenance Strategy (Superseded)
+
+> **This strategy is superseded.** Roadmap maintenance is now handled by the
+> refinement skill and deterministic rendering from vBRIEF lifecycle folders.
+>
+> See **[skills/deft-directive-refinement/SKILL.md](../skills/deft-directive-refinement/SKILL.md)**
+> for issue ingest, evaluation, and promotion/demotion workflows.
+>
+> Run `task roadmap:render` to regenerate `ROADMAP.md` from `vbrief/` lifecycle folders.