pi-anchorloop 2.0.2 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-anchorloop",
-  "version": "2.0.2",
+  "version": "2.1.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 (anchor gate, decision trail tool, Jev second thought, skill validator, stream rules).",
   "author": "Wei Hung",
   "license": "MIT",

package/skills/anchorloop/SKILL.md

@@ -23,7 +23,7 @@ Before the first change, state:
 
 The anchorloop extension holds `write` and `edit` outside `scratch/` and `docs/specs/` until this line appears after the user's latest message.
 
-Size the anchor to the change's actual reach and pick one method: an executable check, a user operation, human judgment, or a focused review. An anchor assigned by a coordinator governs. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security, or when the Jev second thought rates its review `full`; 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; after fixes it re-checks only those findings and the lines the fixes changed, and when two consecutive rounds still raise new blocking findings the run stops and hands the trend to the user, because a fresh exploratory review each round finds new edge cases instead of converging. The checkpoint is normally once, after the last increment.
+Size the anchor to the change's actual reach and pick one method: an executable check, a user operation, human judgment, or a focused review. An anchor assigned by a coordinator governs. Pick a review anchor when the change touches a shared contract, authorization or permission data, a migration, or security, or when the Jev second thought rates its review `full`; 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. 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, and when two consecutive rounds still raise new blocking findings the run stops and hands the trend to the user, because a fresh exploratory review each round finds new edge cases instead of converging. The checkpoint is normally once, after the last increment.
 
 ## Act
 
@@ -33,7 +33,7 @@ Give follow-up work (a fix round, a retry, the next item) to a fresh subagent ca
 
 Report problems outside the contract as follow-ups rather than fixing them in this change, because each extra fix reopens review on code the round never meant to touch.
 
-[PRINCIPLES.md](PRINCIPLES.md) holds the named principles the playbooks cite. The reply names a principle only when it changed a decision, together with that decision.
+The reply names a [principle](PRINCIPLES.md) only when it changed a decision, together with that decision.
 
 ### Friction Notes
 
@@ -47,15 +47,15 @@ Keep them in `scratch/friction.md` unless the entry names another home.
 
 ### Decision Trail
 
-A run the user reviews after stepping away records one row per fork, completed unit, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool. 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 picks up an existing trail reads its last rows, then records a `start` row with its run id. Before handing back, check every row against what the run actually did and build the report from the trail.
+A run the user reviews after stepping away records one row per fork, completed unit, pivot, or blocker in `scratch/decisions-<task-slug>.tsv` with the `anchorloop_decision` tool. 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 actually did and build the report from the trail.
 
 ## Verify
 
-Exercise the anchor and report what it observed. A requirement the anchor did not exercise is `unknown`; a green unrelated check is not evidence for it. Report local tests, builds, interactive runs, commit, push, CI, and deployment as separate claims; one never stands in for another. 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 unrelated checks show. Report local tests, builds, interactive runs, commit, push, CI, and deployment as separate claims; one never stands in for another. 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. When none can run or its result is lost, report `blocked: independent review` and keep merge and release closed, because the author's own review, green tests, and CI each miss what an independent reader catches.
 
-Write the reply the playbook's `Reply:` line names, with the anchor's evidence. After a run that changed something, the extension may add a Jev second thought on that reply; it is advisory: recheck the evidence it questions, then finish or continue on your own judgment. When a calling workflow supplies an artifact, write the results into it instead of a separate report or plan.
+Write the reply the playbook's `Reply:` line names, with the anchor's evidence. A Jev second thought the extension may add after a changing run is advisory: recheck the evidence it questions, then decide. When a calling workflow supplies an artifact, write the results into it instead of a separate report or plan.
 
 ### Reflexive Pass
 
@@ -73,4 +73,4 @@ Lifecycle playbooks wrap the entry playbook that does the work.
 
 ---
 
