@deftai/directive-runtime 0.129.5 → 0.129.6

package/vendor/directive-content/Taskfile.yml

@@ -845,6 +845,241 @@ tasks:
         vars:
           ENGINE_CMD: 'release-wait-npm {{.CLI_ARGS}}'
 
+  # Phase 7 maintainer primary checkout closeout (#5953 Prefer-A Bound 6430511888).
+  # Inline cmds only — no engine:invoke / no deps:[ts:build] so the post-install
+  # payload can replace the N-1 runtime the cut was using. Never reset/force-push/
+  # commit / npm i -g.
+  release:local-update:
+    desc: "Phase 7 fail-closed maintainer checkout update (#5953) -- task release:local-update -- <version> --checkout <primary-occupancy-root>"
+    dir: '{{.USER_WORKING_DIR}}'
+    env:
+      PYTHONUTF8: "1"
+    cmds:
+      - |
+        set -e
+        # node -e bodies use shell single quotes + JS double quotes only (no apostrophes).
+        PARSE_OUT="$(node -e '
+          const raw = process.argv[1] || "";
+          const tokens = [];
+          let cur = "";
+          let q = null;
+          const DQ = String.fromCharCode(34);
+          const SQ = String.fromCharCode(39);
+          for (let i = 0; i < raw.length; i++) {
+            const ch = raw[i];
+            if (q) {
+              if (ch === q) { q = null; continue; }
+              cur += ch;
+              continue;
+            }
+            if (ch === DQ || ch === SQ) { q = ch; continue; }
+            if (/\s/.test(ch)) {
+              if (cur.length) { tokens.push(cur); cur = ""; }
+              continue;
+            }
+            cur += ch;
+          }
+          if (q) { console.error("release:local-update: unmatched quote in args"); process.exit(2); }
+          if (cur.length) tokens.push(cur);
+          let version = "";
+          let checkout = "";
+          for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t === "--checkout") {
+              const v = tokens[++i];
+              if (!v) { console.error("release:local-update: --checkout requires a path"); process.exit(2); }
+              checkout = v;
+              continue;
+            }
+            if (t.startsWith("--")) {
+              console.error("release:local-update: unknown flag " + t);
+              console.error("Usage: task release:local-update -- <version> --checkout <maintainer-primary-occupancy-root>");
+              process.exit(2);
+            }
+            if (!version) { version = t; continue; }
+            console.error("release:local-update: unexpected arg " + t);
+            process.exit(2);
+          }
+          if (!version) {
+            console.error("release:local-update: missing <version>");
+            console.error("Usage: task release:local-update -- <version> --checkout <maintainer-primary-occupancy-root>");
+            process.exit(2);
+          }
+          if (!checkout) {
+            console.error("release:local-update: refuse ambient release-worktree-only success; require --checkout naming the maintainer primary occupancy root (#5953)");
+            process.exit(1);
+          }
+          process.stdout.write(JSON.stringify({ version, checkout }));
+        ' "{{.CLI_ARGS}}")"
+        VERSION="$(node -e 'const j=JSON.parse(process.argv[1]); process.stdout.write(j.version);' "$PARSE_OUT")"
+        CHECKOUT="$(node -e 'const j=JSON.parse(process.argv[1]); process.stdout.write(j.checkout);' "$PARSE_OUT")"
+        case "$CHECKOUT" in
+          /*|[A-Za-z]:*) ;;
+          *) CHECKOUT="$(pwd)/$CHECKOUT" ;;
+        esac
+        CHECKOUT="$(node -e 'const fs=require("fs"); const path=require("path"); const inPath=process.argv[1]; try { process.stdout.write(fs.realpathSync(inPath)); } catch { process.stdout.write(path.resolve(inPath)); }' "$CHECKOUT")"
+        if [ ! -d "$CHECKOUT/.git" ] && [ ! -f "$CHECKOUT/.git" ]; then
+          echo "release:local-update: --checkout is not a git checkout: $CHECKOUT" >&2
+          exit 1
+        fi
+        COMMON_DIR="$(git -C "$CHECKOUT" rev-parse --git-common-dir 2>/dev/null || true)"
+        if [ -z "$COMMON_DIR" ]; then
+          echo "release:local-update: cannot resolve git-common-dir for $CHECKOUT" >&2
+          exit 1
+        fi
+        case "$COMMON_DIR" in
+          /*|[A-Za-z]:*) ;;
+          *) COMMON_DIR="$CHECKOUT/$COMMON_DIR" ;;
+        esac
+        MAIN_ROOT="$(node -e 'const path=require("path"); process.stdout.write(path.resolve(path.dirname(process.argv[1])));' "$COMMON_DIR")"
+        SAME_MAIN="$(node -e 'const a=process.argv[1]; const b=process.argv[2]; const norm=s => process.platform==="win32" ? s.split(String.fromCharCode(92)).join("/").toLowerCase() : s.split(String.fromCharCode(92)).join("/"); process.stdout.write(norm(a)===norm(b)?"1":"0");' "$CHECKOUT" "$MAIN_ROOT")"
+        if [ "$SAME_MAIN" != "1" ]; then
+          echo "release:local-update: refuse ambient release-worktree-only success; --checkout must name the maintainer primary occupancy root (dirname git-common-dir=$MAIN_ROOT), not $CHECKOUT (#5953)" >&2
+          exit 1
+        fi
+        CHECKOUT_NORM="$(node -e 'process.stdout.write(String(process.argv[1]||"").split(String.fromCharCode(92)).join("/"));' "$CHECKOUT")"
+        case "$CHECKOUT_NORM" in
+          */.deft-scratch/worktrees/*)
+            echo "release:local-update: refuse ambient release-worktree-only success; --checkout must name the maintainer primary occupancy root, not $CHECKOUT (#5953)" >&2
+            exit 1
+            ;;
+        esac
+        print_deposit_recovery() {
+          echo "Phase 7 local closeout INCOMPLETE (#5953)." >&2
+          echo "Recovery: merge the version-matched agent-hook deposit for $VERSION onto tip, then re-run:" >&2
+          echo "  task release:local-update -- $VERSION --checkout $CHECKOUT" >&2
+          echo "Expected managed deposit paths include: .grok/hooks/ .cursor/hooks.json .claude/settings.json .codex/ (and related deposit files)." >&2
+          echo "Do not auto-commit deposit bytes inside the release flow; do not npm i -g." >&2
+        }
+        OCC_FILE="$CHECKOUT/.deft/occupancy.json"
+        if [ -f "$OCC_FILE" ]; then
+          node -e '
+            const fs = require("fs");
+            const path = process.argv[1];
+            const checkout = process.argv[2];
+            const raw = fs.readFileSync(path, "utf8");
+            let rec;
+            try { rec = JSON.parse(raw); } catch { process.exit(0); }
+            const sid = String(rec.session_id || rec.sessionId || "");
+            const hb = Date.parse(rec.heartbeat_at || rec.heartbeatAt || "");
+            const claimed = Date.parse(rec.claimed_at || rec.claimedAt || "");
+            const now = Date.now();
+            const TTL = 20 * 60 * 1000;
+            const MAX = 24 * 60 * 60 * 1000;
+            if (!Number.isFinite(hb) || !Number.isFinite(claimed)) process.exit(0);
+            if (now - claimed > MAX || now - hb > TTL) process.exit(0);
+            const providers = ["grok", "claude", "cursor", "codex", "openclaw"];
+            const rawPresenters = [
+              process.env.DEFT_SESSION_ID,
+              process.env.GROK_SESSION_ID,
+              process.env.CLAUDE_SESSION_ID,
+              process.env.CURSOR_SESSION_ID,
+              process.env.CODEX_SESSION_ID,
+            ].filter((v) => typeof v === "string" && v.trim().length > 0).map((v) => v.trim());
+            const presenters = new Set(rawPresenters);
+            for (const p of rawPresenters) {
+              if (p.startsWith("host:")) continue;
+              for (const provider of providers) {
+                presenters.add("host:" + provider + ":v1:" + Buffer.from(p, "utf8").toString("base64url"));
+              }
+            }
+            let sidRaw = null;
+            const m = /^host:([a-z]+):v1:([A-Za-z0-9_-]+)$/.exec(sid);
+            if (m) {
+              try { sidRaw = Buffer.from(m[2], "base64url").toString("utf8"); } catch { sidRaw = null; }
+            }
+            const grants = Array.isArray(rec.grants) ? rec.grants : [];
+            const grantIds = grants
+              .filter((g) => Date.parse(g.expires_at || g.expiresAt || 0) > now)
+              .map((g) => g.session_id || g.sessionId || g.child_session_id || g.childSessionId)
+              .filter(Boolean)
+              .map(String);
+            const admitted = [...presenters].some((p) => p === sid || grantIds.includes(p) || (sidRaw && p === sidRaw));
+            if (!admitted && presenters.size > 0) {
+              console.error("release:local-update: refuse live foreign occupancy lease on " + checkout + " (occupant=" + sid + ") before any write (#5953)");
+              process.exit(1);
+            }
+            if (!admitted && presenters.size === 0 && sid) {
+              console.error("release:local-update: refuse live occupancy lease on " + checkout + " (occupant=" + sid + "); no presenter session id in env (#5953)");
+              process.exit(1);
+            }
+          ' "$OCC_FILE" "$CHECKOUT"
+        fi
+        cd "$CHECKOUT"
+        if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+          echo "release:local-update: not a git work tree: $CHECKOUT" >&2
+          exit 1
+        fi
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "release:local-update: refuse dirty tree at $CHECKOUT" >&2
+          git status --short >&2
+          exit 1
+        fi
+        DEFAULT_BRANCH="$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed "s@^refs/remotes/origin/@@" || true)"
+        if [ -z "$DEFAULT_BRANCH" ]; then DEFAULT_BRANCH=master; fi
+        CURRENT="$(git rev-parse --abbrev-ref HEAD)"
+        if [ "$CURRENT" != "$DEFAULT_BRANCH" ]; then
+          echo "release:local-update: refuse; checkout must be on default branch $DEFAULT_BRANCH (on $CURRENT)" >&2
+          exit 1
+        fi
+        echo "release:local-update: ff-only pull on $DEFAULT_BRANCH at $CHECKOUT"
+        git pull --ff-only
+        if [ -f pnpm-workspace.yaml ]; then
+          if grep -q "minimumReleaseAgeExclude" pnpm-workspace.yaml; then
+            if ! grep -q "@deftai/directive-runtime@$VERSION" pnpm-workspace.yaml; then
+              echo "release:local-update: AgeExclude missing @deftai/directive-runtime@$VERSION before frozen install (#5953 footnote)" >&2
+              exit 1
+            fi
+          fi
+        fi
+        echo "release:local-update: pnpm install --frozen-lockfile"
+        pnpm install --frozen-lockfile
+        PIN_PKG="$(node -e 'const fs=require("fs"); const p=JSON.parse(fs.readFileSync("package.json","utf8")); const v=(p.dependencies||{})["@deftai/directive-runtime"]||(p.devDependencies||{})["@deftai/directive-runtime"]||""; console.log(String(v).replace(/^[^0-9]*/, ""));')"
+        INST_PKG="$(node -e 'const fs=require("fs"); const p=JSON.parse(fs.readFileSync("node_modules/@deftai/directive-runtime/package.json","utf8")); console.log(p.version);')"
+        if [ "$PIN_PKG" != "$VERSION" ] || [ "$INST_PKG" != "$VERSION" ]; then
+          echo "release:local-update: tip-pin-equals-released FAILED; want $VERSION; package.json pin=$PIN_PKG installed=$INST_PKG" >&2
+          exit 1
+        fi
+        echo "release:local-update: tip-pin-equals-released ok ($VERSION)"
+        RUNTIME_BIN="node_modules/@deftai/directive-runtime/dist/bin.js"
+        if [ ! -f "$RUNTIME_BIN" ]; then
+          echo "release:local-update: missing checkout runtime bin $RUNTIME_BIN" >&2
+          exit 1
+        fi
+        echo "release:local-update: require version-matched agent-hook deposit already on tip"
+        if ! DEFT_DOCTOR_HOOK_DIAGNOSTIC=1 node "$RUNTIME_BIN" verify:hooks-installed --project-root "$CHECKOUT" --scope=agent; then
+          print_deposit_recovery
+          exit 1
+        fi
+        UPGRADE_BIN=""
+        if [ -x "node_modules/.bin/directive" ]; then
+          UPGRADE_BIN="node_modules/.bin/directive"
+        elif [ -f "node_modules/@deftai/directive/dist/bin.js" ]; then
+          UPGRADE_BIN="node node_modules/@deftai/directive/dist/bin.js"
+        elif command -v directive >/dev/null 2>&1; then
+          UPGRADE_BIN="directive"
+        else
+          echo "release:local-update: cannot resolve directive upgrade binary after frozen install" >&2
+          exit 1
+        fi
+        echo "release:local-update: $UPGRADE_BIN upgrade --target-version $VERSION --yes --root $CHECKOUT"
+        $UPGRADE_BIN upgrade --target-version "$VERSION" --yes --root "$CHECKOUT"
+        if [ -n "$(git status --porcelain)" ]; then
+          echo "release:local-update: tracked-file diff after upgrade; closeout non-zero/incomplete (#5953)" >&2
+          git status --short >&2
+          print_deposit_recovery
+          exit 1
+        fi
+        echo "release:local-update: verify:hooks-installed --project-root --scope=all"
+        DEFT_DOCTOR_HOOK_DIAGNOSTIC=1 node "$RUNTIME_BIN" verify:hooks-installed --project-root "$CHECKOUT" --scope=all
+        INST_PKG2="$(node -e 'const fs=require("fs"); const p=JSON.parse(fs.readFileSync("node_modules/@deftai/directive-runtime/package.json","utf8")); console.log(p.version);')"
+        if [ "$INST_PKG2" != "$VERSION" ]; then
+          echo "release:local-update: post-upgrade runtime $INST_PKG2 != $VERSION" >&2
+          exit 1
+        fi
+        echo "release:local-update COMPLETE; checkout=$CHECKOUT version=$INST_PKG2 hooks=verify:hooks-installed --scope=all green"
+        echo "global npm i -g was NOT run (report-only drift remains Phase 7 step 2)."
+
 
   # ------------------------------------------------------------------
   # Triage v1 user-facing alias tasks (#845, #913).

