@tianhai/pi-workflow-kit 0.17.1 → 1.0.0

package/docs/plans/completed/2026-05-08-migrate-earendil-works-design.md

@@ -1,39 +0,0 @@
-# Migrate from @mariozechner to @earendil-works
-
-## Context
-
-pi has moved from `@mariozechner` to `@earendil-works` on GitHub and npm. The old `@mariozechner/pi-coding-agent@0.73.1` is deprecated. This package has two unused peer deps (`pi-ai`, `pi-tui`) that should be cleaned up.
-
-## Changes
-
-### 1. `extensions/workflow-guard.ts` — update import
-
-```diff
--import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-```
-
-### 2. `package.json` — update peerDependencies
-
-```diff
- "peerDependencies": {
--    "@mariozechner/pi-ai": "*",
--    "@mariozechner/pi-coding-agent": "*",
--    "@mariozechner/pi-tui": "*",
-+    "@earendil-works/pi-coding-agent": "*",
-     "@sinclair/typebox": "*"
- },
-```
-
-- Rename `pi-coding-agent` to `@earendil-works/pi-coding-agent`
-- Remove `@mariozechner/pi-ai` (unused)
-- Remove `@mariozechner/pi-tui` (unused)
-
-## Verification
-
-- `ExtensionAPI` is exported identically from both old and new packages (same export map, same `.d.ts` path)
-- No other imports from `@mariozechner/*` exist in the codebase
-
-## Impact
-
-Users on old `@mariozechner/pi-coding-agent` will get a peer dependency resolution error — they must update pi. The old package is explicitly deprecated pointing to the new one.

package/docs/plans/completed/2026-05-08-migrate-earendil-works-implementation.md

@@ -1,45 +0,0 @@
-# Implementation Plan: Migrate from @mariozechner to @earendil-works
-
-## Task 1: Update package scope and clean up peer dependencies
-
-<!-- tdd: trivial -->
-<!-- checkpoint: done -->
-
-Migrate the sole import and peerDependencies from `@mariozechner/*` to `@earendil-works/pi-coding-agent`, dropping the two unused deps (`pi-ai`, `pi-tui`).
-
-### Files to modify
-
-1. **`extensions/workflow-guard.ts`** — line 2:
-
-```diff
--import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-```
-
-2. **`package.json`** — `peerDependencies`:
-
-```diff
- "peerDependencies": {
--    "@mariozechner/pi-ai": "*",
--    "@mariozechner/pi-coding-agent": "*",
--    "@mariozechner/pi-tui": "*",
-+    "@earendil-works/pi-coding-agent": "*",
-     "@sinclair/typebox": "*"
- },
-```
-
-### Verify
-
-```bash
-grep -r "@mariozechner" extensions/ package.json
-# Expected: no output
-
-npm run check
-# Expected: passes (lint + tests)
-```
-
-### Commit
-
-```
-chore: migrate from @mariozechner to @earendil-works, drop unused peer deps
-```

package/docs/plans/completed/2026-05-08-migrate-earendil-works-progress.md

@@ -1,10 +0,0 @@
-# Progress: Migrate from @mariozechner to @earendil-works
-
-Plan: docs/plans/2026-05-08-migrate-earendil-works-implementation.md
-Branch: migrate-earendil-works
-Started: 2026-05-08T00:00:00Z
-Last updated: 2026-05-08T00:02:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Update package scope and clean up peer dependencies (checkpoint: done) | 0a29af0 |

package/docs/plans/completed/2026-05-08-worktree-handoff-design.md

