Agent neutrality PR-1: vendor-neutral cross-project rules and checkpoint procedure

AGENTS.md

@@ -10,6 +10,8 @@ order:
 4. [`operating-model/decision-log.md`](operating-model/decision-log.md)
 5. [`operating-model/agent-work-loop.md`](operating-model/agent-work-loop.md), when you take work
    from a shared board (an issue queue such as Beads)
+6. [`operating-model/procedures/checkpoint.md`](operating-model/procedures/checkpoint.md), before a context
+   compaction or handoff, and when resuming after one
 
 Use [`operating-model/project-profile.template.md`](operating-model/project-profile.template.md)
 to establish a project profile. The target project’s own guidance, handoff,

CLAUDE.md

@@ -9,6 +9,8 @@ technical project, read the shared operating model in this order:
 4. [`operating-model/decision-log.md`](operating-model/decision-log.md)
 5. [`operating-model/agent-work-loop.md`](operating-model/agent-work-loop.md), when you take work
    from a shared board (an issue queue such as Beads)
+6. [`operating-model/procedures/checkpoint.md`](operating-model/procedures/checkpoint.md), before a context
+   compaction or handoff, and when resuming after one
 
 Use [`operating-model/project-profile.template.md`](operating-model/project-profile.template.md)
 when establishing project-specific context. Project repositories remain the

claude/skills/README.md

@@ -9,3 +9,4 @@ mkdir -p ~/.claude/skills && ln -s ~/work/code/personal/env/claude/skills/<name>
 ## Available skills
 
 - **pre-compaction-checkpoint**: Use before a context compaction (/compact), when the user says they are about to compact, or when asked to "record everything so nothing is lost". Materializes every fact, decision, approval, in-flight task and next step into durable files, so the session can resume exactly where it left off without hallucinating.
+  This skill is a thin loader; the procedure itself is `operating-model/procedures/checkpoint.md`.

claude/skills/pre-compaction-checkpoint/SKILL.md

@@ -5,57 +5,8 @@ description: Use before a context compaction (/compact), when the user says they
 
 # Pre-compaction checkpoint (and resume)
 
-**Goal:** after compaction you remember only a summary. Anything not written to disk may be lost or misremembered.
-Before compacting, write down everything needed to continue; after compacting, reload it from disk and verify it
-against live sources before acting.
+This skill is a loader. The procedure is vendor-neutral and lives in one place:
+`~/work/code/personal/env/operating-model/procedures/checkpoint.md`.
 
