fix(pdca): complete predecessor phase Task before advancing (#137, v2.1.29)

.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "bkit-marketplace",
-  "version": "2.1.28",
+  "version": "2.1.29",
   "description": "POPUP STUDIO's Vibecoding Kit marketplace - PDCA methodology and AI-native development tools. Requires Claude Code v2.1.143+ for the bkit plugin (older versions reject the displayName field).",
   "owner": {
     "name": "POPUP STUDIO PTE. LTD.",
@@ -33,12 +33,12 @@
     },
     {
       "name": "bkit",
-      "description": "Requires Claude Code v2.1.143+ (older versions reject the strict plugin-manifest displayName field — run `npm install -g @anthropic-ai/claude-code@latest` to upgrade; see docs/06-guide/cc-compatibility.guide.md). Vibecoding Kit - PDCA + Sprint Management + CTO-Led Agent Teams + Living Context System + 43 PM frameworks. v2.1.14 6 differentiations (Memory Enforcer, Layer 6 Defense, Sequential Dispatch, Effort-aware, PostToolUse continueOnBlock, Heredoc-bypass). v2.1.15 pdca-status.json fix. v2.1.16 4 GitHub issues (Quality Gates UX). v2.1.17 5/12~5/20 contract red 8-day class close. v2.1.18 Issues #100/#101/#102 — Sprint Trust UX Fix. v2.1.19 Quality Maturation Sprint — 5 sub-sprint master plan (S1 Self-Dogfooding Enablement / S2 Convention Restoration / S3 Sprint Report Maturity / S4 External Dogfooder Lifecycle / S5 Sprint Maturity Index) + ENH-318 차별화 7/7 정식 편입 + Real User Hall of Fame 도입 + 첫 외부 dogfooder entry @pruge. v2.1.20 Marketplace Recovery — minimum CC v2.1.143 advisory (F1+F4) + plugin manifest 21-key whitelist CI gate (F5+F6, ENH-322) + claude plugin validate wire (F7, ADR 0006 § Empirical Validation Gate) + cc-regression R3-321 (F8, ENH-321) + SessionStart CC version detection (F10, ENH-323) + ADR 0011 Plugin Manifest Schema Compliance Policy + Hall of Fame @bj (#2 external dogfooder, Lifecycle 5-stage). v2.1.21 Issue Response — Session Title Isolation (#111: per-session sessions[sessionId] cache map + GC + legacy migration + stable session tag for parallel-window disambiguation) + Sprint Output Enforcement (#113: lib/sprint/executive-summary.js sprint-shape + scripts/sprint-skill-stop.js run-export Stop hook + SKILL_HANDLERS sprint registration + advancePhase phaseTransitionSummary + /sprint status·watch human-readable display) + ADR 0012 Sprint Stop Hook Output Enforcement. v2.1.24 Skill Namespace Hardening — Issues #125/#126 (@hslee-cmyk): normalizeSkillName() canonicalizes CC `plugin:skill` form (bkit:pdca → pdca) so getSkillConfig + skill-post + implicit-trigger injection + Stop-handler dispatch resolve the bare folder; hook-reachability check no longer false-positives skill_post (event-driven vs canary correlation). v2.1.25 Claude 5 Model Alignment + Issue Response — 4-tier role-based model matrix (9 fable verification/orchestration core + 7 opus deep-reasoning/security + 16 sonnet implementers + 2 haiku monitors), dual floor (install v2.1.143 / model v2.1.170 advisory ENH-368), Claude 5 pricing sync; Issues #128 (@NEXCODE-MK: 6 deprecated pdca-eval-* stubs removed from the prompt surface → deprecation registry, ADR 0014) + #129 (@NEXCODE-MK: agent description token diet −44%, compact 8-language triggers) + #130 (@s99606931: learning-stop.js piped-stdin isTTY gate fix). v2.1.26 MCP Manifest Relocation + Fable Cost Retune — fixes the /plugin 'Needs attention: bkit MCP failed' defect (repo-root .mcp.json dual-loaded as plugin manifest + project config where CLAUDE_PLUGIN_ROOT is undefined; now declared inline in plugin.json, root file deleted, regression-locked MS-016) + release-plugin-tag.sh drift fix + full test-state isolation refactor (projectRoot injectable through batch-orchestrator/sprint-registry/audit-logger; tests no longer leak fixtures into the real .bkit) + ADR 0011 amendment/ADR 0015 (locale-scoped deferral)/eval re-baseline SOP + Fable cost retune (ENH-370: high-frequency PDCA verifiers gap-detector/design-validator/pdca-iterator fable→opus for cost → 6 fable / 10 opus / 16 sonnet / 2 haiku). v2.1.27 Slash-Path Orchestration Restored — Issue #132 (@hslee-cmyk): bkit's four orchestrator side-effects (next-skill/agent guidance, PDCA phase auto-advance, decision-trace phase_transition, audit skill_executed) were wired only to PostToolUse:Skill, which never fires on native slash commands (/bkit:pdca ...) — the only invocation form bkit's docs teach — so the advertised audit trail was empty for real usage; ENH-371 dual-wires the effects into a source-agnostic module fired from BOTH PostToolUse:Skill AND a new fail-open UserPromptExpansion hook (slash path records a new skill_invoked action), plus repays two latent defects (dead IntentRouter onboardingContext ReferenceError + slash-path Stop-handler marker) — graceful degradation on CC without UserPromptExpansion, no version floor bump. v2.1.28 Runtime-Phase-Aware Skill Guidance — Issue #135 (@hslee-cmyk), the narrower follow-up to #132: the next-step GUIDANCE-TEXT half of the same UserPromptExpansion mechanism never fired for multi-action routers (pdca/sprint/+9) because orchestrateSkillPost derived suggestions only from STATIC frontmatter (next-skill/pdca-phase), which those routers declare null by design. Root fix: new lib/orchestrator/runtime-guidance.js resolves the phase at call time from args.action + live PDCA/Sprint state and REUSES the manual-path SSoT (getNextPdcaActionAfterCompletion / buildNextActions) — no duplicated phase table; wired at the shared runSkillInvocationEffects chokepoint so BOTH slash and Skill-tool paths surface guidance; fail-open; only pdca/sprint eligible (9 utility routers stay intentionally silent); suggestedAgent extended (design→design-validator, qa→qa-lead); hardcoded Korean guidance strings migrated to EN-default + KO via i18n detector. 23-TC regression test, 0 main-baseline regressions. 🚀 bkit Early Adopter Program — running bkit on a non-trivial production project + filing detailed bug reports makes you part of bkit's quality system: public Hall of Fame recognition, E2E regression test absorption, Trust Score externalDogfoodFeedbackResponseRate component (weight 0.05). 44 Skills, 34 Agents (6 pdca-eval-* registry-tombstoned per ADR 0014), 61 Scripts, 195 Lib Modules, 22 Hook Events (25 blocks), 40 Templates, 4 Output Styles, 2 MCP Servers (19 tools, declared inline in plugin.json), 13 ADR invariants.",
+      "description": "Requires Claude Code v2.1.143+ (older versions reject the strict plugin-manifest displayName field — run `npm install -g @anthropic-ai/claude-code@latest` to upgrade; see docs/06-guide/cc-compatibility.guide.md). Vibecoding Kit - PDCA + Sprint Management + CTO-Led Agent Teams + Living Context System + 43 PM frameworks. v2.1.14 6 differentiations (Memory Enforcer, Layer 6 Defense, Sequential Dispatch, Effort-aware, PostToolUse continueOnBlock, Heredoc-bypass). v2.1.15 pdca-status.json fix. v2.1.16 4 GitHub issues (Quality Gates UX). v2.1.17 5/12~5/20 contract red 8-day class close. v2.1.18 Issues #100/#101/#102 — Sprint Trust UX Fix. v2.1.19 Quality Maturation Sprint — 5 sub-sprint master plan (S1 Self-Dogfooding Enablement / S2 Convention Restoration / S3 Sprint Report Maturity / S4 External Dogfooder Lifecycle / S5 Sprint Maturity Index) + ENH-318 차별화 7/7 정식 편입 + Real User Hall of Fame 도입 + 첫 외부 dogfooder entry @pruge. v2.1.20 Marketplace Recovery — minimum CC v2.1.143 advisory (F1+F4) + plugin manifest 21-key whitelist CI gate (F5+F6, ENH-322) + claude plugin validate wire (F7, ADR 0006 § Empirical Validation Gate) + cc-regression R3-321 (F8, ENH-321) + SessionStart CC version detection (F10, ENH-323) + ADR 0011 Plugin Manifest Schema Compliance Policy + Hall of Fame @bj (#2 external dogfooder, Lifecycle 5-stage). v2.1.21 Issue Response — Session Title Isolation (#111: per-session sessions[sessionId] cache map + GC + legacy migration + stable session tag for parallel-window disambiguation) + Sprint Output Enforcement (#113: lib/sprint/executive-summary.js sprint-shape + scripts/sprint-skill-stop.js run-export Stop hook + SKILL_HANDLERS sprint registration + advancePhase phaseTransitionSummary + /sprint status·watch human-readable display) + ADR 0012 Sprint Stop Hook Output Enforcement. v2.1.24 Skill Namespace Hardening — Issues #125/#126 (@hslee-cmyk): normalizeSkillName() canonicalizes CC `plugin:skill` form (bkit:pdca → pdca) so getSkillConfig + skill-post + implicit-trigger injection + Stop-handler dispatch resolve the bare folder; hook-reachability check no longer false-positives skill_post (event-driven vs canary correlation). v2.1.25 Claude 5 Model Alignment + Issue Response — 4-tier role-based model matrix (9 fable verification/orchestration core + 7 opus deep-reasoning/security + 16 sonnet implementers + 2 haiku monitors), dual floor (install v2.1.143 / model v2.1.170 advisory ENH-368), Claude 5 pricing sync; Issues #128 (@NEXCODE-MK: 6 deprecated pdca-eval-* stubs removed from the prompt surface → deprecation registry, ADR 0014) + #129 (@NEXCODE-MK: agent description token diet −44%, compact 8-language triggers) + #130 (@s99606931: learning-stop.js piped-stdin isTTY gate fix). v2.1.26 MCP Manifest Relocation + Fable Cost Retune — fixes the /plugin 'Needs attention: bkit MCP failed' defect (repo-root .mcp.json dual-loaded as plugin manifest + project config where CLAUDE_PLUGIN_ROOT is undefined; now declared inline in plugin.json, root file deleted, regression-locked MS-016) + release-plugin-tag.sh drift fix + full test-state isolation refactor (projectRoot injectable through batch-orchestrator/sprint-registry/audit-logger; tests no longer leak fixtures into the real .bkit) + ADR 0011 amendment/ADR 0015 (locale-scoped deferral)/eval re-baseline SOP + Fable cost retune (ENH-370: high-frequency PDCA verifiers gap-detector/design-validator/pdca-iterator fable→opus for cost → 6 fable / 10 opus / 16 sonnet / 2 haiku). v2.1.27 Slash-Path Orchestration Restored — Issue #132 (@hslee-cmyk): bkit's four orchestrator side-effects (next-skill/agent guidance, PDCA phase auto-advance, decision-trace phase_transition, audit skill_executed) were wired only to PostToolUse:Skill, which never fires on native slash commands (/bkit:pdca ...) — the only invocation form bkit's docs teach — so the advertised audit trail was empty for real usage; ENH-371 dual-wires the effects into a source-agnostic module fired from BOTH PostToolUse:Skill AND a new fail-open UserPromptExpansion hook (slash path records a new skill_invoked action), plus repays two latent defects (dead IntentRouter onboardingContext ReferenceError + slash-path Stop-handler marker) — graceful degradation on CC without UserPromptExpansion, no version floor bump. v2.1.28 Runtime-Phase-Aware Skill Guidance — Issue #135 (@hslee-cmyk), the narrower follow-up to #132: the next-step GUIDANCE-TEXT half of the same UserPromptExpansion mechanism never fired for multi-action routers (pdca/sprint/+9) because orchestrateSkillPost derived suggestions only from STATIC frontmatter (next-skill/pdca-phase), which those routers declare null by design. Root fix: new lib/orchestrator/runtime-guidance.js resolves the phase at call time from args.action + live PDCA/Sprint state and REUSES the manual-path SSoT (getNextPdcaActionAfterCompletion / buildNextActions) — no duplicated phase table; wired at the shared runSkillInvocationEffects chokepoint so BOTH slash and Skill-tool paths surface guidance; fail-open; only pdca/sprint eligible (9 utility routers stay intentionally silent); suggestedAgent extended (design→design-validator, qa→qa-lead); hardcoded Korean guidance strings migrated to EN-default + KO via i18n detector. 23-TC regression test, 0 main-baseline regressions. v2.1.29 PDCA Predecessor-Task Completion — Issue #137 (@hslee-cmyk): the `pdca` skill chains phase Tasks via `blockedBy` ([Plan]→[Design]→[Do]→…) but SKILL.md documented Task creation only, never predecessor completion, so a prior-phase Task left `in_progress` leaked a stale phase (e.g. \"design\" during \"do\") into Claude Code's ambient prompt context — disagreeing with `.bkit/state/pdca-status.json`'s phase (the phase source of truth). The issue's Option-2 (a hook auto-completing the predecessor) is technically infeasible — CC hooks communicate via stdout/exit-code/additionalContext only and cannot call TaskUpdate; only the model can — so v2.1.29 applies Option-1: every phase action now instructs the model to mark predecessor Task(s) `completed` before creating the next phase Task, and a new `## Task Integration` Phase Transition Rule codifies the completion semantics + rationale; a regression test guards each transition. Cosmetic/informational fix, zero runtime/architecture-count change. 🚀 bkit Early Adopter Program — running bkit on a non-trivial production project + filing detailed bug reports makes you part of bkit's quality system: public Hall of Fame recognition, E2E regression test absorption, Trust Score externalDogfoodFeedbackResponseRate component (weight 0.05). 44 Skills, 34 Agents (6 pdca-eval-* registry-tombstoned per ADR 0014), 61 Scripts, 195 Lib Modules, 22 Hook Events (25 blocks), 40 Templates, 4 Output Styles, 2 MCP Servers (19 tools, declared inline in plugin.json), 13 ADR invariants.",
       "author": {
         "name": "POPUP STUDIO PTE. LTD.",
         "email": "contact@popupstudio.ai"
       },
-      "version": "2.1.28",
+      "version": "2.1.29",
       "repository": "https://github.com/popup-studio-ai/bkit-claude-code",
       "source": {
         "source": "url",

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bkit",
-  "version": "2.1.28",
+  "version": "2.1.29",
   "displayName": "bkit — AI Native Development OS",
   "description": "The only Claude Code plugin that verifies AI-generated code against its own design specs.",
   "author": {

CHANGELOG.md

@@ -5,6 +5,58 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.29] - 2026-07-06
+
+> **Status**: Issue #137 (@hslee-cmyk) — a low-priority, cosmetic follow-up in the
+> same task-lifecycle area as #132/#135, reported with a full reproduction. The
+> `pdca` skill chains phase Tasks with `blockedBy` (`[Plan]→[Design]→[Do]→[Check]→…`),
+> but `skills/pdca/SKILL.md` documented Task *creation* only — no step ever told the
+> model to mark the *predecessor* phase Task `completed` when advancing, and no
+> hook/orchestrator did it either. A predecessor left `in_progress` (e.g. `[Design]`
+> during the whole `Do` phase) leaked a stale phase into Claude Code's ambient
+> prompt context on every turn, disagreeing with `.bkit/state/pdca-status.json`'s
+> `phase` field — the phase source of truth, which was correct throughout. No
+> Guessing: reproduced in-source (grep confirms zero predecessor-completion
+> instructions) and the fix strategy was decided against CC's documented hook
+> constraints, not assumptions.
+
+### PDCA Predecessor-Task Completion Chain (Issue #137)
+
+- **Root cause**: `## Task Integration` and each per-action step block in
+  `skills/pdca/SKILL.md` describe creating `[Phase] {feature}` Tasks with a
+  `blockedBy` reference to the prior phase, but never instruct completing that prior
+  Task. For a `blockedBy` chain to be semantically correct — and, more visibly, to
+  keep Claude Code's native task list (surfaced into prompt context each turn)
+  consistent with `pdca-status.json` — the predecessor must be `completed` by the
+  time the successor is created.
+- **Why the issue's Option 2 (hook auto-complete) was rejected as infeasible**:
+  per the official Claude Code hooks guide, command hooks communicate only through
+  stdout / stderr / exit codes / `additionalContext` and **cannot call `TaskUpdate`
+  or any tool — only the model can**. `TaskCreated`/`TaskCompleted` are real firing
+  events, but a handler for them could at most emit a reminder, which *still* relies
+  on the model performing the completion — no more deterministic than an explicit
+  skill step, and noisier. Option 2 is therefore strictly worse than Option 1.
+- **Fix (Option 1 — deterministic, model-executed)**: each advancing `pdca` phase
+  action (`design`, `do`, `analyze`, `iterate`, `qa`, `report`) now embeds a
+  **"Complete predecessor Task first"** step immediately before its Create-Task
+  step, and `archive` completes the terminal `[Report]` Task. A general
+  **Phase Transition Rule** in `## Task Integration` states the rule ("mark every
+  prior `[Phase] {feature}` Task still `in_progress` as `completed`") and its
+  two-sources-of-truth rationale; the wording is branch-safe for the `qa`/`act`
+  parts of the 9-phase lifecycle. Uses the `TaskList`/`TaskUpdate` tools the skill
+  already grants — no new runtime surface, no hook change.
+- **Scope**: `skills/pdca/SKILL.md` only. Related skills carry no multi-phase
+  `blockedBy` chain — `plan-plus` creates a single `[Plan]` Task (completed by
+  `pdca design`'s new step), `cc-version-analysis` uses a single Task with subtask
+  tracking, and `sprint` uses per-feature Tasks — so none required changes.
+- **Regression guard**: new `test/regression/issue-137-predecessor-task-completion.test.js`
+  (25 assertions) asserts the Phase Transition Rule and each per-transition
+  completion instruction are present; it fails if any is removed.
+- **No architecture-count or runtime-behavior change**: 44 Skills / 34 Agents /
+  22 Hook Events (25 blocks) / 195 Lib Modules unchanged; `TaskCreated`/`TaskCompleted`
+  audit + auto-advance handlers unchanged. Zero new regressions vs the `main`
+  baseline (identical failing-file set).
+
 ## [2.1.28] - 2026-07-03
 
 > **Status**: Issue #135 (@hslee-cmyk) — the direct, narrower follow-up to #132.

README.md

@@ -6,7 +6,7 @@
 
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Claude Code](https://img.shields.io/badge/Claude%20Code-v2.1.143+-purple.svg)](https://code.claude.com)
-[![Version](https://img.shields.io/badge/Version-2.1.28-green.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/Version-2.1.29-green.svg)](CHANGELOG.md)
 [![Author](https://img.shields.io/badge/Author-POPUP%20STUDIO-orange.svg)](https://popupstudio.ai)
 
 > **Requirement**: bkit requires Claude Code **v2.1.143 or later** (the strict plugin-manifest path recognizes the official `displayName` field only from v2.1.143). On older Claude Code you will see `Validation errors: Unrecognized key: "displayName"` during `claude plugin install`. Run `npm install -g @anthropic-ai/claude-code@latest` to upgrade, or see [`docs/06-guide/cc-compatibility.guide.md`](docs/06-guide/cc-compatibility.guide.md).
@@ -209,7 +209,7 @@ Full architecture deep-dive: [README-FULL.md §9](README-FULL.md#9-architecture)
 | Path | What's there |
 |---|---|
 | [README-FULL.md](README-FULL.md) | Full command reference, deep workflow internals, agent teams, architecture, Skill Evals |
-| [CHANGELOG.md](CHANGELOG.md) | Release history (single source of truth — latest release: v2.1.28) |
+| [CHANGELOG.md](CHANGELOG.md) | Release history (single source of truth — latest release: v2.1.29) |
 | [CUSTOMIZATION-GUIDE.md](CUSTOMIZATION-GUIDE.md) | Override any bkit component in your `.claude/` directory |
 | [AI-NATIVE-DEVELOPMENT.md](AI-NATIVE-DEVELOPMENT.md) | The 6 AI-Native principles and how bkit implements them |
 | [`bkit-system/philosophy/`](bkit-system/philosophy/) | Core mission, Context Engineering, PDCA methodology, AI-Native principles |

bkit.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.1.28",
+  "version": "2.1.29",
   "ui": {
     "sessionTitle": {
       "enabled": true,