@tianhai/pi-workflow-kit 0.18.1 → 1.1.0

package/docs/plans/completed/2026-06-09-incremental-workflow-and-rename-verification-report.md

@@ -1,81 +0,0 @@
-# Verification Report: Incremental workflow and skill rename
-
-**Date:** 2026-06-09
-**Scope:** 10 commits on `incremental-workflow-and-rename` — pwk- prefix rename, feature-based planning, design-review repositioning, verify phase in workflow-guard
-**Reviewer:** AI verify skill (security + optimization + traceability)
-
-## Summary
-
-| Pass | Critical | High | Medium | Low |
-|------|----------|------|--------|-----|
-| Security | 0 | 0 | 0 | 0 |
-| Optimization | — | 0 | 0 | 3 |
-| Traceability | 0 | 0 | 2 | 1 |
-| **Total** | **0** | **0** | **2** | **4** |
-
-## 🔴 Security Findings
-
-No findings. This is a documentation/configuration-only change — no HTTP endpoints, no SQL queries, no user inputs, no secrets, no auth logic. No external attack surface.
-
-## 🟡 Optimization Findings
-
-### [O-001] P2 — Stale `shouldBlockFilePath` docstring
-
-**Location:** `extensions/workflow-guard.ts:150`
-
-**Issue:** JSDoc says "Only writes under docs/plans/ are allowed during brainstorm and plan phases" — missing the verify phase added in this change.
-
-**Fix:** Change to "...during brainstorm, plan, and verify phases."
-
-### [O-002] P2 — Stale `DESTRUCTIVE_PATTERNS` comment
-
-**Location:** `extensions/workflow-guard.ts:15`
-
-**Issue:** Comment says "Destructive commands blocked in brainstorm/plan phases" — missing verify.
-
-**Fix:** Change to "...in brainstorm/plan/verify phases."
-
-### [O-003] P2 — Inconsistent backtick formatting
-
-**Location:** `skills/pwk-executing-tasks/SKILL.md:158`
-
-**Issue:** `**Read \`docs/lessons.md\` if it exists**` is missing the closing backtick. All other skills use backtick-enclosed format: `**Read \`docs/lessons.md\`**`.
-
-**Fix:** Add closing backtick: `**Read \`docs/lessons.md\` if it exists**`
-
-## 🔵 Traceability Findings
-
-### [T-001] Medium — `writing-plans` hazard check runs before feature identification
-
-**Location:** `skills/pwk-writing-plans/SKILL.md:11-27`
-
-**Issue:** Step 1 evaluates the hazard checklist (database, auth, etc.) *before* reading the Features table to identify the next `⬜ pending` feature. The hazard prompt says "This feature involves..." but the feature isn't known yet. Flow is: read design doc → evaluate hazards → *then* read Features table → mark `🔄 planned`.
-
-**Fix:** Move the Features table reading before the hazard check. Flow should be: read design doc → find next `⬜ pending` feature → mark `🔄 planned` → *then* evaluate hazards for that specific feature.
-
-### [T-002] Medium — `executing-tasks` step 2 re-reads full Features table every task
-
-**Location:** `skills/pwk-executing-tasks/SKILL.md:158`
-
-**Issue:** Per-task step 2 says "Read the design doc's Features table for context on the overall feature set." This re-reads the entire table on every task execution — redundant and imprecise.
-
-**Fix:** Change to "skim the Features table for current feature status" to avoid re-processing the whole table.
-
-### [T-003] Low — `design-review` trivial case may target nonexistent plan doc
-
-**Location:** `skills/pwk-design-review/SKILL.md:12-22`
-
-**Issue:** Step 1 allows proceeding if either doc exists. Step 2 says to append to the plan doc. If only the design doc exists (no plan doc yet), the agent would try to append to a nonexistent file. Edge case since design-review runs after writing-plans, but the instructions don't enforce this.
-
-**Fix:** In step 2, add: "If no plan doc exists, skip and say: 'No plan doc found. Run `/skill:pwk-writing-plans` first.'"
-
-## Remediation Task List
-
-| ID | Priority | Finding | Estimated Effort |
-|----|----------|---------|-----------------|
-| O-001 | P2 | Stale `shouldBlockFilePath` docstring missing verify | small |
-| O-002 | P2 | Stale `DESTRUCTIVE_PATTERNS` comment missing verify | small |
-| O-003 | P2 | Missing closing backtick in executing-tasks lessons reference | small |
-| T-001 | Medium | Hazard check ordering in writing-plans (should run after feature identification) | small |
-| T-002 | Medium | executing-tasks re-reads full Features table every task | small |
-| T-003 | Low | design-review trivial case may target nonexistent plan doc | small |

