@deftai/directive-content 0.100.0 → 0.101.0

package/commands.md

@@ -137,6 +137,12 @@ Common commands:
 - `task scope:promote -- --batch` -- batch-promote **all** `xbrief/proposed/` scopes to `pending/` in one command (#3011 / epic #3009). Optional: `--batch <path>…` for an explicit list; `--force` overrides WIP cap (logged). Does **not** activate; implement remains one `scope:activate` at a time.
 - `task scope:activate -- xbrief/pending/<file>.xbrief.json` -- move accepted work to `active/` and set status to `running`.
 - `task scope:complete -- xbrief/active/<file>.xbrief.json` -- move running work to `completed/` and set status to `completed`.
+  - **Per-criterion acceptance evidence (#3240 / #3305):** each non-terminal `plan.items[]` entry needs either namespaced typed evidence or a human-origin disposition before complete may advance it:
+    - `plan.items[].x-directive/evidence` — `{ kind: test|review|merge|deploy|smoke|uat|observed_behavior, pointer, recorded_at, recorded_by }`
+    - `plan.items[].x-directive/disposition` — `{ disposition: waived|deferred|not_applicable, reason, provenance (human-origin), recorded_at }`
+  - Bare `evidence` / `disposition` keys are **not** valid (#1620 / Option B #3305). They fail `verify:vbrief-conformance` and are treated as missing by `scope:complete` (no dual-read). Migrate bare keys or narrative-only `Result`/`Verification` workarounds to the namespaced fields above while items are still non-terminal.
+  - Already-terminal items (`completed`/`failed`/`cancelled`/…) are not re-checked for typed evidence; pre-marking items complete to skip the gate is unsupported for the typed path.
+  - `merge`/`review` alone cannot satisfy smoke/UAT/deploy/observed_behavior criteria (title/Acceptance text or explicit axis).
 - `task scope:fail -- xbrief/active/<file>.xbrief.json` -- mark running work failed when the scope cannot complete.
 - `task scope:cancel -- <path>` -- move a scope to `cancelled/`.
 - `task scope:restore`, `task scope:block`, `task scope:unblock`, `task scope:demote`, and `task scope:undo:*` -- repair or reverse lifecycle transitions.
@@ -269,7 +275,8 @@ Current status: the validation, extractor, provider, registry, generated MAP, an
 - `task verify:capacity`, `task verify:wip-cap`, and `task verify:judgment-gates` -- policy/capacity gates.
 - `task verify:orphan-active` -- fail closed when active/running xBRIEFs still point at closed issues or merged PRs (#2321).
 - `task verify:completed-tracked` -- fail closed when closed scoped issues lack a tracked `xbrief/completed/` or `xbrief/cancelled/` artifact on the delivery tip (#3264); remediate with `task swarm:finalize-cohort` or a lifecycle PR. Standalone verb (not part of `task check`); use `--tip HEAD` when validating an in-flight land branch.
-- `task verify:literal-ac` -- run stated acceptance commands from the active (or `--xbrief`) scope artifact **verbatim** before done (#3267); same flags/cwd; fail closed on non-zero. `--capture-only` lists resolved commands without executing. Standalone (not part of `task check`); required on ceremony dial rapid/minimal. Extends #973.
+- `task verify:ac` -- product-first acceptance gate (#3284). Runs `plan.acceptance.commands` (or #3267 literal ledger) **verbatim** before done; records AC-source rung (`stated`/`derived`/`project_floor`). Empty commands require `none_stated: true`. Primary name used first in `task check` (fail-fast); `--soft-missing-xbrief` for check composition. Rapid ceremony = AC-only; pressure/degraded makes hygiene advisory. `--capture-only` lists resolved commands without executing. Extends #3267 / #973.
+- `task verify:literal-ac` -- #3267 mechanism alias for verbatim stated-command run (same flags/cwd); prefer `verify:ac` for product-first done-gate.
 - `task coverage:hotspots` / `deft coverage:hotspots` -- read the latest coverage report, compare global metrics to the project's vitest thresholds, fail closed below the branch floor or below configured headroom (default 0.3pp), and list lowest modules plus uncovered branch samples for git-diff paths (`--json` for agents). Complements `deft verify:forward-coverage` (#1310) and `--allow-coverage-debt=#N` (#2573); does not replace them.
 
 Use `task --list` for the exact current verify namespace.
@@ -343,6 +350,7 @@ When the workflow needs an Approach 1 monitor, scope the Cursor leaf `stop-at: p
 - The P0 hook slice does not classify shell-mediated *file* writes, richer unified-exec calls, or WebSearch by default. **Runtime authority (#1394 / #2711)** adds opt-in path allow/deny lists and graduated `scopes` (`edits`, `push`, `merge`) under `plan.policy.runtimeAuthority` — inspect with `deft policy:show --field=runtimeAuthority`. When `enabled: true`, PreToolUse denies classifiable direct-write targets outside `allowPaths` or matching `denyPaths` after ritual/scope/read-only gates; `scopes.edits` gates all direct writes. `scopes.push` / `scopes.merge` deny classifiable Shell/Bash (`git push`, `gh pr merge`) and classifiable MCP push/merge tool names; unclassifiable shell/MCP calls fail open (see `content/contracts/runtime-authority.md`). **Unified path write fence (#516 / #2443 / #2948 Wave 3):** PreToolUse also intersects project allow/deny with the active story’s `plan.metadata.swarm.file_scope` via `resolveWriteFence` (single evaluation SoT; optional `writeScope` alias normalizes at read-time only). Full contract: `content/contracts/path-write-fence.md`.
 - **Human-origin authz + UAT mutation lease (#2944 / #2948 Wave 1)** — `deft authz:uat-start` / `authz:grant` / `authz:show`. When UAT is active, PreToolUse denies product/UI edits, push, PR create/advance, and merge without a named fix-cohort human-origin grant; tests, issue filing, and evidence/defect-capture writes stay allowed. Self-authored xBRIEF/lifecycle/dispatch tokens never satisfy implement gates. Contract: `content/contracts/human-origin-authz.md`.
 - **Closed-verb release gates + AFK templates (#1095 / #2948 Wave 4)** — `deft authz:grant -- --template release-publish --target <ver>` (also `release-cut`, `release-rollback`) mints Wave 1 operator-cli grants only. `deft release-publish` / `task release:publish` fails closed before draft→public unless a matching grant exists or `DEFT_ALLOW_RELEASE_PUBLISH=1`. No second session-auth mint engine. Contract: `content/contracts/closed-verb-authz.md`.
+- **Structural scope:decompose apply grant (#3239 / #3291)** — after `scope:decompose --check` validates a draft, mint with `deft authz:grant -- --parent <parent.xbrief.json> --draft <draft.json> [--repo owner/name] [--single-use] --confirm` (typed phrase `mint` on a real TTY). Digests exact draft bytes and binds parent/target/worktree (and optional repo). Then `deft scope:decompose -- <parent> --draft <draft>`. `--check` stays ungated. Apply denies print the exact mint command.
 - **Walk-away finish-loop (#871 / #2948 Wave 5)** — `deft authz:grant -- --template finish-loop`; `task directive:finish-loop` / `task pr:finish-loop -- <N>`. Progress log `.deft-cache/finish-loop-progress.jsonl`. Contract: `content/contracts/finish-loop.md`.
 - **Typed escalation queue (#518 slim / #2948 Wave 5)** — `deft escalation:file` / `list` / `resolve` / `batch-approve`. Fixed types (`cmd_approval`, `design_decision`, `approval`, `resource`, `external`, `question`) under `.deft/escalations/`. Bulk approve only for non-dangerous `cmd_approval` + `question`. Full priority-inbox web UI residual. Contract: `content/contracts/escalation.md`.
 
@@ -395,6 +403,7 @@ Cross-link: spawn three postures and deny recoveries live under § Agent-host di
 ### Mutable ritual (mutation posture)
 
 - ! On **mutation** 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).
+- ! **Orientation compression Now (#3286):** mutation cold `session:start` composes `doctor` + #3282 toolchain preflight (and deposit-sha fast-paths for `agents:refresh` / `verify:cache-fresh`) as inline sections with per-section status lines — composition of existing steps, not a new monolith. When the deposit fingerprint (payload + templates + engine) is unchanged, refresh surfaces print one-line `unchanged - sha match` no-ops. Opt-in compact output: `deft session:start -- --compact` or `DEFT_SESSION_COMPACT=1` (verbose remains the default). #2176 read-only default is unchanged. Dual-path Later (`deft orient`) stays open until run-summary telemetry shows ritual+gate share ≥ 25% after Now ships (#2899).
 - ! Cold `session:start` does **not** run the live agent-hook probe. Functional readiness belongs to the gated mutation path so cold ceremony retains the #2990/#2991 latency profile.
 - ! **Hot path latency (#2991):** by default, mutation `session:start` does **not** block ritual-state write on optional network. It skips the npm release-availability probe and triage cache empty-hydrate / self-heal (`ensureTriageCacheHydrated` / `maybeSelfHealCache`). Targets (operator-facing, not CI-hard): warm hot path typically under a few seconds once tools are on PATH; cold path dominated by local `verify:tools` and git, usually well under ~30s when optional network is off. Empty-cache GitHub fetch-all and npm `view` previously accounted for multi-minute hangs in the WWYSYDH pilot — those stay off the critical path unless opted in.
 - ! **Cold vs re-arm ceremony tiers (#2992):** default `session:start` is the **cold** (full) path. After age staleness or compact re-arm (#2113) on the **same worktree** with continuous HEAD and previously-passing quick steps, prefer `deft session:start --rearm` (alias `--tier=rearm`) to refresh the ritual clock + HEAD/worktree bind without `verify:tools`, triage welcome, release probe, or staleness tickler. Full cold remains required for missing/invalid state, worktree change, discontinuous HEAD, first install, or failed/missing quick steps. Compact marks `rearm_needed`; PreToolUse denial and inspect/verify messages prefer re-arm recovery when cold is unnecessary.
@@ -530,6 +539,7 @@ Directive does not guess your mix. Either you name the next units in order (**or
 - `task triage:bulk-accept|bulk-reject|bulk-defer|bulk-needs-ac` -- apply predictable decisions over filtered cached candidates.
 - `task triage:summary`, `task triage:scope`, `task triage:scope-drift`, `task triage:subscribe`, `task triage:unsubscribe`, `task triage:classify`, `task triage:welcome`, and `task triage:smoketest` -- supporting workflow and onboarding commands.
 - `task triage:classify -- --mirror [--apply] [--re-enrich] [--include-closed] [--author LOGIN|@me] [--repo owner/name] [--batch-size N] [--delay-ms N] [--sample-limit N] [--json]` -- **Bootstrap mass-triage / Tier-1 SCM label mirror (#1423 Wave 1–2 / #3125, #3129, #3197).** Runs the existing classify engine over the github-issue cache and mirrors outcomes as labels (`triaged` idempotency marker + optional `plan.policy.triageLabelMirror.actionLabels`). **Default state filter is open-only** (opt-in `--include-closed` for closed archive stamps). Optional `--author` / `--author-mine` scopes plan/apply to matching `author.login` (AND with open-only; digest surfaces the filter) (#3129). Dry-run by default: operator digest with totals (scanned/planned/already_triaged/no_match/closed_skipped/author_skipped/errors), breakdown by **state / rule / action**, and samples (not a full dump as primary UX); `--json` includes the same aggregates. `--apply` writes via the SCM label client / repo-mutation boundary in **batches** (`--batch-size`, default 10) with **rate-limit delay** (`--delay-ms`, default 1000), reports partial failures, and is idempotent on re-run (already-`triaged` skip). **Re-run vs re-enrich (#3124 / #3197):** default re-run keeps the one-shot stamp (`skipped_already_triaged`). After `actionLabels` / auto-classify rule / hold-marker changes, opt in with **`--re-enrich`** (still dry-run by default; pair with `--apply` to write) to re-classify already-stamped issues and plan **additive** label deltas only (v1 never removes obsolete chips; never full reconcile). Digest distinguishes `kind=first-time` vs `kind=re-enrich` planned/applied rows (`planned_kind` / `re_enrich_planned`). Missing labels fail closed per issue with a create-label hint. **Never** calls `triage:accept` and **never** writes `proposed/` xBRIEFs. Wave 3 (agent Tier-2 comments) remains out of scope.
+- **Operator discovery for SCM label mirror (#3124).** Cold `session:start` (via `triage:welcome` default mode) surfaces a **throttled** tip until the first successful `--mirror` dry-run or operator ack — **not** on every re-arm. Tip teaches existence **and** get-the-most: dry-run `deft triage:classify -- --mirror` (open-only; `--include-closed` opt-in); `--apply` batches writes and **never** auto-accepts into `proposed/`; defaults only stamp **`triaged` on matches** (control stamp, not disposition); **board usability is greatly decreased without `actionLabels`** — recommend full five-chip map (`defer→triage:deferred`, `archive→triage:archived`, `accept→triage:lifecycle-linked`, `escalate→triage:needs-human` + always `triaged`); more matches → `plan.policy.triageAutoClassify` in PROJECT-DEFINITION; inspect via `deft policy:show --field=plan.policy.triageLabelMirror`; labels must exist on GitHub; applying `triaged` before action chips skips re-enrichment on re-run (use `--re-enrich`); point at consumer kit **#2611** (`content/docs/consumer-issue-label-kit.md`) — do not invent vocabulary. Dismiss without dry-run: `deft triage:classify -- --ack-discovery` (production entry for tip ack). Dry-run digests SHOULD footer-hint when `actionLabels` is empty or open `no_match` dominates. **Anti-swallow:** when the tip fires, agents MUST restate existence + get-the-most in the **user-visible** message (not absorb ceremony alone).
 
 ### Cache Tasks
 
@@ -603,6 +613,7 @@ Taskfile targets are the stable surface for validation, rendering, lifecycle mov
 - `.deft/core/run spec` -- interactive scope/spec interview flow.
 - `.deft/core/run validate` -- configuration validation compatibility surface.
 - `.deft/core/run doctor` -- compatibility entry to doctor checks.
+- **`DEFT_SESSION_CODA` (interactive doctor success, #2712):** after the final human success footer only (exit 0; TTY stdout; not CI; not `--json`): **unset** prints `Session coda: off (set DEFT_SESSION_CODA=1 to enable)`; **`=1`** prints one deterministic `✦ <line>` from the content pack; **`=0`** is silent. Never on hard fail, never in JSON. See `deft doctor --help`.
 - `.deft/core/run reset` -- reset helper.
 - `.deft/core/run upgrade` -- legacy metadata acknowledgment; it does not replace the framework payload.
 

package/conventions/content-manifest.json

@@ -87,6 +87,11 @@
       "bucket": "content",
       "note": "Consumer-facing concept/guide docs promoted from the maintainer docs/ tree (BROWNFIELD.md, getting-started.md, good-agents-md.md) per #1669 Wave-1 C3."
     },
+    {
+      "path": "content/doctor",
+      "bucket": "content",
+      "note": "Doctor operator microcopy pack (session-coda.json) for optional interactive session coda (#2712). Human TTY only; never AGENTS/skills/JSON."
+    },
     {
       "path": "content/events",
       "bucket": "content",

package/docs/consumer-issue-label-kit.md

@@ -50,6 +50,17 @@ Optional action chips (only if you set `plan.policy.triageLabelMirror.actionLabe
 
 Richer chips (`triage:lifecycle-linked`, `triage:needs-human`) exist in the maintainer set; adopt them only when your policy maps those actions.
 
+### Optional project routing
+
+Not part of Core always-recommend. Create on the forge **only if your project uses the path**, then document the name in the consumer catalog (for example `.github/ISSUE_LABELS.md`) so agents do not invent labels outside the catalog.
+
+| Label | Role |
+|-------|------|
+| `security` | Marks security-axis issues/PRs for **advisory** security review routing when the project has that path (for example a Security Officer or security-review checklist). |
+
+- ⊗ Treat `security` as a merge gate or as a substitute for review bots (Greptile / SLizard / host security-review).
+- ⊗ Import maintainer-only AppSec facet trees or the full maintainer security taxonomy -- this kit stays portable and thin (#2609 boundary; #3007 is a different surface).
+
 ---
 
 ## Story / PR (MUST)
@@ -103,6 +114,9 @@ https://github.com/deftai/directive/blob/master/content/docs/consumer-issue-labe
 - optional action chips: triage:deferred, triage:archived
   (only if plan.policy.triageLabelMirror.actionLabels maps them)
 
+## Optional project routing (only if used)
+- security (advisory security review routing; not a merge gate)
+
 Do not invent labels outside this file. Prefer existing names over twins.
 ```
 

package/doctor/session-coda.json

@@ -0,0 +1,22 @@
+[
+  "A one-shot plan beats a ten-shot apology.",
+  "If the agent re-asked, the standard was soft.",
+  "Context is rent; spend it on the task, not the monologue.",
+  "Prefer a boring vertical slice to an exciting horizontal mess.",
+  "Doctor first. Then continue.",
+  "If it is not deterministic, it is not a gate.",
+  "Clarity over cleverness; cleverness over ceremony.",
+  "The next command is the product; everything else is noise.",
+  "Anti-slop is a practice, not a banner.",
+  "Ship the small true thing.",
+  "Agents forget; standards remember.",
+  "One next step. Not five optional journeys.",
+  "Brownfield is a path, not a personality.",
+  "Exit codes are for machines; codas are for operators.",
+  "Keep the success path shorter than the failure path.",
+  "Prefer a content pack to a hard-coded personality.",
+  "Interactive TTY is not a second API.",
+  "JSON mode stays silent; humans can tolerate one line.",
+  "Scope is a kindness to the next session.",
+  "Leave the repo easier to doctor than you found it."
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-content",
-  "version": "0.100.0",
+  "version": "0.101.0",
   "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.",
   "license": "MIT",
   "type": "module",