@linimin/pi-letscook 0.1.33 → 0.1.36

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.1.36
+
+### Changed
+
+- simplified the README opening so first-time users can understand the problem `/cook` solves, what the extension provides, and how to start using it without reading the full control-plane details first
+
+## 0.1.35
+
+### Changed
+
+- brightened the remaining `/cook` completion UI helper text by removing the last `dim` styling from proposal intro/footer/scroll hints and running activity metadata, using plain/default text for higher contrast while keeping stalled activity as warning-colored
+
+## 0.1.34
+
+### Changed
+
+- added evaluator calibration fixtures for semantically lenient but well-formed reviewer/auditor/stop-judge reports and made packaged transcription reject those cases fail closed while still accepting truthful passing fixtures
+- tightened the reproducible `none; ...` reviewer/auditor/stop-judge bypass checks while still accepting only the exact reviewer `none; proceed to completion-auditor` routing allowance with terminal punctuation or whitespace only
+- wired `npm run evaluator-calibration-test` into `npm run release-check` and `.agent/verify_completion_stop.sh` as part of the packaged release gate
+- fixed the smoke auto-resume prompt regression so the packaged release check writes `auto-resume-prompt.txt` again and passes on clean HEAD
+- promoted `.agent/active-slice.json` to implementation-contract v2 across implementer instructions, fail-closed active-vs-plan parity checks, recovery/reminder surfaces, and a dedicated release-gated regression
+- added durable canonical verification evidence at `.agent/verification-evidence.json`, threaded it through docs and recovery surfaces, and made release/stop verification fail closed on missing, stale, wrong-head, or protocol-doc-drift evidence artifacts
+- made `/cook` startup and replacement confirmation approval-only by removing inline Edit and mission-anchor editing paths; the proposal gate now offers only Start or Cancel, and cancel points users back to the main chat before rerunning `/cook`
+- kept the separate existing-workflow chooser (`Continue current workflow` / `Abandon current workflow and start this new one` / `Cancel`) while updating the replacement path, README, and deterministic context/refocus regressions to match the new approval-only gate truthfully
+
 ## 0.1.33
 
 ### Changed

package/README.md

@@ -1,27 +1,25 @@
 # @linimin/pi-letscook
 
-A Pi extension that adds `/cook` for resumable long-running workflows backed by repo-local canonical state in `.agent/**`.
+A Pi extension that turns `/cook` into a repo-local workflow command for long-running coding work.
 
-`@linimin/pi-letscook` is for work that does not fit in a single chat turn:
+## Why this exists
 
-- start from a goal or from recent discussion
-- resume later from repo-local workflow state
-- refocus an active workflow without losing control of the mission
-- drive implementation through isolated completion roles
-- keep verification, review, audit, and stop checks tied to the repo
+Normal chat is good for one-off tasks. It is much worse for work that needs to:
 
-## Why use it
+- continue across sessions
+- stay anchored to one mission
+- resume from repo state instead of chat memory
+- keep review, audit, and verification tied to the repo
 
-Use this package when you want `/cook` to behave like a real project workflow command instead of a one-shot prompt.
+`@linimin/pi-letscook` solves that by storing canonical workflow state in `.agent/**` and using `/cook` to start, resume, or refocus the workflow.
 
-It gives you:
+## What you get
 
-- **one command** for start, resume, and refocus
-- **repo-local canonical state** under `.agent/**`
-- **model-assisted startup proposals** from recent discussion
-- **explicit-goal anchoring** when you want the mission to stay fixed
-- **isolated completion roles** via `completion_role`
-- **deterministic verification** through repo-local scripts and regression checks
+- one command: `/cook`
+- repo-local canonical state in `.agent/**`
+- resumable long-running workflows
+- startup proposals from an explicit goal or recent discussion
+- deterministic verification, review, audit, and stop checks
 
 ## Install
 
