@deftai/directive-content 0.73.1 → 0.75.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,5 @@ run_deft verify:forward-coverage --staged --project-root "$REPO_ROOT" || exit $?
21
21
 
22
22
  if [ -d "$REPO_ROOT/xbrief" ] || [ -d "$REPO_ROOT/vbrief" ]; then
23
23
  run_deft verify:vbrief-conformance --staged --project-root "$REPO_ROOT" || exit $?
24
+ run_deft verify:xbrief-drift --staged --project-root "$REPO_ROOT" || exit $?
24
25
  fi
25
-
26
- run_deft verify:xbrief-drift --staged --project-root "$REPO_ROOT" || exit $?
@@ -14,5 +14,5 @@ fi
14
14
 
15
15
  . "$REPO_ROOT/.githooks/_deft-run.sh"
16
16
 
17
- run_deft preflight-gh --pre-push-stdin
17
+ run_deft preflight-gh --pre-push-stdin --project-root "$REPO_ROOT"
18
18
  exit $?
package/QUICK-START.md CHANGED
@@ -38,42 +38,34 @@ Invoke-WebRequest -Uri https://github.com/deftai/directive/releases/latest/downl
38
38
 
39
39
  ⊗ Do NOT `go build` from a source checkout or a developer-specific path (e.g. a hardcoded `/Users/<name>/...` clone). Once the installer finishes, continue with Step 1 below.
40
40
 
41
- ## Step 1 — Who are you?
42
-
43
- Ask the user: **"Are you (1) using deft in your project, or (2) working on deft itself?"**
44
-
45
- - If **(2)**: Tell the user: "Read `./AGENTS.md` in this directory instead — it has contributor instructions." **Stop here.**
46
- - If **(1)**: Continue to Step 2.
47
-
48
- ## Step 2 — Detect project state
41
+ ## Step 1 — Detect project state
49
42
 
50
43
  Before touching `../AGENTS.md`, inspect the user's project root to decide whether this is a fresh install, a re-run, a stale-AGENTS.md upgrade, or a pre-cutover project that needs migration.
51
44
 
52
45
  Run these deterministic checks, in order:
53
46
 
54
- ### 2a. Does `../AGENTS.md` exist?
47
+ ### 1a. Does `../AGENTS.md` exist?
55
48
 
56
- - **No:** treat as fresh install — jump to Case F ("No AGENTS.md") in Step 3.
57
- - **Yes:** continue to 2b.
49
+ - **No:** treat as fresh install — jump to Case F ("No AGENTS.md") in Step 2.
50
+ - **Yes:** continue to 1b.
58
51
 
59
- ### 2b. Does `../AGENTS.md`'s managed section match the current template? Do referenced paths resolve?
52
+ ### 1b. Does `../AGENTS.md`'s managed section match the current template? Do referenced paths resolve?
60
53
 
61
54
  Three checks here, in this order. The first match wins; later checks only run when earlier checks pass.
62
55
 
63
56
  1. **Template-content byte comparison (Case G gate).** Locate the managed section in `../AGENTS.md` (the block bounded by the `<!-- deft:managed-section v2 -->` and `<!-- /deft:managed-section -->` markers). Compare those bytes against the current `./templates/agents-entry.md` rendered managed-section output.
