@tianhai/pi-workflow-kit 0.18.1 → 1.1.0

package/docs/workflow-phases.md

@@ -1,15 +1,13 @@
 # Workflow Phases
 
-`pi-workflow-kit` has 4 phases and 1 utility skill. You invoke each one explicitly with `/skill:`.
+`pi-workflow-kit` has 5 pipeline skills plus 2 utility skills. You invoke each one explicitly with `/skill:`.
 
 ```
-brainstorm → plan → [design-review?] → execute → [verify?] → finalize
+brainstorm → writing-plans → executing-tasks → finalizing
+                          (per requirement: tests → ⏸ checkpoint → implement → ⏸ checkpoint → code-review)
 ```
 
-For complex features, each phase loops per feature:
-```
-brainstorm (name features) → plan next feature → [design-review?] → execute feature → [verify?] → loop...
-```
+A design doc is one PR; a requirement is one testable slice within it. For multi-design work (a large issue split into several design docs — each its own PR), run the pipeline once per design doc.
 
 ## brainstorm
 
@@ -17,50 +15,80 @@ brainstorm (name features) → plan next feature → [design-review?] → execut
 /skill:pwk-brainstorming
 ```
 
-- Explore requirements and shape the design
-- Ask questions one at a time, propose approaches
-- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` with a `## Features` table listing all features and their status
+- Explore requirements and shape the design.
+- Produce `docs/plans/YYYY-MM-DD-<topic>-design.md` — descriptive, opening with a `## Requirements` list, ending with a `## Feature acceptance` section (end-to-end scenarios that prove the requirements compose into the PRD's behavior — the feature's definition-of-done).
+- May split a large issue into multiple design docs (human-approved).
+- ADRs go to `docs/adr/` (permanent, never archived).
 
 Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
 
-## plan
+## writing-plans
 
 ```
 /skill:pwk-writing-plans
 ```
 
-- Read the design doc's Features table, identify the next `⬜ pending` feature
-- Mark it `🔄 planned` and create a per-feature implementation plan
-- Produce `docs/plans/YYYY-MM-DD-<topic>-<feature-name>-implementation.md`
-- Optionally trigger design review for non-trivial features
+- Creates the feature branch first (`git checkout -b <topic>`), so design + plan docs live on the branch, not `main`.
+- Reads the design doc's `## Requirements`; for each, derives **acceptance criteria + integration-test cases** (a behavioral spec, no implementation code), lists requirements in build order (dependencies positioned earlier), and challenges the design when `## Production-risk areas` is present.
+- Derives a **`## Feature acceptance` section** in the plan from the design's Feature acceptance — an end-to-end integration test that exercises the requirements together (distinct from per-requirement tests). If the design has none, stops and asks the human to brainstorm one.
+- Produce `docs/plans/YYYY-MM-DD-<topic>-implementation.md`.
 
-Write boundary: only `docs/plans/` is writable. Source files are hard-blocked.
+Write boundary: only `docs/plans/` is writable.
 
-## execute
+## executing-tasks
 
 ```
 /skill:pwk-executing-tasks
 ```
 