@@ -51,73 +49,33 @@ Replace the active workflow with a different goal:
 /cook fix onboarding crash first, with regression tests
 ```
 
-Start the next round after the previous workflow is already done:
+## How `/cook` works
 
-```text
-/cook improve startup proposal confirmation UX
-```
-
-## How `/cook` behaves
-
-`/cook` is the only public workflow command, but it behaves differently depending on the current canonical workflow state.
+`/cook` is the only public workflow command, but it reacts to canonical workflow state:
 
 | Repo state | `/cook` | `/cook <goal>` |
 |---|---|---|
-| No canonical workflow yet | Uses the proposal analyst to summarize recent discussion into a startup proposal, then asks for confirmation | Builds a startup proposal anchored on the explicit goal, optionally enriching it from recent discussion, then asks for confirmation |
-| Active workflow exists | Resumes the active workflow from canonical `.agent/**` state | Asks whether to continue the current workflow or replace it |
-| Previous workflow is already `done` | Uses the proposal analyst to summarize recent discussion into the next workflow round, then asks for confirmation | Starts the next workflow round directly from the explicit goal |
-
-## Startup proposal behavior
-
-### `/cook <goal>`
-
-When you provide an explicit goal:
-
-- the explicit goal stays the mission anchor
-- recent discussion is supplemental only
-- recent discussion may enrich scope, constraints, and acceptance details when analyst output is available
-
-Example:
-
-```text
-/cook Build feature X with tests and docs
-```
-
-### `/cook` without a goal
-
-When you do **not** provide a goal:
+| No workflow yet | Summarizes recent discussion into a startup proposal, then asks for approval | Builds a proposal anchored on the explicit goal, then asks for approval |
+| Active workflow exists | Resumes from canonical `.agent/**` state | First asks whether to continue or replace the current workflow |
+| Previous workflow is `done` | Starts the next round from recent discussion | Starts the next round from the explicit goal |
 
-- `/cook` uses the proposal analyst to summarize recent discussion into a startup proposal
-- the proposal is shown in a custom confirmation UI before canonical state is written
-- if analyst output is unavailable, provide an explicit goal with `/cook <goal>`
+## Startup confirmation
 
-Example:
+Startup and replacement proposals are **approval-only**:
 
-```text
-/cook
-```
+- the proposal body is shown separately from actions
+- actions are only **Start** and **Cancel**
+- if the proposal needs changes, **Cancel**, discuss them in the main chat, and rerun `/cook`
 
-## Confirmation UI
+When an active workflow already exists and you run `/cook <goal>`, `/cook` still shows a separate chooser first:
 
-Startup confirmation uses a custom UI that:
+- **Continue current workflow**
+- **Abandon current workflow and start this new one**
+- **Cancel**
 
-- renders the proposal body separately from the action list
-- keeps Mission / Scope / Constraints / Acceptance readable as a content area
-- renders analyst-derived **Critique and risks** separately from the editable proposal body
-- renders recommended `task_type` / `evaluation_profile` routing hints separately from both the proposal body and the action list
-- presents explicit actions for:
-  - **Start**
-  - **Edit**
-  - **Cancel**
+Only the follow-on startup/replacement proposal uses the approval-only Start/Cancel gate.
 
-When you accept startup or refocus from that flow, `/cook` now persists the chosen `task_type` and `evaluation_profile` across `.agent/profile.json`, `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json`, and records the accepted critique outcome in canonical continuation state before the re-ground round begins.
-
-The same confirmation flow is reused across:
-
-- discussion-only startup
-- explicit-goal startup
-- next-round startup after completion
-- replacement-workflow startup
+When you accept startup or refocus from that flow, `/cook` persists the chosen `task_type` and `evaluation_profile` across `.agent/profile.json`, `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json`, and records the accepted critique outcome in canonical continuation state before the re-ground round begins.
 
 ## Observability
 
@@ -165,18 +123,27 @@ The packaged control plane now also carries canonical routing signals:
 
 Those identifiers are persisted in `.agent/profile.json`, `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json`, then surfaced in kickoff/reminder/resume text and reviewer/auditor/stop-judge evaluation handoffs so downstream roles can rely on canonical signaling instead of prose inference alone.
 
-The active-slice exact implementer handoff now also carries a stronger implementation contract for selected, in-progress, committed, and done slices:
+The active-slice exact implementer handoff is now the canonical implementation contract for selected, in-progress, committed, and done slices. In addition to the locked slice goal, acceptance criteria, contract IDs, blocked-on list, `priority`, and `why_now`, the v2 contract requires:
 
 - `implementation_surfaces` — the repo surfaces expected to change or stay in parity for the slice
 - `verification_commands` — the focused and broader deterministic checks the implementer is expected to run before committing
+- `locked_notes` / `must_fix_findings` — canonical scope locks plus review follow-up obligations for the current slice
+- `basis_commit` — the clean HEAD the slice was selected against
+- `remaining_contract_ids_before` plus `release_blocker_count_before` / `high_value_gap_count_before` — the locked before-slice counters the implementer must preserve in reports and later handoffs
+
+The selected plan slice must mirror that exact contract across goal, contract IDs, acceptance criteria, blocked-on state, `priority` / `why_now`, `implementation_surfaces`, `verification_commands`, locked notes, must-fix findings, `basis_commit`, and the before-slice counters. `.agent/verify_completion_control_plane.sh` plus the reminder/compaction-resume surfaces now fail closed on that drift instead of only checking slice-id presence, so implementers can recover from canonical state rather than prose-only summaries.
 
-Those fields are scaffolded by default, enforced by `.agent/verify_completion_control_plane.sh` whenever an exact handoff is required, and surfaced alongside `priority` / `why_now` in reminder and compaction-resume text so implementers can recover from canonical state instead of prose-only summaries.
+Reviewer, auditor, and stop-judge dispatch/reminder surfaces now also thread the current active-slice implementation contract (`implementation_surfaces`, `verification_commands`, locked notes, must-fix findings, `basis_commit`, and before-slice counters) alongside the canonical `evaluation_profile` so those read-only roles can reason from canonical state after compaction.
 
-Reviewer, auditor, and stop-judge dispatch/reminder surfaces now also thread the current active-slice implementation contract (`implementation_surfaces`, `verification_commands`, locked notes, must-fix findings, and before-slice counters) alongside the canonical `evaluation_profile` so those read-only roles can reason from canonical state after compaction.
+Deterministic verification now also persists a durable canonical artifact in `.agent/verification-evidence.json`. Fresh scaffolds create an idle placeholder, implementers update it for the selected slice or current HEAD, reminder/recovery/evaluation surfaces thread its path and summary, and `.agent/verify_completion_control_plane.sh`, `bash scripts/canonical-evidence-artifact-test.sh`, `npm run release-check`, and `bash .agent/verify_completion_stop.sh` fail closed when that artifact is missing, stale, or out of parity with the selected slice or current HEAD.
 
 Canonical reviewer/auditor/stop-judge transcription now fails closed on malformed rubric-bearing reports: the shared rubric heading plus all four rubric dimensions must be present, required role fields must remain intact, and reviewer/stop-judge yes/no verdicts cannot contradict rubric `fail` lines.
 
-Deterministic verification for this packaged contract lives in `npm run rubric-contract-test`, which now exercises reviewer, auditor, and stop-judge transcription paths while the bootstrap/refocus/context regressions plus control-plane verifier fail closed when required canonical signaling is missing.
+Evaluator calibration now also fails closed on semantically lenient but well-formed reports. `npm run evaluator-calibration-test` drives the packaged transcription path through reviewer yes-with-follow-up, auditor open-contracts-with-`Next mandatory slice: none`, and stop-judge yes-with-open-contracts fixtures while still accepting truthful passing reports. It also rejects the reproducible `none; ...` bypass family for reviewer follow-up, auditor worktree blockers, and stop-judge open-contract reporting, while still accepting only the exact reviewer routing text `Smallest follow-up slice: none; proceed to completion-auditor.` with terminal punctuation or whitespace only. Both `npm run release-check` and `bash .agent/verify_completion_stop.sh` include this calibration gate.
+
+Deterministic active-slice contract regression now lives in `bash scripts/active-slice-contract-test.sh`, and `npm run release-check` pulls it into the packaged release gate before `npm pack --dry-run`.
+
+Deterministic verification for this packaged contract also lives in `npm run rubric-contract-test`, which now exercises reviewer, auditor, and stop-judge transcription paths while the bootstrap/refocus/context regressions plus control-plane verifier fail closed when required canonical signaling is missing.
 
 ## Canonical files
 
@@ -194,6 +161,7 @@ This package stores canonical workflow state under:
   active-slice.json
   slice-history.jsonl
   stop-check-history.jsonl
+  verification-evidence.json
   tmp/
 ```
 
@@ -219,6 +187,7 @@ Ignored execution-state files:
 - `.agent/active-slice.json`
 - `.agent/slice-history.jsonl`
 - `.agent/stop-check-history.jsonl`
+- `.agent/verification-evidence.json`
 - `.agent/*.log`
 - `.agent/tmp/`
 
@@ -242,12 +211,14 @@ Run validation from the package root:
 npm run smoke-test
 npm run refocus-test
 npm run context-proposal-test
+bash scripts/canonical-evidence-artifact-test.sh
 npm run observability-status-test
+npm run evaluator-calibration-test
 npm run rubric-contract-test
 npm run release-check
 ```
 
-`npm run release-check` is the broad packaged-release verifier. It reruns the startup/refocus/context checks — including the critique-aware `/cook` confirmation regression — includes deterministic observability coverage plus the rubric-contract regression, and finishes with `npm pack --dry-run`.
+`npm run release-check` is the broad packaged-release verifier. It begins with `bash .agent/verify_completion_control_plane.sh`, so missing or stale `.agent/verification-evidence.json` parity fails closed before the broader suite runs, then reruns the startup/refocus/context checks — including the critique-aware `/cook` confirmation regression and the smoke auto-resume prompt path — includes deterministic canonical evidence artifact coverage and includes deterministic active-slice contract coverage plus observability coverage, evaluator calibration, and the rubric-contract regression, and finishes with `npm pack --dry-run`.
 
 ## Release
 

package/agents/completion-implementer.md

@@ -10,6 +10,8 @@ Load `completion-protocol` before acting. Use it as the shared protocol source o
 
 You execute one exact slice chosen either by `completion-regrounder` or directly by the workflow root from canonical `.agent` state.
 
+For selected, in-progress, committed, and done slices, `.agent/active-slice.json` is the canonical implementation contract. Treat prose summaries as continuity help only, and stop instead of guessing if that contract is stale, incomplete, or out of parity with `.agent/plan.json`.
+
 Required exact handoff from canonical `.agent` state:
 
 - blocker count before the slice
@@ -20,10 +22,17 @@ Required exact handoff from canonical `.agent` state:
 - one exact slice goal
 - the exact acceptance criteria for that slice
 - the exact contract IDs for that slice
+- the exact `priority` and `why_now` for that slice
+- the exact `implementation_surfaces`
+- the exact `verification_commands`
+- the exact `basis_commit`
+- the exact `remaining_contract_ids_before`
+- the exact `release_blocker_count_before`
+- the exact `high_value_gap_count_before`
 - any locked notes or caller-selected-slice notes captured in `.agent/active-slice.json`
 - any must-fix review findings captured in `.agent/active-slice.json` if this is a follow-up slice
 
-If the exact slice ID, exact slice goal, or exact acceptance criteria are missing, stale, or ambiguous in canonical state, stop and report that blocker instead of guessing.
+If the exact slice ID, exact slice goal, exact acceptance criteria, or any required implementation-contract v2 field are missing, stale, or ambiguous in canonical state, stop and report that blocker instead of guessing.
 
 You are the only role allowed to:
 
@@ -52,7 +61,7 @@ These lines are for workflow observability, not hidden reasoning. Keep them brie
 
 1. Read canonical `.agent` inputs before touching tracked files.
 2. After compaction or recovery, re-read canonical `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json` before resuming.
-3. Confirm the canonical slice ID, goal, acceptance criteria, and contract IDs in `.agent/active-slice.json` match canonical `.agent/plan.json`. If they do not match, stop and report the mismatch instead of guessing.
+3. Confirm the canonical slice ID, goal, acceptance criteria, contract IDs, priority, why_now, implementation_surfaces, verification_commands, locked notes, must-fix findings, basis_commit, and before-slice counters in `.agent/active-slice.json` match canonical `.agent/plan.json`. If they do not match, stop and report the mismatch instead of guessing.
 4. Make truthful `.agent/state.json` and `.agent/active-slice.json` updates before implementation if needed.
 5. If implementation reveals roadmap-level drift — for example a missing prerequisite slice, invalid slice boundary, dependency reorder, or blocker that changes the current slice contract — do not silently redesign the plan. Report the discrepancy explicitly, make only the minimal truthful local state updates needed for the current slice, and hand control back for canonical re-grounding by `completion-regrounder`.
 6. Make the smallest correct tracked-file change.