package/docs/plans/completed/2026-06-09-verification-fixes-implementation.md

@@ -1,69 +0,0 @@
-# Implementation Plan: Verification findings fix
-
-## Overview
-
-Fix 6 findings from `docs/plans/2026-06-09-incremental-workflow-and-rename-verification-report.md`.
-
-All findings are small effort — documentation/comment fixes and minor instruction reordering.
-
-## Task 1: Fix stale comments in workflow-guard.ts
-
-<!-- tdd: trivial -->
-
-Fix O-001 and O-002.
-
-Files:
-- `extensions/workflow-guard.ts`
-
-Steps:
-1. Change `shouldBlockFilePath` JSDoc: "during brainstorm and plan phases" → "during brainstorm, plan, and verify phases"
-2. Change `DESTRUCTIVE_PATTERNS` comment: "blocked in brainstorm/plan phases" → "blocked in brainstorm/plan/verify phases"
-
-## Task 2: Fix backtick formatting in executing-tasks
-
-<!-- tdd: trivial -->
-
-Fix O-003.
-
-Files:
-- `skills/pwk-executing-tasks/SKILL.md`
-
-Steps:
-1. In per-task step 2, change `**Read \`docs/lessons.md` if it exists**` to `**Read \`docs/lessons.md\` if it exists**` (add closing backtick)
-
-## Task 3: Reorder writing-plans hazard check after feature identification
-
-<!-- tdd: trivial -->
-
-Fix T-001. The hazard checklist currently runs before reading the Features table. Move the Features table reading to before the hazard check so the prompt can say "This feature involves..." accurately.
-
-Files:
-- `skills/pwk-writing-plans/SKILL.md`
-
-Steps:
-1. Move the Features table paragraph (currently at the end of step 1) to just after the design doc reading, before the hazard checklist
-2. Verify the flow is now: read design doc → find next `⬜ pending` feature → mark `🔄 planned` → evaluate hazards for that feature
-
-## Task 4: Narrow executing-tasks Features table read
-
-<!-- tdd: trivial -->
-
-Fix T-002.
-
-Files:
-- `skills/pwk-executing-tasks/SKILL.md`
-
-Steps:
-1. In per-task step 2, change "Read the design doc's Features table for context on the overall feature set" to "Check the current feature's status in the design doc's Features table"
-
-## Task 5: Add plan doc guard to design-review trivial case
-
-<!-- tdd: trivial -->
-
-Fix T-003.
-
-Files:
-- `skills/pwk-design-review/SKILL.md`
-
-Steps:
-1. In step 2, add a guard before the triviality check: "If no plan doc was found in step 1, skip this check and say: 'No plan doc found to append to. Run `/skill:pwk-writing-plans` first.' and stop."

package/docs/plans/completed/2026-06-09-verification-fixes-progress.md