-- Read the plan doc, resolve the design doc and feature row from metadata
-- Implement tasks one at a time: implement → test → fix → commit
-- Mark feature `✅ done` in the design doc's Features table when complete
-- Suggest planning the next feature or verifying
+- Per requirement: write the integration tests (red) → **⏸ checkpoint: tests** → implement to green (full autonomy — the executor chooses structure/signatures/internals) → **⏸ checkpoint: complete** → commit → **per-requirement review** (four parallel reviewers via the `subagent` tool; falls back to inline `/skill:pwk-code-review` when `pi-subagents` is absent — see [code-review](#code-review)).
+- Two **mandatory** human checkpoints per requirement — unless the plan tags a requirement lighter (see [Proportionality](#proportionality)).
+- **Composition check after each commit** — if a requirement touched shared code, the executor runs the full suite now and fixes cross-requirement regressions immediately, rather than discovering them only at the integration gate.
+- Progress tracked in `docs/plans/*-progress.md`.
+- After all requirements: **integration gate** — run the full suite, **run the feature-acceptance test** (the end-to-end check from the plan's `## Feature acceptance` section), and confirm the requirements compose into the feature before `/skill:pwk-finalizing`.
 
 No write restrictions. All tools available.
 
-## finalize
+## Proportionality
+
+The defaults preserve the 1.0.0 behavior (two checkpoints + parallel review per requirement). At plan time the human can tag each requirement lighter to right-size the workflow:
+
+- **Checkpoints** — `full` (both stops, default) | `spec` (tests stop only — cheap spec-correctness gate, implementation covered by review) | `none` (no stops, trivial only). Test-first is preserved either way: even `none` writes tests first (red) and implements to green; only the human *stops* are optional. `spec` requires at least `inline` review (never combine with `skip`).
+- **Review** — `parallel` (four fresh-context reviewers, default) | `inline` (single `pwk-code-review` pass) | `skip` (trivial diffs with no behavioral surface only).
+
+A trivial fix can also skip the multi-turn brainstorm dialogue via the brainstorming trivial fast-path (compress to one turn, minimal design doc) — the guard still enforces read-only. Tags default conservatively, so nothing changes unless the human opts in.
+
+## code-review
+
+```
+/skill:pwk-code-review
+```
+
+The **inline reviewer**: code tracing, spec alignment (vs acceptance criteria), code smells (applies fixes), production hazard check. Unlocked — may modify code to fix smells.
+
+**Not a phase you drive manually.** During `pwk-executing-tasks`, per-requirement review runs **four specialized reviewers in parallel** via the `subagent` tool (spec, tracing, smell, hazard — each fresh-context, read-only reporters); this skill is the **fallback** when [`pi-subagents`](https://pi.dev/packages/pi-subagents) is not installed. You can also invoke `/skill:pwk-code-review` standalone for an ad-hoc review of any diff.
+
+No write restrictions.
+
+## finalizing
 
 ```
 /skill:pwk-finalizing
 ```
 
-- Archive plan docs to `docs/plans/completed/`
-- Update CHANGELOG, README if needed
-- Create PR
-- Clean up worktree if one was used
+- **Pre-check: run the full test suite** — don't ship a red suite (resume spans sessions; don't trust the last execute session).
+- Delete consumed plan docs (per-`<topic>`) — code + tests are the source of truth; ADRs stay at `docs/adr/`.
+- Curate `docs/lessons.md`, update README/CHANGELOG, create PR or merge.
 
-No write restrictions. All tools available.
+No write restrictions.
+
+## status
+
+```
+/skill:pwk-status
+```
+
+Read-only overview of all active pipeline topics (phase + progress) when several designs are in flight. Not a pipeline phase — and it **does not exit the gated phase** (`pwk-status` is read-only; it runs fine under the brainstorm/plan write block, so the boundary stays up).
 
 ## diagnose
 
@@ -68,8 +96,14 @@ No write restrictions. All tools available.
 /skill:pwk-diagnose
 ```
 
-Not a pipeline phase. A utility skill invoked on demand when debugging is needed.
+Not a pipeline phase. A utility skill invoked on demand when debugging is needed. Invoking it **exits the gated phase** — diagnosis needs to write failing tests and `[DEBUG-…]` instrumentation. To stay read-only mid-brainstorm, use `/skill:pwk-status` instead, or re-lock with `/pwk-guard on`.
+
+No write restrictions.
+
+## Manual override
+
+`/pwk-guard on|off|auto` overrides the guard regardless of phase: `on` forces a read-only lock, `off` disables the guard entirely, `auto` (default) returns to skill-driven phases. Subcommands autocomplete. Use it as an escape hatch when the guard blocks something you genuinely need; phase transitions otherwise happen only via `/skill:` commands.
+
+## Continuity across sessions
 
-- Build a feedback loop (failing test, curl script, etc.)
-- Reproduce, hypothesise, instrument, fix, cleanup
-- No write restrictions (used during execute/finalize, or outside the pipeline)
+A new session resumes by invoking the skill for the phase to continue. The skill globs `docs/plans/` for its artifact (progress file / plan doc), resumes the single match, or asks if several. Each resumption skill reports what it found on entry — no registry file needed; the `<topic>` slug in the filenames is the identity.

package/extensions/workflow-guard.ts

@@ -4,14 +4,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 /**
  * Workflow Guard extension.
  *
- * Blocks write/edit outside docs/plans/ and unsafe bash during brainstorm, plan, and verify phases.
- * You control phases explicitly via /skill: commands — no auto-detection,
- * no state persistence, no prompts.
+ * Blocks write/edit outside docs/plans/ and destructive bash during brainstorm and plan phases.
+ * Bash uses a simple common-blacklist (DESTRUCTIVE_PATTERNS) — a command is allowed unless it matches
+ * a destructive pattern. A short phase reminder is appended after the user's message each turn via
+ * before_agent_start. You control phases explicitly via /skill: commands — no auto-detection, no prompts.
  */
 
-type Phase = "brainstorm" | "plan" | "verify" | null;
+type Phase = "brainstorm" | "plan" | null;
 
-// Destructive commands blocked in brainstorm/plan/verify phases
+// Destructive commands blocked in brainstorm/plan phases (simple common blacklist)
 const DESTRUCTIVE_PATTERNS = [
   /\brm\b/i,
   /\brmdir\b/i,
@@ -27,15 +28,22 @@ const DESTRUCTIVE_PATTERNS = [
   /\btruncate\b/i,
   /\bdd\b/i,
   /\bshred\b/i,
-  /(^|[^<])>(?!>)/,
-  />>/,
   /\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
   /\byarn\s+(add|remove|install|publish)/i,
   /\bpnpm\s+(add|remove|install|publish)/i,
   /\bpip\s+(install|uninstall)/i,
   /\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
   /\bbrew\s+(install|uninstall|upgrade)/i,
-  /\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash(?!\s+list)|cherry-pick|revert|tag(?!\s+(-l|--list))|init|clone)/i,
+  // git add/commit/apply merge files and are blocked below. Plain `git branch`/`checkout`/`switch`
+  // only create or move between branches (no source-file changes), so they are intentionally allowed
+  // during gated phases — pwk-writing-plans creates the feature branch before authoring the plan.
+  /\bgit\s+(add|commit|push|pull|merge|rebase|reset|branch\s+-[dD]|stash(?!\s+list)|cherry-pick|revert|tag(?!\s+(-l|--list))|init|clone|apply)/i,
+  // Edit-via-bash vectors: in-place editors, patch appliers, find-delete (bypass the write/edit tool block)
+  /\bsed\b.*\s-i\b/i,
+  /\bperl\b.*\s-[a-z]*i\b/i,
+  /\bawk\b.*-i\s+inplace\b/i,
+  /^\s*patch\b/i, // command-position only — avoids FP on "patch" in paths/searches (grep/cat/cd)
+  /\bfind\b.*\s-delete\b/i,
   /\bsudo\b/i,
   /\bsu\b/i,
   /\bkill\b/i,
@@ -48,73 +56,9 @@ const DESTRUCTIVE_PATTERNS = [
   /^\s*(vim?|nano|emacs|code|subl)\b/i,
 ];
 
-const SAFE_PATTERNS = [
-  /^\s*cat\b/,
-  /^\s*head\b/,
-  /^\s*tail\b/,
-  /^\s*less\b/,
-  /^\s*more\b/,
-  /^\s*grep\b/,
-  /^\s*find\b/,
-  /^\s*ls\b/,
-  /^\s*pwd\b/,
-  /^\s*echo\b/,
-  /^\s*printf\b/,
-  /^\s*wc\b/,
-  /^\s*sort\b/,
-  /^\s*uniq\b/,
-  /^\s*diff\b/,
-  /^\s*file\b/,
-  /^\s*stat\b/,
-  /^\s*du\b/,
-  /^\s*df\b/,
-  /^\s*tree\b/,
-  /^\s*which\b/,
-  /^\s*whereis\b/,
-  /^\s*type\b/,
-  /^\s*env\b/,
-  /^\s*printenv\b/,
-  /^\s*uname\b/,
-  /^\s*whoami\b/,
-  /^\s*id\b/,
-  /^\s*date\b/,
-  /^\s*cal\b/,
-  /^\s*uptime\b/,
-  /^\s*ps\b/,
-  /^\s*top\b/,
-  /^\s*htop\b/,
-  /^\s*free\b/,
-  /^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
-  /^\s*git\s+ls-/i,
-  /^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
-  /^\s*yarn\s+(list|info|why|audit)/i,
-  /^\s*node\s+--version/i,
-  /^\s*python\s+--version/i,
-  /^\s*curl\s/i,
-  /^\s*wget\s+-O\s*-/i,
-  /^\s*jq\b/,
-  /^\s*sed\s+-n/i,
-  /^\s*awk\b/,
-  /^\s*rg\b/,
-  /^\s*fd\b/,
-  /^\s*bat\b/,
-  /^\s*eza\b/,
-  /^\s*cd\b/,
-  /^\s*gh\s+pr\s+(view|list|diff|checks|status)\b/i,
-  /^\s*gh\s+issue\s+(view|list)\b/i,
-  /^\s*gh\s+repo\s+(view|fork|list)\b/i,
-  /^\s*gh\s+release\s+(view|list|download)\b/i,
-  /^\s*gh\s+run\s+(view|list)\b/i,
-  /^\s*git\s+blame\b/,
-  /^\s*git\s+shortlog\b/,
-  /^\s*git\s+stash\s+list\b/i,
-  /^\s*git\s+tag\s+(-l|--list)\b/i,
-  /^\s*git\s+describe\b/,
-  /^\s*go\s+doc\b/,
-  /^\s*go\s+list\b/,
-  /^\s*go\s+version\b/,
-  /^\s*go\s+env\b/,
-];
+// Redirect operators — tested on a quote-stripped command so '>' inside quoted
+// arguments (e.g. grep 'x > y') doesn't false-positive.
+const REDIRECT_PATTERNS = [/(^|[^<])>(?!>)/, />>/];
 
 /** Split a compound command into individual sub-commands.
  * Splits on &&, ||, and ; operators, ignoring leading whitespace.
@@ -134,24 +78,71 @@ function stripHarmlessRedirects(cmd: string): string {
   return cmd.replace(/\s*2\s*>\s*(\/dev\/null|&1)\b/g, "");
 }
 
+/** Blank out single- and double-quoted substrings so operators (>,
+ *  >>, &&) inside quoted arguments don't trigger destructive-pattern
+ *  false-positives. Replaces quoted content and quote chars with spaces,
+ *  preserving length so operators outside quotes still match.
+ *  Advisory only — not a full shell parser. */
+function stripQuoted(cmd: string): string {
+  let out = "";
+  let i = 0;
+  let inQuote = false;
+  while (i < cmd.length) {
+    const ch = cmd[i];
+    const code = cmd.charCodeAt(i);
+    if (inQuote) {
+      if (code === 0x5c) {
+        out += "  ";
+        i += 2;
+        continue;
+      }
+      out += " ";
+      if (code === 0x22 || code === 0x27) {
+        inQuote = false;
+      }
+      i++;
+      continue;
+    }
+    if (code === 0x22 || code === 0x27) {
+      inQuote = true;
+      out += " ";
+      i++;
+      continue;
+    }
+    out += ch;
+    i++;
+  }
+  return out;
+}
+
 export function isSafeCommand(command: string): boolean {
-  const parts = splitCompoundCommand(command);
-  return parts.every((part) => {
+  return splitCompoundCommand(command).every((part) => {
     const cleaned = stripHarmlessRedirects(part);
-    const isDestructive = DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
-    const isSafe = SAFE_PATTERNS.some((p) => p.test(cleaned));
-    return !isDestructive && isSafe;
+    if (REDIRECT_PATTERNS.some((p) => p.test(stripQuoted(cleaned)))) return false;
+    return !DESTRUCTIVE_PATTERNS.some((p) => p.test(cleaned));
   });
 }
 
 const SKILL_TO_PHASE: Record<string, Phase> = {
   "pwk-brainstorming": "brainstorm",
   "pwk-writing-plans": "plan",
-  "pwk-verify": "verify",
+};
+
+/** Skills whose invocation exits a gated phase (used by the input handler; exported for tests/
+ *  skill-lint). Deliberately excludes pwk-status (read-only by design; stays gated). */
+export const UNLOCK_SKILLS = ["pwk-executing-tasks", "pwk-finalizing", "pwk-code-review", "pwk-diagnose"] as const;
+
+/** Phase-aware reminder appended after the user's message each turn while a gated phase is active.
+ *  Returned as a message (not a system-prompt change) so it sits at the tail of the request and
+ *  never invalidates the cached prefix. */
+const PHASE_REMINDERS: Record<Exclude<Phase, null>, string> = {
+  brainstorm:
+    "[pi-workflow-kit] BRAINSTORM phase: read-only. No source edits; writes only under docs/plans/. No mutations.",
+  plan: "[pi-workflow-kit] PLAN phase: read-only. No source edits; writes only under docs/plans/. No mutations.",
 };
 
 /** Determine if a write/edit to filePath should be blocked during the given phase.
- *  Only writes under docs/plans/ are allowed during brainstorm, plan, and verify phases.
+ *  Only writes under docs/plans/ are allowed during brainstorm and plan phases.
  */
 export function shouldBlockFilePath(filePath: string, cwd: string): boolean {
   const absolute = resolve(cwd, filePath);
@@ -164,10 +155,84 @@ export function getCurrentPhase(): Phase {
 }
 
 let phase: Phase = null;
+// True on the turn a gated phase is entered; consumed once by before_agent_start so the reminder
+// is shown only on the first turn of the phase (and re-armed on any later phase change into it).
+let pendingPhaseReminder = false;
+
+/**
+ * Manual guard override set by `/pwk-guard`.
+ * - null  → "auto": enforcement follows the skill-driven phase (default).
+ * - "on"  → force a read-only lock (enforce regardless of phase).
+ * - "off" → disable the guard entirely (escape hatch).
+ * Skill transitions still update `phase` while an override is active, so returning
+ * to `auto` recovers the correct state; enforcement itself ignores `phase`.
+ */
+let guardOverride: "on" | "off" | null = null;
+
+/** Is the guard actively enforcing read-only right now? */
+function enforceActive(): boolean {
+  if (guardOverride === "off") return false;
+  if (guardOverride === "on") return true;
+  return phase !== null;
+}
+
+/** Label for the current enforcement context, used in block reasons and reminders. */
+function enforceLabel(): string {
+  return guardOverride === "on" ? "GUARD ON" : phase ? phase.toUpperCase() : "";
+}
 
 export default function (pi: ExtensionAPI) {
   pi.on("session_start", () => {
     phase = null;
+    pendingPhaseReminder = false;
+    guardOverride = null;
+  });
+
+  // --- Manual override (escape hatch) -----------------------------------
+  // Phases are driven by `/skill:` commands; `/pwk-guard` lets the user pin the
+  // guard regardless of phase. `/pwk-guard auto` returns control to skill transitions.
+  pi.registerCommand("pwk-guard", {
+    description:
+      "Manual guard override: /pwk-guard on (force read-only lock) | off (disable guard) | auto (skill-driven phases, default).",
+    getArgumentCompletions: (prefix) => {
+      const p = (prefix ?? "").trim().toLowerCase();
+      const opts = [
+        { value: "on", label: "on", description: "Force read-only lock (ignore skill phases)" },
+        { value: "off", label: "off", description: "Disable the guard entirely" },
+        { value: "auto", label: "auto", description: "Follow skill-driven phases (default)" },
+      ];
+      const matched = opts.filter((o) => o.value.startsWith(p));
+      return matched.length ? matched : opts;
+    },
+    handler: async (args, ctx) => {
+      const arg = (args ?? "").trim().toLowerCase();
+      if (arg === "auto") {
+        guardOverride = null;
+        if (phase) pendingPhaseReminder = true; // re-announce the active gated phase, if any
+        ctx.ui.notify("Guard AUTO — enforcement follows skill-driven phases.", "info");
+        return;
+      }
+      if (arg !== "on" && arg !== "off") {
+        ctx.ui.notify("Usage: /pwk-guard on | off | auto", "info");
+        return;
+      }
+      guardOverride = arg;
+      pendingPhaseReminder = false; // override announces itself via the message below
+      pi.sendMessage({
+        customType: "pwk-guard:override",
+        content:
+          arg === "on"
+            ? "[pi-workflow-kit] GUARD ON (manual override): read-only lock active — no source edits; writes only under docs/plans/. No mutations. Use /pwk-guard auto to resume skill-driven phases."
+            : "[pi-workflow-kit] GUARD OFF (manual override): enforcement disabled — writes and bash are unrestricted. Use /pwk-guard auto to resume skill-driven phases.",
+        display: false,
+      });
+      ctx.ui.notify(
+        arg === "on"
+          ? "Guard ON — read-only lock active (skill phases ignored)."
+          : "Guard OFF — enforcement disabled (skill phases ignored).",
+        arg === "on" ? "warning" : "info",
+      );
+    },
   });
 
   pi.on("input", (event) => {
@@ -176,27 +241,65 @@ export default function (pi: ExtensionAPI) {
     if (match) {
       const skill = match[1];
       if (skill in SKILL_TO_PHASE) {
-        phase = SKILL_TO_PHASE[skill];
+        const nextPhase = SKILL_TO_PHASE[skill];
+        if (phase !== nextPhase) {
+          phase = nextPhase;
+          // The reminder is a phase-entry cue; only relevant when the guard is auto-driven.
+          if (guardOverride === null) pendingPhaseReminder = true;
+        }
         return;
       }
     }
-    if (text.startsWith("/skill:pwk-executing-tasks") || text.startsWith("/skill:pwk-finalizing")) {
+    // Phase transitions happen only via skills — no message keyword unlocks the plan phase.
+    // Run /skill:pwk-executing-tasks (or another write-needing skill) to leave a gated phase.
+    //
+    // Unlock list rationale: execute/finalize/code-review/diagnose all need to write source
+    // (implement, edit review fixes, add [DEBUG-] instrumentation), so they exit the gate.
+    // pwk-status is NOT here on purpose: it is read-only orientation, so it stays inside the
+    // gated phase and never drops the write boundary the user is relying on.
+    // (Orientation never needs write access; see skills/pwk-status.)
+    if (UNLOCK_SKILLS.some((s) => text.startsWith(`/skill:${s}`))) {
       phase = null;
     }
   });
 
+  // Show the phase reminder exactly once: on the first turn of a gated phase (before_agent_start
+  // fires before the LLM is called). It is NOT repeated every turn. Re-armed on any phase change.
+  // Returned as a tail-appended custom message so it never touches the cached system-prompt prefix.
+  //
+  // Note: a soft reminder on every *permitted* bash call is not possible — tool_call can only
+  // return { block, reason }, not a message. So at bash time the reminder surfaces only when a
+  // destructive command is actually blocked (the reactive `reason` in the tool_call handler).
+  pi.on("before_agent_start", async () => {
+    if (!phase || !pendingPhaseReminder) return {};
+    pendingPhaseReminder = false;
+    // Override states announce themselves via the /pwk-guard handler; this reminder
+    // is the auto-mode phase-entry cue only.
+    if (guardOverride !== null) return {};
+    return {
+      message: {
+        customType: "pwk-phase-reminder",
+        content: PHASE_REMINDERS[phase],
+        display: false,
+      },
+    };
+  });
+
   pi.on("tool_call", (event, ctx) => {
-    if (!phase) return;
+    if (!enforceActive()) return;
+    const label = enforceLabel();
+    const manual = guardOverride === "on";
+    const scope = manual ? "manual read-only lock" : `${label.toLowerCase()} phase`;
 
     if (event.toolName === "bash") {
       const command = (event.input as { command?: string }).command ?? "";
       if (!isSafeCommand(command)) {
         if (ctx.hasUI) {
-          ctx.ui.notify(`Blocked bash command during ${phase} phase: ${command}`, "warning");
+          ctx.ui.notify(`Blocked bash command (${scope}): ${command}`, "warning");
         }
         return {
           block: true,
-          reason: `⚠️ ${phase.toUpperCase()} PHASE: Bash command blocked (not allowlisted). Only read-only commands are permitted during brainstorming, planning, and verification.\nCommand: ${command}`,
+          reason: `⚠️ ${label}: read-only — no source writes or destructive bash. Only read-only commands are permitted.\nBlocked command: ${command}`,
         };
       }
       return;
@@ -210,15 +313,14 @@ export default function (pi: ExtensionAPI) {
     if (!shouldBlockFilePath(filePath, ctx.cwd)) return;
 
     if (ctx.hasUI) {
-      ctx.ui.notify(
-        `Blocked ${event.toolName} to ${filePath} during ${phase} phase. Only docs/plans/ is writable.`,
-        "warning",
-      );
+      ctx.ui.notify(`Blocked ${event.toolName} to ${filePath} (${scope}). Only docs/plans/ is writable.`, "warning");
     }
 
     return {
       block: true,
-      reason: `⚠️ ${phase.toUpperCase()} PHASE: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable during brainstorming, planning, and verification.`,
+      reason: `⚠️ ${label}: Cannot ${event.toolName} to ${filePath}. Only docs/plans/ is writable${
+        manual ? " under the manual read-only lock" : " during brainstorming and planning"
+      }.`,
     };
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "0.18.1",
+  "version": "1.1.0",
   "description": "Enforce structured brainstorm→plan→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",
@@ -16,7 +16,8 @@
   "scripts": {
     "test": "vitest run",
     "lint": "biome check .",
-    "check": "biome check . && vitest run"
+    "skill-lint": "node tests/skill-lint.mjs",
+    "check": "biome check . && vitest run && node tests/skill-lint.mjs"
   },
   "license": "MIT",
   "author": "yinloo-ola",
@@ -27,7 +28,11 @@
   "files": [
     "extensions/",
     "skills/",
-    "docs/",
+    "agents/",
+    "docs/developer-usage-guide.md",
+    "docs/workflow-phases.md",
+    "docs/oversight-model.md",
+    "docs/lessons.md",
     "LICENSE",
     "README.md"
   ],
@@ -39,9 +44,20 @@
       "skills"
     ]
   },
+  "pi-subagents": {
+    "agents": [
+      "./agents"
+    ]
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@sinclair/typebox": "*"
+    "@sinclair/typebox": "*",
+    "pi-subagents": "*"
+  },
+  "peerDependenciesMeta": {
+    "pi-subagents": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.15",