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

package/dist/verify-observable-scope.js

@@ -46,6 +46,28 @@ export function parseArgs(argv) {
         else if (arg?.startsWith("--plan-id=")) {
             parsed.planId = arg.slice("--plan-id=".length);
         }
+        else if (arg === "--pr") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --pr: expected one argument" };
+            }
+            parsed.pr = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--pr=")) {
+            parsed.pr = arg.slice("--pr=".length);
+        }
+        else if (arg === "--repo") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...parsed, error: "argument --repo: expected one argument" };
+            }
+            parsed.repo = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--repo=")) {
+            parsed.repo = arg.slice("--repo=".length);
+        }
         else if (arg === "--base-ref") {
             return {
                 ...parsed,
@@ -71,6 +93,8 @@ export function run(argv) {
         staged: args.staged,
         quiet: args.quiet,
         planId: args.planId,
+        pr: args.pr,
+        repo: args.repo,
     });
     if (result.message.length > 0) {
         if (result.stream === "stdout")

package/dist/verify-review-monitor.d.ts

@@ -13,6 +13,13 @@ interface ParsedArgs {
     mergePathArm: boolean;
     liveWait: boolean;
     explicitFinish: boolean;
+    /**
+     * Product mint-gate BLOCKED — refuse --explicit-finish write (#5690).
+     * Pass-through to writeMergePathExplicitFinishAttestation.mintGateBlocked.
+     */
+    mintGateBlocked: boolean;
+    /** Optional attestation reason; mint markers also refuse the write (#5690). */
+    reason: string | null;
     stickyLease: boolean;
     /** DeliveryAttemptRecord.startedAt for Approach 1 arm-startup halt (#5278 P3). */
     dispatchStartedAt: string | null;

package/dist/verify-review-monitor.js

@@ -24,6 +24,8 @@ export function parseVerifyReviewMonitorArgs(argv) {
         mergePathArm: false,
         liveWait: false,
         explicitFinish: false,
+        mintGateBlocked: false,
+        reason: null,
         stickyLease: false,
         dispatchStartedAt: null,
         help: false,
@@ -45,6 +47,20 @@ export function parseVerifyReviewMonitorArgs(argv) {
         else if (arg === "--explicit-finish") {
             acc.explicitFinish = true;
         }
+        else if (arg === "--mint-gate-blocked") {
+            acc.mintGateBlocked = true;
+        }
+        else if (arg === "--reason") {
+            const value = argv[i + 1];
+            if (value === undefined) {
+                return { ...acc, error: "argument --reason: expected one argument" };
+            }
+            acc.reason = value;
+            i += 1;
+        }
+        else if (arg?.startsWith("--reason=")) {
+            acc.reason = arg.slice("--reason=".length);
+        }
         else if (arg === "--sticky-lease") {
             acc.stickyLease = true;
         }
@@ -159,6 +175,9 @@ export function run(argv) {
             "                         pr:watch CLEAN attestation — #5219;\n" +
             "                         parent-shell pr:watch (parent_id=pr-watch) does not arm.\n" +
             "  --explicit-finish      Attest option-C BLOCKED/FAILED finish for this PR\n" +
+            "  --mint-gate-blocked    Refuse --explicit-finish write for product mint-gate\n" +
+            "                         BLOCKED (non-option-C; #5690)\n" +
+            "  --reason TEXT          Attestation reason; mint markers also refuse write (#5690)\n" +
             "  --sticky-lease         Attest a fresh sticky lease (not sufficient alone)\n" +
             "  --dispatch-started-at  DeliveryAttemptRecord.startedAt ISO for Approach 1\n" +
             "                         arm-startup halt (#5278); when merge-path-arm stays\n" +
@@ -202,6 +221,8 @@ export function run(argv) {
             else {
                 const written = writeMergePathExplicitFinishAttestation(resolve(args.projectRoot), args.pr, {
                     source: "verify:review-monitor --explicit-finish",
+                    reason: args.reason ?? undefined,
+                    mintGateBlocked: args.mintGateBlocked,
                 });
                 if (!written.ok) {
                     process.stderr.write(`verify_review_monitor: ${written.reason}

package/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/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/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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deftai/directive-runtime",
-  "version": "0.126.0-beta.2",
+  "version": "0.127.0",
   "description": "Directive runtime — pinned product commands, hooks, content, and engine.",
   "license": "MIT",
   "homepage": "https://deftai.github.io/directive/",