@tianhai/pi-workflow-kit 2.5.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tianhai/pi-workflow-kit",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Enforce structured design→execute→finalize workflow with TDD discipline in AI coding agents",
   "keywords": [
     "pi-package",

package/skills/pwk-executing-tasks/SKILL.md

@@ -179,8 +179,11 @@ key files capped `at 5`.
 
 ```markdown
 # Progress: <topic>
+
 Design: docs/plans/<date>-<topic>/<leaf>-design.md
+
 Feature phase: e2e-written
+
 ## Requirements
 | # | Done | Requirement | Per-req ceremony | Commit |
 ## Execution summary

package/skills/pwk-executing-tasks/references/progress-format.md

@@ -2,16 +2,21 @@
 
 Read before creating or changing progress rows, or writing/re-presenting the code digest. This reference owns the unchanged progress artifact schema.
 
-2. **Create the progress file** `docs/plans/<date>-<topic>/<leaf>-progress.md`, beside the design doc it belongs to (`<leaf>` is `<topic>` for a single-part topic; an umbrella part uses its roster slug), so `pwk-finalizing` finds it inside the topic folder:
+2. **Create the progress file** `docs/plans/<date>-<topic>/<leaf>-progress.md`, beside the design doc it belongs to (`<leaf>` is `<topic>` for a single-part topic; an umbrella part uses its roster slug), so `pwk-finalizing` finds it inside the topic folder. Keep the blank lines between the header fields: the blank lines are load-bearing, because CommonMark merges consecutive plain lines into one paragraph, so without them every preview renders the whole header as a single run-on line.
 
    ```markdown
    # Progress: <topic>
 
    Design: docs/plans/<date>-<topic>/<leaf>-design.md
+
    Branch: <branch>
+
    Setup: n/a
+
    Started: <ISO timestamp>
+
    Last updated: <ISO timestamp>
+
    Feature phase: e2e-written
 
    <!-- a trivial design doc (no `## Feature acceptance`) starts at `implementing (0/N)` instead — there is no E2E to write -->
@@ -36,25 +41,25 @@ Read before creating or changing progress rows, or writing/re-presenting the cod
 
    ### Summary
    ### Flow
-   Spine
-     <entry point> -> [R1] <step> -> [R2] <step> -> <outcome>
-   Branches
-     <condition> -> <outcome>   [R2]
-     <changed behavior>   was: <previous behavior>
-   Side effects
-     reads: <what>   writes: <what>
+   - **Spine** — `<entry point> -> [R1] <step> -> [R2] <step> -> <outcome>`
+   - **Branches**
+     - `<condition> -> <outcome>` [R2]
+     - `<changed behavior> — was: <previous behavior>`
+   - **Side effects** — reads: `<what>` · writes: `<what>`
    ### Gotchas
+   - <one real risk per bullet>
    ### Key files
+   - `<file>` — <what shifted inside it>
    ```
 
-   The `## Code digest` is filled once, at the write point in the ship checkpoint — never per requirement. Fill rules: plain language, R# anchors where natural, no test names (the execution-summary rule). `### Summary` is 2–3 sentences: what the code now does differently, and why. `### Flow` uses `A -> B -> C` arrow chains. `### Gotchas` lifts real risks from the review findings — `[ALERT]` only for reviewer-confirmed issues, never invented; with no findings, write `none beyond review findings` and mean it. `### Key files` is capped at 5 pivotal files, one line each: what shifted inside them.
+   The `## Code digest` is filled once, at the write point in the ship checkpoint — never per requirement. Fill rules: plain language, R# anchors where natural, no test names (the execution-summary rule). `### Summary` is 2–3 sentences: what the code now does differently, and why. `### Flow` uses `A -> B -> C` arrow chains, one spine or branch per bullet line, so every renderer shows each hop chain on its own line — bare label lines would merge into one run-on paragraph. `### Gotchas` lifts real risks from the review findings, one bullet each — `[ALERT]` only for reviewer-confirmed issues, never invented; with no findings, write `none beyond review findings` and mean it. `### Key files` is capped at 5 pivotal files, one bullet each: what shifted inside them.
 
    **Flow shape** — this is the ship stop's navigable map, so it is the one digest section that carries structure, not just prose:
 
    - **Spine** — the happy path as `A -> B -> C` hops, each hop named by symbol or module, with no line numbers anywhere and no file paths: symbol names survive edits and stay greppable, so a stale anchor can never mislead. Tag each hop `[R<n>]` with the requirement it comes from — that is what lets the coverage table's verdict rows be traced into the code without opening the diff.
    - **Branches** — every alternative and error path as `condition -> outcome` (a linear spine with no branches reads as "there are no edge cases", which is rarely true). Put ⚠️ on the genuinely surprising ones. Add a `was: <previous behavior>` clause for each requirement whose behavior changed; skip it for purely additive requirements — honest-empty, never invented.
    - **Inline worked values** — where a mapping is non-obvious, show it concretely (`` `implementing (2/5)` -> `execute 2/5` ``), so a reader can falsify it without running anything.
-   - **Side effects** — a line naming what is read and written, only when the feature performs I/O, network, or migrations; omit it entirely otherwise rather than filling a placeholder.
+   - **Side effects** — a bullet naming what is read and written, only when the feature performs I/O, network, or migrations; omit it entirely otherwise rather than filling a placeholder.
    - **Cap: roughly 15 lines.** If the change genuinely needs more, the ship checkpoint **offers `/skill:pwk-walkthrough`** as the deep read (it regenerates a `file:line`-anchored walkthrough on demand) instead of growing the digest — the digest is what the human reads at the one remaining stop, and an unbounded Flow recreates the digging it exists to prevent.
 
    `Feature phase` is one of: `e2e-written`, `implementing (k/N)`, `reviewing`, `ship-paused`, `done`.

package/skills/pwk-executing-tasks/scripts/build-review-packet.py

@@ -266,7 +266,9 @@ def build(args):
         ('Diff', git(project, 'diff', '--no-ext-diff', '--no-textconv', '--no-color', span, *pathspec)),
     ]
     label = 'feature review' if args.scope == 'feature' else f'requirement R{args.requirement} review'
-    packet = f'# Review packet: {design_path.parent.name} — {label}\n\nBase: {base}\nHead: {head}\n\n'
+    # The blank line between Base and Head is load-bearing: CommonMark merges
+    # consecutive plain lines into one paragraph in every preview.
+    packet = f'# Review packet: {design_path.parent.name} — {label}\n\nBase: {base}\n\nHead: {head}\n\n'
     for title, content in sections:
         packet += f'## {title}\n\n{content}\n'
     # All parsing and Git reads finish before a temporary file exists. A failure in

package/skills/pwk-walkthrough/SKILL.md

@@ -37,7 +37,7 @@ Five sections, always: Summary / How it works / Key flows / Gotchas & invariants
    One subsection per component: responsibility + mechanism.
 
    ## Key flows
-   Execution/data movement as arrow chains (A -> B -> C), anchored per step.
+   Execution/data movement as arrow chains (A -> B -> C), anchored per step, one flow per bullet line.
 
    ## Gotchas & invariants
    Edge cases, implicit assumptions, ordering constraints.