@deftai/directive-content 0.55.0

package/events/registry.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "./registry.schema.json",
+  "version": "1",
+  "description": "Deft framework event registry -- unified structural artifact listing every framework event in a single data file, partitioned by the required `category` enum (`detection-bound` | `behavioral`). Wired under epic #635 per the canonical #642 workflow comment, unified per the Repair Authority [AXIOM] proposal (#709) and the data-file-convention check follow-up (#710); the prior `events/behavioral.yaml` registry has been folded into this file. Detection-bound events have detectors that already exist in the framework; behavioral events require runtime instrumentation (agent emission point or script-internal capture). Each entry pins an event name, category, payload contract, detector / emission pointer, and consumer pointers. The shape of an emitted event record is governed by event-record.schema.json. Two emission helpers consume this registry: scripts/_event_detect.py for detection-bound events (validates against the full registry) and scripts/_events.py for behavioral events (validates against the behavioral subset, manages 1:1 session-pair invariants, persists to a JSONL log).",
+  "events": [
+    {
+      "name": "pre-cutover:detected",
+      "category": "detection-bound",
+      "description": "Pre-v0.20 legacy artifacts present at the project root: SPECIFICATION.md or PROJECT.md exist without the deft:deprecated-redirect sentinel. Indicates the project has not yet completed the vBRIEF-centric document model migration (#312, RFC #309).",
+      "trigger": "run::_check_upgrade_gate calls run::_detect_pre_cutover_legacy and emits when SPECIFICATION.md or PROJECT.md exist at project root without the redirect sentinel. Emission flows through scripts/_event_detect.py::emit.",
+      "payload": {
+        "project_root": "string -- absolute path to the project root scanned",
+        "legacy_files": "array<string> -- filenames at project root that lack the redirect sentinel"
+      },
+      "consumers": [
+        "skills/deft-directive-setup/SKILL.md Pre-Cutover Detection Guard -- routes the operator to task migrate:vbrief",
+        "run::_check_upgrade_gate -- emits a pre-v0.20 warning",
+        "QUICK-START.md Step 2c -- equivalent prose-encoded detection"
+      ]
+    },
+    {
+      "name": "vbrief:invalid",
+      "category": "detection-bound",
+      "description": "One or more vBRIEF files failed validator D1-D11 checks (schema, status enum, lifecycle folder mapping, filename convention, narratives, items, references) or post-migration placeholder integrity. Emitted by scripts/vbrief_validate.py on every run that surfaces errors or warnings.",
+      "trigger": "scripts/vbrief_validate.py validate_all collects errors and warnings across the vbrief/ tree; emits when len(errors) > 0 or len(warnings) > 0. Existing exit-code semantics (0 with warnings, 1 on errors, 1 with --warnings-as-errors) are unchanged.",
+      "payload": {
+        "vbrief_dir": "string -- absolute path to the vbrief/ directory scanned",
+        "error_count": "integer -- D1-D11 hard errors",
+        "warning_count": "integer -- D1-D11 warnings (origin missing, render staleness, deprecated placeholder)",
+        "errors": "array<string> -- error messages (capped at 50 to keep payload bounded)",
+        "warnings": "array<string> -- warning messages (capped at 50)"
+      },
+      "consumers": [
+        "tasks/vbrief.yml validate -- consumed via exit code today; event surface is the structured equivalent",
+        "Taskfile.yml check (deps: vbrief:validate) -- pre-commit gate"
+      ]
+    },
+    {
+      "name": "agents-md:stale",
+      "category": "detection-bound",
+      "description": "AGENTS.md references one or more skill paths that either do not exist on disk or contain the deft:deprecated-skill-redirect sentinel. Indicates the consumer's AGENTS.md was generated by a prior framework version and needs the QUICK-START refresh path. Detection logic codified from QUICK-START.md Step 2b prose; the canonical 200-character window is preserved verbatim.",
+      "trigger": "scripts/_event_detect.py::detect_agents_md_stale parses AGENTS.md for deft/skills/<name>/SKILL.md tokens, then checks each path's existence and the first 200 characters for the deprecated-skill-redirect sentinel. Emits when missing_paths or redirect_paths is non-empty.",
+      "payload": {
+        "agents_md_path": "string -- absolute path to AGENTS.md",
+        "missing_paths": "array<string> -- referenced skill paths absent from disk",
+        "redirect_paths": "array<string> -- referenced skill paths whose first 200 chars contain the deft:deprecated-skill-redirect sentinel"
+      },
+      "consumers": [
+        "QUICK-START.md Step 2b / Case G -- routes the operator to refresh AGENTS.md from templates/agents-entry.md",
+        "skills/deft-directive-sync/SKILL.md -- detects stale references during sync"
+      ]
+    },
+    {
+      "name": "version:drift",
+      "category": "detection-bound",
+      "description": "vbrief/.deft-version (or fallback project-root .deft-version) records a framework version that differs from the current run::VERSION constant. Indicates the consumer ran an older framework against this project last and may need task migrate:vbrief or .deft/core/run upgrade.",
+      "trigger": "run::_check_upgrade_gate compares _read_version_marker() to VERSION; emits when both are non-None and unequal. The deft-repo self-detection short-circuit (run::_running_inside_deft_repo) suppresses the gate but does not suppress the event so framework maintainers can still observe drift in test fixtures.",
+      "payload": {
+        "project_root": "string -- absolute path to the consumer project root",
+        "recorded_version": "string -- version read from .deft-version",
+        "current_version": "string -- run.VERSION (the framework version currently executing)",
+        "marker_path": "string -- absolute path of the .deft-version file that won the precedence rule (vbrief/.deft-version > .deft-version)"
+      },
+      "consumers": [
+        "run::cmd_upgrade -- writes the marker to clear drift",
+        "skills/deft-directive-sync/SKILL.md -- routes the operator through the upgrade flow"
+      ]
+    },
+    {
+      "name": "dirty-tree:detected",
+      "category": "detection-bound",
+      "description": "git status --porcelain reports uncommitted changes in the project root. Migration is destructive by default; the migrator refuses to run with a dirty tree unless --force is set (#497-3). The event is emitted whenever the dirty-tree guard trips so any orchestrator (skill, task, CI) can react uniformly.",
+      "trigger": "scripts/_vbrief_safety.py::is_tree_dirty returns True; the migrator's dirty-tree refusal call site (migrate_vbrief.migrate, line ~1169) emits before returning the canonical refusal message.",
+      "payload": {
+        "project_root": "string -- absolute path of the project root checked"
+      },
+      "consumers": [
+        "tasks/migrate.yml migrate:vbrief -- the gate this event annotates",
+        "skills/deft-directive-pre-pr/SKILL.md -- pre-PR loop already requires a clean tree before the lint phase"
+      ]
+    },
+    {
+      "name": "framework:remote-drift",
+      "category": "detection-bound",
+      "description": "The directive framework's upstream remote ships a higher semver tag than the run::VERSION currently executing in the consumer's project. Indicates the consumer's `./deft` submodule (or framework checkout) is behind upstream and a `task sync` / `git submodule update --remote --merge deft` would pull a new release. Emitted by run::_maybe_emit_remote_drift_warning (#801) only when the read-only `git ls-remote --tags --refs <upstream>` probe returns BEHIND, throttled per-tag at 24h via vbrief/.deft-remote-probe.json.",
+      "trigger": "run::_maybe_emit_remote_drift_warning runs the probe via _run_remote_probe (which shells out to `git ls-remote --tags --refs <upstream>` once per 24h, parses the highest semver tag, and compares it to VERSION). Emits when result.status == 'behind' AND the per-tag notification cadence allows. Honors DEFT_NO_NETWORK=1 (silent skip) and DEFT_FORCE_REMOTE_PROBE=1 (bypass throttle).",
+      "payload": {
+        "project_root": "string -- absolute path of the consumer project root scanned",
+        "current_version": "string -- run.VERSION currently executing",
+        "remote_version": "string -- highest semver tag visible on the upstream remote (with leading `v` preserved)",
+        "upstream_url": "string -- upstream remote URL the probe consulted (origin of ./deft submodule, or origin of the run-rooted repo)",
+        "commits_behind": "integer | null -- number of commits the consumer is behind upstream when computable, null when the probe cannot determine it without a fetch"
+      },
+      "consumers": [
+        "run::_check_upgrade_gate -- emits the warn line and event from the gate-integration site",
+        "skills/deft-directive-sync/SKILL.md Phase 2 -- the user-triggered remote refresh that resolves the drift",
+        "tasks/framework.yml framework:check-updates -- the synchronous interactive surface that reuses the same probe"
+      ]
+    },
+    {
+      "name": "session:interrupted",
+      "category": "behavioral",
+      "description": "Agent detected a session-state shift (context window pressure, session resume, 'are you using Deft?' alignment probe) and is about to re-confirm Deft alignment per AGENTS.md. Paired with session:resumed -- every session:resumed MUST reference the id of a prior session:interrupted via payload.interrupted_id; orphan resumed records are surfaced by scripts/_events.py::validate_pairing.",
+      "trigger": "Agent runtime emission point: scripts/_events.py::emit when AGENTS.md 'Deft Alignment Confirmation' fires (context-window-shift, alignment-probe, manual-resume). Skills emit via `python -m scripts._events emit session:interrupted --session-id <id> --reason <enum>`.",
+      "payload": {
+        "session_id": "string -- stable identifier for the agent session being interrupted; agents SHOULD reuse a single session_id across the lifetime of one logical conversation so multiple interrupt/resume pairs share provenance",
+        "reason": "string enum -- one of context-window-shift | alignment-probe | manual-resume | other; agents SHOULD prefer the named values over 'other'",
+        "detail": "string (optional) -- free-form one-liner with additional context"
+      },
+      "consumers": [
+        "skills/deft-directive-sync/SKILL.md Framework Events Emitted Here -- emits the pair on every alignment confirmation",
+        "scripts/_events.py::validate_pairing -- enforces the 1:1 session:interrupted -> session:resumed invariant"
+      ]
+    },
+    {
+      "name": "session:resumed",
+      "category": "behavioral",
+      "description": "Agent has finished re-confirming Deft alignment after a session:interrupted and is resuming work. MUST reference a prior session:interrupted event id via payload.interrupted_id; one interrupted_id may satisfy at most one session:resumed (1:1 pairing per Greptile #706 P2). Orphan or double-resumed records are flagged by scripts/_events.py::validate_pairing.",
+      "trigger": "Agent runtime emission point: scripts/_events.py::emit immediately after the agent emits the alignment confirmation line. Skills emit via `python -m scripts._events emit session:resumed --session-id <id> --interrupted-id <id-from-prior-emit>`.",
+      "payload": {
+        "session_id": "string -- same identifier used in the matching session:interrupted",
+        "interrupted_id": "string -- id of the matching session:interrupted event; cross-referenced by scripts/_events.py::validate_pairing",
+        "detail": "string (optional) -- free-form one-liner with additional context"
+      },
+      "consumers": [
+        "skills/deft-directive-sync/SKILL.md Framework Events Emitted Here -- emits the pair on every alignment confirmation",
+        "scripts/_events.py::validate_pairing -- enforces the 1:1 session:interrupted -> session:resumed invariant"
+      ]
+    },
+    {
+      "name": "plan:approved",
+      "category": "behavioral",
+      "description": "User approved a plan reaching the Phase 5 -> 6 merge gate per skills/deft-directive-review-cycle and the canonical #642 workflow comment ready-to-merge templates. Emitted when the user types yes / confirmed / approve on a ready-to-merge PR thread or equivalent gate. Downstream effects (auto-merge, status update, notifications) are explicitly deferred to follow-up work; this event currently emits a record only.",
+      "trigger": "Agent runtime emission point: scripts/_events.py::emit when a skill detects an affirmative reply (yes / confirmed / approve) on a ready-to-merge PR thread. Skills emit via `python -m scripts._events emit plan:approved --plan-ref <pr-url> --approver <login> --approval-phrase <yes|confirmed|approve> --pr-number <N>`.",
+      "payload": {
+        "plan_ref": "string -- pointer to the plan being approved; format: GitHub PR URL (preferred) or vBRIEF path; agents SHOULD use the canonical URL when available",
+        "approver": "string -- identifier of the approving user (GitHub login when available, 'user' otherwise)",
+        "approval_phrase": "string enum (optional) -- one of yes | confirmed | approve | other; the exact affirmative phrase the user used, normalised to lowercase; skills SHOULD prefer one of the canonical phrases per the canonical #642 workflow comment",
+        "pr_number": "integer (optional) -- GitHub PR number, when applicable"
+      },
+      "consumers": [
+        "skills/deft-directive-review-cycle/SKILL.md Framework Events Emitted Here -- Phase 5 -> 6 merge gate emission",
+        "(deferred -- no downstream consumer in this PR; future auto-merge / status-update / audit handlers will subscribe by name)"
+      ]
+    },
+    {
+      "name": "legacy:detected",
+      "category": "behavioral",
+      "description": "Migrator captured a non-canonical pre-cutover section (SPECIFICATION.md / PROJECT.md / PRD.md hand-edit) to vbrief/legacy/ or an inline LegacyArtifacts narrative during task migrate:vbrief (#505). Emitted once per captured section; additive to the existing vbrief/migration/LEGACY-REPORT.md write -- this event is structural emission only. Action policy (warn vs auto-migrate vs block) is explicitly out of scope for this PR and is deferred to follow-up.",
+      "trigger": "Script-internal emission point: scripts/_vbrief_legacy.emit_legacy_artifacts invokes the event_emitter callback wired by scripts/migrate_vbrief.py once per captured section. Emission flows through scripts/_events.py::emit (the migrator wires a project-root-scoped emitter; failures are swallowed so legacy capture remains the primary contract).",
+      "payload": {
+        "title": "string -- original section heading (e.g. 'Open Questions')",
+        "source": "string -- source filename (e.g. SPECIFICATION.md, PROJECT.md, PRD.md)",
+        "range": "string -- 1-indexed line range (e.g. '12-34' or '12')",
+        "size_bytes": "integer -- UTF-8 byte size of the captured section body",
+        "inline": "boolean (optional) -- true if the body fit inline; false if it overflowed to a sidecar at vbrief/legacy/{stem}-{slug}.md",
+        "sidecar": "string (optional) -- sidecar relative path when inline is false; null/absent otherwise",
+        "flagged": "boolean (optional) -- true for PRD.md hand-edit captures (warning prefix applied)"
+      },
+      "consumers": [
+        "scripts/migrate_vbrief.py -- wires the emitter into all three _emit_legacy_artifacts call sites (SPECIFICATION / PROJECT / PRD captures)",
+        "(deferred -- no downstream handler in this PR; future migrate:vbrief audit reporting and consumer-facing legacy-handling skills will subscribe by name)"
+      ]
+    }
+  ]
+}

