@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.
- package/.githooks/pre-commit +1 -2
- package/.githooks/pre-push +1 -1
- package/QUICK-START.md +28 -34
- package/Taskfile.yml +10 -0
- package/UPGRADING.md +38 -0
- package/commands.md +18 -1
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +23 -23
- package/scm/github.md +50 -0
- package/skills/deft-directive-setup/SKILL.md +16 -0
- package/tasks/engine.yml +26 -5
- package/tasks/verify.yml +11 -1
- package/templates/agents-entry.md +16 -71
- package/skills/deft-build/SKILL.md +0 -20
- package/skills/deft-interview/SKILL.md +0 -16
- package/skills/deft-pre-pr/SKILL.md +0 -16
- package/skills/deft-review-cycle/SKILL.md +0 -16
- package/skills/deft-roadmap-refresh/SKILL.md +0 -16
- package/skills/deft-setup/SKILL.md +0 -20
- package/skills/deft-swarm/SKILL.md +0 -16
- package/skills/deft-sync/SKILL.md +0 -16
package/.githooks/pre-commit
CHANGED
|
@@ -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 $?
|
package/.githooks/pre-push
CHANGED
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 —
|
|
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
|
-
###
|
|
47
|
+
### 1a. Does `../AGENTS.md` exist?
|
|
55
48
|
|
|
56
|
-
- **No:** treat as fresh install — jump to Case F ("No AGENTS.md") in Step
|
|
57
|
-
- **Yes:** continue to
|
|
49
|
+
- **No:** treat as fresh install — jump to Case F ("No AGENTS.md") in Step 2.
|
|
50
|
+
- **Yes:** continue to 1b.
|
|
58
51
|
|
|
59
|
-
###
|
|
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
|
|
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
|
|
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
|
|
69
|
-
-
|
|
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
|
|
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
|
-
###
|
|
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
|
|
85
|
-
- If both contain the sentinel (or neither exists), continue to
|
|
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
|
-
###
|
|
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
|
|
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
|
-
###
|
|
83
|
+
### 1e. Everything clean
|
|
92
84
|
|
|
93
|
-
If none of
|
|
85
|
+
If none of 1a–1d 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
|
|
87
|
+
## Step 2 — Act on detected state
|
|
96
88
|
|
|
97
|
-
Pick exactly one case from Step
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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.
|
|
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": [
|