@deftai/directive-content 0.55.0

package/skills/deft-roadmap-refresh/SKILL.md

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-refinement` (at `skills/deft-directive-refinement/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

package/skills/deft-setup/SKILL.md

@@ -0,0 +1,20 @@
+<!-- DEFT-PREAMBLE-V1 -->
+<!-- deft:deprecated-skill-redirect -->
+! Before any other instruction in this file or in the consumer AGENTS.md, run `python3 deft/run gate`.
+! If exit code is 0, continue.
+! Otherwise: read `deft/UPGRADING.md`, find the section whose "Applies when" clause matches the state vector printed by the gate, and follow that section verbatim. Respect any "Restart required" directive -- if present, stop and tell the user to start a fresh session after cleanup commands complete.
+
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-setup` (at `skills/deft-directive-setup/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

package/skills/deft-swarm/SKILL.md

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-swarm` (at `skills/deft-directive-swarm/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

package/skills/deft-sync/SKILL.md

@@ -0,0 +1,16 @@
+# Deprecated skill path — v0.19 → v0.20 bridge
+
+<!-- deft:deprecated-skill-redirect -->
+
+This skill path is deprecated. Read `deft/QUICK-START.md` for current routing.
+The current replacement skill is `deft-directive-sync` (at `skills/deft-directive-sync/SKILL.md`).
+
+Do not add real content here. This file exists so that stale v0.19 `AGENTS.md` files
+that reference old `deft/skills/deft-*` paths keep working through one release cycle.
+QUICK-START.md refreshes the Deft-managed section of `AGENTS.md` to the current
+v0.20 `deft-directive-*` skill paths.
+
+See:
+- [../../QUICK-START.md](../../QUICK-START.md) — agent bootstrap + upgrade detection
+- [../../UPGRADING.md](../../UPGRADING.md) — version-by-version upgrade guide
+- [../../docs/BROWNFIELD.md](../../docs/BROWNFIELD.md) — brownfield adoption / migration

package/strategies/README.md

