@linimin/pi-letscook 0.1.26

package/scripts/smoke-test.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PKG_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR"' EXIT
+
+cd "$TMPDIR"
+git init -q
+
+pi -e "$PKG_ROOT" -p "/cook smoke-test mission" >/tmp/pi-completion-smoke.out 2>/tmp/pi-completion-smoke.err &
+PI_PID=$!
+for _ in $(seq 1 60); do
+  if [[ -f .agent/profile.json && -f .agent/state.json && -f .agent/plan.json && -f .agent/active-slice.json ]]; then
+    break
+  fi
+  sleep 1
+done
+if [[ ! -f .agent/profile.json || ! -f .agent/state.json || ! -f .agent/plan.json || ! -f .agent/active-slice.json ]]; then
+  echo "completion bootstrap did not materialize canonical files in time" >&2
+  cat /tmp/pi-completion-smoke.err >&2 || true
+  kill "$PI_PID" >/dev/null 2>&1 || true
+  wait "$PI_PID" >/dev/null 2>&1 || true
+  exit 1
+fi
+kill "$PI_PID" >/dev/null 2>&1 || true
+wait "$PI_PID" >/dev/null 2>&1 || true
+
+bash .agent/verify_completion_control_plane.sh >/dev/null
+bash .agent/verify_completion_stop.sh >/dev/null
+
+python3 - <<'PY2'
+import json
+from pathlib import Path
+path = Path('.agent/active-slice.json')
+active = json.loads(path.read_text())
+active.update({
+    'status': 'selected',
+    'slice_id': 'smoke-slice',
+    'goal': 'verify selected handoff schema',
+    'contract_ids': ['smoke-contract'],
+    'acceptance_criteria': ['criterion'],
+    'blocked_on': [],
+    'locked_notes': [],
+    'must_fix_findings': [],
+    'basis_commit': 'deadbeef',
+    'remaining_contract_ids_before': ['smoke-contract'],
+    'release_blocker_count_before': 1,
+    'high_value_gap_count_before': 0,
+})
+active.pop('priority', None)
+active.pop('why_now', None)
+path.write_text(json.dumps(active, indent=2) + '\n')
+PY2
+
+if bash .agent/verify_completion_control_plane.sh >/dev/null 2>&1; then
+  echo "expected control-plane verification to fail when selected active-slice omits priority/why_now" >&2
+  exit 1
+fi
+
+python3 - <<'PY3'
+import json
+from pathlib import Path
+path = Path('.agent/active-slice.json')
+active = json.loads(path.read_text())
+active['priority'] = 1
+active['why_now'] = 'smoke test exact handoff'
+path.write_text(json.dumps(active, indent=2) + '\n')
+PY3
+
+bash .agent/verify_completion_control_plane.sh >/dev/null
+bash .agent/verify_completion_stop.sh >/dev/null
+
+echo "smoke test passed: $TMPDIR"