package/events/registry.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/deftai/directive/events/registry.schema.json",
+  "title": "Deft Events Registry",
+  "description": "Schema for events/registry.json. Validates the structural event registry that lists detection-bound and behavioral framework events. The registry is the single source of truth for event names, payload contracts, and detector/consumer pointers. See events/event-record.schema.json for the shape of an emitted event record.",
+  "type": "object",
+  "required": ["version", "events"],
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer to this schema for editor tooling."
+    },
+    "version": {
+      "type": "string",
+      "description": "Registry schema version. Bumped when the registry's own shape changes (not when individual events are added/removed)."
+    },
+    "description": {
+      "type": "string"
+    },
+    "events": {
+      "type": "array",
+      "description": "Registered events. Order is not significant, but names MUST be unique.",
+      "items": {
+        "$ref": "#/$defs/Event"
+      }
+    }
+  },
+  "$defs": {
+    "Event": {
+      "type": "object",
+      "required": ["name", "category", "description", "trigger", "payload", "consumers"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Canonical event name. Convention: lowercase, colon-separated namespace (e.g. 'pre-cutover:detected', 'session:interrupted').",
+          "pattern": "^[a-z][a-z0-9-]*(:[a-z][a-z0-9-]*)+$"
+        },
+        "category": {
+          "type": "string",
+          "enum": ["detection-bound", "behavioral"],
+          "description": "detection-bound: detectable from filesystem state alone. behavioral: requires runtime instrumentation (agent emission point or script-internal capture)."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what the event represents."
+        },
+        "trigger": {
+          "type": "string",
+          "description": "Free-form pointer to the detection logic or emission point (file::function or skill section)."
+        },
+        "payload": {
+          "type": "object",
+          "description": "Field-name -> contract-string map. Each value is a free-form description of the field's type and meaning.",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "consumers": {
+          "type": "array",
+          "description": "Pointers to skills, tasks, or scripts that consume this event by name. At least one consumer is required so the surface stays usable.",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/glossary.md

@@ -0,0 +1,145 @@
+# Glossary
+
+The authoritative vocabulary for the Deft framework.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+
+! When a term used in any directive file is not locally defined, load this file to resolve it.
+! When introducing a new term in any directive file, define it here first.
+⊗ Define the same term differently in two files — one definition, one source of truth.
+
+---
+
+## Deft Work Decomposition Hierarchy
+
+```
+Release          ← Shippable version (one or more features)
+  └── Feature    ← Independently demo-able vertical capability
+       └── Task  ← Context-window-sized unit of work
+```
+
+**Release** — A shippable version of the product. Contains one or more features. Maps to a git tag and a CHANGELOG entry. See [versioning.md](./meta/versioning.md).
+
+**Feature** — An independently demo-able vertical capability. Scoped by a **demo sentence**: "After this, the user can ___." If you can't fill in that blank with something a human can observe, the feature is scoped wrong. Features are vertical (user-visible) not horizontal ("implement the database layer").
+
+**Task** — The atomic unit of work. Must fit in one agent context window. If it doesn't fit, it's two tasks. This is an iron rule — violating it is where agents lose coherence.
+
+---
+
+## Terms Introduced by Deft (with GSD lineage)
+
+These concepts originate from [GSD](https://github.com/gsd-build/get-shit-done) and have been adapted into the Deft framework.
+
+**Anchor pruning** — Giving each task a fresh context window by pruning prior tasks' tool calls, intermediate reads, and debugging traces. Eliminates context rot. See [resilience/context-pruning.md](./resilience/context-pruning.md).
+
+**Context rot** — The silent degradation of agent reasoning quality as the context window fills with stale tool output, dead-end debugging, and outdated file reads from prior tasks. By task 3–4 in a sequence, signal-to-noise has collapsed.
+
+**Decision locking** — Decisions made during the discuss/interview phase are recorded in a context file and treated as **locked** for all downstream work. Downstream tasks inherit them — they don't re-debate. See [strategies/discuss.md](./strategies/discuss.md).
+
+**Demo sentence** — The scoping test for a feature: "After this, the user can ___." If the blank can't be filled with something a human can observe, the feature is scoped wrong.
+
+**Fractal summaries** — Hierarchical memory compression: task summaries compress into feature summaries, which compress into release summaries. Iron rule: never summarize summaries — regenerate each level from the level below + code state. See [context/fractal-summaries.md](./context/fractal-summaries.md).
+
+**Specification vbrief** — The source-of-truth pattern for project intent. `./vbrief/specification.vbrief.json` is the canonical specification file; `SPECIFICATION.md` is a generated artifact rendered from it. The spec vbrief is created via interview (`templates/make-spec.md`), reviewed by the user, approved (`status: approved`), then rendered. Never edit the `.md` directly — edit the source vbrief. See [vbrief/vbrief.md](./vbrief/vbrief.md).
+
+**Stub detection** — Scanning completed code for incomplete implementations: `TODO`/`FIXME` markers, `return null`/`return {}`/`pass` placeholders, functions under ~8 lines returning hardcoded values. See [verification/verification.md](./verification/verification.md).
+
+**Verification ladder** — A 4-tier model for verifying agent work, picking the strongest tier reachable: (1) Static — files exist, exports present, no stubs. (2) Command — tests pass, build succeeds. (3) Behavioral — flows work, APIs respond correctly. (4) Human — manual verification only when tiers 1–3 can't confirm. See [verification/verification.md](./verification/verification.md).
+
+**Zero discovery calls** — The principle that agents should never spend tokens figuring out where they are, what exists, or what was decided. All of that should be pre-assembled in context before the task starts. See [resilience/context-pruning.md](./resilience/context-pruning.md).
+
+**Brownfield mapping** — Structured reconnaissance of an existing codebase before modifying it. Produces four artifacts: STACK (languages, frameworks, infrastructure), ARCHITECTURE (layers, entry points, data flow), CONVENTIONS (naming, patterns, file layout), and CONCERNS (tech debt, fragile areas, missing tests). See [strategies/map.md](./strategies/map.md). Invoked via `/deft:run:map`.
+
+**Integration checking** — Cross-feature wiring verification that every export has a matching import, every API endpoint has a consumer, auth gates protect all required routes, and at least one E2E flow traces through the full stack. See [verification/integration.md](./verification/integration.md).
+
+**Plan checking** — Pre-execution verification of a plan across four dimensions: (1) coverage — every acceptance criterion maps to at least one task, (2) completeness — every task has a verify command, (3) wiring — cross-feature dependencies declared in boundary maps, (4) scope — task count within sanity thresholds (2–3 ideal, 5+ requires split). See [verification/plan-checking.md](./verification/plan-checking.md).
+
+**Scope sanity** — A threshold-based guard against over-scoped plans that degrade context window quality. 1–3 tasks per plan is ideal; 4 is a warning; 5+ is a blocker requiring plan split. Part of plan checking dimension 4. See [verification/plan-checking.md](./verification/plan-checking.md).
+
+**Spec delta** — A scoped document capturing how a change modifies existing requirements. Shows new requirements and was/now diffs for modified ones. Linked to the baseline spec via vBRIEF `references` with `type: "x-vbrief/plan"`. Lives in `history/changes/<name>/specs/`. See [context/spec-deltas.md](./context/spec-deltas.md). Invoked as part of `/deft:change`.
+
+**Verify command** — A concrete, runnable command specified per task that confirms the task's work is correct (e.g., `pytest tests/test_auth.py`, `curl localhost:8080/health`). Required by plan checking dimension 2 (completeness). Tasks without a verify command fail the plan check.
+
+---
+
+## Framework Design Terms
+
+Terms describing how directive itself is structured and governed.
+
+**Bounded context** (framework sense) — A file or directory in directive that owns a specific rule domain. Other files reference it; they do not restate its rules. Prevents rule drift through duplication. Examples: `coding/hygiene.md` owns hygiene rules; `coding/testing.md` owns universal testing standards.
+
+**Rule ownership** — The principle that each concept in directive has exactly one owning file. When multiple files need to reference the concept, they link to the owner rather than duplicating the rule.
+
+**Ubiquitous language** — The shared, precisely defined vocabulary used consistently across all directive files and by all agents. This glossary is the source of truth. Synonyms and informal restatements of defined terms are not permitted.
+
+---
+
+## Hygiene Terms
+
+Terms used in [coding/hygiene.md](./coding/hygiene.md).
+
+**Hygiene** — The ongoing practice of keeping a codebase clean beyond what individual changes introduce: removing dead code, eliminating circular dependencies, surfacing hidden errors, and removing legacy/deprecated code paths. Distinct from per-change quality gates, which only govern new code.
+
+**Dead code** — Code that is defined but never executed: unused functions, unreachable branches, stale feature flags, and commented-out blocks. Distinct from deprecated code, which may still execute on a legacy path.
+
+**Error hiding** — Any pattern that prevents an error from being observed by the caller or operator: empty catch blocks, silent fallbacks, returning neutral/zero values to mask failures, or log-and-continue without surfacing the error upstream.
+
+**Legacy code** — A code path, implementation, or feature flag that has been superseded but not removed. Identified by markers such as `LEGACY`, `COMPAT`, `OLD_`, `TODO: remove`, or the presence of two parallel implementations without a migration path.
+
+**Circular dependency** — An import cycle where module A depends on module B which depends (directly or transitively) on module A. Indicates architectural coupling that prevents modular testing and signals a layering violation.
+
+---
+
+## GSD → Deft Term Mapping
+
+For readers familiar with [GSD](https://github.com/gsd-build/get-shit-done):
+
+| GSD Term | Deft Term | Notes |
+|----------|-----------|-------|
+| Milestone | **Release** | Shippable version |
+| Slice | **Feature** | Vertical capability with demo sentence |
+| Task | **Task** | Same — add "fits in one context window" |
+| Must-haves | **Acceptance criteria** | With subcategories: truths, artifacts, key links |
+| Continue file | **Continue checkpoint** | `./vbrief/continue.vbrief.json` (singular) |
+| Discuss phase | **Interview** (extended) | Adds decision locking + Feynman technique |
+| Boundary map | **Contract** (at planning level) | Extension of Contract-First |
+| Wave execution | **Parallel group** | Speckit `[P]`/`[S]` markers |
+| Research phase | **Research** | Already in speckit |
+
+---
+
+## vBRIEF Lifecycle Terms (v0.20+)
+
+Canonical vocabulary for the vBRIEF lifecycle. (Merged from the former top-level `glossary.md` during the #1875 content/ move; deduplicated to a single canonical glossary.)
+
+- **Scope vBRIEF** -- A durable unit-of-work record, one per feature / bug / initiative, stored as `YYYY-MM-DD-slug.vbrief.json` inside a [lifecycle folder](#terms). Scope vBRIEFs are the primary work artifact in v0.20 (see [vbrief/vbrief.md -- Scope vBRIEFs and Lifecycle Folders](./vbrief/vbrief.md#scope-vbriefs-and-lifecycle-folders)).
+
+- **Lifecycle folder** -- One of the five subdirectories under `vbrief/`: `proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`. Folder location reflects (but does not define) `plan.status`; see [vbrief/vbrief.md -- Directory Structure](./vbrief/vbrief.md#directory-structure) and [Status-Driven Moves](./vbrief/vbrief.md#status-driven-moves).
+
+- **Plan-level narrative** -- A key under `plan.narratives` in a vBRIEF file, describing the scope/plan as a whole (e.g. `Description`, `Acceptance`, `Traces`). Plan-level narratives describe the *what and why*; see [vbrief/vbrief.md -- Narratives](./vbrief/vbrief.md#narratives).
+
+- **Item-level narrative** -- A narrative string under `plan.items[].narrative` describing a single `PlanItem` (a task / subtask within a scope). Both plan-level and item-level narratives MUST be plain strings -- never objects (see [vbrief/vbrief.md -- Narratives](./vbrief/vbrief.md#narratives)).
+
+- **Filename stem** -- The portion of a vBRIEF filename before `.vbrief.json`. For scope vBRIEFs the stem follows `YYYY-MM-DD-<slug>`; for speckit Phase 4 emissions the stem is `YYYY-MM-DD-ip<NNN>-<slug>` with `NNN` zero-padded to 3 digits (see [vbrief/vbrief.md -- Filename Convention](./vbrief/vbrief.md#filename-convention)).
+
+- **Cross-scope dependency** -- A dependency between two scope vBRIEFs (rather than between items inside a single scope). Cross-scope dependencies live at `plan.metadata.dependencies` as an array of dependency IDs -- plan-level by design (see [vbrief/vbrief.md -- Plan-level metadata](./vbrief/vbrief.md#plan-level-metadata)).
+
+- **Exit Commands** -- The seven deterministic `task scope:*` commands that transition a scope vBRIEF between lifecycle folders: `scope:promote`, `scope:activate`, `scope:complete`, `scope:cancel`, `scope:restore`, `scope:block`, `scope:unblock` (see [tasks/scope.yml](../tasks/scope.yml)). Agents MUST use these instead of moving files by hand.
+
+- **Origin provenance** -- A `references` entry on a scope vBRIEF linking back to the issue / ticket / user-request that spawned it (`type: github-issue`, `jira-ticket`, or `user-request`). Required for ingestion dedup; see [vbrief/vbrief.md -- Origin Provenance](./vbrief/vbrief.md#origin-provenance).
+
+- **Canonical narrative key** -- One of the small set of reserved plan-level narrative keys (`Description`, `Acceptance`, `Traces`) that tooling (`task roadmap:render`, swarm allocator) reads by name. See [vbrief/vbrief.md -- Scope vBRIEF narrative keys](./vbrief/vbrief.md#scope-vbrief-narrative-keys).
+
+- **Preparatory strategy** -- A [strategies/](./strategies/) workflow that gathers context without producing a spec directly (e.g. `research.md`, `discuss.md`, `map.md`, `bdd.md`). Preparatory strategies chain into a [spec-generating strategy](#terms).
+
+- **Spec-generating strategy** -- A [strategies/](./strategies/) workflow that emits `vbrief/specification.vbrief.json` (and optionally scope vBRIEFs) as its authoritative output (e.g. `interview.md`, `speckit.md`, `enterprise.md`, `rapid.md`, `yolo.md`).
+
+- **Rendered export** -- A human-readable `.md` file (`SPECIFICATION.md`, `PRD.md`, `ROADMAP.md`) generated on demand by a `task *:render` command from the underlying `.vbrief.json` file. Rendered exports are read-only views; direct edits are overwritten on the next render (see [UPGRADING.md -- What to expect](./UPGRADING.md#what-to-expect)).
+
+- **Source of truth** -- The file that tooling treats as authoritative for a given piece of information. In v0.20 the `.vbrief.json` files are the source of truth; the corresponding `.md` files are [rendered exports](#terms). Editing a rendered export does not change the source of truth -- edit the `.vbrief.json` instead.
+
+- **Deterministic mode** -- The interaction shape used by every Deft skill that asks the user structured questions (via `ask_user_question` single-select / multi-select) or numbered-menu prompts in skill prose. Every deterministic-mode prompt MUST include `Discuss` and `Back` as the final two numbered options (#767). The canonical rule and verbatim Discuss-pause semantic live at [`contracts/deterministic-questions.md`](./contracts/deterministic-questions.md); skill prose `!` cross-references that contract instead of duplicating the rule body.
+
+- **Branch-protection policy** -- The Deft policy surface that controls whether direct commits to the default branch (master/main) are allowed. The typed flag is `plan.policy.allowDirectCommitsToMaster` on `vbrief/PROJECT-DEFINITION.vbrief.json` (#746); default `false` (enforce feature branches). Three enforcement surfaces back the policy: skill-level guards at the entry of `deft-directive-{swarm,review-cycle,pre-pr,release}` (#746 part C), the detection-bound `scripts/preflight_branch.py` reachable via `task verify:branch` and the `.githooks/pre-commit` + `.githooks/pre-push` hooks (#747), and the CI `branch-gate` workflow asserting `head_ref != base_ref` (#747 part E). Reconfigure via `task policy:show` / `task policy:enforce-branches` / `task policy:allow-direct-commits -- --confirm`. Emergency bypass: `DEFT_ALLOW_DEFAULT_BRANCH_COMMIT=1`.
+
+- **Policy audit log** -- One-line append-only ledger at `meta/policy-changes.log` recording every transition of `plan.policy.allowDirectCommitsToMaster`. Written by `scripts/policy_set.py` whenever `task policy:enforce-branches` or `task policy:allow-direct-commits -- --confirm` is invoked, including the actor, previous value, and any operator-supplied `--note`. Surface introduced by #746 acceptance criterion G2.

package/incidents/README.md

@@ -0,0 +1,81 @@
+# Incidents Library
+
+This directory captures real-world incidents that motivated specific Deft
+Directive rules. Each entry is short, structured, and answers one question:
+"if our rules had been in force, would this incident have been prevented?"
+
+The library was stood up by Wave 2 cohort issue [#708](https://github.com/deftai/directive/issues/708)
+alongside the destructive-op guardrails it documents.
+
+## Why this exists
+
+Rules without recurrence records become advisory prose. Recurrence records
+without rules become war stories. The pairing -- rule body in `coding/`,
+incident entry here, deterministic test in `tests/content/` -- is the
+[AXIOM] strongest-applicable-encoding tier in `main.md`.
+
+When a future agent reads `coding/security.md` and asks "do I really need
+the Environment Isolation Gate?", the incident entry answers in the
+agent's own terms: a real database with real backups got wiped in nine
+seconds because the agent acted on the user's prompt instead of a trusted
+environment signal.
+
+## Entry format
+
+Every entry MUST follow this shape. Use [`_template.md`](_template.md) as
+the starting point.
+
+1. **One-line summary** (`# <date>: <plain-English summary>`)
+2. **Date** -- ISO 8601; the date of the incident, not the date of the
+   write-up
+3. **Source** -- canonical external link (vendor postmortem, news article,
+   GitHub issue, internal write-up)
+4. **What happened** -- one or two paragraphs in the actor's perspective;
+   no editorialising
+5. **Root cause** -- the structural gap, not the proximate trigger
+6. **Which Deft rule(s) would have intervened** -- explicit cross-reference
+   to the rule body in `coding/` (path + section heading + issue number).
+   If no rule existed at incident time, name the rule introduced by this
+   entry
+7. **Eval / regression coverage** -- link to the test that exercises the
+   lesson (typically `tests/content/test_*.py` for content-pinned rules,
+   or `tests/cli/` for behavioural rules)
+8. **Status** -- one of: `rules-in-place`, `rules-proposed`, `no-rule-yet`
+
+## Filename convention
+
+`YYYY-MM-<short-slug>.md` for incidents identified by month;
+`YYYY-MM-DD-<short-slug>.md` when the exact date matters.
+
+Examples:
+
+- `2026-04-pocketos-railway-prod-db-wipe.md`
+- `2026-04-15-some-other-incident.md`
+
+Filenames use hyphens, not underscores -- this mirrors the project-wide
+filename convention in [`main.md`](../../main.md).
+
+## When to add an entry
+
+Add an entry when ALL of these are true:
+
+- The incident is publicly documented (vendor postmortem, news article,
+  GitHub issue) OR is reproducible from a synthetic prompt
+- The structural gap maps to a specific Deft rule (existing or proposed)
+- The lesson is non-obvious -- "the agent ran `rm -rf /`" without a
+  structural takeaway does not warrant an entry
+
+Add an entry WITHOUT a backing rule only when the entry itself is the
+proposal mechanism (status: `rules-proposed`); the rule MUST land in a
+follow-up PR within the same cycle.
+
+## Anti-patterns
+
+- Long, editorialising write-ups -- the goal is a structured record, not
+  a narrative
+- Entries without a `Which Deft rule(s) would have intervened` section --
+  the cross-reference is the load-bearing field
+- Entries that cite a rule body without a deterministic test reference --
+  use [AXIOM] tier 1 enforcement, not prose alone
+- Speculative incidents ("imagine if an agent did X") -- this directory
+  is for documented or synthetic-reproducible recurrence records only

package/incidents/_template.md

@@ -0,0 +1,38 @@
+# YYYY-MM-DD: <one-line plain-English summary>
+
+**Date:** YYYY-MM-DD
+**Status:** <rules-in-place | rules-proposed | no-rule-yet>
+**Source:** <https://example.com/canonical-link>
+
+## What happened
+
+One or two paragraphs in the actor's perspective. Name the system, the
+operator action, the agent action, and the user-visible outcome. No
+editorialising.
+
+## Root cause
+
+The structural gap, not the proximate trigger. "Agent ran a destructive
+command" is a proximate trigger; "agent acted on a prompt-claimed
+environment without verifying the trusted signal" is the structural gap.
+
+## Which Deft rule(s) would have intervened
+
+- `<coding/path.md>` `## <section heading>` (#<issue>) -- <one-line
+  explanation of how the rule blocks the failure mode>
+- (add as many bullets as there are intervening rules)
+
+If no rule existed at incident time, name the rule(s) introduced by this
+entry and link them.
+
+## Eval / regression coverage
+
+- `tests/content/test_<file>.py::<test_name>` -- pins the rule body
+- `tests/cli/test_<file>.py::<test_name>` -- exercises the runtime
+  behaviour (if applicable)
+
+## References
+
+- Source postmortem / news article
+- Related GitHub issues
+- Related incidents (other entries in this directory)

package/interfaces/cli.md

@@ -0,0 +1,104 @@
+# CLI Best Practices
+
+Opinionated patterns for command-line interfaces with AI agents.
+
+Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
+Tags: Py=Python; TS=TypeScript; Node=Node.js
+
+## Framework Selection
+
+**Python:**
+- ! Use Typer (except: existing Click+plugins, simple argparse scripts)
+
+**TypeScript/Node.js:**
+- ! Use commander (except: existing codebases, simple scripts)
+- ⊗ Use `readline` for complex CLIs (use TUI libraries instead)
+
+## Output
+
+- ~ Support multiple formats for data CLIs (JSON, tree, markdown, HTML)
+- ! Enforce format flag mutual exclusivity
+- ~ Default to human-readable (tree, table); JSON for machines/LLMs
+- Use individual flags (`--json`, `--tree`) not `--format=json`
+
+## Commands
+
+- ! One command = one action
+- ~ Use subcommands for related actions
+- ~ Keep names short and clear
+- ! Provide `--help` / `-h` with clear descriptions
+- ~ Provide `--ai-help` for LLM-detailed guidance
+- ! Provide rich error messages with actionable suggestions
+
+## Architecture
+
+- ~ Separate concerns: cli.py (parsing), client.py (logic), formatters.py (output)
+- ~ Use enums for options
+- ! Validate before execution
+- Config hierarchy: CLI flags > env vars > config file > defaults
+
+## UX
+
+- ~ Show help (not error) when no args
+- ~ Support flexible input parsing (natural language where practical)
+- ~ Support shell completion (Typer/commander provide this)
+- ! Version info available
+
+## Authentication
+
+- ⊗ Hardcode credentials
+- ! Use environment variables or secure stores
+- ~ Support multiple auth methods
+- ! Clear error when auth fails
+
+## Output Handling
+
+- ≉ Buffer large outputs
+- ~ Stream when possible
+- ~ Consider pagination for large results
+
+## Testing
+
+See [testing.md](../coding/testing.md) for universal requirements.
+
+- ! Test all command paths, format options, error conditions
+- ~ Snapshot test output formats (CLI output, help text)
+
+## Common Patterns
+
+**Config priority:**
+1. CLI flags (highest)
+2. Environment variables
+3. Config file
+4. Defaults (lowest)
+
+**Dual mode**:
+- ? Switch to TUI when interactive, CLI otherwise
+```python
+if sys.stdout.isatty() and not format_flags:
+    run_tui()
+else:
+    run_cli()
+```
+
+**Plugin architecture**:
+- ? Support plugin discovery via entry points
+- ? Validate plugins before use
+- ? Define protocol/interface for plugins
+
+## Documentation
+
+- ! Module docstrings with usage examples
+- ! Command docstrings with descriptions and examples
+- ~ README: quick start, commands, config, dev setup
+
+## Anti-patterns
+
+- ⊗ Assume user timezone (document behavior)
+- ⊗ Allow multiple format flags simultaneously
+- ⊗ Buffer large outputs without streaming
+- ⊗ Provide unclear error messages
+
+---
+
+**See also**: [python.md](../languages/python.md) | [typescript.md](../languages/typescript.md) | [tui.md](../interfaces/tui.md)