-**The principle: disk, not memory. Verify, don't recall.** Every fact you record should come from a source you
-just checked (git, `gh`, files), not from what you remember of the conversation.
-
-## A. Before compaction (checkpoint)
-
-1. **Freeze new work.** Don't launch new tasks until the checkpoint is written. Tasks already running may continue.
-2. **Capture the user's words verbatim.** Append every user ruling, approval, answer and preference given since the
-   last checkpoint to the project's rulings log, with the date, quoted exactly as typed (typos included). Add a
-   short "reading" beneath each only if you need to interpret it. Approvals of cost, merges and scope matter most.
-3. **Capture your own decisions.** Append every decision you made (on reviews, deviations, contradictions, plans)
-   to the project's decisions or notes log, with its reason and what it supersedes.
-4. **Snapshot live state from the sources**, not from memory:
-   - the main branch SHA; every PR merged since the last checkpoint with its merge SHA (`gh pr view N --json
-     mergeCommit`); every open PR with its head SHA, merge state, checks and next step;
-   - the running background tasks and agents: their id, role, current state, and what each is waiting for;
-   - spend: approved against actual, per budget line, read from ledgers or logs;
-   - the open questions for the user, and questions already answered (so they aren't asked again).
-5. **Write ONE dated state file, READ FIRST,** that supersedes the previous one. It has these sections:
-   - 0. Role, and the standing rules (how to work, what is forbidden, who approves what);
-   - 1. Where the truth lives (paths);
-   - 2. Git and PR state (tables with SHAs);
-   - 3. The work items or tasks by milestone;
-   - 4. Costs (approved and spent);
-   - 5. Open questions for the user;
-   - 6. Answered questions (don't re-ask);
-   - 7. Next actions, in order;
-   - 8. The running agents, with ids and how to resume each.
-6. **Update persistent memory.** Point a "READ FIRST" entry at the top of the memory index to the new state file.
-   Save each new standing preference the user gave as its own feedback memory (the rule, why, how to apply). Update
-   or delete memories the session proved wrong.
-7. **Put durable decisions in version control where the project expects them** (e.g. a decisions file or ADR), or
-   list them in the state file as "owed to Git" with the PR that will land them.
-8. **Verify the checkpoint:**
-   - every user message since the last checkpoint maps to a line in the rulings log;
-   - every open PR and running agent is in the state file;
-   - every number in the state file was read from a source this turn;
-   - grep the state file for "TODO" or "?" and resolve each.
-9. **Tell the user** what was recorded and where, what is still in flight (and that it keeps running), and that
-   it's safe to compact.
-
-## B. After compaction (resume)
-
-1. Read the READ-FIRST state file in full, then the tail of the rulings log and the decisions log, then the memory
-   index.
-2. **Re-verify live state before acting:** the main SHA, the open PRs (`gh pr list`), and each running agent's
-   status. Trust the live state over the file where they differ, and note the difference.
-3. Don't redo finished work. Don't re-ask answered questions. Don't restate the summary to the user.
-4. Continue from "Next actions" in order, and pick up messages from agents that arrived during the compaction.
-5. If anything in the file is ambiguous, check the source (the PR, the log, the report) before deciding. Never fill
-   a gap from memory.
+Read that file in full and follow it: part A before a compaction, part B right after one. Do not keep a copy of the
+steps here; amend the procedure file instead.

operating-model/README.md

@@ -30,6 +30,7 @@ repository or secure system.
 | [Working style](working-style.md) | Confirmed collaboration preferences and communication expectations. |
 | [Execution and handoffs](execution-and-handoffs.md) | How bounded work, delegation, reviews, checkpoints, and blockers are handled. |
 | [Agent work loop](agent-work-loop.md) | How agents take work from a shared board: a dispatcher launches one clean-context sub-agent per job; what next, when to stop, who reviews and repairs. Projects inherit it and override only its parameters. |
+| [Checkpoint and resume](procedures/checkpoint.md) | A vendor-neutral procedure to record everything before a context compaction or handoff, and to resume from disk afterwards. |
 | [Project profile template](project-profile.template.md) | A reusable starting point for a project-specific operating context. |
 | [Decision log](decision-log.md) | Dated, evidence-based operating decisions and observations. |
 

operating-model/decision-log.md

@@ -40,3 +40,4 @@ Status is intentionally explicit:
 | 2026-09-28 | Confirmed | Long documents carry a table of contents with jump links | Sections with four or more `##` level headings get a TOC block right after the title. Automated tooling in projects regenerates and validates the TOC. See `working-style.md` and `agent-work-loop.md`. |
 | 2026-09-29 | Confirmed | The agent launched on a work board is a dispatcher: one fresh, clean-context sub-agent per job, one at a time, up to five jobs per run, then a full stop until a human says go. | Owner: "ideally, you want each agent to work with a clean context, then each agent is launching a sub-agent be the model then, so subagent finishes a bead and changes bead status and reports back to parent agent. parent agent at any point in only running a single sub agent. after the sub agent finished, the parent agent is lanching the next one in a loop, up to a maximum of five and then completely stop until human asks it go again for another five". The dispatcher only reads the board, claims, launches, reads the report and logs; the sub-agent does one job and makes its board transition. Refines the 2026-09-28 work-loop row: the loop and priorities stay, the agent that runs them changes. See `agent-work-loop.md` sections 2, 3, 4 and 6. |
 | 2026-09-29 | Confirmed | Projects keep their launch prompts as named, versioned files in the repo, with an index; a launch is one line naming the prompt and its path, plus parameters; the run report names the prompt version it ran. | The owner approved the lead's design ("go") for replacing pasted launch text with checked-in prompts, so a launch is repeatable and a report says which prompt version produced it. Adds to the 2026-09-29 dispatcher row. See `agent-work-loop.md` section 7. |
+| 2026-10-08 | Confirmed | The owner's cross-project rules live here in vendor-neutral words so any agent works the way the owner wants in every repository: model tiers (deep, standard, light, premium) with a vendor mapping, premium launches only on the owner's per-launch yes, ask before any new service, monitor, workflow or scheduled wakeup, never set a spend cap ($0 by default), they/them for the owner, a fresh brief for a scope change, files only under `~/work`, scratch in the harness's scratchpad or `~/work/code/mastrix/wt/<repo>-<task>-notes/`, never `/tmp`, and a vendor-neutral checkpoint procedure. | Owner, R1008-27: "n1-n8 is good", accepting decisions D1-D8 of the agent-neutrality plan as recommended, and: "any agent can work exactly like the way I want it to on the repo". Sources: the owner's rulings of 2026-09-27, 2026-10-05 and 2026-10-06 as kept in the Claude memory files. Supersedes the vendor-named tier wording of the 2026-09-21, 2026-09-23 and 2026-09-27 rows (they stay as history) and the 2026-09-27 scratch-path example. See `working-style.md` → Model tiers, `execution-and-handoffs.md` → Scratch files and agent worktrees, and `procedures/checkpoint.md`. |

operating-model/execution-and-handoffs.md

@@ -257,11 +257,21 @@ Escalate rather than improvise when work encounters:
 The escalation should include evidence and a proposed safe decision, not only a
 description of the problem.
 
+## Briefs and scope changes
+
+| Situation | Rule |
+| --- | --- |
+| A brief for a sub-agent | Fresh, clean context: the task, the done-when, the rules that bind it and only the facts it needs. Tiers and the brief rule: `working-style.md` → Model tiers. |
+| The scope changes while an agent runs | Put the full delta in a **fresh agent's initial brief**. Do not amend a running agent by a mid-task message: an agent told to stop rather than improvise may treat the amendment as an injected instruction and ignore it. Finish the design before delegating. |
+
 ## Scratch files and agent worktrees
 
-- **Where:** only in the session scratchpad directory the harness gives you (for example
-  `/private/tmp/claude-<uid>/<project>/<session>/scratchpad/`), in **your own subfolder** named for your task and
-  role (e.g. `W-0012-doer/`, `PR-171-adversary/`). Your git worktrees for the task live there too.
+| Item | Where |
+| --- | --- |
+| Files of any kind | Only under `~/work`, never `~/Desktop`, `~/Documents`, `~/Downloads`, `~/` or a `/tmp` folder you make yourself. The one exception is the scratchpad directory the harness itself provides, below. |
+| Scratch (notes, logs, PR bodies) | The harness's scratchpad directory when it gives one, in **your own subfolder** named for your task and role (e.g. `W-0012-doer/`, `PR-171-adversary/`). When it gives none: `~/work/code/mastrix/wt/<repo>-<task>-notes/`, beside the worktree. |
+| Git worktrees | `~/work/code/mastrix/wt/<repo>-<task>`, fresh from the remote's default branch, one writer per worktree, unless the harness provides the worktree. |
+
 - **Never:**
   - at the scratchpad's root, which is shared by every agent in the session;
   - inside any repository's working tree (no repo-relative `scratchpad/` folder);

operating-model/procedures/checkpoint.md

@@ -0,0 +1,66 @@
+# Checkpoint and resume
+
+A procedure any agent follows, in any harness. Use it:
+
+| When | Part |
+| --- | --- |
+| Before a context compaction, reset or handoff to another session; when the owner says they are about to compact; when asked to "record everything so nothing is lost" | A. Checkpoint |
+| Right after a compaction, reset or handoff, or when you start a session from someone else's state file | B. Resume |
+
+**Goal:** after a compaction an agent holds only a summary, and anything not written to disk may be lost or
+misremembered. Before it, write down everything needed to continue; after it, reload that from disk and verify it
+against live sources before acting.
+
+**Principle: disk, not memory. Verify, don't recall.** Every fact recorded comes from a source just checked (git,
+`gh`, files), not from the conversation.
+
+Where the files live is the project's rule (its lane or state folder). This procedure names the files by role.
+
+| Role | Holds |
+| --- | --- |
+| State file | The one dated, READ-FIRST file that supersedes the previous one |
+| Rulings log | The owner's words, verbatim, with dates |
+| Decisions or notes log | The agent's own decisions, with reasons |
+
+## A. Before compaction (checkpoint)
+
+| # | Do | Check |
+| --- | --- | --- |
+| 1 | **Freeze new work.** Launch nothing new until the checkpoint is written. Tasks already running may continue. | |
+| 2 | **Capture the owner's words verbatim.** Append every ruling, approval, answer and preference given since the last checkpoint to the rulings log, with the date, quoted exactly as typed (typos included). Add a short "reading" beneath each only if it needs interpreting. Approvals of cost, merges and scope matter most. | Every owner message since the last checkpoint maps to a line. |
+| 3 | **Capture your own decisions.** Append every decision you made (on reviews, deviations, contradictions, plans) to the decisions log, with its reason and what it supersedes. | |
+| 4 | **Snapshot live state from the sources.** The main branch SHA; every PR merged since the last checkpoint with its merge SHA (`gh pr view N --json mergeCommit`); every open PR with its head SHA, merge state, checks and next step; the running agents and background tasks (id, role, state, what each waits for); spend, approved against actual per budget line, read from ledgers or logs; the open questions for the owner and the questions already answered. | Every number was read from a source this turn. |
+| 5 | **Write ONE dated state file, READ FIRST,** sections 0 to 8 below. | Every open PR and running agent is in it. |
+| 6 | **Update the agent's persistent memory, if the harness has one,** as pointers only: a READ-FIRST entry naming the new state file, and for each rule a pointer to its canonical home in Git. Rule text is not kept in memory. Delete or correct entries the session proved wrong. | |
+| 7 | **Put durable decisions in version control** where the project expects them (a decisions file, an ADR), or list them in the state file as "owed to Git" with the PR that will land them. | |
+| 8 | **Verify the checkpoint.** Search the state file for "TODO" and "?" and resolve each. | Nothing unresolved remains. |
+| 9 | **Tell the owner** what was recorded and where, what is still in flight (and that it keeps running), and that it is safe to compact. | |
+
+State file sections:
+
+| # | Section |
+| --- | --- |
+| 0 | Role, and the standing rules (how to work, what is forbidden, who approves what) |
+| 1 | Where the truth lives (paths) |
+| 2 | Git and PR state (tables with SHAs) |
+| 3 | The work items or tasks, by milestone |
+| 4 | Costs, approved and spent |
+| 5 | Open questions for the owner |
+| 6 | Answered questions (do not re-ask) |
+| 7 | Next actions, in order |
+| 8 | The running agents, with ids and how to resume each |
+
+## B. After compaction (resume)
+
+| # | Do |
+| --- | --- |
+| 1 | Read the READ-FIRST state file in full, then the tail of the rulings log and the decisions log, then the memory index if the harness has one. |
+| 2 | **Re-verify live state before acting:** the main SHA, the open PRs (`gh pr list`), and each running agent's status. Trust the live state over the file where they differ, and note the difference. |
+| 3 | Do not redo finished work. Do not re-ask answered questions. Do not restate the summary to the owner. |
+| 4 | Continue from "Next actions" in order, and pick up messages from agents that arrived during the compaction. |
+| 5 | If anything in the file is ambiguous, check the source (the PR, the log, the report) before deciding. Never fill a gap from memory. |
+
+## Harness hooks
+
+A harness may run steps of this procedure automatically (for example before and after a compaction). A hook is a
+convenience that calls the same steps; the procedure works without it, so run it by hand when no hook fires.