@@ -0,0 +1,83 @@
+<!-- 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) -->
+
+# Strategies
+
+Development strategies define the workflow from idea to implementation.
+
+## Available Strategies
+
+| Strategy | Command | Type | Use Case | Phases |
+|----------|---------|------|----------|--------|
+| [interview.md](./interview.md) | `/deft:run:interview` | spec-generating | Standard projects (default) | Sizing gate: Light (Interview → SPECIFICATION) or Full (Interview → PRD → SPECIFICATION) |
+| [yolo.md](./yolo.md) | `/deft:run:yolo` | spec-generating | Quick prototyping | Auto-pilot sizing gate: Light or Full (Johnbot picks) |
+| [speckit.md](./speckit.md) | `/deft:run:speckit` | spec-generating | Large/complex projects | Principles → Specify → Plan → Phase/Epic Scope → Story Readiness → Implement |
+| [map.md](./map.md) | `/deft:run:map` | preparatory | Existing codebases | Map → Chaining Gate |
+| [discuss.md](./discuss.md) | `/deft:run:discuss` | preparatory | Alignment before planning | Feynman technique → locked decisions → Chaining Gate |
+| [probe.md](./probe.md) | `/deft:run:probe` | preparatory | Adversarial plan stress-testing | Walk decision tree → challenge assumptions → surface risks → Chaining Gate |
+| [research.md](./research.md) | `/deft:run:research` | preparatory | Pre-implementation research | Research → Don't Hand-Roll + Common Pitfalls → Chaining Gate |
+| [roadmap.md](./roadmap.md) | `/deft:run:roadmap` | preparatory | Roadmap maintenance | Discover → Triage → Cleanup |
+| [bdd.md](./bdd.md) | `/deft:run:bdd` | preparatory | Acceptance-test-first development | Scenarios → Failing Tests → Lock Decisions → Spec → Chaining Gate |
+| [rapid.md](./rapid.md) | `/deft:run:rapid` | spec-generating | Quick prototypes | Forced-Light path |
+| [enterprise.md](./enterprise.md) | `/deft:run:enterprise` | spec-generating | Compliance-heavy | Forced-Full path |
+
+## Strategy Types
+
+Every strategy has a **Type** that determines its behavior in the
+[chaining gate](./interview.md#chaining-gate):
+
+- **`preparatory`** — Produces artifacts that inform spec generation (research docs,
+  context files, mapping docs). On completion, returns to the chaining gate so the user
+  can run additional strategies or proceed to spec generation. Can be run multiple times.
+  Some preparatory strategies (currently `map.md`) also support **standalone** invocation
+  via `/deft:run:<name>` — when invoked outside an interview context, they present their
+  own next-step options instead of returning to the chaining gate. See each strategy file
+  for standalone support.
+- **`spec-generating`** — Produces v0.20-conformant output per [v0-20-contract.md](./v0-20-contract.md) (lifecycle folders + PROJECT-DEFINITION.vbrief.json + date-prefixed proposed/ scope vBRIEFs only; SPECIFICATION.md/PROJECT.md as deprecation stubs or omitted). Selecting one at the chaining gate switches the pipeline to that strategy’s spec flow.
+
+Custom strategies MUST declare their type in this table. If the `Type` column is missing,
+the chaining gate cannot include the strategy.
+
+## v0.20 Output Contract (for spec-generating strategies)
+
+All spec-generating strategies (interview, yolo, speckit, rapid, enterprise) MUST produce output conforming to [v0-20-contract.md](./v0-20-contract.md):
+
+- Five vbrief/ lifecycle folders (proposed/ pending/ active/ completed/ cancelled/)
+- vbrief/PROJECT-DEFINITION.vbrief.json (full)
+- Scope vBRIEFs ONLY as date-prefixed in vbrief/proposed/YYYY-MM-DD-*.vbrief.json
+- Never dual-write legacy vbrief/specification.vbrief.json
+- SPECIFICATION.md/PROJECT.md only as deprecation-redirect stubs (banner + sentinel) or omitted
+
+This contract is the single source of truth for s1-contract and the #1166 migrations (s3-s5). Preparatory strategies follow the same dated proposed/ rule when emitting vBRIEFs.
+
+
+## Selecting a Strategy
+
+Use a slash command:
+
+```
+/deft:run:interview my-project
+```
+
+Or specify in `project.md`:
+
+```markdown
+## Strategy
+Use [strategies/interview.md](../strategies/interview.md) for this project.
+```
+
+**Naming rule:** `/deft:run:<x>` always maps to `strategies/<x>.md`. Custom strategies follow the same pattern.
+
+## Creating Custom Strategies
+
+A strategy file defines:
+
+1. **When to use** — project types, team sizes, constraints
+2. **Workflow phases** — ordered steps with transition criteria
+3. **Artifacts** — what documents are produced
+4. **Agent behavior** — how AI should conduct each phase
+
+Name your file `strategies/<name>.md` and invoke it with `/deft:run:<name>`.

package/strategies/artifact-guards.md

@@ -0,0 +1,85 @@
+<!-- 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) -->
+
+# Artifact Idempotency Guards
+
+Shared guard rules for strategies that write to vBRIEF artifacts. Referenced by individual strategy files to prevent silent overwrites of approved or completed work.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/v0-20-contract.md](./v0-20-contract.md) | [strategies/interview.md](./interview.md)
+
+---
+
+## When to Use
+
+This file is not a standalone strategy — it is a shared guard referenced by other strategies. It activates automatically when a strategy writes to vBRIEF artifacts.
+
+- ! Referenced by spec-generating strategies: [speckit](./speckit.md), [enterprise](./enterprise.md), [rapid](./rapid.md)
+- ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)
+
+## Workflow
+
+1. Strategy reaches its output step
+2. Strategy follows the appropriate guard (Spec-Generating or Preparatory) from this file
+3. Guard checks file existence and status, prompts user if needed
+4. Strategy proceeds with the write or aborts based on user response
+
+---
+
+## Spec-Generating Guard (Full)
+
+Applies to strategies that write to `PROJECT-DEFINITION.vbrief.json` (⊗ never `specification.vbrief.json` per [v0-20-contract.md](./v0-20-contract.md)): **speckit**, **enterprise**, **rapid**.
+
+! Before writing to `vbrief/PROJECT-DEFINITION.vbrief.json`, the strategy MUST perform the following checks (⊗ Never target the legacy `specification.vbrief.json`):
+
+1. ! **Check existence**: Does the target file already exist?
+   - If NO: proceed with the write — no guard needed.
+   - If YES: continue to step 2.
+
+2. ! **Read `plan.status`**: Parse the existing file and read `plan.status`.
+
+3. ! **Status: `approved` or `completed`**: Refuse to overwrite without explicit user confirmation.
+   - ! Display: "This artifact has status `{status}`. Overwriting will reset it to `draft` and discard approved/completed state. Continue? (yes/no)"
+   - ! Accept only explicit affirmative (`yes`, `confirmed`) — not vague responses (`proceed`, `ok`, `go ahead`)
+   - ⊗ Silently overwrite an approved or completed artifact
+
+4. ! **Status: `draft` or `running`**: Warn and ask before overwriting.
+   - ! Display: "A `{status}` version of this artifact already exists. Replace it? (yes/no)"
+   - ~ If the user declines, offer to enrich (merge narratives) instead of replacing
+
+5. ! **Narrative preservation**: When overwriting `PROJECT-DEFINITION.vbrief.json`, read existing `narratives` keys first. If the strategy only writes a subset of narratives (e.g. speckit Phase 1 writes only `Principles`), merge the new narrative into the existing set — do NOT replace all narratives with only the new key.
+   - ⊗ Overwrite all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only produces a single narrative key
+
+---
+
+## Preparatory Guard (Light)
+
+Applies to strategies that write scoped vBRIEFs to `vbrief/proposed/`: **bdd**, **discuss**, **research**, **map**.
+
+! Before writing a scope vBRIEF to `vbrief/proposed/`, the strategy MUST check for existing files with the same scope or feature name:
+
+1. ! **Check for existing file**: Scan `vbrief/proposed/` for files matching the target scope/feature slug (e.g. `*-{feature}-bdd.vbrief.json`, `*-{scope}-context.vbrief.json`).
+   - If NO match: proceed with the write — no guard needed.
+   - If a match exists: continue to step 2.
+
+2. ! **Warn and ask**: Display: "A vBRIEF for this scope already exists at `{path}`. Replace it, or create a new version? (replace/new)"
+   - ! If replace: overwrite the existing file
+   - ! If new: append a numeric suffix or use today's date to create a distinct file
+
+3. ~ **Read existing decisions**: If the existing file contains a `LockedDecisions` or similar narrative, surface those decisions to the agent context so they are not lost even if the user chooses to replace.
+
+⊗ Silently overwrite an existing scope vBRIEF with the same feature/scope name without warning the user.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Writing to `PROJECT-DEFINITION.vbrief.json` without checking the file's current status (⊗ never write `specification.vbrief.json` at all per v0-20-contract.md)
+- ⊗ Silently overwriting an `approved` or `completed` artifact — this discards locked decisions and approval state
+- ⊗ Replacing all `PROJECT-DEFINITION.vbrief.json` narratives when the strategy only contributes one narrative key (e.g. `Principles`)
+- ⊗ Overwriting a scope vBRIEF in `vbrief/proposed/` without checking if one already exists for the same scope
+- ⊗ Accepting vague confirmation (`proceed`, `ok`) when the guard requires explicit confirmation for approved/completed artifacts