@@ -1,14 +0,0 @@
-# Progress: Verification fixes
-
-Plan: docs/plans/2026-06-09-verification-fixes-implementation.md
-Branch: incremental-workflow-and-rename
-Started: 2026-06-09T23:10:00
-Last updated: 2026-06-09T23:10:00
-
-| # | Status | Task | Commit |
-|---|--------|------|--------|
-| 1 | ✅ done | Fix stale comments in workflow-guard.ts (O-001, O-002) | c5ab39f |
-| 2 | ✅ done | Fix backtick formatting in executing-tasks (O-003) | c5ab39f |
-| 3 | ✅ done | Reorder writing-plans hazard check after feature identification (T-001) | c5ab39f |
-| 4 | ✅ done | Narrow executing-tasks Features table read (T-002) | c5ab39f |
-| 5 | ✅ done | Add plan doc guard to design-review trivial case (T-003) | c5ab39f |

package/skills/pwk-design-review/SKILL.md

@@ -1,115 +0,0 @@
----
-name: pwk-design-review
-description: "Audit a plan and design doc for production risks — security, scalability, fault tolerance, and operational hazards. Use after writing-plans for non-trivial features, when the plan has concrete code that makes hazard checks meaningful."
----
-
-# Design Review
-
-Read-only exploration of the design and plan docs. You **may** edit the plan doc to append review findings. You may **not** edit source code or configuration.
-
-## Process
-
-1. **Find the design and plan docs** — look for `docs/plans/*-design.md` and `docs/plans/*-implementation.md`. If neither exists, say "No design or plan doc found. Run `/skill:pwk-brainstorming` first." and stop. Read the plan doc for concrete code context alongside the design doc for architectural context.
-
-2. **Check triviality** — if a plan doc was found in step 1 and the design doc notes "Simple change — no design review needed", append a brief section to the plan doc:
-
-   ```markdown
-   ## Architectural Review
-
-   **Status**: Skipped — trivial change. No high-risk operations detected.
-   ```
-
-   Then say: "Review complete — no action needed. Ready to execute? Run `/skill:pwk-executing-tasks`" and stop.
-
-   If no plan doc was found, skip this check and say: "No plan doc found to append to. Run `/skill:pwk-writing-plans` first." and stop.
-
-3. **Read the design and plan docs in full** — understand the architecture from the design doc, and concrete code from the plan doc. The plan doc's implementation details (SQL queries, type definitions, function bodies) are what the hazard checks audit.
-
-4. **🏛️ Architectural Pillars Review** — evaluate the design against the 6 Pillars of Production-Grade Design:
-
-   1. **Robustness & Fault Tolerance**: How expected failures are handled, subsystem isolation, graceful degradation.
-   2. **Atomicity & Consistency**: Database transactions, state rollback on error, endpoint idempotency.
-   3. **Security & Access Control**: Input validation/sanitization, authorization checks at the boundary.
-   4. **Scalability & Performance**: Connection pooling, closing resource leaks, preventing N+1 queries.
-   5. **Backwards Compatibility**: Schema migration safety, zero-downtime deployment, API versioning.
-   6. **Testability**: Injection seams for external dependencies (APIs, system clocks, randomizers) to keep tests 100% deterministic.
-
-   For each pillar, write a 1-2 sentence assessment. Flag any concerns.
-
-5. **⚠️ High-Risk Hazard Audit** — evaluate the design against the 8 High-Risk Production Hazards. For each hazard, write either `[SAFE]` (with a 1-sentence justification) or `[TRIGGERED]` (detailing the mitigation):
-
-   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.
-   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.
-
-6. **🔍 Socratic Risk Discovery** — put on your **SRE Hat** and audit the proposed logic against 3 heuristics to identify novel or domain-specific risks:
-
-   - **The "Scale to 100x" Heuristic**: 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**: 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**: If this downstream dependency or query hangs or fails silently, how does our server react? Is there a timeout, a back-off, or logging?
-
-   For each heuristic, note any risks discovered. If a risk overlaps with a triggered hazard, cross-reference it.
-
-7. **Present findings** — show the full review to the user. For each triggered hazard or Socratic risk, propose a concrete mitigation. Wait for user feedback and incorporate changes.
-
-8. **Append to plan doc** — add a `## Architectural Review` section to the plan doc (not the design doc — review is per-feature, and the plan doc is the per-feature artifact). Two cases:
-
-   **All clear** (no hazards triggered, no Socratic risks):
-   ```markdown
-   ## Architectural Review
-
-   **Status**: ✅ No high-risk hazards detected.
-
-   **Pillars reviewed**: All 6 — no concerns.
-   **Hazards audited**: All 8 [SAFE].
-   **Socratic risks**: None identified.
-   ```
-
-   **Hazards or risks found**:
-   ```markdown
-   ## Architectural Review
-
-   **Status**: ⚠️ High-risk operations detected — see mitigations below.
-
-   ### Pillar Assessments
-   - **Robustness**: [assessment]
-   - **Atomicity**: [assessment]
-   - **Security**: [assessment]
-   - **Scalability**: [assessment]
-   - **Backwards Compatibility**: [assessment]
-   - **Testability**: [assessment]
-
-   ### Hazard Audit
-   - 1. Unbounded Redis: [SAFE / TRIGGERED — mitigation]
-   - 2. In-Memory OOM: [SAFE / TRIGGERED — mitigation]
-   - 3. Unbounded Concurrency: [SAFE / TRIGGERED — mitigation]
-   - 4. Missing Indexes: [SAFE / TRIGGERED — mitigation]
-   - 5. Long-Running Transactions: [SAFE / TRIGGERED — mitigation]
-   - 6. Unrestricted Uploads: [SAFE / TRIGGERED — mitigation]
-   - 7. Query Interpolation: [SAFE / TRIGGERED — mitigation]
-   - 8. Silent Swallowing: [SAFE / TRIGGERED — mitigation]
-
-   ### ⚠️ High-Risk Operations & Mitigations
-   [Detailed mitigation for each TRIGGERED hazard and Socratic risk]
-
-   ### Socratic Risks
-   - **Scale to 100x**: [finding or "none identified"]
-   - **Hostile World**: [finding or "none identified"]
-   - **Silent Error**: [finding or "none identified"]
-   ```
-
-## Principles
-
-- Be specific — every `[TRIGGERED]` hazard must include a concrete mitigation, not just "be careful"
-- Be honest — if the design is risky and the risk can't be mitigated easily, say so
-- Be proportional — a simple CRUD endpoint doesn't need the same depth as a batch processing pipeline
-- Don't redesign — flag risks and propose mitigations, but the design owner decides
-
-## After the review
-
-Ask: "Review complete. Ready to execute? Run `/skill:pwk-executing-tasks`"