-Playbooks, principles, and the decision trail are adapted from [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT License), revision `e44668c`.
+Playbooks, principles, and the decision trail are adapted from [pstack](https://github.com/backnotprop/pstack) by Lauren Tan (MIT License), revision `e44668c`. 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/anchorloop/playbooks/autonomous-run.md

@@ -5,7 +5,7 @@
 1. Align: state the exit condition as a predicate a command or artifact can pass or fail; a duration is not one.
 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.
 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 iteration.
+4. Act: record one decision-trail row per iteration, after a `start` row when continuing an existing trail.
 5. Act: fix reversible mid-run discoveries yourself in their own commits, then return to the predicate. Bring only irreversible actions, user-owned decisions, or a real dead end to the user, and leave them in the trail when the user is asleep.
 6. Verify: stop when the predicate holds. On a plateau, change approach; never relax the predicate to declare victory. A genuine dead end ends the run with a written reason.
 

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, and processes still running.
-3. Treat the trail as authoritative: name the resume point 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, and redo nothing it shows finished.
 4. Route the remaining work to its entry playbook, which owns the rest of the 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/coding/MINI-SDD.md

@@ -1,12 +1,12 @@
 # Durable phases and artifacts
 
-Read this when work is classified as durable. The threshold itself lives in [SKILL.md](SKILL.md); this file holds the Durable phases and what each artifact contains.
+The Durable threshold lives in [SKILL.md](SKILL.md).
 
-Artifacts live in `docs/specs/YYYY-MM-DD-<slug>/`. Create each file when its phase is reached, not up front. Link to project instructions, ADRs, code, research, tickets, and visuals rather than copying them.
+Artifacts live in `docs/specs/YYYY-MM-DD-<slug>/`. Create each file when its phase is reached, not up front. Link to instructions, ADRs, code, and tickets rather than copying them.
 
 ## Decision → `decision.md`
 
-Resolve facts from their source; use `investigating` or `inspecting` when search is wide. Invoke `grilling` with `decision.md` only when it has an `open` row. Check that core rules are ready before implementation.
+Resolve facts from their source; use `investigating` or `inspecting` when search is wide. Invoke `grilling` with `decision.md` only when it has an `open` row. Before implementation, note core-rule readiness in `decision.md`.
 
 The file holds outcome and actors; in and out of scope; concrete scenarios; confirmed decisions; open consequential decisions. Explore every consequential branch in:
 
@@ -16,13 +16,13 @@ The file holds outcome and actors; in and out of scope; concrete scenarios; conf
 | ... | ... | request, evidence, or decision link | grounded, confirmed, or open |
 ```
 
-Status is `grounded`, `confirmed`, or `open`. `grounded` comes from the request, source facts, or existing decisions; `confirmed` comes from the user; `open` is a consequential user-owned decision.
+`grounded` comes from the request, source facts, or existing decisions; `confirmed` comes from the user; `open` is a consequential user-owned decision.
 
 **Complete when:** no open row blocks observable behavior.
 
 ## Spec → `spec.md`
 
-State the observable contract, edge cases, compatibility constraints, non-goals, and the applied project standards. Persist it in `spec.md` under `Status: proposed` before presenting it, then await explicit user confirmation. `proposed` keeps production source untouched while artifacts and read-only work stay open. Only the user's approving reply sets `Status: approved`, `Approved at`, and `Approved from`.
+Persist the spec in `spec.md` under `Status: proposed`, then have a fresh-context subagent read it and its links, restate the contract, and list each point it would have to guess to build it. Fold each guess into the spec or add it to `decision.md` as an `open` row, because the author cannot see assumptions it never wrote; rerun the reader once when a fold changes observable behavior. Then present it for explicit user confirmation. `proposed` keeps production source untouched while artifacts and read-only work stay open. Only the user's approving reply sets `Status: approved`, `Approved at`, and `Approved from`.
 
 The file opens with the approval header, then observable behavior and edge cases; compatibility constraints and non-goals; applied standards with their impact; evidence and precedent links; the selected reality anchor and checkpoint.
 
@@ -36,7 +36,7 @@ Approved from: <the user reply that approved it, empty while proposed>
 
 Choose the smallest approach that fits the approved spec and architecture. Follow the matching playbook's design steps ([feature](playbooks/feature.md) for interfaces and seams, [prototype](playbooks/prototype.md) when a named question is cheaper to settle by experiment) and the project's exact skill.
 
-The file holds the chosen approach; interfaces and data flow affected; existing precedent; decisions, trade-offs, and risks; the method selected inside the reality anchor. A straightforward design may be short, but it still names precedent and seam. Friction notes recorded during Act go under `## Friction Notes`.
+The file holds the chosen approach; interfaces and data flow affected; existing precedent; decisions, trade-offs, and risks; the method selected inside the reality anchor. Friction notes recorded during Act go under `## Friction Notes`.
 
 **Complete when:** implementation invents no product behavior or architecture.
 
@@ -50,8 +50,8 @@ Review the diff against project standards, the approved spec, and the confirmed
 | Observable behavior from spec | Real interface executed and the specific output observed | pass / fail / unknown |
 ```
 
-- **pass**: The reality anchor ran against the actual implementation and directly observed the expected behavior.
-- **fail**: The anchor executed and observed a deviation from the spec or an error.
+- **pass**: The anchor ran against the actual implementation and observed the expected behavior.
+- **fail**: The anchor observed a deviation from the spec or an error.
 - **unknown**: No anchor exercised the requirement in this run.
 
 Then human appropriateness verdicts; deviations from the approved spec or design; unresolved verification gaps and their impact. When friction notes exist, include a Reflexive section listing each with its classification (`misdirection` or `gap`) and its action.
@@ -59,3 +59,7 @@ Then human appropriateness verdicts; deviations from the approved spec or design
 ## Updates
 
 Update the owning phase file when new information changes it. A new consequential decision returns to `decision.md`; a change to user intent or observable behavior returns to Spec and user confirmation.
+
+---
+
+The fresh-reader spec check is adapted from the Goldfish comprehension review in [google/elephant-goldfish-model](https://github.com/google/elephant-goldfish-model) (Apache-2.0), revision `a8380ab`, `agents/comprehension.md`.