@deftai/directive-runtime 0.129.5 → 0.129.7

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

@@ -58,6 +58,8 @@ directive doctor
 
 After clone or a new worktree: run the project package manager (`npm install` / `pnpm install`), then the first eligible runtime command or registered hook completes local activation.
 
+**Dependabot / pin-only bumps (AC14.10):** a PR that changes only the `@deftai/directive-runtime` pin + lockfile is valid. After `pnpm install` / `npm install` brings `node_modules` to the new pin, the first eligible skill, hook, or ordinary runtime command runs local automatic setup (wiring / `GENERATION` / readiness). `directive doctor` stays read-only — dirty doctor output before that eligible invocation is expected. CI may either rely on that first eligible command or run explicit `directive install --repair --yes`. Do not treat "deposit bytes must land in the same pin PR" as product law. Human-test mirror: HT-17 in `docs/installer-refactor-ovpr/install-ovpr-human-test-plan.md`. Schema/data behind the new pin still needs `directive upgrade` (AC14.11), not repair alone.
+
 **Repair (pin unchanged):** `npm i -g @deftai/directive`, then `directive install --repair`.
 
 **Upgrade version or migrate data:** `directive upgrade` (alias: `update`).

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

@@ -45,10 +45,24 @@ Allowance = clamp(count of **concrete** production files on the merge-base `file
 When the bound story is in the change set:
 
 1. A human-stamped merge-base mint for the **continuity-resolved** story is the allowlist when present (planId match ignores stale `xbriefRelPath`; no-`plan.id` is path-first + basename-keyed mint with matching `xbriefRelPath`).
-2. Otherwise membership evaluates against the merge-base brief's **concrete** `file_scope` as agent precommitment. Head brief cannot widen.
+2. Otherwise membership evaluates against the merge-base brief's **concrete** `file_scope` as agent precommitment. Head brief cannot widen, except under a qualifying forge approval (#6203, below).
 3. Free paths: bound brief, verified peer briefs, `CHANGELOG.md`, and continuity lifecycle paths of the bound identity. An xBRIEF-only change set may omit a mint.
 4. Empty / invalid / unreadable mint records fail closed (they are not absence).
 
+#### Forge-approved head brief (#6203)
+
+A PR can carry a new or widened brief plus its code when a human approves it on GitHub. With PR context (`--pr N` / `--repo OWNER/NAME`, or `GITHUB_PR_NUMBER` / `GITHUB_REPOSITORY` in CI), a failing membership check under precommitment or missing authority consults the forge. When a qualifying approval exists, membership evaluates against the **head** brief's concrete `file_scope` instead of the merge-base brief.
+
+- **Mint wins.** A present mint keeps the mint path. The forge is never consulted.
+- **Auth-hash v1** (`sha256:` over canonical JSON; strings byte-exact, no Unicode normalization) covers `plan.id`, the xbrief path, the concrete `file_scope`, and the acceptanceCriteria array: `plan.acceptance`, `plan.narratives.AcceptanceCriteria`, and each item's `narrative.Acceptance`, in document order. `productPullRequest` and other delivery metadata stay out, so a PPR stamp keeps the approval. Any change to the covered fields drops it.
+- **Qualifying approval:** the reviewer's latest deciding review (APPROVED / CHANGES_REQUESTED / DISMISSED) is APPROVED; the reviewer is a `User` (not Bot or App), not the PR author, and has `write`, `maintain` or `admin` on the repo; the repo is the checkout's `origin` (a `--repo` value may only confirm it, so a fork's approval never counts) and is the PR's base repo; the evaluated HEAD is the PR head (or GitHub's merge commit whose second parent is the PR head); and the brief at the reviewed commit hashes the same as the head brief.
+- **Fallback:** missing PR context, no qualifying approval, a hash mismatch, or an unavailable forge keeps today's Path B or mint finding unchanged. The result message adds one `forge approval (#6203)` line with the reason.
+- **Membership only.** The production fence still reads the merge-base brief. A widened brief can pass membership and still fail `production-scope-over-budget`. A brand-new brief has no production fence (as today).
+- **Re-run after approval.** Approval does not re-trigger CI. Re-run the merge gate (or push) after the approval lands.
+- **Residual (#6207):** an agent that holds a second human forge token can satisfy every predicate above. The hash binds the approved bytes; it does not prove independent human intent and does not close that confused-deputy risk. That posture stays open on #6207.
+
+Code: `packages/core/src/scope-provenance/forge-approval.ts`.
+
 #### Path A planning split (#5551)
 
 When an active implementation brief is **outside** the change set, membership is a no-op for that identity (Path A). Supported planning publication is two change sets, not one:

package/vendor/directive-content/packs/lessons/lessons-pack-0.1.json

@@ -711,6 +711,21 @@
       ],
       "source": "Issue #4888 Prefer-A Bound 6050812821 (parent #964). conflict_group mergeable-state-semantic-policy-invisibility.",
       "body": "**Source:** Issue #4888 Prefer-A Bound 6050812821 (split from parent #964).\n\n**Failure mode:** GitHub `mergeable_state` / `mergeable` report only textual (axis-1) conflicts. After a PR opens, behavioral (CI/test) and policy (`task check` / required contexts) gates can land on the base without a textual conflict. Agents read dirty/clean as readiness or gap-size and miss the invisible policy miss until `task check` runs on the merge result.\n\n**Rule:** Use the three-axis model (textual / behavioral / policy). On conflict-resolve and behind-rebase (PR open; local HEAD matches live remote PR head), require machine-checkable candidate validation keyed to `(pr_head_sha, target_head_sha)` via `evaluateNonCascadeCandidateGreen` / `evaluateSemanticGreen({ requireCandidateValidation: true })`. Attestation is a named allowlisted probe exit 0 (typically pre-pr `task check` / `deft check`); prose stamps are not success. On pre-push, run that local merge-chokepoint gate before push; require the SHA-pair attestation only after push when local HEAD matches the live remote PR head. Do not weaken `--cascade` absolute stale-base refusal. Keep #4889 out; do not satisfy with a withdrawn Python semantic-drift script SoT. Forge supersession is #633/#1517 required Merge gate aggregator + up-to-date-required; local probe is interim.\n\n**Canonical encoding (strongest-applicable layer):** probe in `packages/core/src/pr-wait-mergeable/semantic-green.ts` (`requireCandidateValidation` / `validateCandidateAttestation`); operative MUST in `content/scm/github.md` § Cascade / Three-axis (#4888) and `skills/deft-directive-pre-pr/SKILL.md` merge-chokepoint attach; forge supersession in `content/scm/github.md` § Merge-gate aggregator (#633). AGENTS/agents-entry pointer only.\n\n**Cross-references:** #4888, #964, #2385, #1369, #633, #1517, #4883 (CLEAN = axis-1 necessity), #4889 (kept out)."
+    },
+    {
+      "id": "edit-files-search-strings-must-capture-full-units-not-substrings-2026-05",
+      "title": "edit_files search strings MUST capture full units, not substrings (2026-05)",
+      "date": "2026-05",
+      "issue_refs": [
+        "#1037"
+      ],
+      "tags": [
+        "debugging",
+        "agent-orchestration",
+        "github"
+      ],
+      "source": "Issue #1037 Prefer-A Bound 6689115138. Recurrence: PR #1034 (2026-05-11); #911 cascade (2026-05-04).",
+      "body": "**Source:** Issue #1037 Prefer-A Bound 6689115138. Recurrence: PR #1034 (2026-05-11) Greptile P1 on truncated CHANGELOG #441 close-out bullet; sibling outcome class in the #911 cascade (2026-05-04).\n\n**Failure mode:** Exact-string replace tools (`edit_files` / StrReplace-class) replace only the matched `search` bytes. When the agent anchors on a substring of a longer single-line or multi-line entry (CHANGELOG bullet, ROADMAP list item, section body), the unmatched overflow past the search anchor is deleted with the match. The tool did what it was asked; the agent chose too short a search.\n\n**Rule:** When using exact-string-match replacement to modify a single-line or multi-line entry, the `search` value MUST match the FULL line / FULL entry being targeted, including any trailing prose / continuation the agent intends to preserve.\n\n**Anti-pattern:** Pick the first N words of a long bullet as the search anchor; the replacement silently truncates the bullet at the end of the matched substring.\n\n**Mitigation:**\n- ! When targeting a markdown bullet, the `search` value MUST extend to the next blank line or the next top-level list marker, whichever comes first. Re-read the file and capture ALL bytes that belong to the targeted entry.\n- ! When adding a new bullet ABOVE an existing one, an even safer pattern is to anchor `search` on the section heading (e.g. `### Refinement`) and re-emit the heading in `replace` followed by the new bullet and the existing first bullet -- but you MUST still capture every byte of that existing first bullet.\n- ! After every exact-string replace that touches CHANGELOG.md, ROADMAP.md, or any other append-only narrative file, re-read the surrounding 20 lines of the edited region and verify nothing was truncated. This is part of the standard pre-commit file review.\n\n**Recurrence record:**\n- PR #1034 (2026-05-11) -- CHANGELOG.md `### Refinement` first bullet truncated when adding a new bullet above it; Greptile caught it as a P1 in review-cycle.\n- PR #911 cascade (2026-05-04) -- different mechanism (HEAD-only slice resolution), same outcome class: CHANGELOG `[Unreleased]` branch entries dropped on conflict resolution.\n\n**Canonical encoding:** lessons-pack-0.1 entry (this body); projected via `task packs:render` into `meta/lessons.md`. Lesson-tier only -- no new AGENTS.md always-pin; optional `verify:changelog-bullets` stays out of Bound (#1037 Prefer-A Reject).\n\n**Cross-references:** Issue #1037, Prefer-A Bound 6689115138, PR #1034, PR #911 cascade, `skills/deft-directive-build/SKILL.md` / `skills/deft-directive-refinement/SKILL.md` pre-commit file review."
     }
   ]
 }