@linimin/pi-letscook 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.37
+
+### Changed
+
+- documented `/cook` as the single public discussion-first workflow command for startup, active-workflow continue/refocus, and done-workflow next-round flows
+- reframed `/cook <text>` in public docs/help copy as a temporary compatibility shim instead of the primary workflow entrypoint, without removing it from the shipped runtime
+- documented the fail-closed ambiguous-discussion behavior and approval-only Start/Cancel gate before canonical-state writes
+- added release-gated public-parity assertions for README/help/changelog `/cook` single-command copy so docs drift fails closed before packaging
+- 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

package/README.md

@@ -1,28 +1,26 @@
 # @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 discussion-driven 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` as one discussion-first command to start, continue, refocus, or advance the workflow.
 
-It gives you:
+## What you get
 
-- **one command** for start, resume, and refocus
-- **repo-local canonical state** under `.agent/**`
-- **durable canonical verification evidence** in `.agent/verification-evidence.json`
-- **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
+- discussion-first startup, continue, refocus, and next-round routing
+- temporary `/cook <text>` compatibility input when you need to anchor the mission explicitly
+- deterministic verification, review, audit, and stop checks
 
 ## Install
 
@@ -34,99 +32,56 @@ Then run `/reload` in Pi.
 
 ## Quick start
 
-Start from an explicit goal:
-
-```text
-/cook build feature X end-to-end with tests and docs
-```
-
-Resume an active workflow:
+Primary entrypoint:
 
 ```text
 /cook
 ```
 
-Replace the active workflow with a different goal:
-
-```text
-/cook fix onboarding crash first, with regression tests
-```
-
-Start the next round after the previous workflow is already done:
-
-```text
-/cook improve startup proposal confirmation UX
-```
-
-## How `/cook` behaves
+Use bare `/cook` after you discuss the mission in the main chat. The same command can:
 
-`/cook` is the only public workflow command, but it behaves differently depending on the current canonical workflow state.
+- start a brand-new workflow from recent discussion
+- continue the current workflow when recent discussion still matches it, or when discussion is too weak or ambiguous to justify a refocus
+- surface a conservative refocus chooser when recent discussion clearly points to a different workflow
+- start the next workflow round after the previous one is `done`
 
-| 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 | First asks whether to continue the current workflow or replace it, then uses a final Start/Cancel approval gate before any replacement state is written |
-| 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:
+Temporary compatibility shim when you need to anchor the mission explicitly:
 
 ```text
-/cook Build feature X with tests and docs
+/cook build feature X end-to-end with tests and docs
 ```
 
-### `/cook` without a goal
+On startup and next-round flows, if recent discussion is missing, weak, or ambiguous, bare `/cook` fails closed and leaves canonical `.agent/**` state unchanged until the discussion is clarified.
 
-When you do **not** provide a goal:
+## How `/cook` works
 
-- `/cook` uses the proposal analyst to summarize recent discussion into a startup proposal
-- the proposal is shown in a custom approval-only confirmation UI before canonical state is written
-- if analyst output is unavailable, provide an explicit goal with `/cook <goal>`
+Bare `/cook` is now the primary workflow entrypoint. `/cook <text>` is still supported as a temporary compatibility shim, and it uses the same proposal/routing pipeline while treating the explicit text as the mission anchor when provided.
 
-Example:
+| Repo state | Bare `/cook` (primary) | Temporary `/cook <text>` compatibility shim |
+|---|---|---|
+| No workflow yet | Summarizes recent discussion into a startup proposal, then asks for approval with **Start** or **Cancel**. If the discussion is weak or ambiguous, `/cook` fails closed without writing `.agent/**` state. | Uses the same startup proposal and approval-only **Start**/**Cancel** gate, but the explicit text anchors the proposed mission. |
+| Active workflow exists | Reads the current mission plus recent non-command discussion. Matching or unclear discussion resumes from canonical `.agent/**` state. Clear replacement discussion opens a chooser first, then only rewrites canonical state after the follow-on **Start** confirmation. | Uses the same discussion-first routing pipeline. The explicit text is only a temporary compatibility anchor; `/cook` can still continue unchanged or route through the chooser plus final **Start**/**Cancel** replacement confirmation. |
+| Previous workflow is `done` | Starts the next round from recent discussion, then asks for approval with **Start** or **Cancel**. Ambiguous discussion fails closed without rewriting canonical state. | Uses the same next-round proposal and approval-only gate, but the explicit text anchors the next mission. |
 
-```text
-/cook
-```
+## Approval-only confirmation and fail-closed behavior
 
-## Confirmation UI
+All startup, next-round, and replacement proposals are **approval-only**:
 
-Startup and replacement confirmation use a custom approval-only UI that:
+- the proposal body is shown separately from actions
+- actions are only **Start** and **Cancel**
+- **Cancel** is side-effect free: discuss changes in the main chat and rerun `/cook`
 
-- 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 non-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**
-  - **Cancel**
-- treats the proposal as approval-only: if it needs changes, Cancel, discuss them in the main chat, and rerun `/cook`
+When bare `/cook` cannot derive a clear startup, next-round, or replacement proposal from recent discussion, it fails closed instead of guessing. That means no canonical `.agent/**` state is created or rewritten until the discussion is clarified or you temporarily pass `/cook <text>`.
 
-When an active workflow already exists and you run `/cook <goal>`, `/cook` still shows a separate chooser first:
+When an active workflow already exists and recent discussion clearly suggests a different workflow, `/cook` shows a separate chooser first:
 
 - **Continue current workflow**
-- **Abandon current workflow and start this new one**
+- **Start new workflow from recent discussion**
 - **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 approval-only confirmation flow is reused across:
+Only the follow-on startup/replacement proposal uses the approval-only Start/Cancel gate, and canonical `.agent/**` state changes happen only after **Start** is accepted.
 
-- 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
 
@@ -269,7 +224,7 @@ npm run rubric-contract-test
 npm run release-check
 ```
 
-`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`.
+`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 asserts the shipped single-command `/cook` public parity surfaces in `README.md`, `CHANGELOG.md`, and the `/cook` help/fail-closed copy in `extensions/completion/index.ts`, 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