package/skills/completion-protocol/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: completion-protocol
+description: Shared completion workflow protocol for long-running coding tasks with canonical .agent state, one-slice execution, mandatory role dispatch, recovery, and final stop criteria. Use when driving persistent end-to-end completion work across multiple sessions.
+---
+
+# Completion Protocol
+
+Load this skill whenever you are operating inside the `completion` workflow.
+
+This skill defines shared protocol facts only. Role-specific behavior belongs in the dedicated completion agents:
+
+- `completion-bootstrapper`
+- `completion-regrounder`
+- `completion-implementer`
+- `completion-reviewer`
+- `completion-auditor`
+- `completion-stop-judge`
+
+## Shared Rules
+
+- Current repo truth beats stale notes, stale summaries, and conversation memory.
+- `plan.json` is the persistent machine-readable slice backlog. Rebuild it during every re-grounding wave and keep it truthful after every committed slice.
+- `state.json` is the persistent machine-readable workflow controller. Keep `current_phase`, `continuation_policy`, `continuation_reason`, `next_mandatory_role`, and `next_mandatory_action` truthful after every transition.
+- Every slice in `plan.json` must have non-empty `acceptance_criteria` — concrete, verifiable conditions that define done. A slice without acceptance criteria is invalid and must not be selected.
+- Acceptance criteria are immutable after lock except for removing a criterion already satisfied with evidence or adding a missing criterion discovered during implementation.
+- If implementation discovers roadmap-level drift — such as invalid slice boundaries, missing prerequisite slices, dependency reordering, or a blocker that changes the current slice contract — the implementer must not silently redesign the plan. It must report the new truth and return control for canonical reconciliation by `completion-regrounder`.
+- During re-ground, evaluate each slice's `acceptance_criteria` against current repo truth and update `status` and `evidence` accordingly.
+- A slice may only transition to `done` when every acceptance criterion is satisfied with proof in `evidence`.
+- Run exactly one implementation slice at a time.
+- A slice is not complete unless it lands as a new commit.
+- Before selecting or advancing to the next slice after a committed slice, the tracked and unignored worktree must be clean. If it is not clean, treat that dirty state as a blocker to next-slice progression and reopen or continue the latest slice for reconciliation.
+- Docs, config, and runbooks must stay truthful to shipped behavior.
+- `.agent/verify_completion_stop.sh` is a generated repo-level baseline verifier. Onboarding should create a working version from current repo truth rather than an unconditional failing placeholder.
+- Keep slice-specific proof in repo tests or deterministic checks. Refresh `.agent/verify_completion_stop.sh` only when the repo's top-level verification surfaces change or the verifier becomes stale.
+- The workflow topology is flat and primary-driven: the main pi session remains the workflow root and invokes at most one completion role at a time.
+- No completion role may invoke another completion role during the normal workflow.
+- Completion is a sticky workflow. If canonical state says continuation is required, the workflow root must keep advancing through mandatory roles until canonical state switches to `await_user_input`, `blocked`, `paused`, or `done`.
+- `continuation_policy == continue` means the workflow root must not stop after a slice or ask the user whether to continue. It must dispatch the next mandatory role directly.
+- `continuation_policy == await_user_input` means the workflow root must ask only for the exact missing input and then stop.
+- `continuation_policy == blocked` means the workflow root must report the blocker and stop.
+- `continuation_policy == paused` means the user explicitly paused the workflow.
+- `continuation_policy == done` means canonical final stop reconciliation is complete and the workflow may stop.
+- Use `completion-bootstrapper` only for first-time setup or missing tracked contract-file repair.
+- Use `completion-regrounder` for canonical re-grounding, slice selection, post-review or post-audit reconciliation, and final stop reconciliation.
+- Default scratch space for temporary files is repo-local `.agent/tmp/`.
+- Do not write scratch artifacts to `/tmp` or `/private/tmp` by default.
+- If a tool or platform behavior explicitly requires OS temp, prefer a scoped path such as `$TMPDIR/pi-completion/<repo-name>/` and treat it as disposable.
+- Never keep canonical state, required verification evidence, or the only copy of a deliverable exclusively in temp paths.
+
+## Primary Driver Contract
+
+When `completion-protocol` is loaded by the main pi session, that session becomes the workflow driver only.
+
+The workflow driver may:
+
+- read current repo truth and canonical `.agent` state
+- update canonical `.agent/**` state truthfully when needed for handoff
+- choose which completion role to invoke next according to the mandatory dispatch table below
+- summarize or compare role outputs for the user
+- append canonical `.agent/slice-history.jsonl` records, but only as a faithful transcription of actual completion-role outputs
+- append canonical `.agent/stop-check-history.jsonl` `judgment` records during the final stop wave, but only as a faithful transcription of actual `completion-stop-judge` outputs
+
+The workflow driver must not, while completion is active and a slice is selected or in progress:
+
+- directly edit non-`.agent/**` tracked product, docs, config, or test files for that slice
+- directly create the slice commit
+- directly mark a slice implemented, accepted, reopened, reviewed, audited, or judged without the corresponding role output
+- bypass the completion roles for convenience
+- hand control back to the user between slices merely to ask whether to continue when `continuation_policy == continue`
+
+If the workflow driver detects that the next mandatory action belongs to a completion role, it must invoke that role rather than doing the slice work itself.
+
+## Mandatory Dispatch Table
+
+1. If tracked protocol contract files are missing or first-time onboarding is required, invoke `completion-bootstrapper`.
+2. If canonical `.agent` execution state is missing, invalid, contradictory, stale, or ambiguous after compaction or recovery, invoke `completion-regrounder`.
+3. If no slice is selected, invoke `completion-regrounder` to reconcile `.agent/plan.json` and return the next exact handoff payload.
+4. If a slice is `selected` or `in_progress` and no new slice commit exists yet, invoke `completion-implementer`.
+5. If the latest committed slice lacks a review result, invoke `completion-reviewer`.
+6. If the latest committed slice lacks an audit result, invoke `completion-auditor`.
+7. If review or audit have returned and canonical reconciliation is needed, invoke `completion-regrounder`. `completion-regrounder` must not select or hand off a next slice while the latest committed slice leaves the tracked and unignored worktree dirty; instead it must reopen or continue that latest slice for reconciliation.
+8. If all planned slices are done and final closure is being evaluated, invoke the required `completion-stop-judge` sessions directly.
+9. After each required `completion-stop-judge` result is faithfully recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
+
+The workflow driver must not substitute itself for any mandatory dispatch target above.
+
+## Canonical Files
+
+Tracked repo-contract files:
+
+- `.agent/README.md`
+- `.agent/mission.md`
+- `.agent/profile.json`
+- `.agent/verify_completion_stop.sh`
+- `.agent/verify_completion_control_plane.sh`
+
+Ignored canonical execution-state files:
+
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+- `.agent/slice-history.jsonl`
+- `.agent/stop-check-history.jsonl`
+- `.agent/*.log`
+
+## Canonical Inputs
+
+Read these when making completion decisions:
+
+- `.agent/mission.md`
+- `.agent/README.md`
+- `.agent/profile.json`
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+- `.agent/slice-history.jsonl`
+- `.agent/stop-check-history.jsonl`
+
+Optional context only:
+
+- `.agent/backlog.md`
+- `.agent/handoff.md`
+- `.agent/compact.md`
+
+## Scratch Space
+
+- Use `.agent/tmp/` for repo-local temporary files created during completion work.
+- `.agent/tmp/` is scratch space only. Do not treat it as canonical state or durable handoff storage.
+- Keep `.agent/tmp/` ignored in `.gitignore` alongside other non-contract `.agent/*` execution artifacts.
+- Use OS temp only when a tool explicitly requires it, and prefer `$TMPDIR/pi-completion/<repo-name>/` over broad `/tmp` usage.
+
+## Compaction And Recovery
+
+Canonical truth remains in `.agent/**`.
+
+After context compaction, suspected memory loss, stalled-role recovery, or any ambiguous completion state, the workflow driver must re-read:
+
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+
+The workflow driver must invoke `completion-regrounder` before continuing whenever any of the following is true:
+
+- `requires_reground` is `true`
+- `requires_reground` is unknown because canonical state is missing or unreadable
+- `next_mandatory_action` is missing, unknown, or ambiguous
+- `active-slice.json` does not match `.agent/plan.json`
+- acceptance criteria for the selected or active slice are missing or unclear
+- the exact implementer handoff snapshot in `.agent/active-slice.json` is missing, stale, or contradictory
+
+The workflow driver must not continue implementation, review, audit, or stop evaluation from compacted conversation memory alone.
+
+After compaction or recovery, `completion-implementer` must also re-read canonical `.agent/state.json`, `.agent/plan.json`, and `.agent/active-slice.json` before resuming work. If `.agent/active-slice.json` still contains a truthful exact handoff snapshot, continue from canonical state rather than asking the user to resend the original caller payload.
+
+## Shared Report Header
+
+All completion reports must begin with:
+
+- `MISSION ANCHOR: ...`
+- `Remaining contract IDs: ...`
+
+If a role-specific fixed format uses before/after wording, keep the same mission-anchor first line and then follow that role's exact format.
+
+## References
+
+Read these bundled references when you need the full protocol or scaffolding material:
+
+- `references/completion.md`