64
- - ! If the managed section is **byte-different** from the current template render (or the markers are absent in `../AGENTS.md`), treat as **stale content** -- jump to Case G ("Stale AGENTS.md") in Step 3. Case G is the right remediation for byte-different staleness because the refresh actually rewrites the content.
57
+ - ! If the managed section is **byte-different** from the current template render (or the markers are absent in `../AGENTS.md`), treat as **stale content** -- jump to Case G ("Stale AGENTS.md") in Step 2. Case G is the right remediation for byte-different staleness because the refresh actually rewrites the content.
65
58
  2. **Install-path resolution (Case K gate -- #1046 PR-A).** When the managed section IS byte-current, parse the section for its install-path declaration (`Full guidelines: <root>/main.md`, e.g. `.deft/core/main.md` for the canonical install layout or `deft/main.md` for the legacy install layout). Verify that `../<root>/main.md` exists on disk.
66
- - ! If the managed section is **byte-identical** to the current template render BUT the declared install path does NOT resolve, jump to **Case K ("Install location mismatch")** in Step 3. Refreshing the managed section is a documented no-op when the content already matches -- Case K is a different failure class than Case G and demands a different remediation (#1046 finding #2).
59
+ - ! If the managed section is **byte-identical** to the current template render BUT the declared install path does NOT resolve, jump to **Case K ("Install location mismatch")** in Step 2. Refreshing the managed section is a documented no-op when the content already matches -- Case K is a different failure class than Case G and demands a different remediation (#1046 finding #2).
67
60
  3. **Legacy skill-path resolution (v0.19 AGENTS.md backstop).** Parse `../AGENTS.md` for any token matching `deft/skills/<name>/SKILL.md` (the legacy v0.19 path shape) and verify the file exists under `./skills/<name>/SKILL.md` (relative to this QUICK-START.md).
68
- - ! If any referenced path does not exist on disk, treat `../AGENTS.md` as **stale** -- jump to Case G in Step 3.
69
- - ! If the referenced path exists but its first 200 characters contain `<!-- deft:deprecated-skill-redirect -->`, also treat as stale. These stubs exist to keep v0.19 `AGENTS.md` files working until QUICK-START can refresh them. (The 200-character window matches the same budget used in 2c and is guaranteed to cover the sentinel position in every stub this repo ships -- see `tests/content/test_deprecated_skill_redirects.py::test_stub_has_sentinel`.)
70
- - If all referenced paths exist and none are redirect stubs, continue to 2c.
61
+ - ! If any referenced path does not exist on disk, treat `../AGENTS.md` as **stale** -- jump to Case G in Step 2.
62
+ - If all referenced paths exist, continue to 1c.
71
63
 
72
64
  Priority ordering: Case G (byte-different content) always wins over Case K (install-path mismatch) because the refresh path is the higher-priority remediation -- when the template content has moved on, the refresh closes BOTH the content drift and any incidental install-path mismatch that the new content might re-introduce. Case K only fires when the content is byte-current AND the path is unresolved -- the exact "refresh would be a no-op" failure class issue #1046 documents.
73
65
 
74
- **Big-jump joint check (Case G+H gate).** Before acting on ANY Case G routing above (a byte-different managed section, or an unresolved / redirect-stub legacy skill path), first ALSO evaluate the 2c pre-cutover check below against `../`. ! If 2c ALSO holds (real pre-v0.20 `SPECIFICATION.md` / `PROJECT.md` present), the project is in the **joint big-jump state** where both the AGENTS.md refresh (Case G) and the pre-cutover migration (Case H) are due — jump to **Case G+H** (combined single-session remediation) in Step 3 instead of Case G. The combined path runs the refresh and the migration in one session and emits a single restart, avoiding the wasted Case G → restart → Case H round-trip. If 2c does not hold, route to Case G as usual.
66
+ **Big-jump joint check (Case G+H gate).** Before acting on ANY Case G routing above (a byte-different managed section, or an unresolved legacy skill path), first ALSO evaluate the 1c pre-cutover check below against `../`. ! If 1c ALSO holds (real pre-v0.20 `SPECIFICATION.md` / `PROJECT.md` present), the project is in the **joint big-jump state** where both the AGENTS.md refresh (Case G) and the pre-cutover migration (Case H) are due — jump to **Case G+H** (combined single-session remediation) in Step 2 instead of Case G. The combined path runs the refresh and the migration in one session and emits a single restart, avoiding the wasted Case G → restart → Case H round-trip. If 1c does not hold, route to Case G as usual.
75
67
 
76
- ### 2c. Are there pre-v0.20 artifacts at the user's project root?
68
+ ### 1c. Are there pre-v0.20 artifacts at the user's project root?
77
69
 
78
70
  Check both of these files at `../` (the user's project root), using the same
79
71
  rule implemented by `scripts/_precutover.py`:
@@ -81,27 +73,27 @@ rule implemented by `scripts/_precutover.py`:
81
73
  - `../SPECIFICATION.md` — exists and is neither a deprecation redirect nor a current generated spec export. A current generated spec export contains `<!-- Purpose: rendered specification -->` and `<!-- Source of truth: xbrief/specification.xbrief.json -->`, and `../xbrief/specification.xbrief.json` plus all five lifecycle folders exist.
82
74
  - `../PROJECT.md` — exists and is not a deprecation redirect (`<!-- deft:deprecated-redirect -->` or `<!-- Purpose: deprecation redirect -->`).
83
75
 
84
- - If **either** holds (real pre-v0.20 content present), treat as **pre-cutover** — jump to Case H ("Pre-cutover migration") in Step 3.
85
- - If both contain the sentinel (or neither exists), continue to 2d.
76
+ - If **either** holds (real pre-v0.20 content present), treat as **pre-cutover** — jump to Case H ("Pre-cutover migration") in Step 2.
77
+ - If both contain the sentinel (or neither exists), continue to 1d.
86
78
 
87
- ### 2d. Partial migration?
79
+ ### 1d. Partial migration?
88
80
 
89
- Check whether `../xbrief/` exists. If it does, inspect for the 5 lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`). If `xbrief/` exists but any lifecycle subfolder is missing, treat as **partial migration** — jump to Case I ("Partial migration repair") in Step 3.
81
+ Check whether `../xbrief/` exists. If it does, inspect for the 5 lifecycle subfolders (`proposed/`, `pending/`, `active/`, `completed/`, `cancelled/`). If `xbrief/` exists but any lifecycle subfolder is missing, treat as **partial migration** — jump to Case I ("Partial migration repair") in Step 2.
90
82
 
91
- ### 2e. Everything clean
83
+ ### 1e. Everything clean
92
84
 
93
- If none of 2a2d triggered, `../AGENTS.md` is current and the project is on v0.20+. Jump to Case J ("Everything clean") in Step 3.
85
+ If none of 1a1d triggered, `../AGENTS.md` is current and the project is on v0.20+. Jump to Case J ("Everything clean") in Step 2.
94
86
 
95
- ## Step 3 — Act on detected state
87
+ ## Step 2 — Act on detected state
96
88
 
97
- Pick exactly one case from Step 2 and follow its instructions. Do not mix cases.
89
+ Pick exactly one case from Step 1 and follow its instructions. Do not mix cases.
98
90
 
99
91
  ### Case F — No AGENTS.md (fresh install)
100
92
 
101
93
  1. Read `./templates/agents-entry.md` (this directory).
102
94
  2. Write that content to `../AGENTS.md`.
103
95
  3. Tell the user: "✓ Created AGENTS.md at your project root."
104
- 4. Continue to Step 4.
96
+ 4. Continue to Step 3.
105
97
 
106
98
  ### Case G — Stale AGENTS.md (v0.19 → v0.20 upgrade)
107
99
 
@@ -116,12 +108,12 @@ Pick exactly one case from Step 2 and follow its instructions. Do not mix cases.
116
108
  1. Tell the user: "Your project uses the pre-v0.20 document model. Current npm releases no longer ship in-product `task migrate:vbrief` (#2068). Follow [UPGRADING.md § Frozen pre-v0.20 document-model migration](./UPGRADING.md#frozen-pre-v020-document-model-migration-2068): pin framework **v0.59.0** (frozen Go installer or git tag), install Python 3.11+ and `uv`, run `task migrate:vbrief` once from that payload, then upgrade to current npm."
117
109
  2. ! Run `task migrate:preflight` (or `task -t ./.deft/core/Taskfile.yml migrate:preflight`) to confirm pre-cutover state and print the frozen-release guidance. ⊗ Do NOT offer to run `task migrate:vbrief` from the current npm deposit — the migrator is not bundled.
118
110
  3. See [./main.md](../main.md#migrating-from-pre-v020) for what pre-cutover looks like and what the migrator produces, and [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) for the brownfield adoption guide.
119
- 4. After migration completes on v0.59.0 and the operator upgrades to current npm, re-run Step 2 of this QUICK-START — the project state has changed. Most likely you land in Case G (AGENTS.md still references old paths) or Case J.
111
+ 4. After migration completes on v0.59.0 and the operator upgrades to current npm, re-run Step 1 of this QUICK-START — the project state has changed. Most likely you land in Case G (AGENTS.md still references old paths) or Case J.
120
112
  5. When AGENTS.md is refreshed, ! instruct the user: **"Framework updated. Start a new agent session to pick up the changes. The current session has stale context."**
121
113
 
122
114
  ### Case G+H — Combined stale AGENTS.md + pre-cutover migration (big-jump, one session)
123
115
 
124
- Reached only via the **Big-jump joint check** in 2b: the managed section in `../AGENTS.md` is stale (Case G) AND pre-v0.20 artifacts are present at `../` (Case H). This is the typical shape of a multi-version "big jump" that crossed both the AGENTS.md managed-section refresh and the pre-v0.20 document-model cutover.
116
+ Reached only via the **Big-jump joint check** in 1b: the managed section in `../AGENTS.md` is stale (Case G) AND pre-v0.20 artifacts are present at `../` (Case H). This is the typical shape of a multi-version "big jump" that crossed both the AGENTS.md managed-section refresh and the pre-v0.20 document-model cutover.
125
117
 
126
118
  ! Run the two remediations in this exact order — **AGENTS.md refresh first, frozen migration guidance second** — then emit a **single** restart instruction at the very end:
127
119
 
@@ -134,13 +126,13 @@ For the version-by-version context of a big jump, see the [big-jump triage entry
134
126
  ### Case I — Partial migration repair
135
127
 
136
128
  1. Tell the user: "Your project has a partial xBRIEF layout. Missing lifecycle folders: <list the absent ones>. Complete the layout via the frozen v0.59.0 migrator (see UPGRADING.md § Frozen pre-v0.20 document-model migration) or create the missing folders manually after migrating narratives."
137
- 2. Run `task migrate:preflight` to confirm state. If the operator has v0.59.0 deposited, they may run `task migrate:vbrief` there; otherwise point at the frozen path. Re-run Step 2 afterwards.
129
+ 2. Run `task migrate:preflight` to confirm state. If the operator has v0.59.0 deposited, they may run `task migrate:vbrief` there; otherwise point at the frozen path. Re-run Step 1 afterwards.
138
130
  3. If the user declines, point them at [docs/BROWNFIELD.md](./docs/BROWNFIELD.md) §Troubleshooting and stop.
139
131
 
140
132
  ### Case J — Everything clean
141
133
 
142
134
  1. Tell the user: "✓ Deft is already configured and current in your AGENTS.md."
143
- 2. Continue to Step 4.
135
+ 2. Continue to Step 3.
144
136
 
145
137
  ### Case K — Install location mismatch (#1046 PR-A)
146
138
 
@@ -149,9 +141,9 @@ The managed section in `../AGENTS.md` is byte-identical to the current `./templa
149
141
  1. Tell the user (verbatim phrasing, naming the unresolved path): "AGENTS.md's managed section is byte-identical to the current template, but the install path it declares (`<declared-path>`) does NOT exist on disk. Refreshing the managed section would be a no-op -- Case G's remediation does not fix install-location mismatches."
150
142
  2. ! Direct the user to run `task framework:doctor` (forthcoming in PR-B of the #1046 cohort -- the diagnostic + remediation surface that owns Case K's fix path) OR to manually verify that the install path AGENTS.md claims actually exists on disk. Until PR-B merges, the manual check is the operator's only path: confirm the framework is deposited at the path AGENTS.md declares, OR re-run the installer / relocator to deposit at that path, OR hand-edit AGENTS.md to point at the path where the framework actually lives.
151
143
  3. ⊗ Run a Case G refresh -- it is a documented no-op for Case K. The managed section already byte-matches the current template; refreshing the bytes back to the same bytes does not change which install path is declared.
152
- 4. ! Instruct the user: **"Stop here. Do not continue to Step 4 until the install-path mismatch is resolved -- subsequent sessions will re-enter Case K until then."**
144
+ 4. ! Instruct the user: **"Stop here. Do not continue to Step 3 until the install-path mismatch is resolved -- subsequent sessions will re-enter Case K until then."**
153
145
 
154
- ## Step 4 — Continue setup
146
+ ## Step 3 — Continue setup
155
147
 
156
148
  Read and follow `../AGENTS.md`. This starts the normal first-session flow (user preferences, project definition, specification). If you reached Case G or completed Case H/I and rewrote AGENTS.md, you have already told the user to start a new session — do not keep going yourself.
157
149
 
@@ -159,6 +151,8 @@ Read and follow `../AGENTS.md`. This starts the normal first-session flow (user
159
151
 
160
152
  **Upgrade pointer:** Users moving between framework versions should also read [UPGRADING.md](./UPGRADING.md) in the repo root for the version-by-version guide. For a multi-version "big jump", start at its [big-jump triage entry point](./UPGRADING.md#big-jump-triage--multi-version-upgrades-start-here), which names which version buckets apply and in what order. An agent on a big jump that hits both a stale AGENTS.md and pre-cutover artifacts should follow [Case G+H](#case-gh--combined-stale-agentsmd--pre-cutover-migration-big-jump-one-session) above to complete both in one session.
161
153
 
154
+ **Contributor pointer (non-blocking):** Working on Deft itself (a `deftai/directive` source checkout)? See [CONTRIBUTING.md](../CONTRIBUTING.md) and use the maintainer install path (`deft-install --yes --upgrade --maintainer --repo-root . --json`). The repo's root `AGENTS.md` has contributor instructions — you do not need the consumer first-session flow above.
155
+
162
156
  ## Update notifications
163
157
 
164
158
  After a Deft project is set up, the CLI runs a periodic, read-only remote-version probe (issue #801) so you find out when the upstream framework ships a new release. The probe shells out to `git ls-remote --tags --refs <upstream>` against the deft submodule's `origin` remote at most once every 24 hours, parses the highest semver tag, and -- if your local checkout is behind -- prints a single informational warn line below the existing recorded-vs-current message:
package/Taskfile.yml CHANGED
@@ -383,6 +383,7 @@ tasks:
383
383
  - verify:pack-drift
384
384
  - verify-wip-cap-framework-self-check
385
385
  - verify:agents-md-budget
386
+ - verify-eval-health-relocation-framework-check
386
387
  - vbrief:validate
387
388
  - codebase:validate-structure
388
389
  - verify:codebase-map-fresh
@@ -422,6 +423,15 @@ tasks:
422
423
  vars:
423
424
  CLI_ARGS: "--allow-over-cap"
424
425
 
426
+ verify-eval-health-relocation-framework-check:
427
+ internal: true
428
+ desc: "Framework self-check shim for verify:eval-health-relocation (#2373)."
429
+ dir: '{{.USER_WORKING_DIR}}'
430
+ cmds:
431
+ - task: verify:eval-health-relocation
432
+ vars:
433
+ CLI_ARGS: "--base-ref origin/master"
434
+
425
435
  # s2-deterministic-gate (#1166): deterministic validation gate for strategy
426
436
  # output shape. Runs on every `task check` (including CI). Implemented in
427
437
  # scripts/validate_strategy_output.py. Respects Grok Build Windows rules
package/UPGRADING.md CHANGED
@@ -68,6 +68,44 @@ From v0.55.1 onwards `@deftai/directive` is published on npm. The canonical cons
68
68
 
69
69
  Start a **new agent session** after steps 2–3 so the refreshed AGENTS.md and skills load from a clean context.
70
70
 
71
+ ## OpenPackage tiered skills (optional, #2462)
72
+
73
+ The npm engine (`npm i -g @deftai/directive`) remains the canonical runtime handler for gates, lifecycle, and `.deft/core/` refresh. **OpenPackage** is an optional cross-harness distribution path for placing tiered consumer skills into Cursor, Codex CLI, and OpenCode native directories — without a Directive-owned skill router.
74
+
75
+ 1. Install OpenPackage CLI: `npm i -g opkg`
76
+ 2. From a maintainer checkout (or release tree), sync skills into the package:
77
+
78
+ ```bash
79
+ node packaging/openpackage/sync-skills.mjs
80
+ ```
81
+
82
+ 3. From your **project root** (after `directive init`):
83
+
84
+ ```bash
85
+ opkg install /path/to/directive/packaging/openpackage/deft-directive-skills --platforms cursor codex opencode
86
+ ```
87
+
88
+ **Tiers:** **daily-core** (setup, sync, build, pre-pr, review-cycle, triage) for session bootstrap; **standard** for operational workflows; **advanced** (release, swarm, debug, article-review) for deferred install. Full lists: `packaging/openpackage/deft-tiers.json`. Detail: [`packaging/openpackage/deft-directive-skills/README.md`](../packaging/openpackage/deft-directive-skills/README.md).
89
+
90
+ Consumer AGENTS.md stays pointer-thin — scan `.deft/core/REFERENCES.md` Skills Index; do not enumerate skills in the managed section.
91
+
92
+ ### Always-on bootstrap budget (DD-3, #2463)
93
+
94
+ `verify:agents-md-budget` now itemizes the always-on bootstrap surface:
95
+
96
+ - **Managed AGENTS.md** bytes (fail-closed ratchet via `plan.policy.agentsMdBudget.absoluteMaxBytes`)
97
+ - **Harness skill frontmatter** bytes (Cursor `<agent_skill>` shape; advisory unless `skillFrontmatterMaxBytes` is set)
98
+ - **Bootstrap hooks** bytes (0 until #2438 ships)
99
+
100
+ The north-star target is **≤8192 B / ~2k tok combined**. On Cursor with all skills injected, managed AGENTS.md (~16.8 KB) plus skill frontmatter (~7.7 KB) still exceeds that target — remediation paths:
101
+
102
+ 1. **Tier skills** — install only the daily-core six (`setup`, `sync`, `build`, `pre-pr`, `review-cycle`, `triage`) via OpenPackage; set `plan.policy.agentsMdBudget.skillFrontmatterTier` to `daily-core` or export `DEFT_AGENTS_MD_BUDGET_SKILL_TIER=daily-core`.
103
+ 2. **Thin managed AGENTS.md** — continue epic #2369 relocation; push bulk to `commands.md`, `scm/github.md`, and skills.
104
+ 3. **Shorten SKILL.md descriptions** — advanced-tier skills (`release`, `swarm`, `debug`, `article-review`, …) are the largest frontmatter offenders.
105
+ 4. **Optional ratchet** — seed `plan.policy.agentsMdBudget.skillFrontmatterMaxBytes` at the measured tier size when you want fail-closed DD-3 growth control.
106
+
107
+ Non-native-skill harnesses (Codex CLI, OpenCode) report 0 B frontmatter; set `harnessProfile: none` in policy when appropriate.
108
+
71
109
  ## xBRIEF layout migration (#2034 / #2110)
72
110
 
73
111
  After upgrading to a release that ships the xbrief rename, convert legacy on-disk layout if `deft doctor` reports a `vbrief/` tree or `x-vbrief/` reference tokens:
package/commands.md CHANGED
@@ -99,11 +99,16 @@ Common commands:
99
99
  Before implementation work, use:
100
100
 
101
101
  ```bash
102
+ git status --short --branch
102
103
  task verify:story-ready -- --vbrief-path xbrief/active/<file>.xbrief.json
103
104
  deft xbrief:preflight -- xbrief/active/<file>.xbrief.json
104
105
  ```
105
106
 
106
- The implementation gate succeeds only for active scope xBRIEFs with `plan.status == "running"`.
107
+ Gate 0 `task verify:story-ready` machine-checks working-tree cleanliness (or `--allow-dirty`), the target xBRIEF in `xbrief/active/` with `plan.status == "running"`, and the dispatch envelope's `## Allocation context` consent token (#1378). A `swarm-cohort` section is ready only when `allocation_plan_id` AND `batching_rationale` are non-null. Complete stories with `task scope:complete -- <active-story-path>`.
108
+
109
+ **Story Start Gate (#1378):** Before starting any new implementation story or switching stories, run `git status --short --branch`. If the working tree is dirty, stop and summarize the current branch, modified/untracked files, and whether the changes appear related to the next story — ask the operator to choose: commit existing work, stash existing work, include existing work in the current story, or stop. ⊗ Do not begin a new story while unrelated dirty work is present without explicit operator approval. When invoked as part of a swarm cohort dispatch, the approved Phase 5 allocation plan satisfies batching consent (#954); between stories checkpoint-commit it and proceed — do not pause to ask the operator mid-cohort. Promote/activate via `task scope:promote -- <path>` / `task scope:activate -- <path>`; preflight with `deft xbrief:preflight -- <active-story-path>`.
110
+
111
+ The implementation gate succeeds only for active scope xBRIEFs with `plan.status == "running"`. Do not infer implementation intent from lifecycle vocabulary — require explicit action-verb directives (`build`, `implement`, `ship`, `swarm`, `run agents`, `start agent`) per #810.
107
112
 
108
113
  ```mermaid
109
114
  flowchart TD
@@ -176,6 +181,18 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
176
181
 
177
182
  Use `task --list` for the exact current verify namespace.
178
183
 
184
+ ## Session-start ritual (#1149)
185
+
186
+ Full always-on contract for the interactive session-start ritual and its gated verifier (#1149 / #1348).
187
+
188
+ - ! On every interactive session start, run `deft session:start` (or `task session:start` in framework source) after loading AGENTS.md. Records quick-tier ritual in `.deft/ritual-state.json`: alignment confirmation, branch-policy disclosure, `deft verify:tools` guidance, default-branch sync warnings, and `deft triage:welcome` one-liner. State is worktree- and HEAD-bound; stale after `plan.policy.sessionRitualStalenessHours` hours (default 4).
189
+ - ! Before any code-writing tool call or `start_agent` implementation dispatch, run `deft verify:session-ritual -- --tier=gated`. Gated tier fails closed unless quick-tier state is fresh; lazily records `deft doctor` and `deft verify:cache-fresh` entrypoints. Step 0 of the pre-`start_agent` gate stack.
190
+ - ? Postpone with `deft session:start -- --defer step=reason` (`alignment`, `branch_policy`, `triage_welcome`, `doctor`, `cache_fresh`).
191
+ - Headless workers / CI MAY set `DEFT_SESSION_RITUAL_SKIP=1`; verifier exits 0 but warns when bypass hides failure.
192
+ - ⊗ Self-report ritual complete without fresh `deft session:start` state; ⊗ bypass `deft verify:session-ritual` before implementation dispatch; ⊗ reorder/skip/merge ritual tiers without operator override.
193
+
194
+ **Pre-`start_agent` gate stack (#1149/#1348):** (0) `deft verify:session-ritual -- --tier=gated` → (1) `deft verify:story-ready` → (2) `deft xbrief:preflight` → (3) `deft verify:cache-fresh` → (4) `deft verify:branch` + hooks → (5) `start_agent`.
195
+
179
196
  ```mermaid
180
197
  flowchart TD
181
198
  Session["task session:start"] --> Ritual["task verify:session-ritual -- --tier=gated"]
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deftai/directive-content",
3
- "version": "0.73.1",
3
+ "version": "0.75.0",
4
4
  "description": "Shippable Directive framework content in the consumer .deft/core/ layout (C1 flatten), plus the engine surfaces (.githooks/, Taskfile.yml, tasks/) the deposit wires. Python-free per #2022 Phase 3. Refs #11, #1669, #1967.",
5
5
  "type": "module",
6
6
  "files": [