package/skills/pwk-verify/SKILL.md

@@ -1,170 +0,0 @@
----
-name: pwk-verify
-description: "Post-implementation code verification with three expert review passes — security, optimization, and traceability. Use after executing-tasks and before finalizing to catch issues that pass tests but break in production. Runs the 'last prompt' pattern: adversarial security review, dead code and duplication audit, and end-to-end contract verification across every layer. Use this skill whenever the user says 'verify', 'review the code', 'check for issues', 'security review', 'the last prompt', 'audit', or when code has been implemented and needs a quality gate before shipping."
----
-
-# Verify
-
-Three expert review passes over the implemented codebase. Read-only — you **may** write the verification report to `docs/plans/`, but you **may not** modify source code.
-
-The core insight: code that passes tests is not code that's ready. Working code can have security holes, dead branches, duplicated logic, and broken contracts between layers — especially when AI generates across many files without maintaining a single mental model of the whole system. This skill catches what tests miss.
-
-## Process
-
-1. **Check what's been done** — run `git log --oneline` and `git diff --stat` to understand the scope of recent changes. If nothing has been implemented, say "No code changes found. Run `/skill:pwk-executing-tasks` first." and stop.
-
-2. **Identify the project's layers** — before reviewing, map the codebase's architecture. Look for layer boundaries: UI/handlers/routes → services/business logic → repositories/data access → database/models. Note the patterns: does the project use controllers, handlers, or routes? Services or use cases? Repositories or DAOs? This map drives the traceability pass.
-
-3. **Run three expert review passes** — each pass adopts a distinct adversarial framing. Do them sequentially. For each pass, read the relevant code deeply — don't skim. Then write findings.
-
-4. **Compile the report** — write all findings to `docs/plans/*-verification-report.md`. Present the report to the user and wait for feedback.
-
-5. **Offer to create a remediation plan** — after the report, ask: "Want me to create a fix plan from these findings? Run `/skill:pwk-writing-plans` to turn the task list into executable tasks."
-
-## Pass 1 — Security Review 🔴
-
-**Framing:** A junior developer wrote this code. Now the best security expert on the team is reviewing it — adversarial, suspicious of everything. Trust nothing.
-
-**What to look for:**
-
-- **Input validation** — every external input (HTTP params, form data, headers, query strings, environment variables) must be validated and sanitized. Unvalidated input is a critical finding.
-- **Authentication & authorization** — every endpoint that handles user data must have auth checks. Are there endpoints that skip auth? Can one user access another user's data by changing an ID?
-- **Injection** — SQL queries built by string concatenation, unsanitized shell commands, template injection, XSS in HTML output. Any raw variable interpolated into a query or command is critical.
-- **Secrets** — API keys, passwords, tokens hardcoded in source files. Check environment variable loading — are defaults set to empty or to actual secrets?
-- **Data exposure** — are sensitive fields (passwords, tokens, PII) logged, returned in API responses, or stored unencrypted?
-- **Dependency risks** — known-vulnerable packages (if `package.json`/`go.mod`/`requirements.txt` is present).
-
-**Severity classification:**
-
-| Severity | Definition |
-|----------|-----------|
-| Critical | Exploitable right now — auth bypass, injection, data leak |
-| High | Likely exploitable — missing validation on sensitive endpoint, weak auth |
-| Medium | Harder to exploit but real risk — verbose error messages leaking internals, missing rate limits |
-| Low | Best practice violations — missing CSP headers, no HSTS, long session timeouts |
-
-## Pass 2 — Optimization Review 🟡
-
-**Framing:** A code quality expert looking for waste — things that make the codebase harder to maintain, slower to run, or more confusing than necessary.
-
-**What to look for:**
-
-- **Dead code** — functions, methods, types, or exports that are never called anywhere in the codebase. Search for definitions and verify they have callers.
-- **Duplication** — the same logic implemented in slightly different ways across multiple files. AI-generated code is especially prone to this — if context was lost between sessions, the AI solved the same sub-problem differently in two places. Flag each pair with file paths and line numbers.
-- **Over-engineering** — abstractions, interfaces, or layers that add complexity without earning their keep (only one implementation, no real variation across the seam).
-- **Under-engineering** — god functions, 200-line blocks, deeply nested conditionals that should be extracted.
-- **Performance concerns** — N+1 queries, unbounded loops, unnecessary copies of large data structures, missing pagination on list endpoints.
-
-**Priority classification:**
-
-| Priority | Definition |
-|----------|-----------|
-| P0 | Dead code in a critical path or duplicated logic that will diverge |
-| P1 | Significant duplication or over-engineering that increases maintenance cost |
-| P2 | Minor cleanups — long functions, missing pagination, style inconsistencies |
-
-## Pass 3 — Traceability Review 🔵
-
-**Framing:** An integration expert tracing every user-facing action end-to-end — from UI to database and back. The AI generates code file-by-file, and the seams between files are where bugs hide.
-
-**What to look for:**
-
-1. **Map every entry point** — list all handlers, routes, controllers, or event listeners that receive external input.
-2. **Trace each call chain** — for each entry point, follow the call: handler → service → repository → database. At each boundary, verify:
-   - **Function name** — does the caller use the exact function name the callee exposes?
-   - **Argument names** — does the caller pass `userId` when the function expects `user_id`? Does `id` mean the same thing in both layers?
-   - **Argument types** — is a string passed where an integer is expected? Is an object shape different from what the next layer destructures?
-   - **Return shape** — does the caller expect fields that the callee actually returns? Are response DTOs consistent across layers?
-3. **Check error propagation** — when a database query returns no results, does the service layer handle it? Does the handler return 404 or 500? Do errors propagate cleanly or get swallowed silently?
-4. **Verify the round-trip** — if the UI calls `getUser(id)` and displays `user.name`, trace that `name` actually exists in the DB schema, gets selected by the query, mapped by the repository, passed through the service, included in the response, and rendered by the UI.
-
-**This is the pass that catches the most bugs.** AI-generated code will often have a frontend calling `getUserProfile(userId)` and a backend exposing `get_user_profile(user_id)` — both work in isolation, neither works together.
-
-**Severity classification:**
-
-| Severity | Definition |
-|----------|-----------|
-| Critical | Call chain is completely broken — function doesn't exist or signature is fundamentally wrong |
-| High | Signature mismatch — wrong arg names, wrong types, missing required fields |
-| Medium | Silent error handling — errors swallowed without logging or user feedback |
-| Low | Inconsistent naming conventions that could confuse future developers |
-
-## Report Format
-
-Write findings to `docs/plans/*-verification-report.md` using this structure:
-
-```markdown
-# Verification Report: <feature/topic>
-
-**Date:** <ISO date>
-**Scope:** <summary of what was reviewed>
-**Reviewer:** AI verify skill (security + optimization + traceability)
-
-## Summary
-
-| Pass | Critical | High | Medium | Low |
-|------|----------|------|--------|-----|
-| Security | X | X | X | X |
-| Optimization | — | X | X | X |
-| Traceability | X | X | X | X |
-| **Total** | **X** | **X** | **X** | **X** |
-
-## 🔴 Security Findings
-
-### [S-001] Critical — <short title>
-
-**Location:** `path/to/file.ts:line`
-
-**Issue:** <what's wrong and why it matters>
-
-**Fix:** <concrete remediation step>
-
-### [S-002] High — <short title>
-...
-
-## 🟡 Optimization Findings
-
-### [O-001] P0 — <short title>
-
-**Location:** `path/to/file.ts:line` and `path/to/other.ts:line`
-
-**Issue:** <what's wrong>
-
-**Fix:** <concrete remediation step>
-
-### [O-002] P1 — <short title>
-...
-
-## 🔵 Traceability Findings
-
-### [T-001] Critical — <short title>
-
-**Entry point:** `path/to/handler.ts:line`
-**Call chain:** handler → service → repository → DB
-**Broken at:** <which boundary>
-**Issue:** <what's wrong — e.g., handler passes `userId` but service expects `user_id`>
-
-**Fix:** <concrete remediation step>
-
-### [T-002] High — <short title>
-...
-
-## Remediation Task List
-
-Convert findings into actionable tasks:
-
-| ID | Priority | Finding | Estimated Effort |
-|----|----------|---------|-----------------|
-| S-001 | Critical | <one-liner> | <small/medium/large> |
-| T-001 | Critical | <one-liner> | <small/medium/large> |
-| O-001 | P0 | <one-liner> | <small/medium/large> |
-| ...
-```
-
-## Principles
-
-- **Be specific** — every finding must include a file path and line reference. "There might be security issues" is useless.
-- **Be adversarial** — actively look for problems. If you don't find any, say so — but don't phone it in.
-- **Be proportional** — a small config change doesn't need the same depth as a new API endpoint. Adjust your review depth to the scope of changes.
-- **Don't fix anything** — this is read-only. Find and report. The user decides what to fix and when.
-- **Focus on seams** — the traceability pass is where the most value lives. Code within a single file is usually coherent; the bugs hide between files.