package/strategies/bdd.md

@@ -0,0 +1,115 @@
+<!-- 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) -->
+
+# BDD Strategy
+
+Behaviour-Driven Development -- failing acceptance tests drive requirements.
+
+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)
+
+> Acceptance tests are the specification. Write them first, let failures surface ambiguity, then lock decisions before generating a formal spec.
+
+---
+
+## When to Use
+
+- ~ Features where expected behaviour is easier to express as examples (Given/When/Then) than as written requirements
+- ~ Teams wanting executable specifications that double as regression tests
+- ~ Projects where acceptance tests will be the source of truth for feature correctness
+- ? Skip when requirements are already unambiguous and a formal spec exists
+
+---
+
+## Workflow
+
+### Step 1: Identify User Scenarios
+
+! Write Given/When/Then scenarios for the feature before any implementation or specification work.
+
+- ! Each scenario covers one behaviour -- avoid multi-assertion scenarios
+- ~ Capture happy path, edge cases, and error cases as separate scenarios
+- ~ Use concrete values, not placeholders (e.g. "Given a user with 3 items in cart" not "Given a user with items")
+- ! Store scenarios in the project's standard test directory (e.g. `tests/`), not in `specs/`
+
+### Step 2: Write Failing Acceptance Tests
+
+! Translate scenarios into executable test code before writing any implementation.
+
+- ! Tests MUST fail when first written -- a passing test before implementation means the test is wrong or the feature already exists
+- ~ Use the project's test framework (pytest, go test, jest, etc.)
+- ! Place test files in the project's standard test directory (e.g. `tests/`)
+- ⊗ Write implementation code at this step
+
+### Step 3: Run Tests -- Surface Ambiguity
+
+! Run the failing tests. Use the failures to surface missing decisions and ambiguity in requirements.
+
+- ! Each test failure is a question: "What should happen here?"
+- ~ Group failures by theme (data model gaps, API contract gaps, business rule gaps)
+- ! Record every ambiguity discovered -- these become decision items in Step 4
+
+### Step 4: Lock Decisions
+
+! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
+
+! Resolve all ambiguities surfaced by Step 3. Record decisions in `vbrief/proposed/{feature}-bdd.vbrief.json`.
+
+- ! Write a scope vBRIEF with two narratives:
+  - `Scenarios` -- Given/When/Then scenario descriptions from Step 1
+  - `LockedDecisions` -- each decision includes: **what** was decided, **why**, and **alternatives considered**
+- ! Decisions are **locked** -- downstream tasks inherit them, do not re-debate
+- ! Format follows the same vBRIEF narrative structure as [strategies/discuss.md](./discuss.md)
+- ⊗ Leave ambiguities unresolved -- every question surfaced in Step 3 must have a locked answer
+- ⊗ Write decisions to a hand-authored markdown file -- use vBRIEF narratives for token-efficient agent consumption
+
+! After emitting the 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`).
+
+### Step 5: Generate Spec
+
+! Derive SPECIFICATION.md tasks from the now-stable test scenarios and locked decisions.
+
+- ! Each scenario maps to one or more spec tasks with traceability (`traces: scenario-N`)
+- ! Locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` `LockedDecisions` narrative flow into the spec as constraints
+- ~ Use the Light or Full path from [strategies/interview.md](./interview.md) based on project size
+
+### Step 6: Chain into Interview Sizing Gate
+
+! Follow [strategies/interview.md](./interview.md) sizing gate for SPECIFICATION.md finalisation.
+
+- ! On completion, register artifacts in `./vbrief/plan.vbrief.json`:
+  - Update `completedStrategies`: increment `runCount` for `"bdd"`, append artifact paths
+  - Append all new artifact paths to the flat `artifacts` array
+- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
+- ! The locked decisions from `vbrief/proposed/{feature}-bdd.vbrief.json` and the acceptance tests MUST flow into subsequent strategies and spec generation
+
+---
+
+## Output Artifacts
+
+- Executable test files in the project's standard test directory -- derived from Given/When/Then scenarios
+- `vbrief/proposed/{feature}-bdd.vbrief.json` -- scope vBRIEF with `Scenarios` and `LockedDecisions` narratives
+
+---
+
+## Fits into Chaining Gate
+
+BDD is a **preparatory** strategy. It can be combined with other preparatory strategies (research, discuss, map) before spec generation. On completion, the chaining gate reappears so the user can run additional strategies or proceed to specification.
+
+⊗ End the session after BDD without returning to the chaining gate.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Writing implementation before acceptance tests -- tests must come first
+- ⊗ Writing acceptance tests that pass immediately -- a passing test before implementation indicates a wrong test or pre-existing feature
+- ⊗ Leaving ambiguities unresolved after Step 3 -- every surfaced question must be locked in Step 4
+- ⊗ Skipping the vBRIEF file -- decisions that exist only in conversation history will be lost
+- ⊗ Writing scenarios with vague placeholders instead of concrete values
+- ⊗ Combining multiple behaviours into a single scenario -- one scenario, one behaviour
+- ⊗ Ending after BDD without chaining into specification generation