package/skills/completion-protocol/references/completion.md

@@ -0,0 +1,287 @@
+# completion
+
+`completion` is a repo-local control-plane protocol for long-running software-project completion work.
+
+## Tracked Repo-Contract Files
+
+- `.agent/README.md`
+- `.agent/mission.md`
+- `.agent/profile.json`
+- `.agent/verify_completion_stop.sh`
+- `.agent/verify_completion_control_plane.sh`
+
+## Ignored Canonical Execution State
+
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+- `.agent/slice-history.jsonl`
+- `.agent/stop-check-history.jsonl`
+- `.agent/*.log`
+
+## Scratch Space
+
+- Use repo-local `.agent/tmp/` as the default temporary workspace for completion.
+- Keep `.agent/tmp/` ignored in `.gitignore` alongside other non-contract `.agent/*` execution artifacts.
+- Do not write scratch artifacts to `/tmp` or `/private/tmp` by default.
+- If a tool explicitly requires OS temp, prefer a scoped path such as `$TMPDIR/pi-completion/<repo-name>/` and treat it as disposable.
+- Do not store canonical state, required verification evidence, or the only copy of a deliverable exclusively in scratch paths.
+
+## Fixed Profile Schema
+
+```json
+{
+  "schema_version": 1,
+  "protocol_id": "completion",
+  "project_name": "<repo-name>",
+  "required_stop_judges": 3,
+  "priority_policy_id": "completion-default",
+  "docs_surfaces": ["README.md", "docs/"]
+}
+```
+
+## Fixed State Model
+
+`state.json` carries the current authoritative summary.
+
+Required fields:
+
+- `schema_version`
+- `mission_anchor`
+- `current_phase`
+- `continuation_policy`
+- `continuation_reason`
+- `project_done`
+- `requires_reground`
+- `slices_since_last_reground`
+- `remaining_release_blockers`
+- `remaining_high_value_gaps`
+- `unsatisfied_contract_ids`
+- `release_blocker_ids`
+- `next_mandatory_action`
+- `next_mandatory_role`
+- `remaining_stop_judges`
+- `last_reground_at`
+- `last_auditor_verdict`
+- `contract_status`
+- `latest_completed_slice`
+- `latest_verified_slice`
+
+`continuation_policy` must be one of:
+
+- `continue`
+- `await_user_input`
+- `blocked`
+- `paused`
+- `done`
+
+`next_mandatory_role` must be one of:
+
+- `completion-bootstrapper`
+- `completion-regrounder`
+- `completion-implementer`
+- `completion-reviewer`
+- `completion-auditor`
+- `completion-stop-judge`
+- `null`
+
+`current_phase` must be one of:
+
+- `reground`
+- `implement`
+- `post_commit_review`
+- `post_commit_audit`
+- `post_commit_reconcile`
+- `stop_wave`
+- `awaiting_user`
+- `blocked`
+- `done`
+
+Rules:
+
+1. `continuation_policy == continue` means the workflow root must keep advancing and must not stop after a slice to ask whether to continue.
+2. `continuation_policy == await_user_input` means the workflow root must ask only for the exact missing input and then stop.
+3. `continuation_policy == blocked` means the workflow root must report the blocker and stop.
+4. `continuation_policy == paused` means the user explicitly paused the workflow.
+5. `continuation_policy == done` means canonical final stop reconciliation is complete and the workflow may stop.
+
+`plan.json` carries the ordered persistent slice backlog.
+
+Required fields:
+
+- `schema_version`
+- `mission_anchor`
+- `last_reground_at`
+- `plan_basis`
+- `candidate_slices`
+
+Each `candidate_slices[]` entry must include:
+
+- `slice_id`
+- `goal`
+- `acceptance_criteria`
+- `contract_ids`
+- `priority`
+- `status` where status is one of `planned`, `selected`, `in_progress`, `blocked`, `done`, `cancelled`
+- `why_now`
+- `blocked_on`
+- `evidence`
+
+### Acceptance Criteria Contract
+
+`acceptance_criteria` is a non-empty list of concrete, verifiable conditions that define when a slice is done.
+
+Rules:
+
+1. Set at re-ground time. Every slice in `candidate_slices` must have `acceptance_criteria` populated during the re-ground wave that first introduces or re-evaluates it. A slice with empty `acceptance_criteria` is invalid.
+2. Immutable after lock. Once a slice's `acceptance_criteria` are set, subsequent re-ground waves must not weaken, replace, or silently drop criteria. The only allowed mutations are:
+   - removing a criterion because repo truth already satisfies it, with `evidence` updated to prove it
+   - adding a criterion discovered during implementation that was missing from the original assessment
+3. Done requires all satisfied. A slice may only transition to `done` when every acceptance criterion is satisfied and `evidence` contains the proof for each one.
+4. Re-ground validation. During re-ground, the current slice backlog must be revalidated against repo truth. A slice previously marked `done` whose criteria no longer hold must be reopened.
+5. Clean handoff before next slice. After a committed slice is reviewed and audited, the tracked and unignored worktree must be clean before the next slice is selected.
+
+`active-slice.json` carries one current slice cursor.
+
+When `status` is `selected`, `in_progress`, `committed`, or `done`, `active-slice.json` must also carry the exact implementer handoff snapshot so `completion-implementer` can resume after compaction without asking the user to resend the original caller payload.
+
+Required exact handoff fields:
+
+- `acceptance_criteria`
+- `priority`
+- `why_now`
+- `blocked_on`
+- `locked_notes`
+- `must_fix_findings`
+- `basis_commit`
+- `remaining_contract_ids_before`
+- `release_blocker_count_before`
+- `high_value_gap_count_before`
+
+Allowed `status` values:
+
+- `idle`
+- `selected`
+- `in_progress`
+- `committed`
+- `done`
+
+`slice-history.jsonl` is append-only and only accepts:
+
+- `implemented`
+- `reviewed`
+- `audited`
+- `accepted`
+- `reopened`
+
+Minimum record shape:
+
+- `schema_version`
+- `type`
+- `recorded_at`
+- `slice_id`
+- `commit_sha`
+- `head_sha`
+
+`stop-check-history.jsonl` is append-only and only accepts:
+
+- `judgment`
+
+Minimum record shape:
+
+- `schema_version`
+- `type`
+- `recorded_at`
+- `head_sha`
+- `can_stop`
+- `blocker_count`
+- `high_value_gap_count`
+
+Empty history files are legal.
+
+## One-Slice Lifecycle
+
+1. Re-ground from current repo truth.
+2. Choose exactly one highest-value slice.
+3. Mark that slice in canonical state.
+4. Implement the smallest correct tracked-file change.
+5. Add tests or deterministic proof that satisfy one or more `acceptance_criteria`.
+6. Run focused verification first, then broader verification if needed.
+7. Commit.
+8. Update canonical state and append one `implemented` record.
+9. Run read-only review and audit.
+10. Confirm the tracked and unignored worktree is clean before selecting the next slice.
+11. Append `reviewed`, `audited`, and `accepted` or `reopened`.
+12. Repeat until the stop wave concludes the repo may stop.
+
+## Workflow Topology
+
+The workflow topology is mandatory and flat:
+
+1. The main pi session stays the workflow root.
+2. The main pi session invokes at most one completion role at a time.
+3. `completion-bootstrapper` is used only for first-time setup or missing tracked contract-file repair.
+4. `completion-regrounder` is the mandatory role for canonical `.agent` reconciliation, slice selection, post-review or post-audit reconciliation, and final stop reconciliation.
+5. `completion-implementer`, `completion-reviewer`, `completion-auditor`, and `completion-stop-judge` are sibling roles invoked directly by the workflow root.
+6. No completion role may invoke another completion role during the normal workflow.
+
+## Primary Workflow Driver Contract
+
+The main pi session may:
+
+- read repo truth and canonical `.agent` state
+- update canonical `.agent/**` state truthfully for handoff
+- invoke the correct completion role according to the mandatory dispatch table
+- append canonical history records as a faithful transcription of actual role outputs
+
+It must not, while a slice is selected or in progress:
+
+- directly edit non-`.agent/**` tracked product/docs/config/test files for that slice
+- directly create the slice commit
+- directly claim review/audit/acceptance/judgment outcomes without the corresponding role output
+- bypass mandatory completion-role dispatch for convenience
+- hand control back to the user between slices merely to ask whether to continue when `continuation_policy == continue`
+
+## Mandatory Dispatch Table
+
+1. If tracked protocol contract files are missing or first-time onboarding is required, invoke `completion-bootstrapper`.
+2. If canonical `.agent` execution state is missing, stale, invalid, contradictory, or ambiguous after compaction or recovery, invoke `completion-regrounder` first.
+3. If no slice is selected, invoke `completion-regrounder` to reconcile `.agent/plan.json` and return the next exact handoff payload.
+4. If a slice is `selected` or `in_progress` and no new commit exists for it yet, invoke `completion-implementer`.
+5. If the latest committed slice lacks review, invoke `completion-reviewer`.
+6. If the latest committed slice lacks audit, invoke `completion-auditor`.
+7. If canonical reconciliation is needed after review or audit, invoke `completion-regrounder`.
+8. If all slices are done and final closure is under evaluation, invoke the required `completion-stop-judge` sessions directly.
+9. After the required judgments are recorded, rerun `bash .agent/verify_completion_stop.sh` and invoke `completion-regrounder` for final stop reconciliation.
+
+## Compaction And Recovery
+
+After context compaction, suspected memory loss, stalled-role recovery, or any ambiguous completion state, the workflow root must re-read:
+
+- `.agent/state.json`
+- `.agent/plan.json`
+- `.agent/active-slice.json`
+
+The workflow root must invoke `completion-regrounder` before continuing whenever any of the following is true:
+
+- `requires_reground` is `true`
+- `requires_reground` is unknown because canonical state is missing or unreadable
+- `next_mandatory_action` is missing, unknown, or ambiguous
+- `active-slice.json` does not match `.agent/plan.json`
+- acceptance criteria for the selected or active slice are missing or unclear
+- the exact implementer handoff snapshot in `.agent/active-slice.json` is missing, stale, or contradictory
+
+The workflow root must not continue implementation, review, audit, or stop evaluation from compacted conversation memory alone.
+
+## Default Priority Policy
+
+`completion-default` ranks candidate slices in this order:
+
+1. shipped behavior versus docs/config mismatch
+2. safety, security, data-loss, fail-open, or fail-closed critical behavior
+3. startup, install, migration, or restart critical path
+4. operator emergency, rollback, or recovery path
+5. normal primary lifecycle path
+6. docs/config/runbook parity
+7. regression depth
+8. final closure and hygiene