package/vendor/directive-content/UPGRADING.md

@@ -949,6 +949,7 @@ Every **real** policy write (Phase 2 / Phase 4, and every other `meta/policy-cha
 - **On-disk layout changed.** Old: `.deft-cache/issues/<owner>-<repo>/<N>.{json,md}` (flat sidecar). New: `.deft-cache/<source>/<key>/{raw.json,content.md,meta.json}` (per-entry directory; schema-validated meta envelope). `cache:get` validates `meta.json` against `vbrief/schemas/cache-meta.schema.json` on every read so a corrupt or version-incompatible file fails closed.
 - **Audit log UNCHANGED.** `vbrief/.eval/candidates.jsonl` preserves accept / reject / defer / needs-ac / mark-duplicate / reset records across the migration. The Story 3 Tier-2 short-circuit (terminal-decision skip on bulk-* re-runs) operates on the same file.
 - **All other `triage:*` actions UNCHANGED.** `triage:accept` / `triage:reject` / `triage:defer` / `triage:needs-ac` / `triage:mark-duplicate` / `triage:bulk-accept` / `triage:bulk-reject` / `triage:bulk-defer` / `triage:bulk-needs-ac` / `triage:status` / `triage:reset` / `triage:history` / `triage:refresh-active` keep their v0.25.x surface byte-for-byte (13 aliases). The rebind onto `cache:get` is internal. `triage:bootstrap` keeps its v0.25.x command surface but its on-disk output is the new `.deft-cache/<source>/<key>/` per-entry layout (now delegates to `cache:fetch-all`); see the Commands list above.
+- **Gitcrawl fallback semantics no longer apply.** After this cache rebind, the old `docs/gitcrawl-fallback.md` gh-only install/recovery path is withdrawn. Do not follow that doc for v0.26+ triage/cache; use `cache:*` and this migration section instead (#1092).
 
 ### Rollback
 

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

@@ -65,7 +65,7 @@ Record `arc-mode: no-ingest` or `arc-mode: checkout` on the Stop 1 write-back. `
 - ! Parent-unclaimed is its own MUST: `session:start --read-only`, or an explicit occupancy release if a mutation lease is already held. Dest create does not clear occupancy.
 - ! Recognition of `no-ingest` happens before mutation initialization. Refuse github-only when mutation `session:start` has already occurred, unless the lease is released first.
 - ! Posting path that survives a foreign lease: `gh issue comment --body-file -` (stdin). Least-authority envelope: bounded GitHub reads and one comment post.
-- ! Parent fetches, then creates or verifies one dest at origin/<default> tip (`ensureArcDest`). dispatch-sha equals that tip. Against-implementation dest is the fetched PR head SHA, recorded on Stop 1. ⊗ Pin dest to local HEAD.
+- ! Parent fetches, then creates or verifies one dest at origin/<default> tip via the sanctioned pin-bin verb `deft design-critique:ensure-arc-dest` (library `ensureArcDest`; guarded-prep default, or explicit `process-only-no-install`). When guarded-prep is selected, success requires the outer-visible runtime pin. dispatch-sha equals that tip. Against-implementation dest is the fetched PR head SHA, recorded on Stop 1. ⊗ Pin dest to local HEAD. ⊗ Treat gitignored `packages/core/dist` as SoT for `ensureArcDest` on framework-source.
 - ! N>1 process-only critics share that dest with cwd-without-occupy. They are not swarm Phase 2 and not a #4066 mutating worker. Unique dest-lock stays for implement-class. Skip class is a host-visible Grok stdin marker (`subagent_type` `plan` or `process_only`), not dest-path. That marker is the process-only skip class, not an implementation-gate bypass: implement-class never sets `process_only`. ⊗ Skip #2885 on destProven. Keep #4066 primary-path deny. ⊗ Pin dest / process_only skip-class rules into `templates/agents-entry.md`.
 - ! Pin reads to `git show <dispatch-sha>:` against the recorded SHA. ⊗ A moving branch ref.
 - ! Before panel-deposit on a process-only dest, record a closed `verification-path:` line that either (a) names the read-only pin-read path (`git show <dispatch-sha>:`, dest cwd-without-occupy for on-pin file reads), or (b) records a provisioned runnable path when a specific check requires executing fixtures/tests. Default to (a). Keep N≥3 launch-probe (`evaluateN3LaunchProbe`) as launchability, separate from method-verification. `verificationPathRecordLine` / `evaluateVerificationPathBeforePanelDeposit` are the fixtures. ⊗ Mandate full install-on-dest for every panel.

package/vendor/directive-content/contracts/path-write-fence.md

@@ -195,6 +195,12 @@ OS-temp dests and commands with no recognized dest (`git status`,
   remains **escape** polarity (in-tree dest whose realpath leaves the tree) and is
   not this check. The hook still runs before the shell, so a link created between
   check and write is TOCTOU.
+- **Kill-switch / permanent opt-out plant (#6136):** Shell write reissue checks
+  `.deft-directive-disable` / `.no-deft-directive` basenames **before** the
+  `isInRepoShellWritePath` skip, so an out-of-tree plant cannot fail-open. Agent
+  Write/Edit/Shell of those basenames is always-on deny without a human-origin
+  settings grant (docs: `deft-directive-disable.md`). General protected-target /
+  out-of-tree floor work stays on #6138; deny wording on #6139.
 
 Fail-open at this predicate is the bound posture (#3997). Inverting it to
 fail-closed on dests the parser cannot prove external is that issue's refuted

package/vendor/directive-content/docs/deft-directive-disable.md

@@ -82,11 +82,11 @@ rm .deft-directive-disable
 # Start a NEW agent session
 ```
 
-## Agent self-serve ban under UAT (#3186)
+## Agent self-serve ban (always-on, grant-gated) (#3186 / #6136)
 
-Operators plant and remove this flag **outside** an agent session (or with a prior human-origin grant). Under **active UAT**, PreToolUse classifies Shell writes that create `.deft-directive-disable` (and permanent opt-out `.no-deft-directive`) as **settings** and **denies** them without a human grant — same posture as `authz:grant` (#3110). Agents must not self-serve the kill-switch to bypass Write / push / PR / merge gates.
+Operators plant and remove this flag **outside** an agent session (or with a prior human-origin grant covering **settings**). PreToolUse **always** denies agent Write / Edit / Shell that creates or renames-to `.deft-directive-disable` (and permanent opt-out `.no-deft-directive`) without that grant — not only under active UAT. Shell write reissue checks the protected basename **before** skipping out-of-tree dests, so a plant outside the repo tree cannot fail-open. Agents must not self-serve the kill-switch to bypass Write / push / PR / merge gates.
 
-Related: `policy:allow-bot-merge`, `policy:allow-direct-commits`, and `policy:disable-directive` (peers) are also settings under UAT and require a human grant.
+Related: `policy:allow-bot-merge`, `policy:allow-direct-commits`, and `policy:disable-directive` (peers) are settings under UAT and require a human grant.
 
 ## Non-goals (v1)
 

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."
     }
   ]
 }