Organize dirty work from codex/workflow-reliability

.agents/skills/task/SKILL.md

@@ -6,7 +6,7 @@ description: Manage Database task lifecycle transitions safely, including start,
 # Task
 
 1. Use the required task-start script before repository changes.
-2. Run `npm run workflow:lifecycle -- --phase <status|start|handoff|landed|cleanup> --write-evidence`.
+2. Run `npm run primary:status`, then `npm run workflow:lifecycle -- --phase <status|start|handoff|landed|cleanup> --write-evidence`.
 3. Inspect branch, upstream, worktrees, status, and operation markers for the selected phase.
 4. Preserve dirty, ambiguous, active, or unmerged work.
 5. Keep fetch, push, PR, merge, and provider checks approval-gated.

AGENTS.md

@@ -466,6 +466,7 @@ Record one `docs/branch-review-ledger.md` row per PR touched, and end with the p
 - After auth, Supabase, ingestion, answer generation, search/ranking, clinical output, or source-governance changes, run the smallest domain check plus `npm run check:production-readiness`. Run `npm run check:supabase-project` after Supabase env/config changes.
 - For handoff, archive-safety, or upload-style requests, inspect branch/upstream/status first, run the appropriate verification gate, and only commit or push when the request explicitly asks for that workflow.
 - For broad chat/worktree reconciliation or cleanup, run `node scripts/reconciliation-preflight.mjs`, use the cheap ownership/PR/ledger/ancestry funnel before patch comparison, and never print raw process command lines.
+- Keep feature edits in task-owned worktrees. Before any deliberate write, branch switch, fast-forward, or synchronization in the canonical primary checkout, run it through `npm run primary:mutate -- <command> [args...]`; inspect ownership read-only with `npm run primary:status`. The guard must fail closed on a live writer, dirty state, active Git operation, or unreadable ownership record, while read-only work and independent worktrees remain unblocked.
 - For codebase appraisal exports, stage outside the repo, include `EXPORT_MANIFEST.md`, exclude secrets/dependencies/build outputs/local state, and verify the archive can be opened before handoff.
 - When a repeated repo-specific workflow is discovered, update this file or ask the user whether it should be remembered.
 

docs/process-hardening.md

@@ -12,6 +12,13 @@ The reusable procedure is [`docs/reconciliation-playbook.md`](reconciliation-pla
  cleanup. It uses cached Git refs, never fetches, and reports primary/worktree dirty state,
  detached worktrees, ahead/behind counts, and operation markers. Add `--include-processes` only
  when ownership could block cleanup; that path emits metadata/counts and never raw command lines.
+ Its worktree Git checks use bounded asynchronous inspection, per-command fail-closed timeouts,
+ and duration metadata rather than serial subprocess fan-out tied to the host's worktree count.
+- `npm run primary:status` remains read-only. `npm run primary:mutate -- <command> [args...]` is the
+ cooperative write boundary for the canonical primary checkout: it holds an atomic lease for one
+ child mutation, refuses live contention, dirt, or Git operation markers, stores no command
+ arguments, and recovers only owners proven dead (or incomplete records older than the initialization
+ grace period). Feature worktrees and read-only inspection do not acquire this lease.
 - `workflow:lifecycle -- --phase reconcile` selects the preflight locally and lists remote fetch as
  a separate approval-required action.
 - Candidate filtering is cheap-first: owner/open-PR/review-ledger/ancestry before patch comparison;

docs/productivity-workflows.md

@@ -26,7 +26,15 @@ The repository exposes seven offline-first workflow planners. Each planner inspe
 - Use lifecycle phase `reconcile` for broad multi-worktree work. It selects the report-only
  `node scripts/reconciliation-preflight.mjs` locally and keeps `git fetch --prune origin` approval-gated. Add
  `--include-processes` to the preflight only when process ownership may block cleanup; it never
- serializes raw command lines.
+ serializes raw command lines. Worktree inspection is bounded and reports its duration, so the
+ command remains useful when many worktrees are registered without making the test suite depend
+ on that machine-local inventory.
+- Use `npm run primary:status` for a read-only view of the canonical checkout's owner, dirty state,
+ and Git operation markers. Wrap deliberate primary writes with
+ `npm run primary:mutate -- <command> [args...]`. The wrapper holds an atomic lease for the child
+ command, refuses a second live owner or pre-existing dirty/operation state, and recovers a lease
+ whose recorded process is proven dead. It does not serialize read-only work or commands run in
+ independent feature worktrees.
 
 The existing shared `workflow:run`, `workflow:status`, `workflow:verify`, `workflow:deps`, `workflow:clean-state`, `workflow:export`, and `workflow:handoff` commands now resolve their shared implementation through the repository's Git common directory. This keeps them portable in linked and detached Codex worktrees. Set `CODEX_LOCAL_WORKFLOW_ROOT` only when the shared tools live somewhere non-standard.
 

docs/reconciliation-playbook.md

@@ -71,6 +71,17 @@ merges, old review refs, and intentionally retained branches.
 - Start with a red reproducer or exact content proof.
 - Refresh the base between sequential protected-main PRs.
 - Reject stale, mixed, duplicated, refuted, or unmeasured behavior rather than forcing it to apply.
+
+## Canonical checkout synchronization
+
+- Inspect the primary without claiming it: `npm run primary:status`.
+- Keep ordinary edits and verification in task-owned worktrees.
+- Wrap each deliberate primary branch switch or fast-forward so ownership is held until Git exits,
+ for example `npm run primary:mutate -- git merge --ff-only origin/main`.
+- Stop when the guard reports a live owner, dirty entry, active Git operation, or unreadable state.
+ Preserve and classify the checkout; never bypass the lease or discard files to make the guard pass.
+- A dead owner is recovered automatically. A fresh incomplete ownership record fails closed until
+ its 30-second initialization grace period expires.
 - Protected RAG behavior requires the repository RAG declaration, offline contracts, and approved
  baseline/post live canary. A failed canary reverts immediately.
 

package.json

@@ -15,6 +15,8 @@
  "hooks:install": "node scripts/install-git-hooks.mjs",
  "guard:push": "node scripts/guard-push.mjs",
  "guard:push:self-test": "node scripts/guard-push.mjs --self-test",
+ "primary:status": "node scripts/primary-checkout-guard.mjs status",
+ "primary:mutate": "node scripts/primary-checkout-guard.mjs run --",
  "check:base-freshness": "node scripts/check-base-freshness.mjs",
  "ensure": "node scripts/ensure-local-server.mjs",
  "build": "node scripts/run-heavy.mjs --npm-script build:internal",