@deftai/directive-content 0.106.0 → 0.107.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/Taskfile.yml +13 -0
- package/UPGRADING.md +2 -2
- package/commands.md +6 -3
- package/contracts/design-critique.md +268 -14
- package/contracts/issue-eval.md +77 -0
- package/contracts/path-write-fence.md +126 -1
- package/contracts/runtime-authority.md +2 -0
- package/contracts/scm-readiness.md +2 -2
- package/docs/scope-provenance.md +1 -1
- package/package.json +1 -1
- package/packs/skills/skills-pack-0.1.json +19 -5
- package/scm/github.md +34 -1
- package/skills/deft-directive-build/SKILL.md +1 -1
- package/skills/deft-directive-design-critique/SKILL.md +14 -5
- package/skills/deft-directive-feedback/SKILL.md +11 -2
- package/skills/deft-directive-issue-eval/SKILL.md +48 -0
- package/skills/deft-directive-triage/SKILL.md +3 -2
- package/tasks/engine.yml +2 -0
- package/tasks/feedback.yml +1 -1
- package/tasks/occupancy.yml +11 -0
- package/tasks/scm.yml +14 -2
- package/tasks/session.yml +11 -0
- package/tasks/triage-evaluate.yml +22 -0
- package/tasks/verify.yml +10 -0
- package/templates/agent-prompt-preamble.md +19 -2
- package/templates/agents-entry.md +5 -5
- package/templates/design-critique-brief.md +19 -5
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: deft-directive-design-critique
|
|
3
3
|
description: >-
|
|
4
|
-
Thin router for the design-critique motion: triggers and
|
|
5
|
-
|
|
6
|
-
design-critique, critique panel, or mechanism-shaped
|
|
7
|
-
on ordinary implement, build, or swarm work.
|
|
4
|
+
Thin router for the design-critique motion: triggers and pointer stops into
|
|
5
|
+
the contract, including the operator-gated loop. Use when the operator asks
|
|
6
|
+
for a design critique, design-critique, critique panel, or mechanism-shaped
|
|
7
|
+
triage. Do NOT trigger on ordinary implement, build, or swarm work.
|
|
8
8
|
triggers:
|
|
9
9
|
- design critique
|
|
10
10
|
- design-critique
|
|
@@ -30,7 +30,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
30
30
|
|
|
31
31
|
## Stops
|
|
32
32
|
|
|
33
|
-
Normative rules live in [`contracts/design-critique.md`](../../contracts/design-critique.md). Fill [`templates/design-critique-brief.md`](../../templates/design-critique-brief.md) and dispatch from there. Phase 1 gate: [`docs/decisions/ADR-005-design-critique-judgment-gate.md`](../../../docs/decisions/ADR-005-design-critique-judgment-gate.md).
|
|
33
|
+
Normative rules live in [`contracts/design-critique.md`](../../contracts/design-critique.md). Fill [`templates/design-critique-brief.md`](../../templates/design-critique-brief.md) and dispatch from there. Phase 1 gate: [`docs/decisions/ADR-005-design-critique-judgment-gate.md`](../../../docs/decisions/ADR-005-design-critique-judgment-gate.md). Parent-audit principle: [`docs/decisions/ADR-006-parent-side-substantiation.md`](../../../docs/decisions/ADR-006-parent-side-substantiation.md).
|
|
34
34
|
|
|
35
35
|
1. Stop 1 — Gate
|
|
36
36
|
2. Stop 2 — Variant selection
|
|
@@ -38,6 +38,15 @@ Normative rules live in [`contracts/design-critique.md`](../../contracts/design-
|
|
|
38
38
|
4. Stop 4 — Residual reiteration
|
|
39
39
|
5. Stop 5 — Verified synthesis
|
|
40
40
|
|
|
41
|
+
Comment lead (model then role): Stop 3 — Critic envelope.
|
|
42
|
+
Operator-gated loop. Successor lean. Parent-side substantiation. Operator verbs. Dual stop. Halt line. Bind after accepted synthesis.
|
|
43
|
+
After critic post: posted successor lean, then verbs.
|
|
44
|
+
Auto-stamp after operator confirm; not while same-round siblings outstanding.
|
|
45
|
+
Walk / walk all. Auto-stamp when agents agree: Operator verbs.
|
|
46
|
+
Parent chip write: scm:issue:design-critique-chip.
|
|
47
|
+
|
|
48
|
+
Each critic dispatch EXITs after posting.
|
|
49
|
+
|
|
41
50
|
⊗ Auto-dispatch critics from this skill.
|
|
42
51
|
⊗ Copy the variant table, synthesis rules, or other contract bodies into this skill.
|
|
43
52
|
|
|
@@ -37,12 +37,19 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
37
37
|
- ! Batch multiple friction items into one upstream issue when they share a root cause; otherwise prepare separate drafts
|
|
38
38
|
- ~ Prefer attributed phrasing ("encoding gate blocked a valid file") over vague quality claims
|
|
39
39
|
|
|
40
|
+
## Phase 1.5 -- Adoption-blocker judgment
|
|
41
|
+
|
|
42
|
+
- ! Ask whether the gap blocks adoption. A gap blocks adoption when the consumer cannot complete an intended Directive flow and has no reasonable workaround.
|
|
43
|
+
- ! When the answer is yes, collect the body evidence a privileged actor needs before applying `adoption-blocker`: affected consumer flow and version; documented alternatives attempted, or why they are not a reasonable workaround; observed recovery cost. Pass `--blocker` (and `--flow`, `--alternatives`, `--recovery-cost` when known) so the title carries `BLOCKER` and the body carries those sections.
|
|
44
|
+
- ! When the answer is no or unknown, omit `--blocker`. Absence of the token does not mean "not a blocker" -- it means not classified.
|
|
45
|
+
- ⊗ Apply or request the `adoption-blocker` ranking label from a consumer-authored title. The label is a privileged write after the body-evidence test.
|
|
46
|
+
|
|
40
47
|
## Phase 2 -- Draft + dedup
|
|
41
48
|
|
|
42
49
|
- ! For each candidate report, run a dry draft:
|
|
43
50
|
|
|
44
51
|
```bash
|
|
45
|
-
task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --notes "<optional>"
|
|
52
|
+
task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --notes "<optional>" [--blocker --flow "<flow and version>" --alternatives "<alts>" --recovery-cost "<cost>"]
|
|
46
53
|
```
|
|
47
54
|
|
|
48
55
|
- ! Read the printed draft title/body with the operator before proceeding
|
|
@@ -55,7 +62,7 @@ task feedback:file -- --summary "<one-line summary>" --context "<session context
|
|
|
55
62
|
- ! Only after approval, re-run with `--confirm`:
|
|
56
63
|
|
|
57
64
|
```bash
|
|
58
|
-
task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --confirm
|
|
65
|
+
task feedback:file -- --summary "<one-line summary>" --context "<session context>" --expected "<expected>" --actual "<actual>" --confirm [--blocker]
|
|
59
66
|
```
|
|
60
67
|
|
|
61
68
|
- ! Print the filed issue URL to the operator
|
|
@@ -71,3 +78,5 @@ task feedback:file -- --summary "<one-line summary>" --context "<session context
|
|
|
71
78
|
- ⊗ Filing from the maintainer framework repo (consumer-only guard)
|
|
72
79
|
- ⊗ Skipping dedup review when the command reports an existing open issue
|
|
73
80
|
- ⊗ Treating `--confirm` as implicit from broad session approval -- require an explicit filing confirmation step
|
|
81
|
+
- ⊗ Infer "not a blocker" from an unmarked report -- absence of `BLOCKER` means not classified
|
|
82
|
+
- ⊗ Auto-apply `adoption-blocker` from a consumer-authored title
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: deft-directive-issue-eval
|
|
3
|
+
description: >-
|
|
4
|
+
Thin router for Stage A issue evaluation: isolated origin/master validity,
|
|
5
|
+
parent WIP census, named gitignored sink. Use when the operator asks to
|
|
6
|
+
evaluate issues, run issue-eval, or triage:evaluate. Do NOT trigger on
|
|
7
|
+
ordinary implement, build, swarm, or design-critique dispatch.
|
|
8
|
+
triggers:
|
|
9
|
+
- issue-eval
|
|
10
|
+
- issue eval
|
|
11
|
+
- triage:evaluate
|
|
12
|
+
- evaluate issues
|
|
13
|
+
---
|
|
14
|
+
<!-- AUTO-GENERATED by task packs:render -- DO NOT EDIT MANUALLY -->
|
|
15
|
+
<!-- Purpose: rendered skill -->
|
|
16
|
+
<!-- Source of truth: packs/skills/skills-pack-0.1.json -->
|
|
17
|
+
<!-- Regenerate with: task packs:render -->
|
|
18
|
+
<!-- Edit the source, not this file. Slice instead of loading every SKILL.md: task packs:slice skills by-trigger --trigger <kw> (or list) -->
|
|
19
|
+
|
|
20
|
+
# Issue Eval
|
|
21
|
+
|
|
22
|
+
Thin router into the issue-eval contract. Operator runs `task triage:evaluate`.
|
|
23
|
+
|
|
24
|
+
Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
25
|
+
|
|
26
|
+
## When to Use
|
|
27
|
+
|
|
28
|
+
- Operator asks to evaluate issues, run issue-eval, or `triage:evaluate`
|
|
29
|
+
- ⊗ Ordinary implement, build, swarm, or design-critique dispatch
|
|
30
|
+
|
|
31
|
+
## Stops
|
|
32
|
+
|
|
33
|
+
Normative rules live in [`contracts/issue-eval.md`](../../contracts/issue-eval.md).
|
|
34
|
+
|
|
35
|
+
1. Split read sources
|
|
36
|
+
2. Verdict sink
|
|
37
|
+
3. Evaluator worktrees
|
|
38
|
+
4. Value advice grammar
|
|
39
|
+
5. No GitHub writes
|
|
40
|
+
6. Fan-out
|
|
41
|
+
|
|
42
|
+
⊗ Emit `design-critique: warranted | not warranted, because` from evaluation.
|
|
43
|
+
⊗ Reuse `swarm:launch` until #3649.
|
|
44
|
+
⊗ Write `xbrief/proposed/` or GitHub from this skill.
|
|
45
|
+
|
|
46
|
+
## EXIT
|
|
47
|
+
|
|
48
|
+
deft-directive-issue-eval complete -- exiting skill. Next: run `task triage:evaluate`, then decide with existing `triage:*` verbs.
|
|
@@ -37,7 +37,7 @@ Legend (from RFC2119): !=MUST, ~=SHOULD, ≉=SHOULD NOT, ⊗=MUST NOT, ?=MAY.
|
|
|
37
37
|
|
|
38
38
|
## Deterministic Questions Contract
|
|
39
39
|
|
|
40
|
-
! Every numbered-menu prompt rendered in this skill (Phase 2 candidate selection, Phase 3 per-item decision walk) ! MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options are `Discuss` and `Back`, in that order, and the Discuss-pause semantic from the contract applies verbatim -- on `Discuss` the agent halts the in-progress sequence and resumes only on an explicit user signal.
|
|
40
|
+
! Every numbered-menu prompt rendered in this skill (Phase 2 candidate selection, Phase 3 per-item decision walk, post-Accept offer) ! MUST follow [`../../contracts/deterministic-questions.md`](../../contracts/deterministic-questions.md): render the canonical numbered menu in chat unless the host UI visibly preserves numeric option labels and returns numeric selections or exact displayed option text. The final two numbered options are `Discuss` and `Back`, in that order, and the Discuss-pause semantic from the contract applies verbatim -- on `Discuss` the agent halts the in-progress sequence and resumes only on an explicit user signal.
|
|
41
41
|
|
|
42
42
|
## Work selection fork (#2542 / #2402)
|
|
43
43
|
|
|
@@ -101,6 +101,7 @@ What would you like to do with this candidate?
|
|
|
101
101
|
- ~ Bulk: `task triage:bulk-{accept,reject,defer,needs-ac}`; results still flow through the audit log.
|
|
102
102
|
- ⊗ Write to `xbrief/proposed/` directly -- only `task triage:accept` is authorised.
|
|
103
103
|
- ~ **Accept → pending chain (#1136):** `task triage:accept` ingests into **`proposed/`**. To stage into WIP (`pending/`) in one operator action: `task triage:accept -- --issue <N> --repo OWNER/NAME --auto-promote` (WIP cap still enforced; use `--force` on the accept command for WIP override). Separately, promote an already-accepted proposed scope by issue: `task scope:promote -- --from-issue=<N> [--repo OWNER/NAME]` (gates on latest `candidates.jsonl` decision = `accept`; non-accept refuses unless `--force-no-cache`; no decision soft-warns, `--strict` fails). Path-based `task scope:promote -- <file>` remains ungated for refinement scaffolds.
|
|
104
|
+
- ? **After Accept (#3708):** offer `deft-directive-design-critique`. Optional; same after `--auto-promote` (promote already happened). Decline writes nothing. Menu: 1. Run critique (existing ADR-005 path) 2. Skip 3. Discuss 4. Back. Back = Skip (do not re-open Accept; undo is `task triage:reset`).
|
|
104
105
|
|
|
105
106
|
## Phase 4 -- Audit
|
|
106
107
|
|
|
@@ -141,5 +142,5 @@ Live walkers (`triage:queue`, scope-drift, bootstrap) scan `.deft-cache/github-i
|
|
|
141
142
|
|
|
142
143
|
## References
|
|
143
144
|
|
|
144
|
-
- #1119 D6; #1128 D11 (`triage:queue` / `show` / `audit`); #2890 Phase 3 operator brief; #3116 validity + URL-first; #1122 / #1123 / #1127 / #1129 / #1131; #1136 (`scope:promote --from-issue` / `triage:accept --auto-promote`)
|
|
145
|
+
- #1119 D6; #1128 D11 (`triage:queue` / `show` / `audit`); #2890 Phase 3 operator brief; #3116 validity + URL-first; #1122 / #1123 / #1127 / #1129 / #1131; #1136 (`scope:promote --from-issue` / `triage:accept --auto-promote`); #3708 (post-Accept design-critique offer)
|
|
145
146
|
- Siblings: `deft-directive-refinement`, `deft-directive-swarm`, `deft-directive-sync`
|
package/tasks/engine.yml
CHANGED
|
@@ -102,6 +102,8 @@ tasks:
|
|
|
102
102
|
" session:start "|" session-start "|\
|
|
103
103
|
" session:ready "|" session-ready "|\
|
|
104
104
|
" occupancy:steal "|" occupancy-steal "|\
|
|
105
|
+
" occupancy:release "|" occupancy-release "|\
|
|
106
|
+
" session:end "|" session-end "|\
|
|
105
107
|
" lifecycle:event "|" lifecycle-event "|\
|
|
106
108
|
" verify:session-ritual "|" verify-session-ritual "|\
|
|
107
109
|
" verify:tools "|" verify-tools "|\
|
package/tasks/feedback.yml
CHANGED
|
@@ -5,7 +5,7 @@ vars:
|
|
|
5
5
|
|
|
6
6
|
tasks:
|
|
7
7
|
file:
|
|
8
|
-
desc: "Draft or file a deduped framework-gap issue upstream (#1709). -- task feedback:file -- [--summary TEXT | positional] [--context ...] [--confirm] [--dry-run] [--json]"
|
|
8
|
+
desc: "Draft or file a deduped framework-gap issue upstream (#1709 / #3713). -- task feedback:file -- [--summary TEXT | positional] [--context ...] [--blocker] [--confirm] [--dry-run] [--json]"
|
|
9
9
|
deps:
|
|
10
10
|
- task: :engine:_ts-build
|
|
11
11
|
cmds:
|
package/tasks/occupancy.yml
CHANGED
|
@@ -15,3 +15,14 @@ tasks:
|
|
|
15
15
|
- task: :engine:invoke
|
|
16
16
|
vars:
|
|
17
17
|
ENGINE_CMD: 'occupancy:steal --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
|
18
|
+
|
|
19
|
+
release:
|
|
20
|
+
desc: "Release this worktree occupancy lease (#3604). Owner live or expired residue. Non-owner live denied."
|
|
21
|
+
dir: '{{.USER_WORKING_DIR}}'
|
|
22
|
+
# Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
|
|
23
|
+
env:
|
|
24
|
+
PYTHONUTF8: "1"
|
|
25
|
+
cmds:
|
|
26
|
+
- task: :engine:invoke
|
|
27
|
+
vars:
|
|
28
|
+
ENGINE_CMD: 'occupancy:release --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
package/tasks/scm.yml
CHANGED
|
@@ -13,6 +13,7 @@ version: '3'
|
|
|
13
13
|
# - scm:issue:view (thin wrapper over `ghx|gh issue view`)
|
|
14
14
|
# - scm:issue:close (thin wrapper over `ghx|gh issue close`)
|
|
15
15
|
# - scm:issue:edit (thin wrapper over `ghx|gh issue edit`)
|
|
16
|
+
# - scm:issue:design-critique-chip (#3642 closed catalog remaining-set)
|
|
16
17
|
# - scm:body:* (#1555 safe Markdown body posting via github-body TS CLI)
|
|
17
18
|
#
|
|
18
19
|
# Each command is a thin pass-through to `ghx <verb>` (when ghx is on PATH)
|
|
@@ -34,8 +35,9 @@ version: '3'
|
|
|
34
35
|
# stub deliberately does not re-implement; #881 owns the full surface.
|
|
35
36
|
#
|
|
36
37
|
# Forward-compat marker: v1 was issue:* plus #1555 body-posting. #3391
|
|
37
|
-
# adds scm:sync-default (dest-targeted staged sync PRs).
|
|
38
|
-
#
|
|
38
|
+
# adds scm:sync-default (dest-targeted staged sync PRs). #3642 adds
|
|
39
|
+
# scm:issue:design-critique-chip (closed catalog remaining-set). Other PR
|
|
40
|
+
# verbs remain #881.
|
|
39
41
|
# ---------------------------------------------------------------------------
|
|
40
42
|
|
|
41
43
|
vars:
|
|
@@ -89,6 +91,16 @@ tasks:
|
|
|
89
91
|
vars:
|
|
90
92
|
ENGINE_CMD: 'scm issue edit {{.CLI_ARGS}}'
|
|
91
93
|
|
|
94
|
+
issue:design-critique-chip:
|
|
95
|
+
desc: "[#3642] Exclusive design-critique catalog chip -- task scm:issue:design-critique-chip -- --issue N --chip triage-ready|mechanism-shaped [--repo OWNER/NAME]"
|
|
96
|
+
dir: '{{.USER_WORKING_DIR}}'
|
|
97
|
+
deps:
|
|
98
|
+
- task: :engine:_ts-build
|
|
99
|
+
cmds:
|
|
100
|
+
- task: :engine:invoke
|
|
101
|
+
vars:
|
|
102
|
+
ENGINE_CMD: 'scm issue design-critique-chip {{.CLI_ARGS}}'
|
|
103
|
+
|
|
92
104
|
body:issue:create:
|
|
93
105
|
desc: "[#1555] Safely create an issue body from --body-file without shell Markdown interpolation"
|
|
94
106
|
dir: '{{.USER_WORKING_DIR}}'
|
package/tasks/session.yml
CHANGED
|
@@ -30,3 +30,14 @@ tasks:
|
|
|
30
30
|
- task: :engine:invoke
|
|
31
31
|
vars:
|
|
32
32
|
ENGINE_CMD: 'session:ready --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
|
33
|
+
|
|
34
|
+
end:
|
|
35
|
+
desc: "End this mutation session by releasing occupancy (#3604). Same as occupancy:release."
|
|
36
|
+
dir: '{{.USER_WORKING_DIR}}'
|
|
37
|
+
# Runtime/session dispatch: no engine:_ts-build / pnpm build (#2181).
|
|
38
|
+
env:
|
|
39
|
+
PYTHONUTF8: "1"
|
|
40
|
+
cmds:
|
|
41
|
+
- task: :engine:invoke
|
|
42
|
+
vars:
|
|
43
|
+
ENGINE_CMD: 'session:end --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
version: '3'
|
|
2
|
+
|
|
3
|
+
# tasks/triage-evaluate.yml -- Stage A isolated issue-eval (#3648).
|
|
4
|
+
#
|
|
5
|
+
# Wired into Taskfile.yml under include key `triage-evaluate`. Inner task
|
|
6
|
+
# `evaluate` is exposed as `task triage:evaluate`.
|
|
7
|
+
#
|
|
8
|
+
# Per conventions/task-caching.md: NO sources/generates -- user-facing flags.
|
|
9
|
+
|
|
10
|
+
vars:
|
|
11
|
+
DEFT_ROOT: '{{joinPath .TASKFILE_DIR ".."}}'
|
|
12
|
+
|
|
13
|
+
tasks:
|
|
14
|
+
evaluate:
|
|
15
|
+
desc: "Evaluate issues off origin/master (validity + parent WIP + value). -- task triage:evaluate -- <N...> [--concurrency N] [--repo OWNER/NAME] [--json]"
|
|
16
|
+
internal: true
|
|
17
|
+
deps: [":engine:_ts-build"]
|
|
18
|
+
dir: '{{.USER_WORKING_DIR}}'
|
|
19
|
+
cmds:
|
|
20
|
+
- task: :engine:invoke
|
|
21
|
+
vars:
|
|
22
|
+
ENGINE_CMD: 'triage-evaluate --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
package/tasks/verify.yml
CHANGED
|
@@ -512,6 +512,16 @@ tasks:
|
|
|
512
512
|
vars:
|
|
513
513
|
ENGINE_CMD: 'verify:orphan-active --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
|
514
514
|
|
|
515
|
+
completed-write-guard:
|
|
516
|
+
desc: "Fail-closed completed/ write guard (#3679). Newly added xbrief/completed/ (or vbrief/completed/) artifacts must have been written by scope:complete / scope:fail. Historical corpus is advisory via doctor. Remediation names the leftover land PR (#3476). Three-state exit (0 clean / 1 unguarded add / 2 config). Does not change verify:completed-tracked."
|
|
517
|
+
dir: '{{.USER_WORKING_DIR}}'
|
|
518
|
+
deps:
|
|
519
|
+
- task: :engine:_ts-build
|
|
520
|
+
cmds:
|
|
521
|
+
- task: :engine:invoke
|
|
522
|
+
vars:
|
|
523
|
+
ENGINE_CMD: 'verify:completed-write-guard --project-root "{{.USER_WORKING_DIR}}" {{.CLI_ARGS}}'
|
|
524
|
+
|
|
515
525
|
completed-tracked:
|
|
516
526
|
desc: "Fail-closed completed-tracked land guard (#3264 / #1358 / #3476). Closed scoped GitHub issues with a known lifecycle xBRIEF origin must have a tracked xbrief/completed/ or xbrief/cancelled/ artifact on the delivery tip. --issue N is the drive-to DONE form. Remediation: task swarm:finalize-cohort or a lifecycle PR. Three-state exit (0 clean / 1 missing land / 2 config). Pass --skip-gh to rely on triage cache only; --tip to override delivery tip."
|
|
517
527
|
dir: '{{.USER_WORKING_DIR}}'
|
|
@@ -130,6 +130,7 @@ When present, document the fields in a separate `## Runtime and GitHub auth mode
|
|
|
130
130
|
|
|
131
131
|
- `runtime_mode`: one of `local-unsandboxed`, `cursor-native-sandbox`, or `cloud-headless` -- the execution envelope the worker runs in (from the read-only runtime probe, #1557a).
|
|
132
132
|
- `github_auth_mode`: one of `host-gh` or `injected-token` -- which GitHub credential rule applies to this worker (#1557b).
|
|
133
|
+
- `expected_github_login`: the bound user login when the dispatcher injected a user-bearing credential (#1351 / #3665). Login only -- never a token value. Omit when `github_auth_mode` is `host-gh` and no injection occurred.
|
|
133
134
|
|
|
134
135
|
Launch-manifest entries (#1387 C2 contract) carry the same two fields at the top level alongside `allocation_context`. Workers MUST read the dispatch envelope (or launch manifest) and apply the identity-separation rules in §8 according to `github_auth_mode`, not the historical one-size-fits-all injected-token default.
|
|
135
136
|
|
|
@@ -149,10 +150,24 @@ Worked example (cloud / headless worker):
|
|
|
149
150
|
|
|
150
151
|
- runtime_mode: cloud-headless
|
|
151
152
|
- github_auth_mode: injected-token
|
|
153
|
+
- expected_github_login: deft-swarm-bot
|
|
152
154
|
```
|
|
153
155
|
|
|
154
156
|
Reference: `packages/core/src/platform/platform-capabilities.ts` (#1557a), `packages/core/src/intake/github-auth-modes.ts` (#1557b), issue #1557.
|
|
155
157
|
|
|
158
|
+
## 2.75 Identity-bound worker credential injection (#1351)
|
|
159
|
+
|
|
160
|
+
When a dispatcher holds a user-bearing worker credential, it MUST inject that credential at spawn on the grok-build and local hybrid paths. Injection binds an identity; it does not only place a token. This helper is the operator-implemented injection the §8 conjunction names -- a dispatcher-invoked function, not a prompt-embedded token.
|
|
161
|
+
|
|
162
|
+
- ! Before spawn, call `prepareWorkerCredentialInjection` (`packages/core/src/swarm/launch.ts`). It validates the held credential as a **user** principal with the existing `validateGithubAuthForWorker`. Do not write a second validator and do not invent a second approval surface.
|
|
163
|
+
- ! On success, apply the returned `spawnEnv` to the worker **process environment** (`GH_TOKEN` plus `DEFT_EXPECTED_GITHUB_LOGIN`) and copy `envelopeSection` into the dispatch envelope. Stamp `expected_github_login` on the launch-manifest entry when launch already validated the same credential.
|
|
164
|
+
- ! On no available credential and a write-requiring injected-token operation, halt `BLOCKED`, naming the missing credential (`GH_TOKEN` / `GITHUB_TOKEN` / `GH_ENTERPRISE_TOKEN`) and the dispatcher-side remedy. Do not spawn.
|
|
165
|
+
- ⊗ Inject an App-installation credential. Those fail closed as `installation_identity_unverifiable` (#3693).
|
|
166
|
+
- ⊗ Continue under a detected host or maintainer identity, or fall back to the host `gh` token (`patterns/multi-agent.md` :70-75).
|
|
167
|
+
- ⊗ Place a credential value in the dispatch prompt, a transcript, or a launch-manifest entry. `spawnEnv` is process-env only.
|
|
168
|
+
|
|
169
|
+
Token minting remains an operator-owned #983 non-goal. This helper delivers a credential the dispatcher already holds; it does not mint one.
|
|
170
|
+
|
|
156
171
|
## 3. PowerShell 5.1 non-ASCII rule (#798)
|
|
157
172
|
|
|
158
173
|
If your shell is `pwsh 5.x` on Windows AND you are editing a file containing any non-ASCII glyph (em dashes, en dashes, arrows, smart quotes, ⊗, ✓, ellipses, emoji, ...), you MUST route the read AND write through Python `pathlib`:
|
|
@@ -436,7 +451,7 @@ Why: maintainer and workers sharing a single PAT couples the human review/merge
|
|
|
436
451
|
### injected-token mode (required for `github_auth_mode: injected-token` and always for `runtime_mode: cloud-headless`)
|
|
437
452
|
|
|
438
453
|
- ! Consume the GitHub credential injected by the dispatcher (typically `GH_TOKEN` / `GITHUB_TOKEN` / `GH_ENTERPRISE_TOKEN` in the prompt-supplied env). If unset and no other dispatcher-supplied credential is present, FAIL LOUD -- do not silently run under the host's `gh auth status` token.
|
|
439
|
-
- ~ Confirm the credential
|
|
454
|
+
- ~ Confirm the credential is the expected worker principal before GitHub operations. For a user-bearing credential, `gh api user --jq .login` should return the expected bot/account login, not the maintainer login. For a GitHub App installation credential, `/user` is inapplicable (structural 403; no authenticated user) -- do not treat that 403 as API unreachability. Installation identity cannot be verified from the token; fail closed and point at #3693. Do not accept the credential from endpoint reachability or a declared App slug. A user-login mismatch is `BLOCKED: identity mismatch` to the parent.
|
|
440
455
|
- ⊗ Inherit the maintainer's `gh auth status` token implicitly. Host `gh` fallback is forbidden in injected-token and cloud-headless modes.
|
|
441
456
|
|
|
442
457
|
### host-gh mode (permitted only when `github_auth_mode: host-gh`)
|
|
@@ -444,12 +459,14 @@ Why: maintainer and workers sharing a single PAT couples the human review/merge
|
|
|
444
459
|
Applies to local interactive workers (`runtime_mode: local-unsandboxed` or, after validation, `cursor-native-sandbox`) where swarm launch preflight confirmed `gh auth status` and repo access from the worker environment.
|
|
445
460
|
|
|
446
461
|
- ! Use the worker environment's `gh` credential store -- the dispatch envelope explicitly authorises host `gh` for this worker. Do NOT require an injected `GH_TOKEN` when host gh auth is already valid in the worker shell.
|
|
447
|
-
- ! Still verify identity before GitHub operations: `gh auth status` must pass
|
|
462
|
+
- ! Still verify identity before GitHub operations: `gh auth status` must pass. For a user-bearing credential, `gh api user --jq .login` must return the expected account. For a GitHub App installation credential, `/user` cannot return an account and the token cannot disclose which App it belongs to -- fail closed and point at #3693. Do not accept the credential from a declared App slug or from endpoint reachability, including a target-repo GET. User-login mismatch is `BLOCKED: identity mismatch`.
|
|
448
463
|
- ⊗ Fall back to host `gh` when `github_auth_mode` is `injected-token` or `runtime_mode` is `cloud-headless` -- those modes forbid host credential store use regardless of what is available on the host.
|
|
449
464
|
- ~ When `runtime_mode: cursor-native-sandbox`, host `gh` may fail inside the sandbox even when the parent session is authenticated. Fail loud with remediation (full-access execution, trusted-path allowlist, or switch to injected-token handoff) rather than assuming parent auth is visible to the worker.
|
|
450
465
|
|
|
451
466
|
Dispatchers MUST inject worker credentials for injected-token / cloud-headless dispatches and MUST record the selected `github_auth_mode` in the launch manifest and dispatch envelope. v1 deliberately keeps token injection operator-implemented; mode labels make the contract explicit without placing token values in prompts or transcripts.
|
|
452
467
|
|
|
468
|
+
#1351 supplies the identity-bound delivery helper in §2.75. Dispatchers on grok-build and local hybrid still record the mode on **both** the launch manifest and the dispatch envelope. They apply `prepareWorkerCredentialInjection` at spawn so the worker receives the token in process env and a stamped `DEFT_EXPECTED_GITHUB_LOGIN` / `expected_github_login`, not a prompt-embedded secret.
|
|
469
|
+
|
|
453
470
|
This rule is complementary to §5 (REST-by-default) and §7 (rate-limit-aware throttle): REST-by-default reduces GraphQL demand on whichever bucket the worker is using; rate-limit throttle keeps the worker from exhausting its own bucket; mode-aware identity separation prevents the worker bucket from being the maintainer's bucket when injected-token mode applies. All three are required for stable swarm operation.
|
|
454
471
|
|
|
455
472
|
## 9. Sub-agent spawn rules per #727
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
|
|
5
5
|
|
|
6
|
-
! If any .deft/core/.agents/skills/ path
|
|
6
|
+
! If any .deft/core/.agents/skills/ path here cannot be read (missing, stale, or a redirect stub), read .deft/core/QUICK-START.md and follow it — it refreshes this section idempotently for the current version.
|
|
7
7
|
|
|
8
8
|
## Temporary test kill-switch (#3039)
|
|
9
9
|
|
|
@@ -12,7 +12,7 @@ Deft is installed in .deft/core/. Full guidelines: .deft/core/main.md
|
|
|
12
12
|
|
|
13
13
|
## Session routing (#2176)
|
|
14
14
|
|
|
15
|
-
! **Read-only default** until mutation intent: load AGENTS.md / main.md / USER.md / `xbrief/PROJECT-DEFINITION.xbrief.json`; resolve USER.md via `deft session:start` (`USER.md resolved …`; win32 `%APPDATA%\deft\USER.md`; unix `~/.config/deft/USER.md`; ⊗ invent `~/.config/deft` on Windows #2544); confirm Deft alignment + addressing-name; ⊗ no mutable `deft session:start` / triage welcome / sync / branch-policy unless asked or implementation-ready (#2176) — `.deft/core/commands.md` § Session routing. Bootstrap: cold-start → README § Cold-start (#2273) ⊗ never `.deft/core/`; pre-cutover → setup Pre-Cutover (#2068); missing USER.md / PROJECT-DEFINITION → setup Phase 1/2 (#1813) ⊗ before answering; else main → USER → PROJECT-DEFINITION; ~ sync. Mutation → `deft session:start` then `deft verify:session-ritual -- --tier=gated` (#1149). Mutation
|
|
15
|
+
! **Read-only default** until mutation intent: load AGENTS.md / main.md / USER.md / `xbrief/PROJECT-DEFINITION.xbrief.json`; resolve USER.md via `deft session:start` (`USER.md resolved …`; win32 `%APPDATA%\deft\USER.md`; unix `~/.config/deft/USER.md`; ⊗ invent `~/.config/deft` on Windows #2544); confirm Deft alignment + addressing-name; ⊗ no mutable `deft session:start` / triage welcome / sync / branch-policy unless asked or implementation-ready (#2176) — `.deft/core/commands.md` § Session routing. Bootstrap: cold-start → README § Cold-start (#2273) ⊗ never `.deft/core/`; pre-cutover → setup Pre-Cutover (#2068); missing USER.md / PROJECT-DEFINITION → setup Phase 1/2 (#1813) ⊗ before answering; else main → USER → PROJECT-DEFINITION; ~ sync. Mutation → `deft session:start` then `deft verify:session-ritual -- --tier=gated` (#1149). Mutation occupancy lease (#3433/#3604): occupant `occupancy:release`/`session:end` (`commands.md`). ? `deft session:start -- --read-only` (#2176).
|
|
16
16
|
|
|
17
17
|
## Session-start ritual (#1149)
|
|
18
18
|
|
|
@@ -88,10 +88,9 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
|
|
|
88
88
|
## Envelope selection SLA (#3153)
|
|
89
89
|
|
|
90
90
|
! Default story / through-merge unit of work is `drive-to: merge-ready`. Deliberate `stop-at: pr-open` is allowed only when a **partner merge-path owner** is planned (review-cycle babysit / Approach 1 lease / parent-retained) for Greptile + CI + post-merge `scope:complete` — triggers: capacity stall, wall-clock budget, large multi-gate, host nest limits (swarm Phase 0 decision tree). Depth: `deft-directive-swarm` + `deft-directive-review-cycle` partner merge-path.
|
|
91
|
-
! Under human-merge policy, a **durable** owner (parent/monitor sticky lease or Phase 6 closer) MUST remain for post-merge `scope:complete` — CLEAN alone is not lifecycle complete.
|
|
91
|
+
! Under human-merge policy, a **durable** owner (parent/monitor sticky lease or Phase 6 closer) MUST remain for post-merge `scope:complete` — CLEAN alone is not lifecycle complete; ⊗ stand down at CLEAN with no reachable owner.
|
|
92
92
|
⊗ Silent PR-open handback for a worker already scoped `drive-to: merge-ready`.
|
|
93
93
|
⊗ `stop-at: pr-open` without a named babysit / merge-path owner, or dual review-monitor leases on recovery (#3044 / #2261).
|
|
94
|
-
⊗ Stand down at CLEAN under human-merge with no reachable post-merge `scope:complete` owner.
|
|
95
94
|
! After merge of issue `#N`, `deft verify:orphan-active -- --issue N` MUST exit 0 before `DONE` (#3429). After `scope:complete`, `deft verify:completed-tracked -- --issue N` MUST exit 0 on `origin/<deliveryBranch>` before `DONE` (#3476). Exit 1 shipped → printed `scope:complete`; missing tracked land → `swarm:finalize-cohort` or a lifecycle PR; unresolved lookup → retry / `BLOCKED` (⊗ complete unfinished scope).
|
|
96
95
|
⊗ Emit `ISSUE: closed` while that brief is still in `active/`.
|
|
97
96
|
|
|
@@ -112,6 +111,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
|
|
|
112
111
|
## Value feedback and attribution (#1709)
|
|
113
112
|
|
|
114
113
|
! `plan.policy.valueFeedback.enabled` defaults OFF — `deft policy:show --field=valueFeedback` / `deft policy:enable-value-feedback -- --confirm`; `deft value:show`; `deft feedback:file`; `.deft/core/.agents/skills/deft-directive-feedback/SKILL.md` (#1709).
|
|
114
|
+
! Consumer hard-stop (#3713): `BLOCKER` is the sole permitted title classification — `deft feedback:file --blocker`; absence is not a verdict. ⊗ Derive `adoption-blocker` from a consumer title (privileged, body-evidence gated); `.deft/core/scm/github.md`.
|
|
115
115
|
|
|
116
116
|
## Structured decision log (#1396 / #3211)
|
|
117
117
|
! Significant choices → `deft decision:write`; re-load → `deft decision:list` / `xbrief/decisions/`; depth `.deft/core/docs/decision-log.md` (not triage/ADRs/lessons).
|
|
@@ -122,7 +122,7 @@ Legacy `vbrief/` read-accepted; `deft migrate:xbrief` for `xbrief/` (v0.6→v0.8
|
|
|
122
122
|
## Branch policy & branch verification
|
|
123
123
|
|
|
124
124
|
! Feature branches — `deft verify:branch`, `deft verify:forward-coverage` (90% warn-first changed-branch coverage, not the 75 floor, #3514), `deft coverage:hotspots`, hooks, `deft check` (#746 / #747) — `.deft/core/scm/github.md` § Branch policy.
|
|
125
|
-
! Test placement + scope provenance (#3145) — `deft verify:test-boundary
|
|
125
|
+
! Test placement + scope provenance (#3145) — `deft verify:test-boundary` (warn-only until authored policy), `deft verify:scope-provenance` (`--enforce` is empty-scope only; declared `file_scope` without base approval fails closed), `deft verify:consumer-check-contract` (check composition fails closed; CI omissions warn) (docs: `docs/test-boundary.md`, `docs/scope-provenance.md`, `docs/consumer-check-contract.md`).
|
|
126
126
|
|
|
127
127
|
## Branch Policy Disclosure (#746)
|
|
128
128
|
|
|
@@ -4,20 +4,24 @@ Dispatch envelope skeleton for one critic or synthesis pass. Fill the fields. Re
|
|
|
4
4
|
|
|
5
5
|
## Envelope fields
|
|
6
6
|
|
|
7
|
+
- Model (copy onto the first line of the posted comment as `model: <slug>`):
|
|
8
|
+
- Role (copy onto the second line of the posted comment as `role: triage|critic|parent`):
|
|
7
9
|
- Issue:
|
|
8
|
-
-
|
|
10
|
+
- Charter (refutation | open critique), spend (N=1 | N≥3 when panel permission is used), and one-line reason:
|
|
9
11
|
- Round (1 critic | 2 reiteration | 3 synthesis | 4 Pass-4 audit):
|
|
10
12
|
- Critic role (fresh | resume):
|
|
11
13
|
- Id ceiling (GitHub comment id, inclusive):
|
|
12
14
|
- SHA at dispatch:
|
|
13
15
|
- Target (work issue or umbrella):
|
|
16
|
+
- Audit targets (marker ids, comma-separated, or `none`; ids only, no parent rationale):
|
|
14
17
|
|
|
15
18
|
## Forbidden inputs
|
|
16
19
|
|
|
17
20
|
Do not put these in the envelope:
|
|
18
21
|
|
|
19
22
|
- parent hypotheses
|
|
20
|
-
-
|
|
23
|
+
- parent rationale on the audit-targets field (ids only)
|
|
24
|
+
- named refutation target (unless the recorded charter is refutation)
|
|
21
25
|
- parent-edited critic text
|
|
22
26
|
- thread comments after the id ceiling
|
|
23
27
|
- the superseded proposed skill outline on #3434
|
|
@@ -31,11 +35,21 @@ Read, do not restate:
|
|
|
31
35
|
| Topic | Contract heading |
|
|
32
36
|
|---|---|
|
|
33
37
|
| Gate (ADR-005) | Stop 1 — Gate |
|
|
38
|
+
| Stop 1 `refutation-target:` | Stop 1 — Gate |
|
|
34
39
|
| Variant selection | Stop 2 — Variant selection |
|
|
35
|
-
|
|
|
40
|
+
| Parent-facing dispatch rules | Parent-facing dispatch rules |
|
|
41
|
+
| Critic method | Critic method |
|
|
42
|
+
| Envelope and ceiling | Envelope and ceiling |
|
|
43
|
+
| Comment lead (model then role) | Stop 3 — Critic envelope |
|
|
36
44
|
| Fresh reiteration | Stop 4 — Residual reiteration |
|
|
45
|
+
| Operator-gated loop | Operator-gated loop |
|
|
46
|
+
| Successor lean | Successor lean |
|
|
47
|
+
| Parent-side substantiation | Parent-side substantiation |
|
|
48
|
+
| Operator verbs | Operator verbs |
|
|
49
|
+
| Dual stop | Dual stop |
|
|
50
|
+
| Halt line | Halt line |
|
|
37
51
|
| Synthesis format | Stop 5 — Verified synthesis |
|
|
38
|
-
|
|
|
52
|
+
| Bind after accepted synthesis | Bind after accepted synthesis |
|
|
39
53
|
| Untrusted threads | Security context (#480) |
|
|
40
54
|
|
|
41
|
-
Operator dispatches. Auto-dispatch is deferred. The five stops live in the contract.
|
|
55
|
+
Operator dispatches. Auto-dispatch is deferred. Each critic dispatch EXITs after posting. The five stops and the operator-gated loop live in the contract.
|