package/strategies/brownfield.md

@@ -0,0 +1,7 @@
+# Brownfield Strategy (Redirect)
+
+> **This file is a legacy alias.** The brownfield strategy has been renamed to **Map**.
+>
+> See **[strategies/map.md](./map.md)** for the canonical strategy.
+
+Use `/deft:run:map` to invoke the map strategy.

package/strategies/discuss.md

@@ -0,0 +1,129 @@
+<!-- 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) -->
+
+# Discuss Strategy
+
+Structured alignment before planning — front-load decisions, prevent drift.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/interview.md](./interview.md) (Phase 1: Interview) | [strategies/speckit.md](./speckit.md) (Phase 2: Specify) | [core/glossary.md](../glossary.md)
+
+> Extends Deft's Interview phase with decision locking and Feynman technique. Adapted from [GSD](https://github.com/gsd-build/get-shit-done) discuss phase.
+
+---
+
+## Core Principle
+
+The most expensive mistake is building the wrong thing. A 10-minute alignment conversation saves hours of re-implementation. Decisions made here flow through the entire pipeline — planning, execution, verification — and are **never re-debated** downstream.
+
+---
+
+## When to Use
+
+- ! Before planning any feature/phase with gray areas
+- ~ Before any feature where multiple reasonable approaches exist
+- ? Skip only when the path forward is unambiguous and the user confirms
+
+## The Feynman Approach
+
+Use the Feynman technique: if the user (or you) can't explain the feature in simple, concrete terms, the understanding isn't there yet.
+
+- ! **Make the abstract concrete** — "Walk me through using this." "What does that look like on screen?" "What happens when this fails?"
+- ! **Explain it back** — Restate the user's intent in your own words. If the restatement surprises them, the spec is wrong.
+- ! **Find the gaps** — Where the explanation gets hand-wavy is where the bugs will be.
+- ~ Use the "teach it to a child" filter: if the expected behavior can't be described without jargon, it's underspecified.
+
+## Questioning Behaviors
+
+### Follow Energy
+
+- ~ Whatever the user emphasizes, dig deeper into that
+- ⊗ Robotically marching through a predetermined question list
+- ~ If the user spends time on error handling, ask deeper questions about error handling
+
+### Challenge Vagueness
+
+- ! Push back on fuzzy answers: "Make it simple" → "Simple how? For the user? To implement? To extend later?"
+- ! Push back on assumed agreement: "Standard auth" → "JWT with refresh? Server-side sessions? OAuth? Which standard?"
+- ⊗ Accept fuzzy input — it produces divergent output
+
+### Scope Guardrails
+
+- ! If the user suggests a capability belonging to a different feature, capture it as **deferred**
+- ~ Redirect: "That sounds like a new capability — I'll note it. For now, let's focus on [current scope]."
+- ~ Record deferred ideas in `./vbrief/plan.vbrief.json` with `deferred` status and a narrative explaining why
+
+## Domain-Sensitive Questions
+
+Adapt question focus to what's being built:
+
+- **Visual features** → Layout, density, interactions, empty states
+- **APIs/CLIs** → Response format, flags, error handling, verbosity
+- **Data systems** → Schema, validation, migration, edge cases
+- **Organization tasks** → Grouping criteria, naming, duplicates, exceptions
+
+## Output
+
+! Before writing output artifacts, follow the [Preparatory Guard](./artifact-guards.md#preparatory-guard-light).
+
+- ! Produce a `vbrief/proposed/{scope}-context.vbrief.json` scope vBRIEF with a `LockedDecisions` narrative
+- ! Each decision includes: **what** was decided, **why**, and **alternatives considered**
+- ! This vBRIEF is injected into all downstream work: planning, execution, verification
+- ! Persist decisions as vBRIEF narratives on the relevant plan items
+- ⊗ Write decisions to a hand-authored markdown context file -- use vBRIEF narratives for token-efficient agent consumption
+
+! After emitting the 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`).
+
+## Decision Locking
+
+- ! Decisions in the vBRIEF `LockedDecisions` narrative are **locked** -- downstream tasks inherit them, don't re-debate
+- ! If a locked decision needs revisiting, explicitly flag it as unlocked with justification
+- ⊗ Silently making a different choice because the agent forgot what was decided
+- ⊗ Re-debating a settled decision without explicit user approval
+
+---
+
+## Then: Chaining Gate
+
+After alignment is complete and decisions are locked in `vbrief/proposed/{scope}-context.vbrief.json`,
+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 `"discuss"`,
+    append artifact path (`vbrief/proposed/{scope}-context.vbrief.json`)
+  - Append the path to the flat `artifacts` array
+- ! Return to [interview.md Chaining Gate](./interview.md#chaining-gate)
+  (the discuss phase replaces the interview's question-gathering -- decisions are
+  already made, so the interview will be short or skipped entirely)
+- ! The locked decisions from `vbrief/proposed/{scope}-context.vbrief.json` MUST flow into subsequent
+  strategies and spec generation
+- ⊗ End the session after discuss 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. **Open** -- Start with the user's goal statement; restate it in your own words
+2. **Explore** -- Follow energy, challenge vagueness, ask domain-sensitive questions
+3. **Lock** -- Record each decision in `vbrief/proposed/{scope}-context.vbrief.json` `LockedDecisions` narrative with what/why/alternatives
+4. **Verify** -- Explain the full picture back to the user (Feynman check)
+5. **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
+
+- ⊗ Skipping discuss and immediately writing code
+- ⊗ Asking generic checklist questions instead of following energy
+- ⊗ Accepting "make it nice" / "standard approach" / "whatever works" without pushback
+- ⊗ Scope creep — capturing out-of-scope ideas inline instead of deferring
+- ⊗ Decisions that exist only in conversation history (they must be in the vBRIEF `LockedDecisions` narrative)
+- ⊗ Ending after discuss 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/emit-hints.md

@@ -0,0 +1,69 @@
+<!-- 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) -->
+
+# Issue-Emit Hints
+
+Shared hint referenced by strategies at the moment they emit scope vBRIEFs. It names the GitHub-issue tracking choice — none / umbrella / per-vBRIEF — so the choice is discoverable instead of the emission step ending silently.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+**⚠️ See also**: [strategies/artifact-guards.md](./artifact-guards.md) | [vbrief/vbrief.md](../vbrief/vbrief.md) | [strategies/v0-20-contract.md](./v0-20-contract.md)
+
+---
+
+## When to Use
+
+This file is not a standalone strategy — it is a shared hint referenced by other strategies. It activates at the emission step, right after a strategy writes scope vBRIEFs to `vbrief/proposed/` (or `vbrief/pending/`).
+
+- ! Referenced by spec-generating strategies: [speckit](./speckit.md) (Phase 4 and Phase 4.5), [enterprise](./enterprise.md), [rapid](./rapid.md), [interview](./interview.md), [yolo](./yolo.md)
+- ! Referenced by preparatory strategies: [bdd](./bdd.md), [discuss](./discuss.md), [research](./research.md), [map](./map.md), [probe](./probe.md)
+
+## Workflow
+
+1. Strategy reaches its emission step and writes scope vBRIEF(s)
+2. Strategy surfaces the hint below, naming all three patterns
+3. The user picks one — or takes no action (the default)
+4. No issue is filed unless the user explicitly invokes `task deft:issue:emit`
+
+---
+
+## The Hint
+
+! After emitting N scope vBRIEF(s), print the following hint so the user discovers the GitHub-issue tracking choice. The hint is informational text only — it mutates nothing and files no issue.
+
+```
+<strategy> emitted N scope vBRIEF(s).
+
+Optional: track these in GitHub issues.
+  - task deft:issue:emit --umbrella -- vbrief/<path>/<glob>     (one roadmap issue, all vBRIEFs reference it)
+  - task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob>   (one issue per vBRIEF)
+  - Default behavior (vBRIEF-only) requires no further action.
+```
+
+~ Replace `<path>/<glob>` with the actual emission target (e.g. `vbrief/proposed/2026-06-15-*.vbrief.json`).
+
+Note: `task deft:issue:emit` is the consumer-installed surface (this is what strategies render to). The maintainer-side, in-repo form is `task issue:emit` — the same command without the `deft:` prefix.
+
+---
+
+## The Three Patterns
+
+1. **None (default)** — emit vBRIEF(s) only; file no GitHub issue. Requires no further user action. This is the framework default and is unchanged by this hint.
+2. **Umbrella** — `task deft:issue:emit --umbrella -- vbrief/<path>/<glob>` files ONE roadmap issue, and every matched vBRIEF references it.
+3. **Per-vBRIEF** — `task deft:issue:emit --per-vbrief -- vbrief/<path>/<glob>` files one issue per matched vBRIEF.
+
+- ! Name all three patterns (none / `--umbrella` / `--per-vbrief`) when surfacing the hint — do not hide the umbrella / per-vBRIEF escape hatches.
+- ⊗ File a GitHub issue automatically as part of emission. No strategy files an issue unless the user explicitly invokes `task deft:issue:emit`.
+- ~ The emitted issue body is rendered from the vBRIEF `title` + `Description` + `Acceptance` + `Traces` narratives (see [vbrief/vbrief.md](../vbrief/vbrief.md) Origin Provenance), and the source vBRIEF's `references[]` is updated to link the issue.
+
+---
+
+## Anti-Patterns
+
+- ⊗ Ending a strategy's emission step silently — the user never learns the umbrella / per-vBRIEF choice exists.
+- ⊗ Filing a GitHub issue automatically — the default is vBRIEF-only and requires explicit opt-in via `task deft:issue:emit`.
+- ⊗ Naming only one pattern (e.g. only `--umbrella`) — the hint MUST name none / `--umbrella` / `--per-vbrief` together so the full choice is visible.
+- ⊗ Mutating the source vBRIEF or its `references[]` as a side effect of merely showing the hint — mutation happens only when the user runs `task deft:issue:emit`.