Tensor Grep Backlog Campaign

tensor-grep backlog campaign

META-ORCHESTRATOR for backlog drain. Sequences which sibling skill to load; one home per fact — do not re-derive procedures that live in the retiring-fellow library (Sonnet-class audience, ground-truth verified).

End-to-end: audit → plan → research → implement → verify → ship. Load tensor-grep-change-control before ANY edit, merge, or release claim.

This skill has two layers:

1. Universal pipeline — standard-dev-workflow.
2. tensor-grep overlay — shipping discipline (drain, venv, FFI, registration, IDF).

Mission

Deep-dive this codebase end-to-end: bugs, security/infra risks, workflow problems, edge cases, dead/unwired code, and improvements. Work the project backlog to completion with durable receipts — not "looks done" summaries.

You have stale training data. Never act on memory alone for external facts, competitor patterns, library behavior, or release mechanics. Ground claims with use-exa (and agy/use-gemini for a third opinion when stakes are high).

CEO communication

Chat short and business-focused; depth in files. Plan-only mode ("investigate," "what next," "write a spec") stops after Phase 0 plan docs — no code unless CEO explicitly asks to implement.

For “list all backlog,” produce a closed-world snapshot, not a highlight reel. Separate: active/buildable; environment-blocked; nonfinancial decision-gated; financial/spend-gated; demand/research-gated; and terminal corrections that stale trackers still show. Every live row gets one stable ID/alias, owner/decision maker, and reopen/start trigger. Preserve mixed outcomes instead of flattening them into “shipped.”

Also separate artifact states. A green PR head, newer uncommitted worktree bytes, an approved plan hash, a merge SHA, and a published wheel are five different claims. The CEO update names which one each receipt proves and never lets a green older artifact imply approval of a newer one.

Phase 0 — Investigate, rank, and SPEC/TDD plan

Superpowers map

Load using-superpowers first. brainstorming→prompt-engineering; writing-plans; dispatching-parallel-agents→Workflow/subagents; test-driven-development; verification-before-completion→task-completion-verifier; executing-plans deferred in plan-only mode.

Tool audit (tensor-grep — CEO sees only blockers)

If a required provider is not visible in the initial tool list, search the deferred callable-tool catalog before declaring it unavailable. Exa can be exposed there. Record a genuine provider failure, but do not silently substitute stale model memory for required recency research.

Investigate (parallel tracks)

Prioritize: AGENTS.md, CLAUDE.md, docs/BACKLOG.md, docs/SESSION_HANDOFF.md, pyproject.toml, rust_core/, .github/workflows/ci.yml, tests/, .claude/skills/tensor-grep-*.

Tracks: repo/docs · test/CI/ruff-format-preview gate · registration/routing · Rust FFI/maturin · benchmark/dogfood · Exa research · AGENTS.md roadmap (semantic search, registration-check).

Planning artifacts

docs/plans/requirements-tensor-grep-<YYYYMMDD-HHMM>.md
docs/plans/design-tensor-grep-<YYYYMMDD-HHMM>.md
docs/plans/tasks-tensor-grep-<YYYYMMDD-HHMM>.md

(requirements / design / tasks per SPEC+TDD; design must cite 4 command + 2 flag registration sites if touching CLI; tasks include uv run --no-sync gates, dogfood harness, drain/push-race if release-bearing)

Rank + verify

Score: user/agent value, correctness risk, release readiness, testability, push-race coupling. Update docs/BACKLOG.md.

Before CEO summary: verify-plan-against-code on all seams; Phase 0f checklist; no implementation in plan-only mode.

CEO response format

Executive summary · what worked · all backlog by disposition · research already done · research still needed · spend/financial gates · lessons since the prior update · evidence · next action.

Write the detailed snapshot to a dated audit file and update MEMORY.md, docs/SESSION_HANDOFF.md, and the canonical tracker in the same change. A CEO chat summary is not durable state.

CEO approval before: financially consequential spend or procurement unless the user has already granted that authority. For nonfinancial publication, claim, contract, and merge decisions, follow the current user's explicit authority and the repository gates; do not manufacture a question when the user has told you to ask only about money.

Hard rules (always on)

1. common-sense-check — act on reversible, sub-$150, non-public, non-destructive work; don't ask permission while a paid resource burns.

2. prevent-secret-leak — no secrets in tracked files; env-var reads only.

3. tensor-grep-change-control — load before ANY edit/merge/release in this repo.

