@deftai/directive-runtime 0.126.0-beta.2 → 0.127.0

package/vendor/directive-content/contracts/design-critique.md

@@ -13,6 +13,11 @@ This contract scaffolds the motion. Only the ADR-005 judgment gate and the conte
 - ⊗ Pin this contract or `skills/deft-directive-design-critique` into `templates/agents-entry.md` or the AGENTS.md always-pin list. Discovery is on-demand via the Skills Index.
 - ⊗ Auto-dispatch critics from this contract (#3578 / #1702). Operator (or parent after an operator verb) dispatches the next envelope from the brief template.
 
+### Pre-ingest recommendation (#5716)
+
+Before `issue:ingest` for every GitHub issue, run the design-critique arc or record `design-critique: not warranted, because …`. ADR-005 is unchanged: no auto-dispatch, no engine refusal of unarced work. The ingest advisory is exit 0 and never blocks. This scaffolds the recommendation; content-contract tests lock the skip-form string. Discovery stays on-demand (no always-pin of this skill or contract path). Issue-less scopes use `## No-issue target archive (#5486)` — this GitHub ingest advisory does not extend there.
+
+
 ### The arc
 
 **An arc is one recorded motion over one target revision**, from the Stop 1 write-back (or a voluntary dispatch) through accepted synthesis or the halt line. It holds one or more rounds, and therefore one or more ceilings. An arc is per-target, not per-issue: one issue carries several arcs over time, and one arc can span several issues.
@@ -138,6 +143,15 @@ After Handoff, Stop 2 evaluation does not re-select charter from the issue body
 
 Default motion after a mechanism-shaped stamp: fresh open critique. N=1 (and N≥3 when recommend says so under panel permission) only after a resolved `n=` token, a recorded ask-answer, or a recorded `spend-recommend:` resolve. If residual remains, one reiterating pass with a fresh critic that reads a disagreement map, then verified synthesis. Resume is optional sharpening ("does my prior finding still hold"), not the default reiterating agent. A permitted N≥3 does not change that default; the parent records the spend when it uses the permission after parseOperatorSpend, an ask-answer, or a panel-permission-lawful `spend-recommend: N≥3`.
 
+### Target-kind (#5486)
+
+**Target-kind** is what durable identity the arc binds (`issue` | `xbrief` | `envelope-file`). It is orthogonal to `### Target shape` (set-level / against-implementation) and does not select charter or spend.
+
+- ! Record `Target-kind:` on the lean when the target is not a GitHub issue. Default remains `issue`.
+- ! Target-digest hashes canonical target bytes for that kind (REST issue body, xBRIEF file bytes, or envelope-file bytes). Protocol / gate / chip state stays outside digested bytes.
+- ! Envelope-file targets need durable bytes before Stop 1.
+- ⊗ Treat Target-kind as a Target shape row or a charter/spend row.
+
 ### Target shape
 
 Charter is what the critic is given. **Target shape is what is being critiqued.** The two are independent axes, and target shape selects neither the charter nor the spend, so it is not a row in either table above.
@@ -205,6 +219,21 @@ The three tokens are the blocking, sharpening, and footnote classes `walk all` a
 
 The injection / swarm lens is a triggered MUST: it fires only on those target changes. The reviewer-catch rule is a prohibition, not a required recital. Road-not-taken and steelman are SHOULD, and fire only on a real fork.
 
+### Ceiling-kind (#5486)
+
+**Ceiling-kind** names how same-round isolation is frozen:
+
+| Ceiling-kind | Form |
+|---|---|
+| `comment-id` | GitHub comment id (existing issue path) |
+| `dispatch-sha-outbox-manifest` | dispatch-sha + parent-written outbox manifest (stage-(0) file-path) |
+
+- ! Stage-(0) file-path admits `PostconditionArtifactClass` `file-path` at the panel-handback caller (`panel-handback-acceptance.ts`). Obligation fields bind target-id/path; `issueNumber` is optional/N/A. Verdict returns non-numeric `boundArtifactId` alongside `boundCommentId`.
+- ! Construct the outbox-manifest artifact in stage (0); do not defer to archive stage (b). Parent-collected exclusive-create per-seat outboxes feed the retained archive.
+- ! Comment-id path stays unchanged. Do not weaken the GitHub-issue arc path.
+- ⊗ Use bare file existence or chat-success as dispatch proof.
+- ⊗ Fake 8+ digit local ids that collide with GitHub. Chosen local id-model is composite `arc-post:<n>` (published before parser accept).
+
 ### Envelope and ceiling
 
 The envelope is [`templates/design-critique-brief.md`](../templates/design-critique-brief.md). Fill fields. Do not copy rule bodies from this contract into the envelope.
@@ -733,7 +762,7 @@ Closed cite forms on the successor lean (no third coverage-map type):
 
 - `relieves: P1` / `relieves P1`
 - `does-not-relieve: P1`
-- `operator-deferred: P1 #4377` / `operator-deferred: P1 issue 4377`
+- `operator-deferred: P1 #4377`; leftover brief cites `operator-deferred: P1 plan-id github.issue.123` / `operator-deferred: P1 path xbrief/proposed/example.xbrief.json` / `operator-deferred: P1 issue 4377`
 
 Uncited ids and `does-not-relieve` stay residual headings (`unrelieved-pain`). Unknown ids and conflicting dispositions fail closed as `malformed-pain`. `operator-deferred` must cite a **different** issue id; same-number leftover is `unrelieved-pain`, not yolo-confirmable leftover, and is halt or a later lean that binds relief, without ingest clearance.
 
@@ -801,3 +830,12 @@ This motion ingests untrusted issue threads by design.
 ## Test surface
 
 `packages/core/src/content-contracts/standards/design_critique_contract.test.ts` locks required pointer strings, the scaffolds framing, the comment-lead field as model then role from the closed set (not an issue label), the operator-gated loop (successor lean, operator verbs including walk / walk all, dual stop, halt line, exclusive remaining-set replace of the three catalog chips, #3640 auto-stamp on a non-empty all-accept map and no-stamp on stubs, first-lean recording obligation after this round's siblings are posted), the parent-side substantiation token and independence rules, the Stop 1 exclusion (pre-critic premises outside the trigger) and `refutation-target:` field tokens rather than full body sentences, the composed auto-bind conjunct (all-accept map AND zero unresolved audit markers) at Operator verbs and Bind path 1, the variant-table evaluation rule (charter selection and spend permission evaluated independently), the critic-method heading and distinctive obligation tokens (exact class tokens, citations-are-claims, existing mechanisms, injection / swarm trigger nouns, failed-reviewer phrase, finding anatomy) rather than full body sentences, the brief-template forbidden-inputs list, and the thin router skill (existence, line cap, pointer resolution, no-normative-content). `evaluateParentAudit` locks the omission failure modes. This suite locks the SoT MUST and the thin skill pointer for the first-lean recording obligation, including the auto-stamp operator-confirm conjunct and the no-bind-while-unposted-same-round-siblings rule. `evaluateCompletedArcRecord` locks ingest on the completed-arc record rather than a catalog chip. It does not fail-close live parent turns. `packages/core/src/design-critique/citation-grammar.test.ts` locks the `## Citation grammar` closed set, the refused positions, and the diagnostics surface; `packages/core/src/design-critique/completed-arc-record.test.ts` locks one parser for both questions, set membership against the latest lean, and the observation-echoing block details (#3831). Runtime parent-turn detection only if `evaluateParentAudit` is extended; that extension is not required to ship the recording obligation. Panel completeness is locked as contract text only. No predicate observes it on a live arc (#3850). N≥2 round-1 ceiling is the post-panel-deposit snapshot; Envelope Id ceiling stays authoritative; deposit/envelope mismatch is a finding, never a re-ceiling (#4435). Completeness stays unobservable to round-1 critics even with the deposit in envelope. Decomposition MUST plus multi-pointer forbid are locked as contract text; no new grammar and no new evaluator. `evaluatePanelSeatComposition` locks claimed-family composition and PATH paste-ready-first; it is a fixture over claimed families, not a live sibling-count gate, and it does not observe launchability. `evaluateN3LaunchProbe` locks the N≥3 launch-probe fixture: critic argv class with bypass flags, the existing benign pong, no envelope path, amend-spend or dispatch-fail on miss, and no new halt token (#4432). Does not close #3850. `### The arc` and its derived boundaries, the `### Target shape` axis with its twice-run caveat, and the two bind-path-2 non-empty refusals are locked as contract text (#3797). `## Plain-language summary` is locked the same way: the contract test pins the heading token, the MUST-not-SHOULD reasoning, the ADR-006 exemption and its limit, the non-normative marking, and the per-artifact reserved line-start matrix, and `packages/core/src/design-critique/reserved-line-starts.test.ts` exercises each of the five families on each artifact kind against the exported shape predicates and `evaluateCompletedArcRecord`. `packages/core/src/design-critique/handoff.ts` locks `evaluateHandoffPrint`, `evaluateDualStopReservedSlot`, and `postHandoffStop1Writeback`. Do not add `reframe-needed` to `evaluateCompletedArcRecord`. Do not halt Dual-stop on invariant-set equality. `evaluateCompletedArcRecord` observes presence-only `## In plain English` on `citedLeanId` + `synthesisCommentId` (#5415); closed reason `missing-plain-english`. A pointer-only Bound-remedy or comment-id summary is a published miss and stays unobserved by that presence check; both artifacts state the problem then the accepted solution in ordinary language, including auto-posted synthesis-accepted; the thin skill names `## Plain-language summary` and keeps `Plain English first in main-chat` as the widget surface; ingest-open protocol and "Ingest may proceed" stay off this heading. Content-contract tests lock those sentences. No prose-quality parser (#4309). `### Verified-claims table heading`, the closed reason vocabulary, and the re-measured line-start matrix are locked as contract text, and `completed-arc-record.test.ts` exercises the typed refusal partition: the two states, details that differ by more than the id, the untyped null table id, and the seven recorded live arc table ids (#3942). `### Run posture` and `parseOperatorRunPosture` / `evaluateDirectDispatch` lock the closed-token front door, the missing-token ask including yolo, the `session:start --read-only` start verb, stdin posting, SHA-pinned reads, and the no-worktree direct panel; `run-posture.test.ts` exercises those fixtures. `### Spend` and `parseOperatorSpend` / `evaluateSpendRecord` lock the closed-token spend front door, the missing-token ask including yolo, numeric-only resolved tokens, bare panel as ask, colliding classes as ask, Stop 1 `spend-ask: resolved|asked`, and that grok-bot detect does not default spend; `spend.test.ts` exercises those fixtures. Live parent turns stay unenforced (#4705). Does not close #3846. `evaluateCompletedArcRecord` ignores `arc-mode:` (#4072). Yolo standing confirm of a posted all-accept map, the disagree/defer-set refusal, word-boundary parse on the operator chat utterance, and that yolo-confirm is not ingest are locked as contract text plus content-contract tests; live parent turns stay unenforced (#4308). `evaluateAutoStampPath1Write` locks the lean-cite-only unpublished path-1 candidate, the full pain-coverage reason set, skip of ingest-ready remaining-set when path-1 is refused, and that `autoStamp: true` does not return empty verbs when Handoff applies (#4592). English-heading critic after the bind lean with no operative field refuses `writePath1` as `unresolved-pain-audit` (#4648). `packages/core/src/design-critique/leftover-pain.ts` locks yolo leftover-path recommendation, leftover issue-create recording, remainder continue, finish-still-possible, cite honesty and placement, pain-audit follow-through, Dual-stop posts-not-seats default 6 for spend N=1, and asserted reserved-slot coverage (#4593). Pain-audit dispatch fill of operative `audit-targets:` (ids or none), English Pain-audit headings are not targeting, later-arc critic after the bind lean id, footnote-only follow-through is not clearance, and that `buildPainCoverageDeposit` JSDoc does not recut the asserted-marker conjunct (#4648). Dual stop Fingerprint composition with #3448, the Parallel fingerprint working default that no comparable fingerprint exists for a parallel round, and that marker clearance has no verdict field are locked as contract text plus parent-audit tests (#4442). Yolo first-lean cites under standing (#4811) are locked as contract text plus the thin skill pointer: honest pain cites on the bind-capable first all-accept lean, no free-English intermediate hatch, uncited first map stays Handoff, do not recut evaluateHandoffPrint, pain-audit brief after operative first relieves while Dual-stop numbered or reserved slot remains, and Mid-arc EXIT does not default to operator next-envelope after that lean. Live parent turns may stay unenforced. Dual-stop raise stays a raise.
+
+## No-issue target archive (#5486)
+
+When no GitHub issue exists, the durable arc record is a parent-owned ordered archive under a main-checkout-resolved root (`.deft/design-critique/archive`), keyed by target-id + arc-id. Dest-relative `.deft-scratch` is staging only, not archive root. Sidecar mirrors are optional with published read precedence; never two live SoTs. Machine-local / single-operator is the supported durability tier; cross-machine replication is deferred. Single-machine no-Issues consumers may use the archive.
+
+Write posture (pick one): critics zero in-tree writes and parent collects exclusive-create outboxes into the archive (chosen). Harvest `## Bound remedy` into the same brief via plan-id-keyed idempotent update (`hashBoundRemedyBytes` key); do not use `issue:ingest` as the no-issue harvest path. Promotion keeps the archive authoritative with optional link/mirror and refuses two live arcs over one target.
+
+Gate admission for no-issue targets is `evaluateNoIssueGateAdmission`: target identity + authoritative marker + completed-arc proof + live revision via adapter over `GATE_MATCH_PREDICATES` (paths / body-text). Storage fields alone are insufficient. Discovery/recovery or concrete manual-diagnosis path required. No fake GitHub labels.
+

package/vendor/directive-content/docs/getting-started.md

@@ -1,6 +1,6 @@
 # Getting Started with Deft Directive
 
-Deft Directive is a Taskfile-first framework for AI-assisted software work. It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide is the **first-project long form**: one path from install through a green Directive check.
+Deft Directive is a CLI-native framework for AI-assisted software work (`directive` / `deft` primary; Taskfile optional parallel). It combines agent guidance, deterministic gates, xBRIEF lifecycle metadata, installer/doctor handoff, and cache-backed backlog workflows. This guide is the **first-project long form**: one path from install through a green Directive check.
 
 > **Note**: For a single-picture mental model of how Directive turns an idea into shipped work, see [the Directive lifecycle](./directive-lifecycle.md). For command behavior, see [commands.md](../commands.md). Agent detect-state and recovery live in [QUICK-START.md](../QUICK-START.md). This page is that path's long form, not a second install sequence.
 
@@ -8,6 +8,18 @@ Deft Directive is a Taskfile-first framework for AI-assisted software work. It c
 
 Directive is two connected phases that repeat: an **inception** phase (Concept → Strategy Analysis → Specification + Artifacts) that feeds a recurring **per-session** phase (Session Start → Triage/Refine → Slice → Swarm → Review/Fix → Ship). Shipping surfaces new issues that flow back into the queue. The stage-to-command mapping lives in [the Directive lifecycle overview](./directive-lifecycle.md).
 
+## Process-use reporting (#4229)
+
+Claiming used-Directive for product work must name the relevant scope path, lifecycle progress (proposed through completed), and delivery evidence — not deposit or init alone.
+
+**You have not used Directive if:**
+
+1. Only PROJECT-DEFINITION exists and lifecycle folders are empty.
+2. Specs live only under docs/ outside the xBRIEF lifecycle.
+3. There was no promote/activate/session/implement against an active scope for the claimed work.
+
+Lawful idle / empty-active after real history is not failure. ARC-before-ingest posture is owned by open #5716 — do not treat ARC always-on as shipped here.
+
 ## Deft & Directive (naming)
 
 **Deft is the company; Directive is the product.** *Deft* names the organization and the on-disk footprint (`.deft/`, `@deftai/*` npm scope, user config under `~/.config/deft/`). *Directive* names the framework you install and run: the npm package is `@deftai/directive`, and the primary CLI is `directive` (`deft` is an alias). The Go installer (`deft-install`) is deleted — use the global launcher + `directive install` / `directive upgrade` path only.

package/vendor/directive-content/docs/intent-constraint.md

@@ -11,7 +11,13 @@ First ship is a merge-base snapshot of throw/reject/abort sites and new numeric
 3. Numeric-const peel is a while-unwrap of `AsExpression` (any asserted type), `SatisfiesExpression`, unary `+`/`-`, `ParenthesizedExpression`, and angle-bracket `TypeAssertion` until `NumericLiteral`. Do not `forEachChild`-harvest `NumericLiteral` (`Number(1024)`, `{ max: 1024 }`). Do not treat a numeric literal anywhere in an if-condition as a hard constraint.
 4. Same-file helper extract of a posted throw plus same-file const is in the snapshot. Cross-file composition is a recorded first-ship miss.
 5. Leftover is skip/filter/return-error that add neither a new numeric-const nor a throw/reject/abort site. Skip plus a new numeric const is not leftover.
-6. Durable authority is still the merge-base JSON under `.deft/intent-constraint/<plan-id>.json` with `humanApproval` (`isHumanApprovalStamp`). Author `plan["x-directive/intentConstraint"]` when `value` / `unit` / `rejectionScope` already exist, before the implementation PR that introduces the facts -- not at record-approved-scope. File-scope can be named at allocation. Throw values usually cannot. Authority read is `git show <merge-base>` only. Same-PR rewrite fails. Multiple merge-base mints require `--plan-id`, `DEFT_ACTIVE_SCOPE`, or dest unique running xBRIEF. Each mint row covers at most one new numeric-const of that value and at most one new throw/reject/abort site. Do not invent a second snapshot or fill speculative value/unit/rejectionScope so a mint succeeds at park. Chat text is never the evaluate input.
+6. Durable authority is still the merge-base JSON under `.deft/intent-constraint/<plan-id>.json` with `humanApproval` (`isHumanApprovalStamp`). Author `plan["x-directive/intentConstraint"]` when `value` / `unit` / `rejectionScope` already exist, before the implementation PR that introduces the facts -- not at record-approved-scope. File-scope can be named at allocation. Throw values usually cannot. Authority read is `git show <merge-base>` only. Same-PR rewrite fails. Multiple merge-base mints require `--plan-id`, `DEFT_ACTIVE_SCOPE`, dest unique running xBRIEF, or demand-site PR `deft-story: N` adoption (#5782). Each mint row covers at most one new numeric-const of that value and at most one new throw/reject/abort site. Do not invent a second snapshot or fill speculative value/unit/rejectionScope so a mint succeeds at park. Chat text is never the evaluate input.
+
+### PR deft-story plan-id adoption (#5782)
+
+On multi-running or multi-mint tips, when plan-id is unresolved, the gate may adopt the running brief `plan.id` owned by a sole distinct `deft-story: N` mark on the PR body (`GITHUB_PR_NUMBER` or `--pr`, plus `GITHUB_REPOSITORY` / `--repo`). Empty or non-digit PR env is no-PR-context (master push / local check keep dest-unique-running). REST null is config/exit 2. Sole means exactly one distinct issue number after dedupe (duplicate identical lines are sole). Unparseable mark values (including plan-id shaped strings) refuse. Explicit `--plan-id` and a valid `DEFT_ACTIVE_SCOPE` still win.
+
+A `deft-story: N` mark asserts #4864 delivery bind (`metadata.productPullRequest` must equal this PR before leftover finalize). Satisfying that bind closes the whole story at cohort finalize (stamp path is mark-independent). Only put the mark on the PR that is the delivery for #N. Adoption is a multi-active tiebreak; it does not alter finalize-cohort bind semantics and is not an override of sole-running.
 7. Collection UX (#5010 / #5574 Prefer-A): classify the condition, not the API name. Expected operational deny → returned-failure / filter (free). Invariant / corruption / impossible-if-healthy → fail-fast throw (or language-equivalent) + attended mint; rewrite solely to clear the gate is forbidden. Attended harness → detect the hard fact and ask the human in the parent chat; on yes the **human** lands the same merge-base record on a real TTY with `mintedVia: in-harness-ask` (attestation is not an agent-shell bypass). Commit that record on the delivery-branch merge base first, then rebase the implementation branch onto it — same-PR working-tree-only records are not authoritative. Unattended / C1 / operator-gone → operational may rewrite or park; invariant requiring a new hard fact must park pending a human mint — do not ask an empty room and do not treat leave-harness TTY `scope:record-intent-constraint` as the primary path. The legacy verb may remain for repair when a human is on a real TTY. Parent-agent auto-approve is out of scope. Agent/CI markers still refuse. Numeric-const and the four `FACT_KINDS` stay on the human decision / park path; a free rewrite introduces none of them. Language-equivalent fail-fast guidance does not imply new panic/assert extraction beyond production TS/JS.
 8. Site ids are compact statement text, not source offsets. Inserting unrelated text above an existing site does not mint a new fact.
 9. P2 (literal acceptance preservation) is not this first ship. The verb is not `semantic-*`.

package/vendor/directive-content/docs/observable-scope.md

@@ -30,3 +30,9 @@ One remediation: restore the baseline markup structure, or ask in the parent cha
 The verb is composed on `task check` (`FRAMEWORK_CHECK_GATES`, `CONSUMER_CHECK_GATES`, and required consumer enforcement). Missing, stale, invalid, or changed provider material fails; there is no generic fallback. Dependency delta versus master is two pure parser packages (`parse5` and `entities`). The JSX path trades a bundled pinned parser for one resolved from the consumer project, recorded per artifact and never compared against the mint. Truncated or incomplete HTML is refused (parse5 onParseError into anomalies). jsdom is not a dependency.
 
 Three-state exit: `0` skip, warn-findings, or pass / `1` missing mint or unlisted delta / `2` invalid configuration.
+
+### PR deft-story plan-id adoption (#5782)
+
+Same demand-site adopter as `verify:intent-constraint`: on multi-running or multi-mint tips with unresolved plan-id, adopt the unique running `plan.id` for a sole distinct `deft-story: N` on the PR body. Explicit `--plan-id` and a valid `DEFT_ACTIVE_SCOPE` win. Empty/non-digit PR env is no-PR-context. When `DEFT_ACTIVE_SCOPE` is set but not a running xBRIEF **and** PR context is present, adoption is suppressed with a named refuse (pass `--plan-id` or clear the pin) — without PR context the tip fall-through is unchanged. REST null is config/exit 2. No YAML planId pre-export.
+
+A `deft-story: N` mark asserts #4864 delivery bind and whole-story close at cohort finalize — only use it on the PR that is the delivery for #N. Adoption does not change finalize bind semantics.