@@ -1,118 +0,0 @@
-# Worktree Handoff: Stop & Restart in New Directory
-
-## Problem
-
-When the user asks the agent to create a worktree during `executing-tasks`, the agent creates the worktree on disk but continues running in the original directory. All subsequent file operations, git commands, and task execution happen in the wrong place.
-
-Pi sessions are tied to their working directory — the agent cannot `cd` or spawn a sub-session in a different directory.
-
-## Root cause
-
-The `executing-tasks` skill creates the worktree (step 2) then continues executing tasks in the original directory instead of stopping and handing off to a new session.
-
-## Solution
-
-When the user chooses worktree isolation in `executing-tasks`, the agent:
-
-1. Creates the worktree
-2. Moves all plan docs into the worktree
-3. Commits the removal on the current branch
-4. Stops and tells the user to restart in the worktree
-
-The new session in the worktree finds the plan docs and continues seamlessly.
-
-## Changes
-
-### `skills/executing-tasks/SKILL.md`
-
-Replace step 2 ("Suggest workspace isolation") with a "Create & handoff" pattern for worktrees:
-
-```
-2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
-
-   - **Branch** (smaller changes):
-     ```
-     git checkout -b <feature-name>
-     ```
-
-   - **Worktree** (larger features, keeps main clean):
-     ```
-     git worktree add ../<repo>-<feature-name> -b <feature-name>
-     ```
-
-   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
-
-3. **If worktree was chosen — hand off to new session:**
-
-   a. Move plan docs into the worktree:
-      ```
-      mv docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
-      ```
-
-   b. Commit the removal on the current branch (if files were committed):
-      ```
-      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
-      git rm -r docs/plans/adr/ 2>/dev/null || true
-      git commit -m "chore: move plan docs to worktree for <feature-name>"
-      ```
-
-   c. Stop and show the user:
-      ```
-      ✅ Worktree created at ../<repo>-<feature-name>
-      📄 Plan docs moved to the worktree.
-
-      To continue, start a new session there:
-        cd ../<repo>-<feature-name> && pi
-
-      Then run: /skill:executing-tasks
-      ```
-
-   d. **Do not proceed with task execution.** The session ends here.
-```
-
-Remove the current step 3–4 numbering (progress file, commit plan docs) and renumber to account for the new handoff step. The "First run" flow becomes:
-
-1. Parse the implementation plan
-2. Suggest workspace isolation (branch or worktree)
-3. **If branch:** create progress file, commit plan docs, begin execution (existing flow)
-4. **If worktree:** move docs, commit removal, stop with handoff message (new flow)
-
-### No changes to other skills
-
-- `brainstorming` — read-only phase, no isolation needed
-- `writing-plans` — read-only phase, no isolation needed
-- `finalizing` — already handles worktree cleanup (`git worktree remove`)
-
-## User experience
-
-### Branch isolation (unchanged)
-
-```
-Agent: Would you like branch or worktree isolation?
-User: branch
-Agent: [creates branch, creates progress file, begins executing tasks]
-```
-
-### Worktree isolation (new)
-
-```
-Agent: Would you like branch or worktree isolation?
-User: worktree
-Agent: ✅ Worktree created at ../my-repo-auth
-       📄 Plan docs moved to the worktree.
-
-       To continue, start a new session there:
-         cd ../my-repo-auth && pi
-
-       Then run: /skill:executing-tasks
-```
-
-User opens a new terminal, runs the commands, and the new session picks up where the old one left off.
-
-## Edge cases
-
-- **No plan docs exist yet** — just create the worktree, don't try to move files
-- **Partial progress (some tasks done)** — progress file is moved, preserving state
-- **Uncommitted plan docs** — `mv` removes them, no `git rm` needed; commit only if they were previously committed
-- **Other uncommitted changes on current branch** — only touch plan docs, leave everything else untouched

package/docs/plans/completed/2026-05-08-worktree-handoff-implementation.md