4. Orchestrator role — main session coordinates; delegate to subagents / Workflow / CLIs. Don't burn context on scans an implementer could do.

5. Read before write on shared symbols — tensor-grep-code-audit (tg callers, tg blast-radius, tg doctor). Authority is tg --help, not grep.

6. Audit ≠ fix — codebase-audit / frontend-audit are READ-ONLY; implementation is a separate gated loop.

7. Plans are hypotheses — verify-plan-against-code BEFORE multi-file dispatch; subagent-verification-workflow + worktree-fanout-verification-gate AFTER.

8. Never trust a self-report — re-run verification gates yourself in the real venv; worktree/subagent "tests pass" is a hypothesis.

9. Draft-PR-only autonomy — endpoint is a draft PR a human merges. Never auto-merge.

10. WIP CAP (2026-07-08 receipt) — do NOT dispatch a new BUILD while >5 PRs are undrained OR the main gate is red. Generating fixes faster than the ~40–66 min/publish drain empties the queue produces "churning, not completing" (backlog stays constant-size while PRs pile up). Design fork: complete-then-start, not start-then-hope. A red main gate is a drop-everything hotfix that jumps the queue ahead of any new build. Check gh pr list count and gh run list --branch main conclusion before authorizing a new fan-out. Build-vs-merge decoupling: the WIP cap and one-merge-per-tick both gate merge timing, not when work may start -- a PR sequenced "after vX publishes" purely for a CODE-COLLISION reason (it touches the same file, or wants vX's already-merged code as its base) may branch and build off the just-merged main in parallel with an in-flight release; only the final merge stays gated. This saves ~40 min/PR across a campaign. See tensor-grep-change-control Part 7 for the full pattern (named after merge-queue/speculative-CI, release-train, and build-once-promote-everywhere). Batch-merge exception (C-batch, v1.93.0/#703-706): several INDEPENDENTLY already-CI-green PRs may land ~15-20s apart in one tight window and still produce ONE combined, fully-published release — this is not a WIP-cap or one-merge-per-tick violation, provided the operator watches the LAST run in the sequence to full completion (intermediate cancelled/rejected-push runs are benign). Do not confuse a monitored rapid batch with an accidental push-race collision (the v1.17.23/#318/#319 incident) — the discipline is watching the final run through, not merging blind. Full mechanism + the v1.93.0 receipt: tensor-grep-change-control Part 7 (C-batch).

11. Mandatory adversarial security gate before merge — every security-class PR (apply_policy / mcp_server / cpu_backend / index_lock/session_daemon / auth / money / migration / native asset, installer, or doctor-probe construction) gets an adversarial "try-to-BREAK-it, cite file:line, default FIX-FIRST-if-uncertain" review before merge, in addition to (not instead of) the mandatory codex gate below. This is not a rubber stamp: on the 2026-07-08 session it returned SHIP on 3 PRs and caught real issues on 2 — a symlink-follow RCE bypass (.resolve() followed the symlink; fixed with os.path.abspath) and a lock-release TOCTOU (accepted-as-documented after proving a heartbeat thread makes it unreachable). The native-asset/installer/doctor-probe addition is the v1.75.2/v1.75.3 GPU Phase-0 precedent -- PR #596 (P0-5, loud nvidia-to-cpu installer downgrade) was held in draft with an explicit "Opus gate pending before merge" per its council-reviewed plan, because a silent wrong-flavor install or a misleading doctor probe status is a security-relevant integrity failure, not a UX nit. codex is the nominal 2nd-vendor tool but its WSL path is unreliable on this box — an Opus Agent subagent (model: opus) is the reliable substitute when codex is dead, not a reason to skip the gate. Verdict shape: SHIP | FIX-FIRST(+file:line+repro+minimal-fix).

    Review-economy rider (2026-08-03): if a broad model/council prompt times out, retry the exact disputed paragraph and invariant rather than weakening the gate or replaying the whole corpus. A no-verdict seat is failed, not approval and not an infinite wait. Cursor/other economical model work remains a hypothesis until Sol validates the exact resulting bytes/prompt.

    RED/CI evidence rider (2026-08-03, AGENTS A61–A82): behavioral RED pins the exact expected reason — crash/import/panic/setup errors are not RED. Route/start evidence comes from the actual producer/constructor and test-owned OS/raw proof, never a hardcoded bool or production self-attest hook. Containment authenticates writer/client provenance and proves alive-before → dead-after plus cleanup (not Event/EOF/PID text). Crypto negatives need a valid API operation, exact refusal class, and an exportable/trusted positive control. Security grammar validates full sections/types/flags/ effective authority and rejects unknown/inherit-only forms. Resource-owning protocols name close primitives and prove exact-once reverse cleanup on success, BaseException, and cleanup failure while preserving the primary error. RED scaffolds cannot enable partial public behavior or unbounded work before the guard. Immutable-SHA CI clearance needs a real run, expected per-node outcomes, raw artifacts, and the exact population — no run is no clearance. Security green is point-in-time: a fresh fixable advisory blocks merge and is upgraded across all live floors, the lock, validators, and remediation text before a new exact-head audit — never ignored. A77–A82 (2026-08-06 PM): file-based PR-check pollers (never stdin+heredoc empty→ALL_TERMINAL); usage-limit seats FAILED; status-stamp PRs retarget governance pins; gate tip bytes not archaeological RED SHAs; HIGH receipts ≠ Sol SHIP; AMEND_SPINE when READY∩reconcile-BLOCKED.

12. Order the drain by RELEASE impact, not PR number (2026-07-26 receipt). Only fix:/feat: trigger semantic-release. docs:/test:/bench:/chore: complete without publishing, so they create no publish to race — their gate is just "the newest main run completed" (6 min — the GATE duration, i.e. the wait for that main run itself to complete; a DIFFERENT referent from the semantic-release-job-alone figure in the drain-cron section below) versus a full release cycle (30–60 min, longer under runner scarcity). Landing the non-releasing PRs first took a 12-deep queue to 7 in about an hour that would otherwise have bought two merges. One-per-publish protects an in-flight PUBLISH; it is not a per-PR serialisation. Two riders: check for file collisions first (two PRs both editing docs/CONTRACTS.md will conflict once either lands), and re-poll mergeable after each merge — GitHub returns UNKNOWN for a few seconds while it recomputes, and UNKNOWN is not CLEAN.

13. The gate is "newest main run COMPLETED", not "completed GREEN" (2026-07-26 receipt). When main is red, the fix FOR that red must still be mergeable — requiring green before merging the thing that makes it green is a deadlock. Merge the hotfix, then confirm main actually recovered on a later run; that recovery is the evidence the fix worked, not the merge itself. Everything else stays parked while red: merging onto a broken main compounds it and obscures which commit owns the failure.

14. A concurrent agent's PR gets an INDEPENDENT gate, and the verdict goes on the PR (2026-07-26, #786). A PR arriving from another session/worktree is not self-gated by definition, so gate it — then post the verdict as a PR comment with its evidence (what was probed, what the control arm showed). A gate that lives only in your transcript is lost work: the next session re-runs it or reaches a different conclusion, and the author cannot un-draft without waiting on you. Cost: one gh pr comment.

15. Verify the fix on the MERGED artifact, not only pre-merge (2026-07-26). Pre-merge proves the BUG is real (control arm on the unpatched tree); it says nothing about whether the FIX behaves on main after a squash. Re-run the treatment arm against merged main — and check the guard is present structurally (e.g. "_seen" in fn.__code__.co_varnames) rather than by re-reading the diff.

16. Make branch pruning DECIDABLE (2026-07-26). "Don't bulk-nuke agent branches, they may hold WIP" let ~70 husks accumulate. git merge-base --is-ancestor <branch> main is a per-branch proof: an ancestor of main has its commits already in main, so deleting loses nothing. Delete with git branch -d (never -D) so git independently refuses anything unmerged — if the two checks disagree, stop. Receipt: 61 deleted / 0 refused / 2 kept. git branch --merged under-reports after squash-merges, and a CLOSED PR is not a merged PR — one survivor had exactly that shape.

Skill library — retiring-fellow taxonomy (count DERIVED, never stamped — see derive box below)

Ground-truth rule: verify commands/paths against repo + tg --help; re-read each skill's "Provenance and maintenance" when drift suspected. No skill routes around tensor-grep-change-control.

Do NOT maintain a numbered table here — tables rot. This file's table went stale three times (20→26→27 headings) and then omitted 7 on-disk skills (tensor-grep-argv-normalization-and-shadowing, tensor-grep-codex-gated-audit-loop, tensor-grep-cross-platform-path-confinement, tensor-grep-hermetic-hostile-tests, tensor-grep-index-fingerprint-freshness, tensor-grep-release-drift-check, tensor-grep-worldclass-roadmap — verified absent 2026-08-12). Derive the population instead:

ls -1d .claude/skills/tensor-grep-*/ | wc -l      # every tensor-grep-* library skill (was 26/27 in
                                                  # older passes; derived 34 at v1.110.14, 2026-08-12)
ls -1d .claude/skills/code-search-and-retrieval-reference   # +1: the domain-theory skill
# the bare .claude/skills/tensor-grep/ usage skill is EXCLUDED by definition (usage docs for the
# tool itself, not a library entry) — AGENTS.md's gated "**N skills**" sentence counts the same way

Load-when routing: use AGENTS.md's "Carrying the project forward -- the in-repo skill library" index-by-intent (grep that heading) — it carries the Change-safely / Understand / Operate / Advance / Extend / Orchestrate buckets and is pinned to the real folder set by tests/unit/test_skill_index_sync.py, which this file is not.

This skill = meta-orchestrator for generic backlog drain — one entry of the library it indexes (the old table's row-number citations rotted with the table; derive the set above). Semantic-search flagship → tensor-grep-semantic-search-campaign, not here. Scale/hang campaign → tensor-grep-large-repo-scale-campaign, not here.

Also load: tensor-grep (usage), global ~/.claude/skills/ (verify-plan-against-code, dogfood-the-shipped-artifact, …). NO docs/skill_index.md — use AGENTS.md skills section + the derive box above. .claude/skill_rules.json is a separate, harness-level mechanism: project-local keyword/intent triggers consumed by the global skill_activation_gate.py hook to auto-fire a skill on a matching prompt. It seeds only SOME of the library skills (count derived, never stamped — same derive box). Do not trust a number or a name list here -- this sentence enumerated 12 skills in prose and was wrong three ways by 2026-08-02: the real count was 14, and it named tensor-grep-large-repo-scale-campaign as having zero rule when it had since gained one. Derive it:

python -c "import json,os; d=open('.claude/skill_rules.json').read(); \n  lib={x for x in os.listdir('.claude/skills') if x.startswith('tensor-grep-')}; \n  print(sorted(x for x in lib if x not in d))"

Its silence on a topic is not evidence a skill doesn't apply; the AGENTS.md index-by-intent stays authoritative for manual routing.

Backlog + session continuity

• docs/BACKLOG.md — canonical prioritized/historical task ledger: id, P0–P3, description, receipts, and shipped history. Create it on session 0 if absent (seed from memory anchor + gh pr list + session task store, then discard session store as SoT).
• docs/TASK_BOARD.md canonical status index — the machine-parseable live state for the closed-world canonical ID set. Historical prose in either document is not a live-status oracle. Until this index exists, a dated reconciliation audit must derive live state from BACKLOG + SESSION_HANDOFF + GitHub and say that it is an interim snapshot.
• GitHub (gh pr list) — PR source of truth for open/merged work.
• Memory anchor — on every backlog change, update via MEMORY.md / ~/.claude/projects/<slug>/memory/feedback_tensor_grep_backlog.md with: P0 queue, in-flight PRs, last shipped tag, push-race waiter state, "resume here".
• Restart order: memory anchor → docs/BACKLOG.md → docs/SESSION_HANDOFF.md → AGENTS.md → GitHub. Never use the ephemeral session task store as source of truth.
• CEO status = closed-world live backlog + blockers + research + spend + next 3 actions; do not omit demand-gated or mixed-terminal rows merely because they are not immediately buildable.
• Artifact attribution — store PR head, squash merge, main-CI head/run, release commit/tag, and PyPI proof separately. They may be different SHAs. Exact CI proof includes run ID, head SHA, stable job population, and zero unfinished/failing jobs.
• Plan artifact identity — choose one canonical worktree/blob and one SHA-256 method for every thinktank seat. Mixed line endings can make clean-filter-equivalent Windows worktrees hash differently.
• Dependency/lifecycle gate — prove each service/registration/producer precedes its consumer/test; when a numbered draft PR exists, its owning row must be IN_FLIGHT in that PR. Every deferred security behavior needs a canonical ID, owner, threat boundary, and reopen trigger.

Steward cron (this repo): the backlog-steward tick is session-scoped — it re-arms with a NEW id and schedule every session, so any recorded id goes stale immediately. Do NOT trust a previously-recorded id (this file, MEMORY.md, a handoff note). Verify the live cron via CronList at session start; re-arm if absent. (Verified 2026-07-16: three different sources cited three different ids/schedules — all stale.) Re-confirmed 2026-07-24: a session-scoped cron also dies SILENTLY on a mid-session CLI restart or a PC reboot, not only at session boundary — the same steward was lost twice in one session this way, once to each. There is no error or notification when it dies; the only way to know is to check. After ANY restart or crash — not only at the start of a fresh session — re-verify with CronList and re-arm if absent, and keep the durable state (queue, in-flight PRs, "resume here") in the task store + MEMORY.md, which survive a restart even when the cron itself does not (AGENTS.md A25).

Verify in BOTH directions — a presumed-dead cron can still be alive (AGENTS.md A26, same session). The mirror failure to the one above: a cron assumed dead from an earlier loss turned out to still be running, ALONGSIDE its freshly re-created replacement, and fired a stale instruction (telling a later tick to gate a PR that had already merged). Do not just re-arm and move on after a restart — call CronList, read every entry it returns (not just the count), and explicitly delete any superseded duplicate. A stale backstop that still fires looks authoritative and can act on data that is no longer true; it is strictly worse than having no backstop at all.

Risk-calibrated ceremony

Primary execution path: Cursor Agent tool subagents

• Fable (model: fable) — design audit, synthesis, plan review, final vs-plan check
• Sonnet — TDD implementation, routine review

Fable constraints:

• Use Agent subagent model: fable. Do NOT rely on claude -p --model claude-fable-5 headless.
• Workflow tool cannot reach Fable — silently falls back to session model. Use Agent subagents for Fable; Workflow for haiku/sonnet file-grounded fan-out only.
• Fable is ~2× token cost. Cap Fable parallel fan-out at ≤2–3 (vs ≤3–5 for sonnet/haiku).
• Fable's classifier may route explicit vuln-hunting to Opus — frame audits as correctness/quality to stay on Fable; run explicit security audits on Opus.

Resume-from-transcript, not re-dispatch (broadened 2026-07-08 — ANY transient failure, not just session-limit kills). A background subagent (Fable or otherwise) that dies mid-task — a session-limit kill (had-no-active-task) or a transient "Agent terminated early due to an API error: 500" — is resumed via SendMessage to its agent ID, not re-dispatched fresh: the transcript carries the partial work forward. Message it plainly: "you hit a transient error, your work is intact, continue + ." Receipt: happened 3x in one session (2 builds + 1 security-gate agent hit a transient API 500) and all 3 recovered cleanly with zero lost work. Re-dispatching fresh instead of resuming loses everything the agent had already done.

Don't kill a build on staleness (2026-07-08 receipt). A complex build (a routing redesign, heavy test-rewiring) can legitimately run 10–15+ minutes between visible output flushes. A "stale, no output for N minutes → kill it" heuristic destroys a working agent — this exact heuristic killed an in-progress build TWICE on this session before the kill-notes proved it had been actively rewiring tests the whole time, not hung. Trust the harness's own completion notification; only intervene on a genuine hang, and diagnose from the kill-note's last line (or anti-hang-test-protocol's exit-124/137 signal), never from an elapsed-time guess alone.

A "stopped" agent may have already committed — check the worktree before re-dispatching (2026-07-24 receipt). A build agent's process exited after committing but before emitting its own completion summary; the notification read as "no completion record found," which looks like the work is lost. It was not: git -C <worktree> status/log showed a clean tree with the real commits present and correct. Re-dispatching fresh on a "stopped" notification without checking the worktree first risks duplicating (or conflicting with) work that already landed — run git -C <worktree> status and git -C <worktree> log --oneline -5 BEFORE deciding the work needs to be redone. Full incident: AGENTS.md Campaign Orchestration A23.

A worktree agent can commit on a detached HEAD — verify HEAD matches the branch ref before pushing/opening a PR (2026-07-24 receipt). git push origin <branchname> can push a stale branch REF (still at main's tip) while the agent's real commit sits at the worktree's detached HEAD, unreachable from that ref — GitHub then rejects the PR with "No commits between main and <branch>," which reads like the work vanished a second, distinct way. Compare git rev-parse HEAD against git rev-parse <branchname>; if they differ, push the SHA explicitly (git push origin <sha>:refs/heads/<branchname>) before opening the PR. See tensor-grep-debugging-playbook §16 for the full triage row and AGENTS.md's A24.

External CLIs:

• codex — MANDATORY adversarial gate on every money / auth / security / migration diff before merge (separate quota; catches agent over-claims). Fallback for general peer review when Agent subagents are throttled. When codex's WSL path is unreliable, an Opus Agent subagent is the reliable substitute for the mandatory gate (Hard Rule 11) — never skip the gate outright.
• agy / cursor-agent — fallback only when Agent subagents are throttled or unavailable.

Phase pipeline (default: standard-dev-workflow)

0 — Orient

Read CLAUDE.md, AGENTS.md, docs/SESSION_HANDOFF.md, memory anchor, docs/BACKLOG.md, open PRs.

1 — Prompt engineering (prompt-engineering)

Bounded spec: scope, non-goals, required reads, verification gates, risk tier (lean vs full), noise band for quantitative claims.

2 — Plan (superpowers:writing-plans + skill discovery)

Numbered plan; per-step skill + risk + verification gate. TDD-first for behavior changes.

3 — Research (use-exa + optional agy) — REQUIRED before non-trivial execution

Fold findings as ADDED / CONTRADICTED / SUPERSEDED. Competitive/prior-art → derive edge cases → plan + tests BEFORE implementation. Wire-format / provider-contract claims on money/auth paths (webhook field values, event semantics, SDK response shapes) must be Exa-verified against the provider's live docs before shipping — a wrong premise silently breaks working billing.

4 — Council review (use-thinktank / Fable) — risk-tiered

Mandatory for load-bearing / security / concurrency / FFI / public-ship / >$50. Pass verbatim plan. Skip for contained fixes.

• Multi-round hash-frozen approval loop (2026-08-13 receipt): freeze the artifact hash, run the 8-seat council, apply ONLY the verified findings, re-hash, re-run until N/N APPROVE (5 rounds to 7/7 on docs/plans/2026-08-13-backlog-completion-plan.md). Failed seats are not votes. A step whose content depends on a future verdict must be written NOW as a named GATE with command + trigger + re-approval rule — "EXPAND AT WAVE START" reads as a placeholder to half the council. Cite the artifact hash in every round's question file. (A108)

5 — Pre-dispatch gate (verify-plan-against-code)

Adversarial seam verification (file:line). BLOCK build until clean.

Run that skill's Step 0 (the PREMISE check) FIRST on every board item. Seam verification proves the anchors are real; it cannot tell you the item is already CLOSED — a plan against a fixed bug has citations that resolve perfectly. Reproduce the defect or find the fixing commit before dispatching. Receipt: the 2026-08-01/02 reconcile found 17 of ~24 open items already shipped, refuted, or by-design, and one agent was dispatched at finished work (#58). The machine-parsed canonical status index in docs/TASK_BOARD.md is the live-status view; docs/BACKLOG.md remains the canonical prioritized/historical ledger. GitHub remains the PR-state oracle.

Extend the premise check from board items to BRANCHES/WORKTREES (2026-08-12). Before dispatching a repair on a stale-looking branch, premise-check its CONTENT, not just its existence: git cherry <target> <branch> proves only PATCH-ID distinctness, never novel content (the same fix can land as a different patch); enumerate the branch's touched paths, diff each endpoint against the target, and confirm the symbols/tests actually exist on the target; use blob identity (git rev-parse <rev>:<path>) + pickaxe (git log -S"<exact string>") for historical-blob claims. A branch whose "missing" work already landed elsewhere is the same finished-work dispatch as #58.

6 — Implement

Pass subagents Phase-1 spec verbatim + relevant BACKLOG item + carry-forward audit lessons.

7 — Review loop (calibrate to risk)

• Contained fix: Fable-audit-found → Sonnet-TDD-build → verify-in-real-venv → CI parity → draft PR.
• Load-bearing: add thinktank → code-reviewer/Opus → codex adversarial gate (mandatory on money/auth/security/migration) → Fable vs plan + code. Repeat until zero must-fix findings.
• Always: project CI parity gates; dogfood shipped binary for CLI/routing changes (scripts/dogfood/).

Exit only on task-completion-verifier PASS with receipts you reproduced in the real venv.

8 — Ship + document

• Merge via the self-firing drain-cron pattern (one PR at a time; see push-race below) — never a long-lived backgrounded drain loop.
• Update docs/BACKLOG.md, memory anchor, docs/SESSION_HANDOFF.md, AGENTS.md if practice changed.
• Record proven Workflow recipes in workflow-ledger if used.

tensor-grep operating rules (govern shipping here)

Merge / release — the self-firing drain-cron, not a backgrounded loop (2026-07-08 receipt)

A long-lived bash drain_loop.sh & background process is the wrong shape. It kept dying during the long CI/publish waits on this session (and once, an inner & inside a run_in_background wrapper orphaned it entirely) — a ~40–66 min wait window is a long time for a backgrounded shell process to survive uninterrupted. Note there is no scratchpad/drain_v2.sh checked into this repo — any ad hoc drain script an agent writes lives in the OS scratch/temp dir (session-ephemeral), never committed at that path; do not cite it as a repo-relative file.

The fix: a per-fire, short-lived cron/loop tick that does at most ONE merge, then exits. Each fire is cheap and stateless — nothing to be killed, because nothing stays running between fires. Arm it with the loop skill (/loop 30m <the one-shot prompt below>) or an equivalent external scheduler — never a backgrounded & shell loop. Cadence ~30 min matches the achievable ~1-PR-per-publish rate (a release-bearing merge's own wait window is ~40–66 min, so firing much faster than that just re-checks a still-in-flight release).

/loop vs CronCreate — pick based on how long the drain needs to survive, not habit. /loop is session-bound: it stops firing the moment the current session ends (context compaction, a crash, the user closing the terminal) — fine for a drain you expect to finish within one sitting, but it silently dies on anything longer. CronCreate schedules a job that survives session end and a process crash, re-arming on its own cron schedule independent of whether this session is still alive — the right choice for a multi-hour/multi-day drain campaign. Whichever you use, re-verify it is still armed at the start of a NEW session (a session-scoped /loop from a prior session is already dead; a CronCreate job persists but its id/schedule should still be confirmed via a listing call, not assumed from a stale note — see the Steward-cron caution below).

Event-driven alternative to blind polling: gh run watch <run-id> --exit-status (or the Monitor tool) beats a fixed cadence for latency-sensitive waits. The 30-min cadence above is sized for drain throughput (don't check faster than a release can possibly finish), but if you specifically need to know the MOMENT one release finishes (to chain the next action immediately rather than wait out to the next cron tick), block on the run directly instead of polling on a timer — gh run watch returns as soon as the run's conclusion is known, and Monitor gives the same event-driven wakeup for a backgrounded process. Use the cadence-based cron for the drain loop itself; use the event-driven watch for "tell me the instant this ONE release publishes so I can act."

One-shot logic per fire (pseudocode; adapt the gh calls to the live PR queue):

# ONE fire = ONE merge attempt, then exit. No internal loop, no backgrounding.
latest_tag_on_pypi() { ... }                    # compare latest git tag vs PyPI's latest version
main_ci_completed()  { [ "$(gh run list --branch main --workflow ci.yml --limit 1 \
                             --json status -q '.[].status')" = "completed" ]; }

# Push-race check FIRST: refuse to merge into an in-flight release window.
latest_tag_on_pypi && main_ci_completed || { echo "release in flight, skip this fire"; exit 0; }

# Pick the lowest-numbered CLEAN, mergeable PR (WIP-cap-respecting: Hard Rule 10).
pr=$(gh pr list --state open --json number,mergeStateStatus \
      -q 'map(select(.mergeStateStatus=="CLEAN")) | sort_by(.number) | .[0].number')
[ -n "$pr" ] || { echo "nothing CLEAN to merge"; exit 0; }

gh pr merge "$pr" --squash --delete-branch

• One merge per fire, one fire per cadence tick — never merge two PRs in the same fire even if both look CLEAN; the next fire will pick up the next one after the push-race check re-clears.
• Push-race check is mandatory on every fire, not just the first: the latest chore(release): vX tag must be confirmed on PyPI AND the latest main CI run must show conclusion: success before merging anything — including docs:/chore: PRs, which don't bump version but are still unsafe to interleave mid-release.
• Real wait window ~40–66 min per release-bearing merge (native-build-smoke + benchmark-regression
  • semantic-release + publish-pypi). The ~6-min figure here is only the semantic-release job in isolation (a DIFFERENT referent from Hard rule 12's ~6-min non-releasing GATE duration, "newest main run completed") — don't cadence the cron faster than the real window or every fire just re-observes "still in flight".
• Green-gap batch merge (2026-08-12): when NO release is in flight or planned, non-releasing docs:/test:/chore: PRs may merge back-to-back within ONE green gap — their only gate is the newest main run completed (Hard rule 12). This makes the referents of the two rules explicit: "one merge per fire" above governs RELEASING PRs (one-per-fire stays for them outside a monitored C-batch — Hard rule 10's exception); it does not serialize non-releasing PRs against each other in a release-free gap. The moment a release is in flight or next in the queue, everything falls back to the push-race wait (change-control Part 7 "Precedence").
• Failed release self-heals on next push (tag-derived). Don't panic-rerun.
• Respect Hard Rule 10 (WIP CAP): if >5 PRs are undrained or the main gate is red, the fire should refuse to dispatch a new build (merging the existing queue is still fine/expected).

Verify in the REAL venv

Worktrees have no built .venv — agent "tests pass" is a hypothesis.

The real venv is OS-owned. From WSL, never pass the Windows checkout (/mnt/c/...) as uv --project: uv can delete/replace the incompatible Windows .venv with a Linux one. Use the WSL worktree's own venv for RED iteration, then run the canonical gate from PowerShell in the Windows checkout. If crossed, move the bad venv aside and rebuild from Windows with uv sync --frozen before trusting any receipt.

uv run --no-sync ruff check .
uv run --no-sync ruff format --check --preview .
uv run --no-sync mypy src/tensor_grep          # src only, NOT tests
uv run --no-sync pytest tests/<targeted>.py    # scoped locally on this desktop

• uv run --no-sync is mandatory — plain uv run re-syncs away the [dev] tree-sitter tree.
• ruff format --preview is a SEPARATE gate from ruff check — check-only misses format CI (#424). Never pass --preview to ruff check. Bare ruff format without --preview reverts preview style.
• Full pytest + Rust test/clippy matrix + benchmarks + release-asset builds → PR/main CI only (grep -n "full pytest, full Rust test/clippy matrices" AGENTS.md; was AGENTS.md:385, now :487 — drifted +102 lines since the 2026-07-23 pass, see Provenance — high-memory; don't run full suite locally unless user explicitly approves).
• Rust changes: maturin develop + cargo test --manifest-path rust_core/Cargo.toml.

Concurrent shared-checkout

While a background code-agent uses the shared checkout: NO git reset --hard, checkout, or branch-switch. Isolate writers with isolation: 'worktree'. Orchestrator: read-only/gh only. Harvesting a worktree's committed work is main-loop-safe (even under rate limit). Before integrate: git worktree remove --force <path> → checkout branch in main → re-run gates above.

Harvest pattern (worktree -> PR, 2026-07-08 receipt)

A worktree agent's "tests pass" is a hypothesis, not a fact — its venv may use a copied or absent native extension, so a green result there proves nothing about the real build. The proven harvest sequence: (1) cherry-pick the worktree agent's commit onto a fresh branch off origin/main; (2) re-verify in the real venv (which has the built Rust extension) — ruff check + ruff format --preview + mypy + a live smoke test, not just the worktree's self-report; (3) run the mandatory adversarial security gate (Hard Rule 11) if the diff touches a security-class surface; (4) THEN open the PR. Clean up after: git checkout main; git reset --hard origin/main; git worktree remove --force <path>. Never open a PR straight from a worktree's own "all green" claim.

Subagent fan-out on shared-pin surfaces (2026-08-20, 11-PR tri-split receipts)

The multi-writer discipline when several agents split/move code concurrently. Full law: AGENTS.md, "An Environment DIFFERENCE Can Be The Only Instrument That Sees A Defect".

• One agent owns each shared file per wave. scripts/file_size_allowlist.json's cli entries are ADJACENT LINES: two green PRs that each edit one line conflict pairwise. Brief every agent to change exactly its own line; resolve at merge with the lower pin.
• Union-merge all open PRs touching a shared pin/census before queueing any. A branch cut before a gate merged is green against a world without the gate — twice this campaign the union failed where every branch passed.
• Every split brief must require the FOUR-shape patch sweep (patch("dotted"), patch.object, monkeypatch.setattr, mod.X =) against the target module, and must state: on a box without the native binary, local green CANNOT clear the native-path branch — CI is the only arm that takes it. Three rounds of one bypass class shipped before this was written down.
• Relocated handlers/emitters must be excluded from source censuses with the reason inline (moving a file do

…(truncated)