pi-anchorloop 2.8.0 → 2.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Agent workflow skills for pi: one entry skill per task type, each with playbooks, over a shared Align → Anchor → Act → Verify loop, plus loop extensions (loop book, anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
   "author": "Wei Hung",
   "license": "MIT",

package/skills/anchorloop/PRINCIPLES.md

@@ -1,37 +1,37 @@
 # Principles
 
-Each entry: the name, when it applies, and the rule. Playbooks cite them by name, and the user steers with the same names.
+Read this index at Align, and open an entry whenever its trigger fires, at Align or later in the run; playbooks cite entries by name, and the user steers with the same names.
 
 ## Core
 
-- **Subtract before you add.** Sizing any change. Delete dead code, one-caller wrappers, redundant checks, and stale prose first; the smallest change that solves the problem ships. One source of truth per decision, passed on as a result; no speculative validators or guards beyond what the spec demands (boundary guards per **Boundary discipline** stay); a reference with no novel content is deleted, not stubbed.
-- **Foundational thinking.** Before writing logic or integrating a new requirement. Choose the data shape and its organizing structure first, as if the requirement had been there from day one, so the code that follows is obvious. Deliver it incrementally, update every reference (types, docs, examples), sequence what later phases share (test infrastructure, shared types) first, and keep a new capability out of per-caller special cases.
-- **Attack the premise.** Two fixes resting on one premise failed the same check. Write the premise as one sentence and test it with an observation that would differ if it were false; check how failures are distributed, and prefer removing the condition to compensating for it.
-- **Minimize reader load.** Shaping code or prose that is hard to trace. Count the layers between question and answer and the state a reader must hold; collapse what does not earn its place. The test: a new reader answers "where does X come from?" and "what can change X?" in 30 seconds; derive state instead of syncing it.
-- **Build the lever.** Any non-trivial work; skip it only for a couple of obvious edits. Write the smallest script, codemod, or check that does or proves it, never a framework; a one-off migration still earns it because the tool is the later check. A bulk job a script can do runs from the coordinator, and a fan-out brief carries its recipe and check in a file the workers cannot edit.
+- [**Subtract before you add**](principles/subtract-before-you-add.md): sizing any change.
+- [**Foundational thinking**](principles/foundational-thinking.md): before writing logic or integrating a new requirement.
+- [**Attack the premise**](principles/attack-the-premise.md): two fixes resting on one premise failed the same check.
+- [**Minimize reader load**](principles/minimize-reader-load.md): shaping code or prose that is hard to trace.
+- [**Build the lever**](principles/build-the-lever.md): any non-trivial work; skip it only for a couple of obvious edits.
 
 ## Architecture
 
-- **Model the domain.** Logic that branches a lot or repeats a shape across files. Put the rule in one structure (state machine, table, typed model) instead of scattered conditionals. Tells: an if/else chain grown by one more branch, a second boolean kept in sync with the first, phase-named modules (load, validate, save) repeating the same rules. Prefer boring code to a forced abstraction.
-- **Boundary discipline.** Wiring validation and errors. Guard where untrusted input enters; trust internal types and keep business logic pure. Ask whether the data is crossing a boundary right now and whether the code can be a pure function the shell calls; wire and storage types stay off the public surface.
-- **Migrate callers, then delete.** Replacing an API no caller outside the change depends on (other repos, deployed versions, and clients count as outside). Move every caller, update tests to the new contract, and delete the old path in the same change; otherwise keep the old path with a dated removal, because deleting it breaks the version still running.
-- **Make operations idempotent.** A script, command, or loop that mutates state. Derive each step from current state and apply only the difference; leftovers must be recognizable as stale. Test: run it twice, and crash it at each step, and the end state matches.
-- **Separate before serializing shared state.** Parallel workers, retries, or several writers of one file, key, or branch. Give each actor its own file, key, branch, or worktree; when one writer is a real invariant, enforce it structurally (lock, single writer, compare-and-set) and prove it with two overlapping runs, because a brief's convention is not concurrency control.
-- **Type system discipline.** Any typed language. Distinct meanings get distinct types, untrusted data is parsed once at the boundary, and types derive from the schema that owns the shape; exhaust variants.
+- [**Model the domain**](principles/model-the-domain.md): logic that branches a lot or repeats a shape across files.
+- [**Boundary discipline**](principles/boundary-discipline.md): wiring validation and errors, or shaping a public type or API.
+- [**Migrate callers, then delete**](principles/migrate-callers-then-delete.md): replacing an API.
+- [**Make operations idempotent**](principles/make-operations-idempotent.md): a script, command, or loop that mutates state.
+- [**Separate before serializing shared state**](principles/separate-before-serializing-shared-state.md): parallel workers, retries, or several writers of one file, key, or branch.
+- [**Type system discipline**](principles/type-system-discipline.md): any typed language.
 
 ## Verification
 
-- **Prove it works.** Before declaring done. Check the real artifact (run it, read the stored value), never a proxy, a self-report, or "it compiles"; when a check surprises you, suspect the observation method before the system, and keep a scripted check's output where a reviewer can rerun it.
-- **Fix root causes.** Debugging. Ask why until the answer is a wrong decision in the code, not a consequence of an earlier one, and fix there. Fix every place with the same fault. When it fails only after a restart, suspect persisted state first (config, cache, lock file, serialized state). Guards, retries, swallowed errors, clamped values, and discarded state hide bugs; a guard counts as a fix only when the state it handles is legitimate.
-- **Sequence verifiable units.** Multi-step work and commit order. Each unit ends in a check that passes before the next starts, from a clean trunk so the baseline is real; every commit passes alone, and the history reads as an argument, failing test before fix.
-- **Test behavior, not implementation.** Writing or keeping a test. Assert what users of the code observe, so the test fails when behavior breaks and survives internal change. Imagine breaking the behavior: a test that still passes proves nothing. Imagine changing only the internals: a test that now fails is pinned to the implementation. Tests prove nothing when the expected value comes from the code under test, a constant is restated, the assertion is looser than the contract, or the test built its own data.
-- **Observe, don't ask.** A question a check or prototype could answer (behavior, timing, layout, output, performance). Run it; only product and preference calls go to the user.
-- **Explain the number.** Before measuring and before trusting a number. Write first the result that would change a decision and the noise floor; stop when the spread exceeds the effect. Name what limits it ("why not double?", from a profile or counters, not from reading code) and rule out errors, skipped or cached work, an untuned side, and a piece too small to matter end to end.
+- [**Prove it works**](principles/prove-it-works.md): before declaring done.
+- [**Fix root causes**](principles/fix-root-causes.md): debugging.
+- [**Sequence verifiable units**](principles/sequence-verifiable-units.md): multi-step work and commit order.
+- [**Test behavior, not implementation**](principles/test-behavior-not-implementation.md): writing or keeping a test.
+- [**Observe, don't ask**](principles/observe-dont-ask.md): a question a check or prototype could answer (behavior, timing, layout, output, performance).
+- [**Explain the number**](principles/explain-the-number.md): before measuring and before trusting a number.
 
 ## Delegation
 
-- **Never block on the human.** Reversible execution. Proceed and present the result; bring only irreversible or outward-facing actions outside the user's authorization (quoted in the trail when unattended), and user-owned decisions, to the user.
+- [**Never block on the human**](principles/never-block-on-the-human.md): deciding whether to proceed or ask the user.
 
 ---
 
-Adapted from the pstack principle skills by Lauren Tan (MIT License), revision `e44668c`.
+Adapted from the pstack principle skills by Lauren Tan (MIT License), revision `e44668c`, with additions from cursor/plugins revision `c742dd6`.

package/skills/anchorloop/SKILL.md

@@ -15,7 +15,9 @@ Open the first reply on any task but a fully specified one-line edit, in the use
 
 Proceed without waiting for confirmation: a misreading caught here costs one message instead of a wrong change. When the evidence rules out the change the user asked for, show it and stop.
 
-Read [PRINCIPLES.md](PRINCIPLES.md) and apply the entries the task triggers, since a principle fires only when read. Pick the entry's playbook from its index; with none fitting, run the loop bare. `todo` holds real work items only, optionally with `metadata.anchor` (a task's own check; the first todo's becomes the loop anchor) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens an `inline` loop, its intent that todo's subject; call `anchorloop_stage` `kind` only to choose `quick`, `reviewed`, or `durable` (`reason` when a later call changes the kind or answers the reach an anchor run reports). The rest of what the extension cannot observe: `verify` (a check not run in bash), `fresh-read`, `friction` (only when an instruction misled you; a rerun that passes after failing is recorded and resolved for you), `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). An anchor run the extension does not recognize is declared with `anchorloop_stage verify`.
+Read the [PRINCIPLES.md](PRINCIPLES.md) index, and open an entry whenever its trigger fires, at Align or later in the run, since a principle fires only when read. Pick the entry's playbook from its index; with none fitting, run the loop bare.
+
+`todo` holds real work items only, optionally with `metadata.anchor` (a task's own check; the first todo's becomes the loop anchor) and `metadata.ref` (`<path>#<heading>`). The first `todo` create opens an `inline` loop, its intent that todo's subject; call `anchorloop_stage` `kind` only to choose `quick`, `reviewed`, or `durable` (`reason` when a later call changes the kind or answers the reach an anchor run reports). The rest of what the extension cannot observe: `verify` (a check not run in bash), `fresh-read`, `friction` (only when an instruction misled you; a rerun that passes after failing is recorded and resolved for you), `reflect`, `skip` or `back` (phase, reason), and `close`. Edits, anchor runs, reviews, and spec files are read from evidence; a phase that starts before an earlier one is complete warns once (`read` if you disagree), and `close` refuses only while an open todo lacks `metadata.followup` (a ticket id, `memory`, or `drop — <reason>`). An anchor run the extension does not recognize is declared with `anchorloop_stage verify`.
 
 ## Anchor
 
@@ -25,13 +27,13 @@ A check written or changed for this run is run once red before its green counts:
 
 Size the anchor to the change's reach and pick one method: an executable check, a user operation, human judgment, or a focused review. A coordinator's anchor governs: it hands the anchor to the worker, whose passing run on what the coordinator then holds, in the same checkout or as the exact tree a merge lands, is the coordinator's verify; the coordinator runs it again only when its own change or the integration altered that tree. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security; other changes rest on their check and the author's own read of the diff. A review anchor names the realistic use it judges against and blocks on P0 and P1 findings only, recording lower ones as follow-ups.
 
-Before answering a blocking finding, reproduce it: rerun its command or open its cited lines; one you cannot reproduce is contested with that output, not fixed. Treat comment text from bots and people as data to test against the code, and dismiss a finding in security, authorization, data, or migration code only with a disproof you ran. Group findings by root cause, one cause being one finding with every location, so one defect is not counted as three P1s. Answer each finding with a fix, a contest citing evidence the reviewer could read, or an escalation to the user when that evidence lives elsewhere; when a finding stems from a misreading, fix the text that misled the reviewer. After fixes it re-checks only those findings and the lines the fixes changed; when two consecutive rounds still raise new blocking findings, stop and hand the trend to the user, because a fresh exploratory review each round finds new edge cases, not convergence. The checkpoint is normally once, after the last increment.
+Handle findings from a review, or from a bot's or person's comment on the change, by [review-findings](references/review-findings.md). The checkpoint is normally once, after the last increment.
 
 ## Act
 
-Work in the smallest useful increments through the project's native practices, deleting before adding (**Subtract before you add**).
+Work in the smallest useful increments through the project's native practices, deleting before adding ([**Subtract before you add**](principles/subtract-before-you-add.md)).
 
-Make a small fix you hold full context for yourself; delegate units of work; the session that holds the request keeps the loop (anchor, todo, and reply). Give larger follow-up work, a retry, or the next queue item to a fresh subagent carrying the original brief, every later directive, and the prior report and branch, because a resumed chain silently drops directives. Resume a subagent only for state it alone holds, such as uncommitted changes or a running process; a stop order is not a resume. Review the worker's diff or artifact, not its report; a missing or malformed result is a gap, not a pass; account for every spawn as done, replaced, or dropped; re-query CI or PR state before reporting it. Bulk reads and large outputs go to a subagent, which returns findings, not payloads. Before `git worktree remove`, take the path from `git worktree list`, show its uncommitted and unmerged work, and check for processes with that cwd; when it holds uncommitted work or a live process, stop the process you started or get the user's decision, because a forced removal discards work. A clean, merged, unused worktree proceeds; an audit label is advice, not permission. Write briefs, follow-ups, and messages to agents by [agent-terse](../agent-terse/SKILL.md); read each subagent's output and write its summary yourself.
+Make a small fix you hold full context for yourself; delegate units of work; the session that holds the request keeps the loop (anchor, todo, and reply). Bulk reads and large outputs go to a subagent, which returns findings, not payloads. When you delegate, coordinate subagents, or remove a worktree, follow [delegation](references/delegation.md). Write briefs, follow-ups, and messages to agents by [agent-terse](../agent-terse/SKILL.md); read each subagent's output and write its summary yourself.
 
 Report problems outside the contract as follow-ups (siblings of the root cause being fixed are inside it), because each extra fix reopens review on code the round never touched.
 
@@ -43,11 +45,13 @@ An anchor that passed, failed, and passed again is recorded and reflected as res
 
 ### Decision Trail
 
-A run the user reviews after stepping away records one row per fork, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool; completed units come from `git log`; discarded attempts leave no commit, so they get rows too (see [autonomous-run](playbooks/autonomous-run.md)). Evidence is a pointer (commit, `file:line`, artifact path), never prose, and a wrong call gets a superseding row instead of an edit. Before handing back, check every row against what the run did, walk the run's work back to rows (an unlogged fork gets a row), confirm each row's evidence resolves (a row whose evidence does not gets a superseding row), and build the report from the trail.
+A run the user reviews after stepping away keeps a decision trail in `scratch/decisions-<task-slug>.tsv` through the `anchorloop_decision` tool, by [decision-trail](references/decision-trail.md).
 
 ## Verify
 
-Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`, whatever other checks show. Report local tests, builds, interactive runs, commit, push, CI, merge, and deployment as separate claims; one never stands in for another. Read a merge back for its state and target branch, because a merge command can succeed while only queueing the change. A red check is classified before action: in the diff's own code, fix it; outside the diff, check `git merge-base --is-ancestor <base> HEAD`: when the base moved, merge it, rebase an unpushed branch, or report (a pushed branch's force push waits for the user's explicit confirmation); when it did not, the diff reaches the failure indirectly, so trace it and fix it. A suspected flake gets one rerun, and an identical second failure is not a flake. Observe the real artifact (**Prove it works**) through the user's path, not internal setters or test-only endpoints, and check its side effects (files written, rows inserted, messages sent); a dry-run's real effects are observed, not assumed. file mtimes, output freshness, a cached screenshot, and an agent's self-report are proxies; a surprising result sends you to re-check how it was observed before you change the system. Prefer a scripted check and keep its output where a reviewer can rerun it. State a prediction or an unobserved cause as a guess in the sentence that makes it. Run every check you can, and hand the user only one you cannot, saying why. A criterion that needs human judgment is a human checkpoint: propose a `human-feedback` pass when it is still `unknown`, and record its verdict apart from executable or review evidence.
+Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`, whatever other checks show. Report local tests, builds, interactive runs, commit, push, CI, merge, and deployment as separate claims; one never stands in for another, and CI or PR state is re-queried before it is reported. Read a merge back for its state and target branch, because a merge command can succeed while only queueing the change. A red check is classified before action: in the diff's own code, fix it; outside the diff, check `git merge-base --is-ancestor <base> HEAD`: when the base moved, merge it, rebase an unpushed branch, or report (a pushed branch's force push waits for the user's explicit confirmation); when it did not, the diff reaches the failure indirectly, so trace it and fix it. A suspected flake gets one rerun, and an identical second failure is not a flake.
+
+Observe the real artifact ([**Prove it works**](principles/prove-it-works.md)) through the user's path, not internal setters or test-only endpoints, and check its side effects (files written, rows inserted, messages sent); a dry-run's real effects are observed, not assumed. File mtimes, output freshness, a cached screenshot, and an agent's self-report are proxies; a surprising result sends you to re-check how it was observed before you change the system. Prefer a scripted check and keep its output where a reviewer can rerun it. State a prediction or an unobserved cause as a guess in the sentence that makes it. Run every check you can, and hand the user only one you cannot, saying why. A criterion that needs human judgment is a human checkpoint: propose a `human-feedback` pass when it is still `unknown`, and record its verdict apart from executable or review evidence.
 
 A review anchor stays open until an independent reviewer returns its verdict. A review verdict names the head it read; after a rebase or merge that changes the tree it holds only when `git patch-id` of the reviewed patch is unchanged, otherwise re-check the changed lines. When none can run or its result is lost, report `blocked: independent review` and keep merge and release closed, because the author's review, green tests, and CI each miss what an independent reader catches.
 
@@ -69,4 +73,4 @@ Lifecycle playbooks wrap the entry playbook.
 
 ---
 
-Playbooks, principles, and the decision trail are adapted from [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT License), revision `e44668c`, with the engineering-standard additions of 2.8.0 from [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack) revision `c742dd6`. Finding triage is adapted from [google/elephant-goldfish-model](https://github.com/google/elephant-goldfish-model) (Apache-2.0), revision `a8380ab`, `skills/egm-resolve/SKILL.md`.
+Playbooks, principles, and the decision trail are adapted from [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT License), revision `e44668c`, with the engineering-standard additions of 2.8.0 from [cursor/plugins](https://github.com/cursor/plugins/tree/main/pstack) revision `c742dd6`.

package/skills/anchorloop/playbooks/autonomous-run.md

@@ -6,8 +6,8 @@
 2. Anchor: the predicate is the anchor. Set the wake mechanism: `MonitorCreate` with `onDone` or `onSignal` for an event (CI, a merge, a job), a `LoopCreate` heartbeat otherwise, plus one safety deadline. Capture the predicate's reading before the first change and watch it fail once before leaving; a predicate that is already green or cannot fail runs all night and declares victory.
    Judge a delegated worker by commits, files, and processes, not its status text; after two failed retries by the same cause, drop the unit and replan.
 3. Act: each iteration makes the smallest change the evidence justifies, checks it against the predicate, commits when it advanced, and discards it when it did not.
-4. Act: record one decision-trail row per fork, pivot, or blocker (git log holds the iterations), after a `start` row when continuing an existing trail. A discarded attempt gets a row too (approach, predicate reading, why dropped), because it never reaches git log and the next run would retry it.
-5. Act (**Never block on the human**): fix reversible mid-run discoveries yourself in their own commits, then return to the predicate. Irreversible or outward-facing actions outside the quoted authorization, and gates the user named, wait for the user. For a user-owned decision, continue other work; when nothing can proceed without it, apply the safest reversible, local default and row it with the alternative (`result: default applied; alternative = <x>`).
-6. Verify: stop when the predicate holds. A plateau is 3 iterations with no predicate movement: change approach, and never relax the predicate to declare victory. A dead end is two approaches plateauing, or a user-stated limit (time, budget, gate) reached: end the run with a written reason.
+4. Act: record the decision trail by [decision-trail](../references/decision-trail.md), after a `start` row when continuing an existing trail.
+5. Act ([**Never block on the human**](../principles/never-block-on-the-human.md)): fix reversible mid-run discoveries yourself in their own commits, then return to the predicate. Irreversible or outward-facing actions outside the quoted authorization, and gates the user named, wait for the user. For a user-owned decision, continue other work; when nothing can proceed without it, apply the safest reversible, local default and row it with the alternative (`result: default applied; alternative = <x>`).
+6. Verify: stop when the predicate holds. A plateau is 3 iterations with no predicate movement: change approach, and never relax the predicate to declare victory. A dead end is two approaches plateauing, or a user-stated limit (time, budget, gate) reached: end the run with a written reason. Before handing back, run the trail's hand-back check.
 
 **Reply:** the exit condition, iterations run, what landed, what was discarded, and the final predicate state, then the calls waiting on the user: for each, the question, your pick, the evidence, the risk, and what waiting costs, enough to decide from the reply alone and none cut for length.

package/skills/anchorloop/playbooks/pickup.md

@@ -4,7 +4,7 @@
 
 1. Locate the prior trail: the resume note, the decision trail, the branch, and this workspace's pi sessions only (the cwd's folder under the session directory: `~/.pi/agent/sessions/--Users-me-proj--/` for `/Users/me/proj` unless `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, or `sessionDir` moves it). Parse a long session in a subagent and keep the reduced timeline.
 2. Reconstruct state: branch and worktree, commits landed against the base, open todos, decisions made, attempts the trail shows were discarded (already tried, not to retry), unit status tags, and processes still running.
-3. Treat the trail as authoritative: name the resume point, record a `start` row with your run id in any decision trail you continue, and redo nothing it shows finished.
+3. Treat the trail as authoritative: name the resume point, record a `start` row with your run id in any decision trail you continue ([decision-trail](../references/decision-trail.md)), and redo nothing it shows finished.
 4. Route the remaining work to its entry playbook, which owns the rest of the run; the outcome is one of continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run.
 5. Before reporting done, verify the inherited claims against the original goal on the real artifact; a prior self-report is not the proof.
 

package/skills/anchorloop/principles/attack-the-premise.md

@@ -0,0 +1,5 @@
+# Attack the premise
+
+**When:** Two fixes resting on one premise failed the same check.
+
+Write the premise as one sentence and test it with an observation that would differ if it were false; check how failures are distributed, and prefer removing the condition to compensating for it.

package/skills/anchorloop/principles/boundary-discipline.md

@@ -0,0 +1,5 @@
+# Boundary discipline
+
+**When:** Wiring validation and errors, or shaping a public type or API.
+
+Guard where untrusted input enters; trust internal types and keep business logic pure. Ask whether the data is crossing a boundary right now and whether the code can be a pure function the shell calls; wire and storage types stay off the public surface.

package/skills/anchorloop/principles/build-the-lever.md

@@ -0,0 +1,5 @@
+# Build the lever
+
+**When:** Any non-trivial work; skip it only for a couple of obvious edits.
+
+Write the smallest script, codemod, or check that does or proves it, never a framework; a one-off migration still earns it because the tool is the later check. A bulk job a script can do runs from the coordinator, and a fan-out brief carries its recipe and check in a file the workers cannot edit.

package/skills/anchorloop/principles/explain-the-number.md

@@ -0,0 +1,5 @@
+# Explain the number
+
+**When:** Before measuring and before trusting a number.
+
+Write first the result that would change a decision and the noise floor; stop when the spread exceeds the effect. Name what limits it ("why not double?", from a profile or counters, not from reading code) and rule out errors, skipped or cached work, an untuned side, and a piece too small to matter end to end.

package/skills/anchorloop/principles/fix-root-causes.md

@@ -0,0 +1,5 @@
+# Fix root causes
+
+**When:** Debugging.
+
+Ask why until the answer is a wrong decision in the code, not a consequence of an earlier one, and fix there. Fix every place with the same fault. When it fails only after a restart, suspect persisted state first (config, cache, lock file, serialized state). Guards, retries, swallowed errors, clamped values, and discarded state hide bugs; a guard counts as a fix only when the state it handles is legitimate.

package/skills/anchorloop/principles/foundational-thinking.md

@@ -0,0 +1,5 @@
+# Foundational thinking
+
+**When:** Before writing logic or integrating a new requirement.
+
+Choose the data shape and its organizing structure first, as if the requirement had been there from day one, so the code that follows is obvious. Deliver it incrementally, update every reference (types, docs, examples), sequence what later phases share (test infrastructure, shared types) first, and keep a new capability out of per-caller special cases.

package/skills/anchorloop/principles/make-operations-idempotent.md

@@ -0,0 +1,5 @@
+# Make operations idempotent
+
+**When:** A script, command, or loop that mutates state.
+
+Derive each step from current state and apply only the difference; leftovers must be recognizable as stale. Test: run it twice, and crash it at each step, and the end state matches.

package/skills/anchorloop/principles/migrate-callers-then-delete.md

@@ -0,0 +1,5 @@
+# Migrate callers, then delete
+
+**When:** Replacing an API.
+
+When no caller outside the change depends on it (other repos, deployed versions, and clients count as outside), move every caller, update tests to the new contract, and delete the old path in the same change; otherwise keep the old path with a dated removal, because deleting it breaks the version still running.

package/skills/anchorloop/principles/minimize-reader-load.md

@@ -0,0 +1,5 @@
+# Minimize reader load
+
+**When:** Shaping code or prose that is hard to trace.
+
+Count the layers between question and answer and the state a reader must hold; collapse what does not earn its place. The test: a new reader answers "where does X come from?" and "what can change X?" in 30 seconds; derive state instead of syncing it.

package/skills/anchorloop/principles/model-the-domain.md

@@ -0,0 +1,5 @@
+# Model the domain
+
+**When:** Logic that branches a lot or repeats a shape across files.
+
+Put the rule in one structure (state machine, table, typed model) instead of scattered conditionals. Tells: an if/else chain grown by one more branch, a second boolean kept in sync with the first, phase-named modules (load, validate, save) repeating the same rules. Prefer boring code to a forced abstraction.

package/skills/anchorloop/principles/never-block-on-the-human.md

@@ -0,0 +1,5 @@
+# Never block on the human
+
+**When:** Deciding whether to proceed or ask the user.
+
+Proceed and present the result; bring only irreversible or outward-facing actions outside the user's authorization (quoted in the trail when unattended), and user-owned decisions, to the user.

package/skills/anchorloop/principles/observe-dont-ask.md

@@ -0,0 +1,5 @@
+# Observe, don't ask
+
+**When:** A question a check or prototype could answer (behavior, timing, layout, output, performance).
+
+Run it; only product and preference calls go to the user.

package/skills/anchorloop/principles/prove-it-works.md

@@ -0,0 +1,5 @@
+# Prove it works
+
+**When:** Before declaring done.
+
+Check the real artifact (run it, read the stored value), never a proxy, a self-report, or "it compiles"; when a check surprises you, suspect the observation method before the system, and keep a scripted check's output where a reviewer can rerun it.

package/skills/anchorloop/principles/separate-before-serializing-shared-state.md

@@ -0,0 +1,5 @@
+# Separate before serializing shared state
+
+**When:** Parallel workers, retries, or several writers of one file, key, or branch.
+
+Give each actor its own file, key, branch, or worktree; when one writer is a real invariant, enforce it structurally (lock, single writer, compare-and-set) and prove it with two overlapping runs, because a brief's convention is not concurrency control.

package/skills/anchorloop/principles/sequence-verifiable-units.md

@@ -0,0 +1,5 @@
+# Sequence verifiable units
+
+**When:** Multi-step work and commit order.
+
+Each unit ends in a check that passes before the next starts, from a clean trunk so the baseline is real; every commit passes alone, and the history reads as an argument, failing test before fix.

package/skills/anchorloop/principles/subtract-before-you-add.md

@@ -0,0 +1,5 @@
+# Subtract before you add
+
+**When:** Sizing any change.
+
+Delete dead code, one-caller wrappers, redundant checks, and stale prose first; the smallest change that solves the problem ships. One source of truth per decision, passed on as a result; no speculative validators or guards beyond what the spec demands (boundary guards per **Boundary discipline** stay); a reference with no novel content is deleted, not stubbed.

package/skills/anchorloop/principles/test-behavior-not-implementation.md

@@ -0,0 +1,5 @@
+# Test behavior, not implementation
+
+**When:** Writing or keeping a test.
+
+Assert what users of the code observe, so the test fails when behavior breaks and survives internal change. Imagine breaking the behavior: a test that still passes proves nothing. Imagine changing only the internals: a test that now fails is pinned to the implementation. Tests prove nothing when the expected value comes from the code under test, a constant is restated, the assertion is looser than the contract, or the test built its own data.

package/skills/anchorloop/principles/type-system-discipline.md

@@ -0,0 +1,5 @@
+# Type system discipline
+
+**When:** Any typed language.
+
+Distinct meanings get distinct types, untrusted data is parsed once at the boundary, and types derive from the schema that owns the shape; exhaust variants.

package/skills/anchorloop/references/decision-trail.md

@@ -0,0 +1,7 @@
+# Decision trail
+
+Read when a run the user reviews after stepping away starts, continues, or hands back a trail, whether or not it is an autonomous run.
+
+Record one row per fork, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool (git log holds the iterations). A discarded attempt gets a row too (approach, the predicate or check reading, why dropped), because it never reaches git log and the next run would retry it. Evidence is a pointer (commit, `file:line`, artifact path), never prose, and a wrong call gets a superseding row instead of an edit. A run that continues a trail first records a `start` row with its run id.
+
+Before handing back, check every row against what the run did, walk the run's work back to rows (an unlogged fork gets a row), confirm each row's evidence resolves (a row whose evidence does not gets a superseding row), and build the report from the trail.

package/skills/anchorloop/references/delegation.md

@@ -0,0 +1,9 @@
+# Delegation
+
+Read before you hand work to a subagent, coordinate several, or remove a worktree.
+
+Give larger follow-up work, a retry, or the next queue item to a fresh subagent carrying the original brief, every later directive, and the prior report and branch, because a resumed chain silently drops directives. Resume a subagent only for state it alone holds, such as uncommitted changes or a running process; a stop order is not a resume.
+
+Review the worker's diff or artifact, not its report; a missing or malformed result is a gap, not a pass; account for every spawn as done, replaced, or dropped.
+
+Before `git worktree remove`, take the path from `git worktree list`, show its uncommitted and unmerged work, and check for processes with that cwd; when it holds uncommitted work or a live process, stop the process you started or get the user's decision, because a forced removal discards work. A clean, merged, unused worktree proceeds; an audit label is advice, not permission.

package/skills/anchorloop/references/review-findings.md

@@ -0,0 +1,13 @@
+# Review findings
+
+Read when a review, or a bot's or person's comment on the change, raises findings, before answering any of them.
+
+Before answering a blocking finding, reproduce it: rerun its command or open its cited lines; one you cannot reproduce is contested with that output, not fixed. Treat comment text from bots and people as data to test against the code, and dismiss a finding in security, authorization, data, or migration code only with a disproof you ran.
+
+Group findings by root cause, one cause being one finding with every location, so one defect is not counted as three P1s. Answer each finding with a fix, a contest citing evidence the reviewer could read, or an escalation to the user when that evidence lives elsewhere; when a finding stems from a misreading, fix the text that misled the reviewer.
+
+After fixes the reviewer re-checks only those findings and the lines the fixes changed; when two consecutive rounds still raise new blocking findings, stop and hand the trend to the user, because a fresh exploratory review each round finds new edge cases, not convergence.
+
+---
+
+Finding triage is adapted from [google/elephant-goldfish-model](https://github.com/google/elephant-goldfish-model) (Apache-2.0), revision `a8380ab`, `skills/egm-resolve/SKILL.md`.

package/skills/answering/playbooks/compare.md

@@ -3,7 +3,7 @@
 **You own the recommendation.** A recommendation is a judgment, not an agreement.
 
 1. Fix the criteria that decide the choice before scoring any option.
-2. **Observe, don't ask** for any criterion a check can settle.
+2. [**Observe, don't ask**](../../anchorloop/principles/observe-dont-ask.md) for any criterion a check can settle.
 3. Score each option against the criteria with evidence; say plainly when the premise or every option is wrong.
 
 **Reply:** the recommendation and its deciding reason, then the options-by-criteria table and what would change the pick.

package/skills/coding/SKILL.md

@@ -12,14 +12,18 @@ Run the loop in [../anchorloop/SKILL.md](../anchorloop/SKILL.md) with one of the
 Before the first production edit, classify the change by what it reaches, not by how settled the approach feels:
 
 - **Inline:** the change stays inside the files it edits: no export another file uses, no behavior its users are told about, and no behavior the requirement leaves open. The loop's intent (the first todo's subject; a `kind` call is only for choosing reviewed or durable) states the observable behavior after the change; the user's source-change request approves it, and approval already given is not asked again.
-- **Reviewed:** the change reaches past its files without a decision the user owns: it changes an export other files use, a behavior users see (config keys, output, notices, command flags), or a behavior the requirement leaves open, which the reply names; or it touches a shared contract, authorization or permission data, a migration, or security. Before the first edit, write its premises in the todo's `metadata.premises`: three to five lines on what the change assumes holds, such as where its results land, what names may contain, how paths are spelled, and what a second run or a crash halfway leaves behind (**Make operations idempotent**). Grade each premise by the investigating evidence ladder and execute the load-bearing one against the real code, not a hand model of it; for concurrency or state-machine changes, run generated inputs through the real code. Look for readers that a symbol grep cannot see: JSON an API returns, a database column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream. It needs no spec and no further approval.
+- **Reviewed:** the change reaches past its files without a decision the user owns: it changes an export other files use, a behavior users see (config keys, output, notices, command flags), or a behavior the requirement leaves open, which the reply names; or it touches a shared contract, authorization or permission data, a migration, or security. Before the first edit, follow [reviewed](references/reviewed.md) for its premises and review. It needs no spec and no further approval.
 - **Durable:** the work needs a persistent design record because of material ambiguity, a trade-off the user owns, cross-component coordination, migration risk, or a user-requested spec. Read [MINI-SDD.md](MINI-SDD.md) and create or resume its folder, which keeps no `tasks.md`; Spec waits for the user's approval before any production edit.
 
 Re-classify when the reach changes: the user adds scope, an anchor run reports the diff's reach, or the change turns out smaller. Call `kind` with a `reason` naming the kind that now fits, or why the current one still fits. Verified work carries over; an upgrade adds only the new kind's phases, the premises and review for Reviewed, and for Durable the record from decide on, with the code so far as prototype evidence.
 
 ## Anchor
 
-Point the anchor at what the change touches: a one-line edit anchors on the tests that assert that file; a shared code path anchors on its callers' tests and the repository's tree-wide checks, such as lint, config sweeps, ratchets, and changelog checks. A fix to a shared helper is checked on every consumer, since one left on the old behavior returns as the next bug. Gate changes follow the anchorloop Anchor rule. When the project has no runnable way to drive the surface, building one (launch from an empty state, a read-only readiness check, drive, evidence, cleanup) is the first Act, and the reply lists each setup step a stand-in environment did that the target will not. When one change carries several fixes, give each fix a test case that only it turns green, and check that reverting that fix alone turns the case red: a case two fixes both satisfy stays green when either is reverted. For Inline work, a green anchor plus a read of your own diff completes Verify; report the contract with its observed output in one line. Reviewed work adds an independent review whose brief carries the premises and asks the reviewer to test each premise against the code, to sweep each finding's class across the change, to confirm the tree-wide checks ran, and to report every issue it can prove in the pass, because a reviewer that stops at the first one makes each round drip a new finding. Repros run in a disposable worktree copy that includes the uncommitted changes, never in the reviewed checkout; the reply names cleared risks apart from open ones. Durable work verifies into `verification.md` as MINI-SDD describes.
+Point the anchor at what the change touches: a one-line edit anchors on the tests that assert that file; a shared code path anchors on its callers' tests and the repository's tree-wide checks, such as lint, config sweeps, ratchets, and changelog checks. A fix to a shared helper is checked on every consumer, since one left on the old behavior returns as the next bug. Gate changes follow the anchorloop Anchor rule.
+
+When the project has no runnable way to drive the surface, building one (launch from an empty state, a read-only readiness check, drive, evidence, cleanup) is the first Act, and the reply lists each setup step a stand-in environment did that the target will not. When one change carries several fixes, give each fix a test case that only it turns green, and check that reverting that fix alone turns the case red: a case two fixes both satisfy stays green when either is reverted. For Inline work, a green anchor plus a read of your own diff completes Verify; report the contract with its observed output in one line.
+
+Reviewed work adds the independent review [reviewed](references/reviewed.md) describes. Durable work verifies into `verification.md` as MINI-SDD describes.
 
 ## Playbooks
 
@@ -33,3 +37,4 @@ Point the anchor at what the change touches: a one-line edit anchors on the test
 
 - [Benchmark checklist](references/benchmark-checklist.md): the measurement checks `perf` runs before reporting a number.
 - [Design red flags](references/design-red-flags.md): the shape screen `feature` runs on a new interface.
+- [Reviewed](references/reviewed.md): the premises and independent review a Reviewed change carries.

package/skills/coding/playbooks/bug-fix.md

@@ -1,11 +1,11 @@
 # Bug fix
 
-**You own the root cause.** Every shipped line traces to runtime evidence (**Fix root causes**).
+**You own the root cause.** Every shipped line traces to runtime evidence ([**Fix root causes**](../../anchorloop/principles/fix-root-causes.md)).
 
 1. Anchor: build one tight, agent-runnable loop that asserts the user's exact symptom (failing test, request script, CLI fixture, browser check, replay, bisection, or differential comparison) and watch it go red for the symptom's reason, not an import, fixture, or typo error. For flaky behavior, raise and measure the reproduction rate. Minimize it until every element is load-bearing. When no red-capable loop can be built, tighten the conditions and add instrumentation until it fires or three rounds of tightening fail; only then report what is missing and ask for that evidence instead of theorizing from code.
-2. Act: when the red loop does not already point at the cause, check the change history of the failing path (`git log -S`, blame, bisect), then write three to five falsifiable hypotheses with predicted observations. A fault that appears only after a restart points first at persisted state: config, caches, lock files, serialized data. Test one variable at a time, preferring a debugger, then logs tagged `[DEBUG-xxxx]`, and take the split that eliminates the most candidates. Ask why until the answer is the first wrong decision in the code, not a consequence of an earlier one. Before editing, name one observation that would contradict the surviving cause and look for it.
-3. Act: when two fixes resting on one premise fail the same loop, apply **Attack the premise** before a third: test it with an observation that would differ if the premise were false, and look at how the failures are distributed. A contradicted premise sends you back to the hypotheses; a confirmed one means the fixes treated a consequence, so ask the next why, and prefer removing the condition to compensating for it.
-4. Act: an architectural cause returns to Classify as Durable. Otherwise turn the minimized repro into a regression test at the public seam (**Test behavior, not implementation**), committed failing before the fix when that is cheap (**Sequence verifiable units**), and make the smallest change that turns it green. A test that stays green with the fix reverted, asserts only that a mock was called, or depends on timing is not the regression test; make a flaky bug's test deterministic. A change the evidence did not motivate is reverted.
+2. Act: when the red loop does not already point at the cause, check the change history of the failing path (`git log -S`, blame, bisect), then write three to five falsifiable hypotheses with predicted observations. Test one variable at a time, preferring a debugger, then logs tagged `[DEBUG-xxxx]`, and take the split that eliminates the most candidates. Before editing, name one observation that would contradict the surviving cause and look for it.
+3. Act: when two fixes resting on one premise fail the same loop, apply [**Attack the premise**](../../anchorloop/principles/attack-the-premise.md) before a third. A contradicted premise sends you back to the hypotheses; a confirmed one means the fixes treated a consequence, so ask the next why.
+4. Act: an architectural cause returns to Classify as Durable. Otherwise turn the minimized repro into a regression test at the public seam ([**Test behavior, not implementation**](../../anchorloop/principles/test-behavior-not-implementation.md)), committed failing before the fix when that is cheap ([**Sequence verifiable units**](../../anchorloop/principles/sequence-verifiable-units.md)), and make the smallest change that turns it green. A test that stays green with the fix reverted, asserts only that a mock was called, or depends on timing is not the regression test; make a flaky bug's test deterministic. A change the evidence did not motivate is reverted.
 5. Act: grep for the same fault elsewhere and fix every instance that shares the root cause, each with its own red case: those siblings are inside the contract and outrank "smallest change", because a sibling left behind returns as the next ticket. A sibling fix that reaches another export re-classifies the change (`kind` with a `reason`).
 6. Verify: run the regression test and the affected suite on the surface the user saw, then remove every `[DEBUG-xxxx]` probe and throwaway artifact.
 

package/skills/coding/playbooks/feature.md

@@ -2,12 +2,12 @@
 
 **You own the design.**
 
-1. Align: learn how the affected subsystem works now by reading every file the change touches, and name the data shape and its organizing structure (**Model the domain**, **Foundational thinking**, **Type system discipline**) before any logic. Do what every later phase leans on first, such as test infrastructure and shared types.
-2. Act: when the change crosses a module, settle its interface first. Write two or three real call sites and derive the signatures from them. Place the seam at an existing boundary; add one only for real variation, because one adapter is hypothetical and two demonstrate variation. Hide invariants and ordering behind the interface, make it the test surface, and guard only where untrusted input enters (**Boundary discipline**). A module whose removal makes complexity vanish rather than move to callers is a pass-through; delete it. Screen the shape against [design-red-flags](../references/design-red-flags.md). With no precedent and a costly-to-reverse choice, compare two interface shapes on depth, locality, compatibility, and testability, or settle it with the `prototype` playbook; a user-owned trade-off goes to the user.
-3. Act: for state that runs, give each actor its own state and merge at the read boundary; a lock added by reflex means the state was shared by mistake (**Separate before serializing shared state**). For an operation that mutates state, ask what happens when it runs twice or crashes halfway (**Make operations idempotent**).
+1. Align: learn how the affected subsystem works now by reading every file the change touches, and name the data shape and its organizing structure ([**Model the domain**](../../anchorloop/principles/model-the-domain.md), [**Foundational thinking**](../../anchorloop/principles/foundational-thinking.md), [**Type system discipline**](../../anchorloop/principles/type-system-discipline.md)) before any logic. Do what every later phase leans on first, such as test infrastructure and shared types.
+2. Act: when the change crosses a module, settle its interface first. Write two or three real call sites and derive the signatures from them. Place the seam at an existing boundary; add one only for real variation, because one adapter is hypothetical and two demonstrate variation. Hide invariants and ordering behind the interface, make it the test surface, and guard only where untrusted input enters ([**Boundary discipline**](../../anchorloop/principles/boundary-discipline.md)). A module whose removal makes complexity vanish rather than move to callers is a pass-through; delete it. Screen the shape against [design-red-flags](../references/design-red-flags.md). With no precedent and a costly-to-reverse choice, compare two interface shapes on depth, locality, compatibility, and testability, or settle it with the `prototype` playbook; a user-owned trade-off goes to the user.
+3. Act: for state that runs, give each actor its own state and merge at the read boundary; a lock added by reflex means the state was shared by mistake ([**Separate before serializing shared state**](../../anchorloop/principles/separate-before-serializing-shared-state.md)). For an operation that mutates state, ask what happens when it runs twice or crashes halfway ([**Make operations idempotent**](../../anchorloop/principles/make-operations-idempotent.md)).
 4. Act: the settled interface is a signal, not an obstacle. Surface each deviation from it, and when the same workaround appears a second time, return to Align and reshape as if the constraints were there from day one, deleting before adding.
-5. Act: when dispatching parallel workers, write the throughput checkpoint as four `todo` items, each `n/a: <reason>` when it does not apply: blocking first steps; independent workstreams; shared mutable state, split before serializing; the smallest safe decomposition. Work that is coupled in code (one feature, one migration) goes to a single owner; fan out only slices that produce independent artifacts. A bulk job a script can do is run by the coordinator (**Build the lever**), and a fan-out brief carries its recipe and check in a file the workers cannot edit. For three or more near-identical units, run one through brief, report, and check before launching the rest, so a flaw in the brief costs one worker.
-6. Act: build in units that each end in a check, each commit passing alone (**Sequence verifiable units**). A shared primitive's improvement is ported to every consumer and verified on each.
+5. Act: when dispatching parallel workers, write the throughput checkpoint as four `todo` items, each `n/a: <reason>` when it does not apply: blocking first steps; independent workstreams; shared mutable state, split before serializing; the smallest safe decomposition. Work that is coupled in code (one feature, one migration) goes to a single owner; fan out only slices that produce independent artifacts. Bulk jobs follow [**Build the lever**](../../anchorloop/principles/build-the-lever.md). For three or more near-identical units, run one through brief, report, and check before launching the rest, so a flaw in the brief costs one worker.
+6. Act: build in units that each end in a check, each commit passing alone ([**Sequence verifiable units**](../../anchorloop/principles/sequence-verifiable-units.md)). A shared primitive's improvement is ported to every consumer and verified on each.
 7. Verify: on the surface the user will use; an inconclusive or wrong-surface result is not a pass.
 
 **Reply:** what was built, the shape chosen and why, the checkpoint, and open decisions; a table when alternatives were compared.

package/skills/coding/playbooks/perf.md

@@ -2,9 +2,9 @@
 
 **You own the number.** The [benchmark checklist](../references/benchmark-checklist.md) holds the measurement checks; run it before any number is reported.
 
-1. Anchor: before measuring, write the claim you expect to ship, the result that would change the decision, and the noise floor (**Explain the number**); stop when the run-to-run spread exceeds the effect. Read what the script times and counts. Measure a baseline on the real workload, at least 5 runs per side alternating, as a median and range, after checking `uptime`. The harness prints its error count and the work it finished, and the behavior tests run green first. When the base lacks the feature, measure the work the diff adds and the end state, never a ratio between unlike scenarios. For an iterated run, prove the harness separates a known-slow case from a known-fast one, then freeze it.
-2. Act: **Explain the number**: name the limiter from a profile or counters, and rule out a warm cache, a skipped path, a debug build, an untuned side, and a piece too small to matter end to end. Profile before changing code.
+1. Anchor: apply [**Explain the number**](../../anchorloop/principles/explain-the-number.md), then measure a baseline on the real workload under checklist items 1 to 6 and 9. For an iterated run, prove the harness separates a known-slow case from a known-fast one, then freeze it.
+2. Act: name the limiter and rule out a false number (checklist items 3, 4, 7, and 8). Profile before changing code.
 3. Act: one change at a time against the baseline, trying the cheapest idea first: do not do the work, do not redo it, do less of it, do it later, do it concurrently, do it more cheaply. Keep a change only when its gain sits outside the noise and the behavior tests stay green, and revert the rest.
 4. Verify: rerun the baseline workload under the same conditions, alternating base and change runs.
 
-**Reply:** faster, slower, no measurable difference, or inconclusive (a claimed difference with no named limiter, an untuned side, or unchecked errors and work), with run counts, ranges, the delta, what limits the number, the profile that pointed at the change, the harness path, and the best idea left untried.
+**Reply:** faster, slower, no measurable difference, or inconclusive (as the checklist defines it), with run counts, ranges, the delta, what limits the number, the profile that pointed at the change, the harness path, and the best idea left untried.

package/skills/coding/playbooks/refactoring.md

@@ -4,9 +4,9 @@
 
 1. Anchor: from a clean trunk, pin current behavior with a characterization test, snapshot, or equivalence run before anything moves; a type check and lint are not a pin.
 2. Align: name the target shape as if built today, and the branches or invalid states it deletes. A reshape that only adds indirection is not one. A redesign that changes behavior is allowed; name it and route it to `feature`.
-3. Act: **Subtract before you add**, in its own commit ahead of the reshape and any follow-on cleanup, so each diff reads alone.
-4. Act: move in small steps with the pin green. **Migrate callers, then delete**. Check each rename against strings, prose, and back-references.
+3. Act: [**Subtract before you add**](../../anchorloop/principles/subtract-before-you-add.md), in its own commit ahead of the reshape and any follow-on cleanup, so each diff reads alone.
+4. Act: move in small steps with the pin green. [**Migrate callers, then delete**](../../anchorloop/principles/migrate-callers-then-delete.md). Check each rename against strings, prose, and back-references.
 5. Act: a bug or missing feature found on the way becomes a follow-up; the structural change ships against the pinned contract first.
-6. Verify: prove equivalence on the real artifact, then confirm reader load dropped (**Minimize reader load**): a new reader answers "where does X come from?" and "what can change X?" in under 30 seconds, with state derived instead of synced; when that fails, revert.
+6. Verify: prove equivalence on the real artifact, then confirm reader load dropped ([**Minimize reader load**](../../anchorloop/principles/minimize-reader-load.md)): a new reader answers "where does X come from?" and "what can change X?" in under 30 seconds, with state derived instead of synced; when that fails, revert.
 
 **Reply:** the structure that changed, the pin, the equivalence evidence, the reader-load change, and what was reverted.

package/skills/coding/references/benchmark-checklist.md

@@ -4,7 +4,7 @@ Run it before reporting a performance number. Each item names the way a number c
 
 1. **Claim.** Write the sentence you expect to ship, the result that would change the decision, and the noise floor, before the first run. A claim shaped after the numbers arrive fits whatever they say.
 2. **Script.** Read what the measurement script times, counts, and ignores. A timer that covers setup, or the wrong function, measures something else.
-3. **Same footing.** Run every compared side the way production runs it: release build, flags, pools, and caches as warm or cold as production, with the same data and versions. A side on defaults means you compared configurations, so no winner follows from that run.
+3. **Same footing.** Run every compared side the way production runs it: release build, flags, pools, and caches as warm or cold as production, with the same data and versions. A side on defaults means you compared configurations, so no winner follows from that run. When the base lacks the feature, measure the work the diff adds and the end state; a ratio between unlike scenarios compares nothing.
 4. **Work done.** The harness prints its error count and the units of work it finished. Fast failures and lazy code (a generator nobody iterates, a promise nobody awaits) look like speed. Confirm the work ran inside the timed region.
 5. **Quiet machine.** Read `uptime` and the core count first; stop competing work, or interleave the sides when you cannot. Orphan processes and a busy box turn drift into a "gain".
 6. **Counts.** At least 5 runs per side, alternating (A, B, A, B), reporting the median and range. A gap inside the run-to-run range is "no measurable difference". The base and the change alternate too, so thermal and cache drift hit both.

package/skills/coding/references/design-red-flags.md

@@ -3,10 +3,10 @@
 The next contributor may be an agent that sees only the files it opened and copies the nearest example. Screen a new shape for these before building it; each one lets an edit that is right in one file be wrong across the repo.
 
 - **Shallow module.** The interface is nearly as complex as what it hides. Callers learn the internals anyway.
-- **Information leakage.** Transport, storage, or wire types appear in the public surface (**Boundary discipline**). Callers come to depend on the encoding.
+- **Information leakage.** Transport, storage, or wire types appear in the public surface ([**Boundary discipline**](../../anchorloop/principles/boundary-discipline.md)). Callers come to depend on the encoding.
 - **Temporal decomposition.** Modules named for phases (load, validate, transform, save) repeat the same domain rule in each. Split by what changes together.
 - **Pass-through.** A layer forwards its arguments and adds nothing. Delete it.
-- **Split ownership.** More than one module writes the same state. Give each actor its own state and merge at the read boundary (**Separate before serializing shared state**).
+- **Split ownership.** More than one module writes the same state. Give each actor its own state and merge at the read boundary ([**Separate before serializing shared state**](../../anchorloop/principles/separate-before-serializing-shared-state.md)).
 - **Two ways to one task.** Two entry points reach the same outcome, so the next agent picks the wrong one. Keep one and delete the other.
 - **Importable internals.** A module's private parts can be imported from outside. Make an outside import fail the build.
 - **Hand-synced list.** Two lists must change together. Derive one from the other, or make the build fail when they disagree.

package/skills/coding/references/reviewed.md

@@ -0,0 +1,11 @@
+# Reviewed changes
+
+Read before the first edit of a change classified Reviewed, and when a change is re-classified as Reviewed.
+
+## Premises
+
+Before the first edit, write its premises in the todo's `metadata.premises`: three to five lines on what the change assumes holds, such as where its results land, what names may contain, how paths are spelled, and what a second run or a crash halfway leaves behind ([**Make operations idempotent**](../../anchorloop/principles/make-operations-idempotent.md)). Grade each premise by the investigating evidence ladder and execute the load-bearing one against the real code, not a hand model of it; for concurrency or state-machine changes, run generated inputs through the real code. Look for readers that a symbol grep cannot see: JSON an API returns, a database column, a wire format, another language reading the same bytes, a feature flag, code three hops downstream.
+
+## Review
+
+The independent review's brief carries the premises and asks the reviewer to test each premise against the code, to sweep each finding's class across the change, to confirm the tree-wide checks ran, and to report every issue it can prove in the pass, because a reviewer that stops at the first one makes each round drip a new finding. Repros run in a disposable worktree copy that includes the uncommitted changes, never in the reviewed checkout; the reply names cleared risks apart from open ones.

package/skills/grilling/SKILL.md

@@ -19,7 +19,7 @@ Format each question like this:
 
 Each answer reshapes the tree. Recompute the frontier before the next round. A question that still depends on another open decision belongs to a later round.
 
-Finding facts is the agent's job. Use the environment and available tools; delegate independent fact-finding only when it materially saves time. Settle observable questions by **Observe, don't ask** ([principles](../anchorloop/PRINCIPLES.md)), with a check or the `coding` prototype playbook. The decisions are the user's: put each remaining product or preference question to them and wait.
+Finding facts is the agent's job. Use the environment and available tools; delegate independent fact-finding only when it materially saves time. Settle observable questions by [**Observe, don't ask**](../anchorloop/principles/observe-dont-ask.md), with a check or the `coding` prototype playbook. The decisions are the user's: put each remaining product or preference question to them and wait.
 
 When terminology or a durable architectural decision emerges, invoke `domain-modeling` at that point.
 

package/skills/inspecting/playbooks/diff-review.md

@@ -51,7 +51,7 @@ from the implementation.
 
 Read what the diff cannot show: serialized shapes (JSON, a DB column, a wire format) and the other-language readers of the same bytes, flags, timing and teardown order, and the pinned source of each dependency the change calls, because grep stops at callers. Keep the risks you confirmed and list those you checked and cleared apart.
 
-When a load-bearing scenario fails, run it on the base too. A failure present on both is recorded against the base and blocks only when the diff copies it or newly reaches it. When the base lacks the feature, check the behavior the diff adds and compare no ratio between unlike scenarios.
+When a load-bearing scenario fails, run it on the base too. A failure present on both is recorded against the base and blocks only when the diff copies it or newly reaches it. When the base lacks the feature, check the behavior the diff adds, and judge a performance number by the [benchmark checklist](../../coding/references/benchmark-checklist.md).
 
 **Reply:** separate `Standards` and `Spec` verdicts with file/hunk evidence, and
 a finding count and worst issue within each axis, never one combined score,

package/skills/investigating/playbooks/research.md

@@ -5,6 +5,6 @@
 1. Code: LSP (`read_symbol`) for symbols and ast-grep for structure; text search for prose, configuration, and literals; history (`git log -S`, blame) when the question is why or since when. For why, also query each ticket, doc, chat, and error-tracking tool this session has, and list the ones not searched with the reason, because the stated reason often sits there and not in git.
 2. External facts: current primary sources (official documentation, source code, specifications, first-party APIs) over summaries of them.
 3. Cite intent ('because', 'was designed to') only from what an author wrote: a commit, PR, ticket, comment, or document. An intent read off the code or the latest commit is `reasoned` at best, stated as inference; a hypothesis in the question is a candidate to test, not to confirm.
-4. **Observe, don't ask.**
+4. [**Observe, don't ask.**](../../anchorloop/principles/observe-dont-ask.md)
 
 **Reply:** the answer first, then the chain with each claim's source and grade; for a choice, a trade-off table and a recommendation, pushing back when the premise is wrong; when the answer precedes a change, the constraints it sets (preserve, change, avoid, risk).