@@ -1,140 +0,0 @@
-# Implementation Plan: Worktree Handoff
-
-## Overview
-
-Modify `skills/executing-tasks/SKILL.md` so that when the user chooses worktree isolation, the agent moves plan docs to the worktree, commits the removal, and stops with a handoff message instead of continuing execution in the wrong directory.
-
-**Design doc:** `docs/plans/2026-05-08-worktree-handoff-design.md`
-
----
-
-## Task 1: Add worktree handoff flow to executing-tasks
-
-<!-- tdd: trivial -->
-<!-- checkpoint: none -->
-
-Modify the "First run" section of `skills/executing-tasks/SKILL.md`. After the workspace isolation prompt (step 2), add a branching path: if the user chose worktree, move docs and stop; if branch, continue with existing flow.
-
-### File: `skills/executing-tasks/SKILL.md`
-
-Replace the current steps 2–5 in the "First run" section:
-
-```markdown
-2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
-
-   - **Branch** (smaller changes):
-     ```
-     git checkout -b <feature-name>
-     ```
-   - **Worktree** (larger features, keeps main clean):
-     ```
-     git worktree add ../<repo>-<feature-name> -b <feature-name>
-     ```
-
-   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
-
-3. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
-
-   ```markdown
-   # Progress: <topic>
-
-   Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-   Branch: <actual branch name>
-   Started: <ISO timestamp>
-   Last updated: <ISO timestamp>
-
-   | # | Status | Task | Commit |
-   |---|--------|------|--------|
-   | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-   ```
-
-   Use the actual branch name — whether it's the original branch or a new one from the isolation step.
-
-4. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
-   ```
-   git add docs/plans/ && git commit -m "docs: add design and implementation plan"
-   ```
-
-5. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task-execution)).
-```
-
-With:
-
-```markdown
-2. **Suggest workspace isolation** — if the user isn't already on a feature branch or worktree, present the options:
-
-   - **Branch** (smaller changes):
-     ```
-     git checkout -b <feature-name>
-     ```
-   - **Worktree** (larger features, keeps main clean):
-     ```
-     git worktree add ../<repo>-<feature-name> -b <feature-name>
-     ```
-
-   Derive `<feature-name>` from the plan doc (e.g. `docs/plans/2026-04-16-auth-design.md` → `auth`). Ask the user which they prefer, then wait for confirmation before proceeding.
-
-3. **If worktree was chosen — hand off to new session:**
-
-   a. Ensure the worktree's `docs/plans/` directory exists:
-      ```
-      mkdir -p <worktree>/docs/plans
-      mkdir -p <worktree>/docs/plans/adr
-      ```
-
-   b. Move plan docs into the worktree:
-      ```
-      mv docs/plans/*-design.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-implementation.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/*-progress.md <worktree>/docs/plans/ 2>/dev/null || true
-      mv docs/plans/adr/*.md <worktree>/docs/plans/adr/ 2>/dev/null || true
-      ```
-
-   c. Commit the removal on the current branch (if any plan docs were committed):
-      ```
-      git rm docs/plans/*-design.md docs/plans/*-implementation.md docs/plans/*-progress.md 2>/dev/null || true
-      git rm -r docs/plans/adr/ 2>/dev/null || true
-      git commit -m "chore: move plan docs to worktree for <feature-name>"
-      ```
-
-   d. Stop and show the user:
-      ```
-      ✅ Worktree created at ../<repo>-<feature-name>
-      📄 Plan docs moved to the worktree.
-
-      To continue, start a new session there:
-        cd ../<repo>-<feature-name> && pi
-
-      Then run: /skill:executing-tasks
-      ```
-
-   e. **Do not proceed with task execution.** The session ends here.
-
-4. **If branch was chosen — continue with execution:**
-
-   a. **Create the progress file** — save to `docs/plans/<plan-name>-progress.md` (replace `-implementation` with `-progress` in the plan filename):
-
-      ```markdown
-      # Progress: <topic>
-
-      Plan: docs/plans/YYYY-MM-DD-<topic>-implementation.md
-      Branch: <actual branch name>
-      Started: <ISO timestamp>
-      Last updated: <ISO timestamp>
-
-      | # | Status | Task | Commit |
-      |---|--------|------|--------|
-      | 1 | ⬜ pending | Task description (preserve checkpoint labels) | — |
-      ```
-
-      Use the actual branch name — whether it's the original branch or a new one from the isolation step.
-
-   b. **Commit the plan docs** — if `docs/plans/` has uncommitted files, commit them on the new branch:
-      ```
-      git add docs/plans/ && git commit -m "docs: add design and implementation plan"
-      ```
-
-   c. **Begin task execution** — start with task 1 (see [Per-task execution](#per-task execution)).
-```
-
-**Commit:** `feat(executing-tasks): add worktree handoff with plan doc migration`

package/docs/plans/completed/2026-05-08-worktree-handoff-progress.md

@@ -1,10 +0,0 @@
-# Progress: Worktree Handoff
-
-Plan: docs/plans/2026-05-08-worktree-handoff-implementation.md
-Branch: main
-Started: 2026-05-08T00:00:00Z
-Last updated: 2026-05-08T00:00:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Add worktree handoff flow to executing-tasks | 2ce48e7 |

package/docs/plans/completed/2026-05-20-generic-lessons-design.md

@@ -1,70 +0,0 @@
-# Design: Enforce Generic Lessons in `docs/lessons.md`
-
-## Problem
-
-During `executing-tasks`, the agent writes lessons to `docs/lessons.md` scoped to the task at hand. In a monorepo, this produces domain-specific rules that are only useful within one feature or sprint — for example:
-
-> "Always validate `userId` before calling `UserProfile.Get`"
-
-The real lesson — applicable across any domain — would be:
-
-> "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
-
-Domain-specific rules decay immediately after the feature is done and pollute the lessons file for future work.
-
-## Goal
-
-Rules in `docs/lessons.md` should be generic patterns applicable to any domain or feature in the repo, not instances of a pattern tied to one service or entity.
-
-## Affected files
-
-- `skills/executing-tasks/SKILL.md`
-- `skills/finalizing/SKILL.md`
-
-## Changes
-
-### 1. `executing-tasks` — Step 6 "Learn from mistakes"
-
-Add a **generalization test** after "Only add rules that would change future behavior."
-
-```
-Before writing, apply the **generalization test**: would this rule apply equally to a
-completely different feature or domain in this repo? If not, rewrite it — strip out
-specific service names, entity types, and domain concepts, and express the underlying
-pattern instead. If you can't express a generic form, don't write the rule.
-
-❌ Domain-specific (only survives this sprint):
-   "Always validate `userId` before calling `UserProfile.Get`"
-
-✅ Generic (applies across the whole repo):
-   "Always validate required ID fields at the service boundary — missing IDs should
-    return 400, not 500"
-```
-
-### 2. `executing-tasks` — `docs/lessons.md` format template comment
-
-Add one line to the comment block so the constraint is visible every time the agent opens the file:
-
-```
-Rules must be generic patterns applicable to any domain or feature — not specific to
-one service, entity, or use case.
-```
-
-### 3. `finalizing` — Step 2 "Review lessons learned"
-
-Add a generalization audit bullet between "Add any lessons..." and "Retire rules...":
-
-```
-- Generalize domain-specific rules — if a rule names a specific service, entity, or
-  feature, either rewrite it as a generic pattern or remove it if no generic form exists
-```
-
-### 4. `finalizing` — `docs/lessons.md` format template comment
-
-Same addition as change 2 — keep both template definitions consistent.
-
-## Slice summary
-
-One end-to-end slice:
-
-> **Lessons stay generic** — at write-time (executing-tasks step 6) the agent is required to generalize before writing; the file's own comment reinforces the constraint; at finalization the agent audits and cleans up anything that slipped through.

package/docs/plans/completed/2026-05-20-generic-lessons-implementation.md

@@ -1,114 +0,0 @@
-# Implementation Plan: Enforce Generic Lessons in `docs/lessons.md`
-
-Design: docs/plans/2026-05-20-generic-lessons-design.md
-
-Two skill files need four text edits total. No tests (markdown-only changes). Both
-tasks are trivial — exact old/new text is specified so the executor can apply them
-without guessing.
-
----
-
-## Task 1: Add generalization test + update format comment in `executing-tasks`
-
-<!-- tdd: trivial -->
-
-File: `skills/executing-tasks/SKILL.md`
-
-Two edits in one file:
-
-### Edit A — Step 6 "Learn from mistakes"
-
-Replace:
-```
-6. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
-```
-
-With:
-```
-6. **Learn from mistakes** — if you caught yourself making a mistake during this task that you've made before or that would apply to future tasks, append a rule to `docs/lessons.md`. Only add rules that would change future behavior. If the file doesn't exist, create it with the standard format (see below).
-
-   Before writing, apply the **generalization test**: would this rule apply equally to a completely different feature or domain in this repo? If not, rewrite it — strip out specific service names, entity types, and domain concepts, and express the underlying pattern instead. If you can't express a generic form, don't write the rule.
-
-   ❌ **Domain-specific** (only survives this sprint):
-   > "Always validate `userId` before calling `UserProfile.Get`"
-
-   ✅ **Generic** (applies across the whole repo):
-   > "Always validate required ID fields at the service boundary — missing IDs should return 400, not 500"
-```
-
-### Edit B — `docs/lessons.md` format template comment
-
-Replace:
-```
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Retire rules that no longer apply during finalizing.
--->
-```
-
-With:
-```
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
-Retire rules that no longer apply during finalizing.
--->
-```
-
-Steps:
-1. Apply Edit A to `skills/executing-tasks/SKILL.md`
-2. Apply Edit B to `skills/executing-tasks/SKILL.md`
-3. Verify: open the file and confirm both edits are present and the surrounding text is intact
-
----
-
-## Task 2: Add generalization audit bullet + update format comment in `finalizing`
-
-<!-- tdd: trivial -->
-
-File: `skills/finalizing/SKILL.md`
-
-Two edits in one file:
-
-### Edit A — Step 2 "Review lessons learned"
-
-Replace:
-```
-   - Add any lessons from this session that were missed during execution
-   - Retire rules that no longer apply (remove the bullet)
-```
-
-With:
-```
-   - Add any lessons from this session that were missed during execution
-   - **Generalize domain-specific rules** — if a rule names a specific service, entity, or feature, either rewrite it as a generic pattern or remove it if no generic form exists
-   - Retire rules that no longer apply (remove the bullet)
-```
-
-### Edit B — `docs/lessons.md` format template comment
-
-Replace:
-```
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Retire rules that no longer apply during finalizing.
--->
-```
-
-With:
-```
-<!--
-Agent: read this at the start of each task during executing-tasks.
-Follow every rule. Add new rules when you catch yourself making repeat mistakes.
-Rules must be generic patterns applicable to any domain or feature — not specific to one service, entity, or use case.
-Retire rules that no longer apply during finalizing.
--->
-```
-
-Steps:
-1. Apply Edit A to `skills/finalizing/SKILL.md`
-2. Apply Edit B to `skills/finalizing/SKILL.md`
-3. Verify: open the file and confirm both edits are present and the surrounding text is intact

package/docs/plans/completed/2026-05-20-generic-lessons-progress.md

@@ -1,11 +0,0 @@
-# Progress: generic-lessons
-
-Plan: docs/plans/2026-05-20-generic-lessons-implementation.md
-Branch: generic-lessons
-Started: 2026-05-20T00:00:00Z
-Last updated: 2026-05-20T00:00:00Z
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Add generalization test + update format comment in `executing-tasks` | 96010f7 |
-| 2 | ✅ done | Add generalization audit bullet + update format comment in `finalizing` | 72f088d |

package/docs/plans/completed/2026-05-22-agentic-agile-enhancements-design.md

@@ -1,77 +0,0 @@
-# Design: Agentic Agile & Architectural Rigor Enhancements
-
-Enforcing rigorous Agile engineering discipline within `pi-workflow-kit` by introducing Behavioral Acceptance Criteria, Cognitive Persona Shifts, automated Lessons Curation, strict Multi-Pillar Architectural Reviews, and High-Risk Operation Safeguards.
-
-## Context & Objectives
-Based on industry standards and modern agentic development templates (such as Microsoft's Agentic Agile model), autonomous coding agents succeed most when operating under tight behavioral boundaries, specialized cognitive roles, and continuous retro/learning loops.
-
-We are enhancing `pi-workflow-kit` by mapping out distinct engineering "Hats" and rigorous check-gates directly into our existing phase-based skills without adding repository clutter or introducing flaky external file lookups:
-1. **The QA Engineer Hat** (in `writing-plans`): Defines rigid, testable `Given/When/Then` Acceptance Criteria for both happy and edge paths during planning.
-2. **The Pragmatic Developer & Senior Refactorer Hats** (in `executing-tasks`): Guides the execution loop through clear cognitive phases (Green Light → Polish / Software Craftsmanship).
-3. **The Agile Scrum Master Hat** (in `finalizing`): Cleans up, de-duplicates, and categorizes persistent lessons to prevent context-bloat and maximize the utility of future sprints.
-4. **Architectural Review & Audit Gates**: Formally audits both the design (brainstorming) and the plan (writing-plans) against the 6 core pillars of production-grade software (Robustness, Atomicity, Security, Scalability, Compatibility, and Testability) before allowing the agent to move forward.
-5. **High-Risk Operation Safeguards**: Auto-detects critical execution hazards (unbounded Redis scans, in-memory OOM loops, unthrottled concurrency, long-running transactions, etc.) and mandates strict mitigation steps and verification checkpoints.
-
----
-
-## Architecture & Detailed Design
-
-Because agent workspaces default tool execution and file-reading relative to the user's project directory, external files bundled in NPM global modules are not reliably reachable. Therefore, all guidelines are **inlined directly within the respective `SKILL.md` prompts**. This guarantees 100% reliability, zero repository pollution, and zero runtime performance overhead.
-
-### Slice 1: Multi-Pillar Design Review & Risk Detection (`brainstorming`)
-Before concluding a brainstorm and generating a design doc, the agent must put on its **Architect Hat** and evaluate the proposed system against the **6 Pillars of Production-Grade Design**:
-1. **Robustness & Fault Tolerance**: How expected failures are handled, subsystem isolation, and graceful degradation.
-2. **Atomicity & Consistency**: Database transactions, state rollback on error, and endpoint idempotency.
-3. **Security & Access Control**: Input validation/sanitization and authorization checks at the boundary.
-4. **Scalability & Performance**: Connection pooling, closing resource leaks, and preventing N+1 queries.
-5. **Backwards Compatibility**: Schema migration safety, zero-downtime deployment, and API versioning.
-6. **Testability**: Injection seams for external dependencies (APIs, system clocks, randomizers) to keep tests 100% deterministic.
-
-#### ⚠️ High-Risk Hazard Auditing
-The agent must proactively audit the design for the **8 High-Risk Production Hazards**:
-1. **Unbounded Redis Deletions / Operations**: Multi-key deletion or scans (e.g. `KEYS` or raw `SCAN` loops) that block single-threaded performance.
-2. **In-Memory OOM Loops**: Fetching complete database datasets into server memory (e.g., raw `select *`) to filter, sort, or map in runtime heap.
-3. **Unbounded Concurrency Spikes**: Running concurrent network requests (e.g. unthrottled `Promise.all`) without strict batch limits (e.g., `p-limit`).
-4. **Missing High-Frequency Indexes**: Running queries on unindexed columns, forcing expensive table-scans under load.
-5. **Nested/Long-Running Transactions**: Holding database connections and locks open while awaiting slow external HTTP, disk, or cryptographic tasks.
-6. **Unrestricted Uploads & Temp Flooding**: Writing uploaded data directly to local temporary paths without validation limits or explicit `finally` cleanup blocks.
-7. **Raw Query String Interpolation**: Merging raw variables into SQL queries or shell command inputs (susceptible to injection).
-8. **Silent Swallowing loops**: Background workers or cron tasks silently catching and suppressing exceptions without logging, back-offs, or alerts.
-
-#### 🔍 Discovering Unknown & Contextual Risks (Socratic Heuristics)
-To identify novel or domain-specific risks that fall outside the standard checklist, the agent must put on its **SRE Hat** and audit the proposed logic against the **3 Socratic Heuristics**:
-* **The "Scale to 100x" Heuristic (Resource Exhaustion)**: If this operation is run 100x/sec or on 100k items, what breaks? (Memory, CPU, Disk I/O, sockets, database connection limits).
-* **The "Hostile World" Heuristic (Security & Malice)**: If a malicious actor has complete control over these inputs (headers, payloads, IDs), how can they exploit, crash, or extract data?
-* **The "Silent Error" Heuristic (Observability & Partitioning)**: If this downstream dependency or query hangs or fails silently, how does our server react? Is there a timeout, a back-off, or logging?
-
-If any of the standard hazards or Socratic risks are identified, the design document **must** include a dedicated `⚠️ High-Risk Operations & Mitigations` section detailing the exact safety protocols applied.
-
-### Slice 2: Behavioral Acceptance Criteria & Plan Audit (`writing-plans`)
-The planning process is enhanced to mandate behavior-driven specifications and an automated plan verification step.
-
-- **Role**: QA Engineer Hat.
-- **Specification Format**: Mandatory `Given/When/Then` blocks covering the Happy Path and Edge/Error Paths.
-- **Plan Acceptance Audit**: Before presenting the plan to the user, the agent must verify:
-  - Every task is a complete vertical slice.
-  - Sizing is correct (no monolithic tasks).
-  - Checkpoint gates are placed on the most critical/risky tasks.
-  - **Risk Enforcement**: Any task containing any of the **8 High-Risk Hazards** or **Socratic Heuristics risks** is strictly required to have a mandatory `checkpoint: done` gate and explicit verification guidelines.
-
-### Slice 3: Cognitive Persona Shifts (`executing-tasks`)
-The implementation execution loop is updated to divide the cognitive workload of a single task into three distinct phases.
-
-- **Phase 1: QA Test Phase**: Translate the Given/When/Then specs into failing test cases.
-- **Phase 2: Pragmatic Developer Phase**: Implement the simplest, raw code to green the tests.
-- **Phase 3: Senior Refactoring Phase**: Refactor and polish using software craftsmanship principles (Shallow Modules, Deletion Test, Duplication, Seam Discipline).
-
-### Slice 4: Lessons Curation & Caching (`finalizing`)
-The finalizing phase is upgraded to run a structured retrospective on our persistent learning files.
-
-- **Role**: Agile Scrum Master Hat.
-- **Curating Rules**: De-duplicate, validate against the Generalization Test, and categorize rules under distinct headers (e.g., `# Tool Usage`, `# Testing Patterns`, `# Architecture Rules`).
-
----
-
-## Verification & Testing Plan
-- **Manual Verification**: Run a mock `/skill:writing-plans` and `/skill:executing-tasks` to verify the generated implementation plan matches our QA template and the task-running agent correctly segments its progress through the three cognitive hats.
-- **Automated Tests**: Confirm existing Vitest suites run successfully without side-effects.