diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e01c178..f6e792c 100644 --- a/.claude-plugin/marketplace.json +++ b/.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", diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bd0d592..3ea3637 100644 --- a/.claude-plugin/plugin.json +++ b/.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": { diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c4a08b..af58fe3 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.md b/README.md index 4a35e44..b1bb02f 100644 --- a/README.md +++ b/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 | diff --git a/bkit.config.json b/bkit.config.json index 7ff5f0c..2e6267b 100644 --- a/bkit.config.json +++ b/bkit.config.json @@ -1,5 +1,5 @@ { - "version": "2.1.28", + "version": "2.1.29", "ui": { "sessionTitle": { "enabled": true, diff --git a/docs/01-plan/features/pdca-task-completion-chain.plan.en.md b/docs/01-plan/features/pdca-task-completion-chain.plan.en.md new file mode 100644 index 0000000..72e395b --- /dev/null +++ b/docs/01-plan/features/pdca-task-completion-chain.plan.en.md @@ -0,0 +1,52 @@ +# Plan — PDCA Predecessor-Task Completion Chain (issue #137, v2.1.29) + +## Executive Summary + +| Perspective | Summary | +|---|---| +| **Problem** | The `pdca` skill creates a `blockedBy` chain of phase Tasks (`[Plan]→[Design]→[Do]→[Check]→…`) but never tells the model to mark the *predecessor* Task `completed` when advancing. Predecessor Tasks stay `in_progress`, and Claude Code's native task list leaks a stale phase (e.g. "design") into prompt context on every turn — disagreeing with the correct `.bkit/state/pdca-status.json` `phase` field. | +| **Solution** | Add an explicit "complete the predecessor phase Task" instruction to each `pdca` phase action immediately before it creates the next phase Task, and codify a Phase Transition Rule in the `## Task Integration` section. Deterministic, model-executed, no dead code. | +| **Function/UX Effect** | The CC task list and `pdca-status.json` agree at all times; users no longer see a stale phase signal after advancing. | +| **Core Value** | Two sources of truth that *should* agree now *do* agree, removing a confusing informational discrepancy at zero functional risk. | + +## Context Anchor + +| Key | Value | +|---|---| +| **WHY** | Stale `in_progress` predecessor Tasks leak an outdated phase into ambient prompt context, contradicting `pdca-status.json`. | +| **WHO** | Every bkit user running the `pdca` skill through more than one phase (i.e. all real PDCA usage). | +| **RISK** | Very low — the change is prose in one skill file + one regression test. No lib/hook behavior change. | +| **SUCCESS** | Each phase transition in `skills/pdca/SKILL.md` instructs completing the predecessor Task; a regression test enforces it; live plugin load stays clean. | +| **SCOPE** | `skills/pdca/SKILL.md` only. Related skills (plan-plus single `[Plan]` task, cc-version-analysis single task, sprint per-feature tasks) do not carry the multi-phase chain and are out of scope. | + +## 1. Background / Reproduction + +- Reporter: @hslee-cmyk (bkit v2.1.28, CC v2.1.199). Rated **low / cosmetic** — deferred severity to maintainer. +- Reproduced in-source: `grep` of `skills/pdca/SKILL.md` shows every action has `Create Task: [X] {feature}` (steps: pm=6, plan=8, design=12, do=14, analyze=12, qa=5, iterate=5, report=9) but **no** instruction to complete the previous phase's Task. The only "completed" mentions are `pdca-status.json` phase writes and archive gating — never Task-tool completion. +- Confirmed via CC official docs (hooks guide + todo-tracking): `TaskCreated`/`TaskCompleted` are real firing hooks, but **hooks cannot mutate Task state** (stdout/exit-code/additionalContext only; only the model may call `TaskUpdate`). + +## 2. Requirements + +- R1: Each `pdca` phase action that advances the chain must instruct the model to mark the predecessor phase Task(s) `completed` before creating the new phase Task. +- R2: The `## Task Integration` section must document the Phase Transition Rule (why + how), so the completion semantics are discoverable, not implicit. +- R3: A regression test must assert the completion instruction is present for each phase transition, so the omission cannot silently return. +- R4: No change to lib/hook runtime behavior; architecture counts (44 skills / 34 agents / 22 hook events / 195 lib modules) unchanged. +- R5: English-only implementation (SKILL.md, test); bilingual docs under `docs/`. + +## 3. Success Criteria + +- [ ] SC1: `design`, `do`, `analyze`, `iterate`, `qa`, `report`, `archive` actions each contain a "complete predecessor Task" step before their Create-Task step (archive completes the terminal `[Report]` Task). +- [ ] SC2: `## Task Integration` documents the Phase Transition Rule with the two-sources-of-truth rationale. +- [ ] SC3: New regression test passes and fails if the instruction is removed. +- [ ] SC4: `check-skill-frontmatter`, `docs-code-sync`, `check-deadcode`, `validate-plugin --strict`, and Contract L1/L4/L5 gates stay green. +- [ ] SC5: Live QA (`claude -p "/bkit:pdca status" --plugin-dir .`) loads the skill with 0 errors. + +## 4. Out of Scope + +- Option 2 from the issue (hook auto-completes the predecessor Task) — technically infeasible: CC hooks cannot call `TaskUpdate`. Documented in the design as a rejected alternative. +- Any change to `plan-plus`, `cc-version-analysis`, `sprint` task patterns (they do not carry the multi-phase `blockedBy` chain). +- Auto-advance behavior in `pdca-task-completed.js` (unaffected and out of the reported gap). + +## 5. Approach + +Reporter Option 1 (SKILL.md prose), chosen because Option 2 is infeasible under CC's hook constraints and any hook approach still relies on the model performing the `TaskUpdate` — making it no more deterministic than an explicit skill step, only noisier. diff --git a/docs/01-plan/features/pdca-task-completion-chain.plan.ko.md b/docs/01-plan/features/pdca-task-completion-chain.plan.ko.md new file mode 100644 index 0000000..aac1149 --- /dev/null +++ b/docs/01-plan/features/pdca-task-completion-chain.plan.ko.md @@ -0,0 +1,52 @@ +# 계획 — PDCA 선행-Task 완료 체인 (issue #137, v2.1.29) + +## Executive Summary + +| 관점 | 요약 | +|---|---| +| **문제** | `pdca` 스킬은 phase Task를 `blockedBy` 체인(`[Plan]→[Design]→[Do]→[Check]→…`)으로 생성만 할 뿐, 다음 phase로 넘어갈 때 **선행 Task를 `completed`로 마킹하라는 지시가 없음**. 선행 Task가 `in_progress`로 남아, Claude Code 네이티브 task 목록이 매 턴 prompt context에 stale phase(예: "design")를 노출 — 올바른 `.bkit/state/pdca-status.json`의 `phase`와 불일치. | +| **해결** | 각 `pdca` phase action이 다음 phase Task를 생성하기 **직전**에 "선행 phase Task 완료" 지시를 추가하고, `## Task Integration` 섹션에 Phase Transition Rule을 명문화. 결정론적·모델 실행·dead code 없음. | +| **기능/UX 효과** | CC task 목록과 `pdca-status.json`이 항상 일치. phase 전환 후 stale 신호가 사라짐. | +| **핵심 가치** | 일치해야 할 두 진실 소스가 실제로 일치하게 되어, 기능 위험 0으로 혼란스러운 정보 불일치를 제거. | + +## Context Anchor + +| 키 | 값 | +|---|---| +| **WHY** | stale `in_progress` 선행 Task가 오래된 phase를 ambient prompt context에 노출, `pdca-status.json`과 모순. | +| **WHO** | `pdca` 스킬을 2개 이상 phase에 걸쳐 쓰는 모든 bkit 사용자(= 실제 PDCA 사용 전부). | +| **RISK** | 매우 낮음 — 스킬 파일 1개 prose + 회귀 테스트 1개. lib/hook 동작 변경 없음. | +| **SUCCESS** | `skills/pdca/SKILL.md`의 각 phase 전환이 선행 Task 완료를 지시; 회귀 테스트가 강제; 라이브 플러그인 로드 정상. | +| **SCOPE** | `skills/pdca/SKILL.md` 한정. 다단계 체인이 없는 plan-plus(단일 `[Plan]`), cc-version-analysis(단일 task), sprint(per-feature task)는 범위 외. | + +## 1. 배경 / 재현 + +- 보고자: @hslee-cmyk (bkit v2.1.28, CC v2.1.199). **low / cosmetic** 등급 — 심각도는 유지자 판단 위임. +- 소스 내 재현: `skills/pdca/SKILL.md` grep 결과, 모든 action에 `Create Task: [X] {feature}`(스텝: pm=6, plan=8, design=12, do=14, analyze=12, qa=5, iterate=5, report=9) 있으나 선행 phase Task 완료 지시는 **없음**. "completed" 언급은 `pdca-status.json` phase 쓰기와 archive 게이팅뿐 — Task 완료는 전무. +- CC 공식문서(hooks guide + todo-tracking) 확인: `TaskCreated`/`TaskCompleted`는 실제 발화 훅이나 **훅은 Task 상태를 mutate 불가**(stdout/exit-code/additionalContext만; `TaskUpdate`는 모델만 호출). + +## 2. 요구사항 + +- R1: 체인을 진행하는 각 `pdca` phase action은 새 phase Task 생성 전에 선행 phase Task(들)를 `completed`로 마킹하도록 지시해야 함. +- R2: `## Task Integration` 섹션은 Phase Transition Rule(왜+어떻게)을 문서화해 완료 의미를 암묵이 아닌 명시로. +- R3: 각 phase 전환에 완료 지시가 존재함을 assert하는 회귀 테스트로 누락 재발 방지. +- R4: lib/hook 런타임 동작 변경 없음; 아키텍처 카운트(스킬 44 / 에이전트 34 / 훅 이벤트 22 / lib 195) 불변. +- R5: 영어 전용 구현(SKILL.md, test); `docs/` 하위는 bilingual. + +## 3. 성공 기준 + +- [ ] SC1: `design`, `do`, `analyze`, `iterate`, `qa`, `report`, `archive` action 각각이 Create-Task 스텝 전에 "선행 Task 완료" 스텝 포함(archive는 종단 `[Report]` Task 완료). +- [ ] SC2: `## Task Integration`이 두 진실 소스 근거와 함께 Phase Transition Rule 문서화. +- [ ] SC3: 신규 회귀 테스트 통과, 지시 제거 시 실패. +- [ ] SC4: `check-skill-frontmatter`, `docs-code-sync`, `check-deadcode`, `validate-plugin --strict`, Contract L1/L4/L5 게이트 green 유지. +- [ ] SC5: 라이브 QA(`claude -p "/bkit:pdca status" --plugin-dir .`) 스킬 로드 0 에러. + +## 4. 범위 외 + +- 이슈의 Option 2(훅이 선행 Task 자동완료) — 기술적 불가능: CC 훅은 `TaskUpdate` 호출 불가. 설계에서 기각 대안으로 문서화. +- `plan-plus`, `cc-version-analysis`, `sprint` task 패턴 변경(다단계 `blockedBy` 체인 없음). +- `pdca-task-completed.js`의 auto-advance 동작(영향 없음, 보고된 갭과 무관). + +## 5. 접근 + +이슈 Option 1(SKILL.md prose) 채택. CC 훅 제약상 Option 2가 불가능하고, 어떤 훅 방식도 결국 모델이 `TaskUpdate`를 수행해야 하므로 명시적 스킬 스텝보다 결정론적이지 않고 노이즈만 크기 때문. diff --git a/docs/02-design/features/pdca-task-completion-chain.design.en.md b/docs/02-design/features/pdca-task-completion-chain.design.en.md new file mode 100644 index 0000000..1771506 --- /dev/null +++ b/docs/02-design/features/pdca-task-completion-chain.design.en.md @@ -0,0 +1,78 @@ +# Design — PDCA Predecessor-Task Completion Chain (issue #137, v2.1.29) + +## Context Anchor + +| Key | Value | +|---|---| +| WHY | Stale `in_progress` predecessor Tasks leak an outdated phase into prompt context, contradicting `pdca-status.json`. | +| WHO | All bkit users running `pdca` across ≥2 phases. | +| RISK | Very low — prose in one skill file + one regression test; no runtime change. | +| SUCCESS | Every phase transition instructs predecessor completion; test enforces it; plugin loads clean. | +| SCOPE | `skills/pdca/SKILL.md` only. | + +## 1. Overview + +Close the reported gap deterministically by instructing the model — inside the `pdca` skill prose — to mark predecessor phase Task(s) `completed` when advancing, and by documenting the rule centrally. + +## 2. Architecture Decision + +### 2.1 Options considered + +**Option A — Minimal Changes (chosen).** Add a "complete predecessor Task" step to each phase action immediately before its Create-Task step, plus a Phase Transition Rule in `## Task Integration`. Model-executed via the already-granted `TaskList`/`TaskUpdate` tools. No lib/hook change, no new runtime surface. + +**Option B — Hook auto-complete (REJECTED, infeasible).** The issue's Option 2 proposed a hook (`task-created-handler.js` / the UserPromptExpansion handler) auto-completing the predecessor Task on new-phase Task creation. **Rejected because CC hooks cannot mutate Task state.** Per the official Claude Code hooks guide, command hooks communicate only through stdout/stderr/exit codes and `additionalContext`; they cannot invoke `TaskUpdate` or any tool — only the model can. The strongest a hook could do is emit an `additionalContext` reminder, which *still* relies on the model performing the `TaskUpdate`. That makes Option B **no more deterministic than Option A**, while adding: +- token noise on every PDCA Task creation (~7 injections per feature lifecycle), +- new model-facing output from an audit-only hook (test churn, behavior change), +- a redundant second code path for a cosmetic issue. +Therefore Option B is strictly worse. `TaskCreated`/`TaskCompleted` remain wired for their existing audit/auto-advance duties (unchanged). + +**Option C — Doc-note only (REJECTED).** A README/guide note would not reach the model at runtime; the gap would persist for the actual skill execution path. + +### 2.2 Chosen design — the Phase Transition Rule + +A single, general rule (robust to branches like `qa` and iterative `[Act-N]`): + +> **Before creating a new phase's Task, mark every prior `[Phase] {feature}` Task for this feature that is still `in_progress` as `completed`** (use `TaskList` to find them, `TaskUpdate {status: "completed"}` on each). This resolves the `blockedBy` chain and keeps the Claude Code Task list consistent with `.bkit/state/pdca-status.json`. + +Using "any prior in_progress phase Task" rather than naming one exact predecessor makes the rule correct across the branching parts of the 9-phase lifecycle (`…→check→act→qa→report→archive`, where `act` may repeat and `qa` may be skipped). + +## 3. Exact edits to `skills/pdca/SKILL.md` + +Insert a completion step immediately before each Create-Task step (renumbering the following steps): + +| Action | Before step | Predecessor(s) to complete | +|---|---|---| +| `plan` | Create Task `[Plan]` | `[PM]` (if it exists) | +| `design` | Create Task `[Design]` | `[Plan]` | +| `do` | Create Task `[Do]` | `[Design]` | +| `analyze` | Create Task `[Check]` | `[Do]` | +| `iterate` | Create Task `[Act-N]` | `[Check]` and any prior `[Act-*]` still in_progress | +| `qa` | Create Task `[QA]` | `[Check]` / latest `[Act-N]` | +| `report` | Create Task `[Report]` | `[QA]` (or `[Check]`/`[Act-N]` if qa skipped) | +| `archive` | (creates no Task) | `[Report]` — add a completion step in the archive cleanup | + +Each inserted step uses the general rule wording (find prior in_progress `[Phase] {feature}` Tasks → complete them), with a short cross-reference to `## Task Integration`. + +Also update `## Task Integration`: +- Keep the creation diagram. +- Add a **Phase Transition Rule** subsection stating the completion rule and the two-sources-of-truth rationale. + +## 4. Regression test + +New file `test/regression/issue-137-predecessor-task-completion.test.js`: +- Reads `skills/pdca/SKILL.md`. +- Asserts the `## Task Integration` section contains the Phase Transition Rule (matches `completed` + `blockedBy`/`in_progress` wording). +- Asserts each of `design`, `do`, `analyze`, `report`, `archive` action bodies contains a `TaskUpdate`/`completed` completion instruction. +- Fails if any completion instruction is removed (guards the fix). + +## 5. Non-goals / invariants + +- Architecture counts unchanged (44 skills / 34 agents / 22 hook events / 25 blocks / 195 lib modules). No lib module added → `check-deadcode` count unchanged. +- No hooks.json change. +- English-only skill + test; bilingual docs. + +## 6. Verification plan + +- Static gates: `check-skill-frontmatter`, `lint-skill-md`, `docs-code-sync`, `check-deadcode`, `validate-plugin --strict`, Contract L1/L4/L5. +- Regression: new test green; whole `test/regression` suite no new failures vs `main`. +- Live QA: `claude -p "/bkit:pdca status" --plugin-dir .` loads skill, 0 errors; skill body shows the new instruction. diff --git a/docs/02-design/features/pdca-task-completion-chain.design.ko.md b/docs/02-design/features/pdca-task-completion-chain.design.ko.md new file mode 100644 index 0000000..d41d601 --- /dev/null +++ b/docs/02-design/features/pdca-task-completion-chain.design.ko.md @@ -0,0 +1,78 @@ +# 설계 — PDCA 선행-Task 완료 체인 (issue #137, v2.1.29) + +## Context Anchor + +| 키 | 값 | +|---|---| +| WHY | stale `in_progress` 선행 Task가 오래된 phase를 prompt context에 노출, `pdca-status.json`과 모순. | +| WHO | `pdca`를 2개 이상 phase에 걸쳐 쓰는 모든 bkit 사용자. | +| RISK | 매우 낮음 — 스킬 파일 1개 prose + 회귀 테스트 1개; 런타임 변경 없음. | +| SUCCESS | 모든 phase 전환이 선행 완료 지시; 테스트가 강제; 플러그인 로드 정상. | +| SCOPE | `skills/pdca/SKILL.md` 한정. | + +## 1. 개요 + +보고된 갭을 결정론적으로 해소: `pdca` 스킬 prose 안에서 모델에게 다음 phase 진행 시 선행 phase Task(들)를 `completed`로 마킹하도록 지시하고, 규칙을 중앙에 문서화. + +## 2. 아키텍처 결정 + +### 2.1 검토한 옵션 + +**Option A — Minimal Changes (채택).** 각 phase action의 Create-Task 스텝 직전에 "선행 Task 완료" 스텝 추가 + `## Task Integration`에 Phase Transition Rule. 이미 부여된 `TaskList`/`TaskUpdate` 도구로 모델이 실행. lib/hook 변경 없음, 신규 런타임 표면 없음. + +**Option B — 훅 자동완료 (기각, 불가능).** 이슈 Option 2는 훅(`task-created-handler.js` / UserPromptExpansion 핸들러)이 새 phase Task 생성 시 선행 Task를 자동완료하도록 제안. **CC 훅이 Task 상태를 mutate 불가하므로 기각.** CC 공식 hooks guide상 command 훅은 stdout/stderr/exit code와 `additionalContext`로만 통신하며 `TaskUpdate` 등 어떤 도구도 호출 불가 — 오직 모델만 가능. 훅이 할 수 있는 최선은 `additionalContext` 리마인더인데, 그마저 **모델이 `TaskUpdate`를 수행해야** 하므로 Option A보다 결정론적이지 않음. 게다가: +- 매 PDCA Task 생성마다 토큰 노이즈(feature 수명당 ~7회 주입), +- audit 전용 훅에 모델 대면 출력 신설(테스트 변경, 동작 변경), +- cosmetic 이슈에 중복 코드 경로. +∴ Option B는 명백히 열등. `TaskCreated`/`TaskCompleted`는 기존 audit/auto-advance 용도로 그대로 배선 유지(불변). + +**Option C — 문서 노트만 (기각).** README/guide 노트는 런타임에 모델에 도달하지 않음; 실제 스킬 실행 경로의 갭이 잔존. + +### 2.2 채택 설계 — Phase Transition Rule + +분기(`qa`, 반복 `[Act-N]`)에도 robust한 단일 일반 규칙: + +> **새 phase의 Task를 생성하기 전에, 이 feature의 아직 `in_progress`인 모든 선행 `[Phase] {feature}` Task를 `completed`로 마킹**(`TaskList`로 찾아 각각 `TaskUpdate {status: "completed"}`). 이로써 `blockedBy` 체인이 해소되고 CC Task 목록이 `.bkit/state/pdca-status.json`과 일치. + +정확한 선행 하나를 지정하기보다 "임의의 선행 in_progress phase Task"로 표현해 9-phase 수명주기의 분기부(`…→check→act→qa→report→archive`, `act` 반복·`qa` 스킵 가능)에서도 정확. + +## 3. `skills/pdca/SKILL.md` 정확한 수정 + +각 Create-Task 스텝 직전에 완료 스텝 삽입(후속 스텝 재번호): + +| Action | 스텝 앞 | 완료할 선행 | +|---|---|---| +| `plan` | Create Task `[Plan]` | `[PM]` (있으면) | +| `design` | Create Task `[Design]` | `[Plan]` | +| `do` | Create Task `[Do]` | `[Design]` | +| `analyze` | Create Task `[Check]` | `[Do]` | +| `iterate` | Create Task `[Act-N]` | `[Check]` 및 in_progress인 이전 `[Act-*]` | +| `qa` | Create Task `[QA]` | `[Check]` / 최신 `[Act-N]` | +| `report` | Create Task `[Report]` | `[QA]` (qa 스킵 시 `[Check]`/`[Act-N]`) | +| `archive` | (Task 생성 없음) | `[Report]` — archive 정리 단계에 완료 스텝 추가 | + +각 삽입 스텝은 일반 규칙 문구(선행 in_progress `[Phase] {feature}` Task 찾아 완료) + `## Task Integration` 상호참조. + +`## Task Integration`도 갱신: +- 생성 다이어그램 유지. +- **Phase Transition Rule** 하위섹션 추가(완료 규칙 + 두 진실 소스 근거). + +## 4. 회귀 테스트 + +신규 `test/regression/issue-137-predecessor-task-completion.test.js`: +- `skills/pdca/SKILL.md` 읽기. +- `## Task Integration`에 Phase Transition Rule 존재 assert(`completed` + `blockedBy`/`in_progress` 문구 매칭). +- `design`, `do`, `analyze`, `report`, `archive` action 본문 각각에 `TaskUpdate`/`completed` 완료 지시 존재 assert. +- 완료 지시 제거 시 실패(fix 보호). + +## 5. 비목표 / 불변식 + +- 아키텍처 카운트 불변(스킬 44 / 에이전트 34 / 훅 이벤트 22 / 블록 25 / lib 195). lib 모듈 미추가 → `check-deadcode` 카운트 불변. +- hooks.json 변경 없음. +- 영어 전용 스킬 + 테스트; bilingual 문서. + +## 6. 검증 계획 + +- 정적 게이트: `check-skill-frontmatter`, `lint-skill-md`, `docs-code-sync`, `check-deadcode`, `validate-plugin --strict`, Contract L1/L4/L5. +- 회귀: 신규 테스트 green; `test/regression` 전체 `main` 대비 신규 실패 0. +- 라이브 QA: `claude -p "/bkit:pdca status" --plugin-dir .` 스킬 로드 0 에러; 스킬 본문에 신규 지시 표시. diff --git a/docs/03-analysis/pdca-task-completion-chain.analysis.en.md b/docs/03-analysis/pdca-task-completion-chain.analysis.en.md new file mode 100644 index 0000000..aa09d92 --- /dev/null +++ b/docs/03-analysis/pdca-task-completion-chain.analysis.en.md @@ -0,0 +1,36 @@ +# Gap Analysis — PDCA Predecessor-Task Completion Chain (issue #137, v2.1.29) + +## Match Rate: 100% (design ↔ implementation) + +| Design item | Implemented? | Evidence | +|---|---|---| +| Completion step before Create-Task in `design` | ✅ | SKILL.md `design` step 12 — "Complete predecessor Task first" ([Plan]) | +| Completion step before Create-Task in `do` | ✅ | SKILL.md `do` step 14 ([Design]) | +| Completion step before Create-Task in `analyze` | ✅ | SKILL.md `analyze` step 12 ([Do]) | +| Completion step before Create-Task in `iterate` | ✅ | SKILL.md `iterate` step 5 ([Check] + prior [Act-*]) | +| Completion step before Create-Task in `qa` | ✅ | SKILL.md `qa` step 5 ([Check] / [Act-N]) | +| Completion step before Create-Task in `report` | ✅ | SKILL.md `report` step 9 ([QA] / [Check] / [Act-N]) | +| Terminal completion in `archive` | ✅ | SKILL.md `archive` step 2 ([Report] + any open phase Task) | +| `plan` completes optional `[PM]` | ✅ | SKILL.md `plan` step 8 | +| Phase Transition Rule in `## Task Integration` | ✅ | New subsection with completion rule + two-sources-of-truth rationale | +| Regression test guarding each transition | ✅ | `test/regression/issue-137-predecessor-task-completion.test.js` — 25/25 pass | +| Option 2 infeasibility documented | ✅ | Design §2.1, CHANGELOG, marketplace description | + +## Quality gates + +- `check-skill-frontmatter`: PASS (44 skills, under cap) +- `lint-skill-md`: PASS (exit 0) +- `check-deadcode`: PASS (195 modules, 0 new dead) +- `docs-code-sync`: PASS (version invariant 2.1.29 across plugin.json/README/CHANGELOG/hooks.json; one-liner 5/5) +- `validate-plugin --strict`: PASS (0 errors, 0 warnings; 44 skills / 34 agents / 2 commands valid) +- Contract L1/L4 vs v2.1.9 (222 assertions) & v2.1.16 (243): PASS +- `integration-runtime` 23/23, `l2-smoke` 105/105, `l2-hook-attribution` 13/13, `invocation-inventory` 213/213, `docs-code-sync.test` 36/36, `bkit-full-system` 36/36: PASS +- Regression baseline: failing-file set **identical** to `main` (13 pre-existing files) — **zero new regressions** + +## Live QA + +`claude -p "…" --plugin-dir .` in a fresh process loads the updated `skills/pdca/SKILL.md`; the model reads the "Complete predecessor Task first" steps and the `### Phase Transition Rule (task completion)` heading — the fix is reachable at runtime. + +## Residual gaps + +None. Architecture counts and runtime behavior unchanged; the fix is a deterministic, model-executed instruction backed by a regression test. diff --git a/docs/03-analysis/pdca-task-completion-chain.analysis.ko.md b/docs/03-analysis/pdca-task-completion-chain.analysis.ko.md new file mode 100644 index 0000000..7bcc12b --- /dev/null +++ b/docs/03-analysis/pdca-task-completion-chain.analysis.ko.md @@ -0,0 +1,36 @@ +# 갭 분석 — PDCA 선행-Task 완료 체인 (issue #137, v2.1.29) + +## Match Rate: 100% (설계 ↔ 구현) + +| 설계 항목 | 구현? | 근거 | +|---|---|---| +| `design`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `design` step 12 — "Complete predecessor Task first" ([Plan]) | +| `do`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `do` step 14 ([Design]) | +| `analyze`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `analyze` step 12 ([Do]) | +| `iterate`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `iterate` step 5 ([Check] + 이전 [Act-*]) | +| `qa`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `qa` step 5 ([Check] / [Act-N]) | +| `report`의 Create-Task 전 완료 스텝 | ✅ | SKILL.md `report` step 9 ([QA] / [Check] / [Act-N]) | +| `archive`의 종단 완료 | ✅ | SKILL.md `archive` step 2 ([Report] + 열린 phase Task) | +| `plan`의 선택적 `[PM]` 완료 | ✅ | SKILL.md `plan` step 8 | +| `## Task Integration`의 Phase Transition Rule | ✅ | 완료 규칙 + 두 진실 소스 근거 신규 하위섹션 | +| 각 전환 보호 회귀 테스트 | ✅ | `test/regression/issue-137-predecessor-task-completion.test.js` — 25/25 통과 | +| Option 2 불가능성 문서화 | ✅ | Design §2.1, CHANGELOG, marketplace 설명 | + +## 품질 게이트 + +- `check-skill-frontmatter`: PASS (44 스킬, cap 이내) +- `lint-skill-md`: PASS (exit 0) +- `check-deadcode`: PASS (195 모듈, 신규 dead 0) +- `docs-code-sync`: PASS (버전 불변식 2.1.29 일관; one-liner 5/5) +- `validate-plugin --strict`: PASS (0 error, 0 warning; 44 스킬 / 34 에이전트 / 2 커맨드 valid) +- Contract L1/L4 vs v2.1.9(222) & v2.1.16(243): PASS +- `integration-runtime` 23/23, `l2-smoke` 105/105, `l2-hook-attribution` 13/13, `invocation-inventory` 213/213, `docs-code-sync.test` 36/36, `bkit-full-system` 36/36: PASS +- 회귀 baseline: 실패 파일 집합이 `main`과 **완전 동일**(pre-existing 13개) — **신규 회귀 0건** + +## 라이브 QA + +신선한 프로세스의 `claude -p "…" --plugin-dir .`가 업데이트된 `skills/pdca/SKILL.md`를 로드; 모델이 "Complete predecessor Task first" 스텝과 `### Phase Transition Rule (task completion)` heading을 읽음 — fix가 런타임에 도달. + +## 잔여 갭 + +없음. 아키텍처 카운트·런타임 동작 불변; fix는 회귀 테스트로 뒷받침되는 결정론적·모델 실행 지시. diff --git a/docs/04-report/features/pdca-task-completion-chain.report.en.md b/docs/04-report/features/pdca-task-completion-chain.report.en.md new file mode 100644 index 0000000..756552a --- /dev/null +++ b/docs/04-report/features/pdca-task-completion-chain.report.en.md @@ -0,0 +1,45 @@ +# Completion Report — PDCA Predecessor-Task Completion Chain (issue #137, v2.1.29) + +## Executive Summary + +| Perspective | Value Delivered | +|---|---| +| **Problem** | `pdca` created a `blockedBy` Task chain but never completed predecessors → stale phase leaked into prompt context, contradicting `pdca-status.json`. | +| **Solution** | Deterministic SKILL.md prose fix: every phase action completes predecessor Task(s) before creating the next; centralized Phase Transition Rule; regression-guarded. | +| **Function/UX Effect** | CC task list and `pdca-status.json` now agree; no stale phase signal after advancing. | +| **Core Value** | Removed a confusing two-sources-of-truth discrepancy at zero functional/architecture risk. | + +## What changed + +- `skills/pdca/SKILL.md` — completion step added to `plan`/`design`/`do`/`analyze`/`iterate`/`qa`/`report` actions and terminal completion to `archive`; new `### Phase Transition Rule (task completion)` subsection under `## Task Integration`. +- `test/regression/issue-137-predecessor-task-completion.test.js` — 25-assertion guard. +- Version bump 2.1.28 → 2.1.29 (bkit.config.json canonical, plugin.json, marketplace.json ×2 + description, hooks.json, session-start.js, session-context.js, README badge + latest-release) + CHANGELOG `## [2.1.29]`. +- Bilingual PDCA docs (plan, design, analysis, report). + +## Key decisions & outcomes + +| Decision | Rationale | Outcome | +|---|---|---| +| Option 1 (SKILL.md prose), not Option 2 (hook auto-complete) | CC hooks cannot mutate Task state (stdout/exit-code/additionalContext only; only the model calls `TaskUpdate`) — confirmed against official CC hooks guide. Any hook approach still needs the model to act, so it is no more deterministic and noisier. | Deterministic fix, no new runtime surface, no dead code. | +| General "complete all prior in_progress phase Tasks" wording | Robust across the branching `qa`/`act` parts of the 9-phase lifecycle. | Single rule covers every transition. | +| Scope limited to `pdca` | Related skills carry no multi-phase `blockedBy` chain (plan-plus single Task, cc-version-analysis subtask tracking, sprint per-feature). | No collateral changes. | + +## Verification + +- All static + contract gates green; zero new regressions vs `main` (identical failing-file set). +- Live QA via fresh `claude -p --plugin-dir .` confirms the fix loads and is model-readable. + +## Success criteria — final status + +- SC1 predecessor-completion step per advancing action: ✅ Met +- SC2 Phase Transition Rule documented: ✅ Met +- SC3 regression test passes/guards: ✅ Met (25/25) +- SC4 CI gates green: ✅ Met +- SC5 live plugin load 0 errors: ✅ Met + +**Overall: 5/5 criteria met.** + +## Lessons learned + +- Before adopting a reporter's suggested hook-based fix, verify the hook capability against official docs — here it disqualified Option 2 outright and made the "cheaper" Option 1 the strictly-better choice. +- Model-facing skill prose is a legitimate, testable fix surface: a contract-style regression test over SKILL.md keeps prose fixes from silently regressing. diff --git a/docs/04-report/features/pdca-task-completion-chain.report.ko.md b/docs/04-report/features/pdca-task-completion-chain.report.ko.md new file mode 100644 index 0000000..69384f1 --- /dev/null +++ b/docs/04-report/features/pdca-task-completion-chain.report.ko.md @@ -0,0 +1,45 @@ +# 완료 리포트 — PDCA 선행-Task 완료 체인 (issue #137, v2.1.29) + +## Executive Summary + +| 관점 | 전달 가치 | +|---|---| +| **문제** | `pdca`가 `blockedBy` Task 체인을 생성만 하고 선행을 완료하지 않음 → stale phase가 prompt context에 노출, `pdca-status.json`과 모순. | +| **해결** | 결정론적 SKILL.md prose fix: 각 phase action이 다음 생성 전 선행 Task 완료; Phase Transition Rule 중앙화; 회귀 테스트 보호. | +| **기능/UX 효과** | CC task 목록과 `pdca-status.json` 일치; 전환 후 stale 신호 없음. | +| **핵심 가치** | 기능/아키텍처 위험 0으로 혼란스러운 두 진실 소스 불일치 제거. | + +## 변경 사항 + +- `skills/pdca/SKILL.md` — `plan`/`design`/`do`/`analyze`/`iterate`/`qa`/`report`에 완료 스텝 추가, `archive`에 종단 완료; `## Task Integration` 하위 `### Phase Transition Rule (task completion)` 신설. +- `test/regression/issue-137-predecessor-task-completion.test.js` — 25 assertion 가드. +- 버전 bump 2.1.28 → 2.1.29 (bkit.config.json canonical, plugin.json, marketplace.json ×2 + 설명, hooks.json, session-start.js, session-context.js, README badge + latest-release) + CHANGELOG `## [2.1.29]`. +- Bilingual PDCA 문서(plan, design, analysis, report). + +## 핵심 결정 & 결과 + +| 결정 | 근거 | 결과 | +|---|---|---| +| Option 1(SKILL.md prose), Option 2(훅 자동완료) X | CC 훅은 Task 상태 mutate 불가(stdout/exit-code/additionalContext만; `TaskUpdate`는 모델만) — CC 공식 hooks guide로 확인. 어떤 훅 방식도 결국 모델이 수행해야 하므로 더 결정론적이지 않고 노이즈만 큼. | 결정론적 fix, 신규 런타임 표면·dead code 없음. | +| "모든 선행 in_progress phase Task 완료" 일반 문구 | 9-phase의 분기부(`qa`/`act`)에도 robust. | 단일 규칙이 모든 전환 커버. | +| 범위 `pdca` 한정 | 연관 스킬에 다단계 `blockedBy` 체인 없음(plan-plus 단일 Task, cc-version-analysis 서브태스크, sprint per-feature). | 부수 변경 없음. | + +## 검증 + +- 모든 정적 + contract 게이트 green; `main` 대비 신규 회귀 0(실패 파일 집합 동일). +- 신선한 `claude -p --plugin-dir .` 라이브 QA가 fix 로드·모델 판독 확인. + +## 성공 기준 — 최종 상태 + +- SC1 각 진행 action의 선행 완료 스텝: ✅ 충족 +- SC2 Phase Transition Rule 문서화: ✅ 충족 +- SC3 회귀 테스트 통과/가드: ✅ 충족(25/25) +- SC4 CI 게이트 green: ✅ 충족 +- SC5 라이브 플러그인 로드 0 에러: ✅ 충족 + +**종합: 5/5 충족.** + +## 교훈 + +- 보고자가 제안한 훅 기반 fix 채택 전 훅 능력을 공식 문서로 검증 — 여기서 Option 2를 곧바로 실격시키고 "더 저렴한" Option 1을 명백히 우월한 선택으로 만듦. +- 모델 대면 스킬 prose는 정당하고 테스트 가능한 fix 표면: SKILL.md 대상 contract형 회귀 테스트가 prose fix의 조용한 재발을 막음. diff --git a/hooks/hooks.json b/hooks/hooks.json index be69ccf..64620db 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -1,6 +1,6 @@ { "$schema": "https://json.schemastore.org/claude-code-hooks.json", - "description": "bkit Vibecoding Kit v2.1.28 - Claude Code", + "description": "bkit Vibecoding Kit v2.1.29 - Claude Code", "hooks": { "SessionStart": [ { diff --git a/hooks/session-start.js b/hooks/session-start.js index a218ad2..363c8a8 100644 --- a/hooks/session-start.js +++ b/hooks/session-start.js @@ -1,6 +1,6 @@ #!/usr/bin/env node /** - * bkit Vibecoding Kit - SessionStart Hook (v2.1.28, uses BKIT_VERSION from lib/core/version) + * bkit Vibecoding Kit - SessionStart Hook (v2.1.29, uses BKIT_VERSION from lib/core/version) * * Thin orchestrator that delegates to startup modules: * 1. migration - Legacy path migration (docs/ -> .bkit/) diff --git a/hooks/startup/session-context.js b/hooks/startup/session-context.js index 1b87ec6..54703b5 100644 --- a/hooks/startup/session-context.js +++ b/hooks/startup/session-context.js @@ -1,5 +1,5 @@ /** - * bkit Vibecoding Kit - SessionStart: Session Context Builder Module (v2.1.28) + * bkit Vibecoding Kit - SessionStart: Session Context Builder Module (v2.1.29) * * Builds the additionalContext string for the SessionStart hook response. * Includes PDCA status injection, Feature Usage rules, Executive Summary rules, diff --git a/skills/pdca/SKILL.md b/skills/pdca/SKILL.md index 93db971..dbabb0b 100644 --- a/skills/pdca/SKILL.md +++ b/skills/pdca/SKILL.md @@ -105,7 +105,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. 5. **Checkpoint 1 — Requirements Confirmation**: Present understanding of the feature (problem, scope, constraints) and use AskUserQuestion: "요구사항 이해가 맞나요? 빠진 건 없나요?" Wait for user confirmation before proceeding. 6. **Checkpoint 2 — Clarifying Questions**: Identify underspecified elements (edge cases, error handling, integration points, compatibility). Present organized question list. Wait for answers before generating the document. 7. Generate Plan document with user-confirmed requirements -8. Create Task: `[Plan] {feature}` +8. **Complete predecessor Task first**: If a `[PM] {feature}` Task exists and is still `in_progress`, use TaskList to find it and TaskUpdate it to `status: "completed"` before creating the Plan Task (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Plan] {feature}` 9. Update `.bkit/state/pdca-status.json`: phase = "plan" 10. Write `## Executive Summary` at document top with 4-perspective table (Problem/Solution/Function UX Effect/Core Value), each 1-2 sentences 11. **Context Anchor Generation**: After generating Plan document, extract Context Anchor (WHY/WHO/RISK/SUCCESS/SCOPE) from Executive Summary, Requirements, and Risk sections. Write as `## Context Anchor` table between Executive Summary and Section 1. This anchor propagates to Design/Do documents for cross-session context continuity. @@ -137,7 +137,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. - Suggest: "UI 컨셉 페이지를 1-2개 먼저 만든 후 `/design-anchor capture {feature}` 로 디자인 토큰을 잠그세요" - If Design Anchor already exists (`docs/02-design/styles/{feature}.design-anchor.md`), embed it in the Design document as `## Design Anchor` section - This ensures design tokens (colors, typography, spacing) are locked before implementation -12. Create Task: `[Design] {feature}` (blockedBy: Plan task) +12. **Complete predecessor Task first**: Use TaskList to find the `[Plan] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Design] {feature}` (blockedBy: Plan task) 13. Update `.bkit/state/pdca-status.json`: phase = "design" **Output Path**: `docs/02-design/features/{feature}.design.md` @@ -174,7 +174,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. - At module/file level: `// Design Ref: §{section} — {decision rationale}` - At critical logic: `// Plan SC: {success criteria being addressed}` - These comments create traceable links from code back to design decisions -14. Create Task: `[Do] {feature}` (blockedBy: Design task) +14. **Complete predecessor Task first**: Use TaskList to find the `[Design] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Do] {feature}` (blockedBy: Design task) 15. Update `.bkit/state/pdca-status.json`: phase = "do" **--scope Parameter**: @@ -261,7 +261,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. - "Critical만 수정" — iterate critical only - "그대로 진행" — accept current state Wait for user decision before proceeding. -12. Create Task: `[Check] {feature}` (blockedBy: Do task) +12. **Complete predecessor Task first**: Use TaskList to find the `[Do] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` — this resolves the `blockedBy` chain and prevents stale phase status from leaking into prompt context (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Check] {feature}` (blockedBy: Do task) 13. Update `.bkit/state/pdca-status.json`: phase = "check", matchRate **Output Path**: `docs/03-analysis/{feature}.analysis.md` @@ -281,7 +281,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. - `QA_PASS` → auto-advance to `report` phase - `QA_FAIL` → fall back to `iterate` phase - `QA_SKIP` → mark qa as skipped, proceed to `report` -5. Create Task: `[QA] {feature}` +5. **Complete predecessor Task first**: Use TaskList to find the `[Check] {feature}` Task and the latest `[Act-N] {feature}` Task (and any earlier phase Task for this feature still `in_progress`) and TaskUpdate each to `status: "completed"` (see [Phase Transition Rule](#task-integration)). Then Create Task: `[QA] {feature}` 6. Update `.bkit/state/pdca-status.json`: phase = "qa", qaStatus = **Output Path**: `docs/05-qa/{feature}.qa-report.md` @@ -294,7 +294,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. 2. **Call pdca-iterator Agent** 3. Auto-fix code based on Gap list 4. Auto re-run Check after fixes -5. Create Task: `[Act-N] {feature}` (N = iteration count) +5. **Complete predecessor Task first**: Use TaskList to find the `[Check] {feature}` Task and any prior `[Act-*] {feature}` Task for this feature still `in_progress` and TaskUpdate each to `status: "completed"` (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Act-N] {feature}` (N = iteration count) 6. Stop when >= 90% reached or max iterations (5) hit **Iteration Rules**: @@ -322,7 +322,7 @@ Run PM Agent Team for product discovery and strategy analysis before Plan phase. - Overall Success Rate: X/Y criteria met 7. Include `## Executive Summary` with `### 1.3 Value Delivered` reflecting actual results (4 perspectives with metrics) 8. **MANDATORY**: After completing the report, also output the Executive Summary table in your response -9. Create Task: `[Report] {feature}` +9. **Complete predecessor Task first**: Use TaskList to find the `[QA] {feature}` Task (or the `[Check] {feature}` / latest `[Act-N] {feature}` Task if QA was skipped) and any earlier phase Task for this feature still `in_progress`, and TaskUpdate each to `status: "completed"` (see [Phase Transition Rule](#task-integration)). Then Create Task: `[Report] {feature}` 10. Update `.bkit/state/pdca-status.json`: phase = "completed" **Output Path**: `docs/04-report/{feature}.report.md` @@ -386,12 +386,13 @@ Feature: user-auth ### archive (Archive Phase) 1. Verify Report completion status (phase = "completed" or matchRate >= 90%) -2. Verify PDCA documents exist (plan, design, analysis, report) -3. Create `docs/archive/YYYY-MM/{feature}/` folder -4. Move documents (delete from original location) -5. Update Archive Index (`docs/archive/YYYY-MM/_INDEX.md`) -6. Update .bkit/state/pdca-status.json: phase = "archived", record archivedTo path -7. Remove feature from status (or preserve summary with `--summary` option) +2. **Complete the terminal Task**: Use TaskList to find the `[Report] {feature}` Task and any other `[Phase] {feature}` Task for this feature still `in_progress`, and TaskUpdate each to `status: "completed"` — the feature is terminal, so no phase Task should remain open (see [Phase Transition Rule](#task-integration)). +3. Verify PDCA documents exist (plan, design, analysis, report) +4. Create `docs/archive/YYYY-MM/{feature}/` folder +5. Move documents (delete from original location) +6. Update Archive Index (`docs/archive/YYYY-MM/_INDEX.md`) +7. Update .bkit/state/pdca-status.json: phase = "archived", record archivedTo path +8. Remove feature from status (or preserve summary with `--summary` option) **Arguments**: | Argument | Description | Example | @@ -559,6 +560,23 @@ Task Creation Pattern: └────────────────────────────────────────┘ ``` +### Phase Transition Rule (task completion) + +The diagram above shows task *creation*. Advancing a phase also requires task *completion*: + +> **Before creating a new phase's Task, mark every prior `[Phase] {feature}` Task for +> this feature that is still `in_progress` as `completed`** — use `TaskList` to find them +> and `TaskUpdate {status: "completed"}` on each. The `archive` action likewise completes +> the terminal `[Report]` Task. + +**Why this matters**: a `blockedBy` chain is only semantically correct when the predecessor +is `completed` by the time the successor is created. More importantly, Claude Code surfaces +the native Task list into ambient prompt context every turn. If a predecessor Task is left +`in_progress`, that stale phase (e.g. "design" during a "do" phase) keeps leaking back to the +user — disagreeing with `.bkit/state/pdca-status.json`'s `phase` field, which is the phase +source of truth. Completing predecessors keeps the two in sync. Each phase action above +embeds this step immediately before its Create-Task step. + ## Agent Integration | Action | Agent | Role | diff --git a/test/regression/issue-137-predecessor-task-completion.test.js b/test/regression/issue-137-predecessor-task-completion.test.js new file mode 100644 index 0000000..5a18156 --- /dev/null +++ b/test/regression/issue-137-predecessor-task-completion.test.js @@ -0,0 +1,105 @@ +#!/usr/bin/env node +'use strict'; +/** + * issue-137-predecessor-task-completion.test.js — Regression guard for GitHub #137. + * + * The `pdca` skill chains phase Tasks via `blockedBy` ([Plan]→[Design]→[Do]→…), + * but SKILL.md historically documented Task *creation* only — never Task + * *completion* of the predecessor phase. A predecessor 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` field. + * + * Option 2 from the issue (a hook auto-completing the predecessor) is infeasible: + * per the CC hooks guide, hooks communicate via stdout/exit-code/additionalContext + * only and cannot call TaskUpdate — only the model can. The v2.1.29 fix is + * therefore Option 1: each phase action instructs the model to complete the + * predecessor Task before creating the next one, and `## Task Integration` + * codifies the Phase Transition Rule. + * + * This test fails if any of those completion instructions is removed. + */ + +const fs = require('node:fs'); +const path = require('node:path'); + +const REPO = path.resolve(__dirname, '..', '..'); +const SKILL = path.join(REPO, 'skills', 'pdca', 'SKILL.md'); +const src = fs.readFileSync(SKILL, 'utf8'); + +let pass = 0, fail = 0; +const failures = []; +function tc(name, cond, detail) { + if (cond) { pass++; } + else { fail++; failures.push(`${name}${detail ? ' :: ' + detail : ''}`); } +} + +// Extract a `### ` section body (up to the next `### ` or `## ` header). +function actionSection(actionHeaderPrefix) { + const re = new RegExp( + '\\n### ' + actionHeaderPrefix + '[^\\n]*\\n([\\s\\S]*?)(?=\\n### |\\n## )', 'm'); + const m = src.match(re); + return m ? m[1] : ''; +} + +// A section "completes a predecessor" if it tells the model to TaskUpdate a +// phase Task to completed status. +function hasCompletionInstruction(body) { + return /TaskUpdate/.test(body) && /status:\s*"completed"|`completed`|to\s+`?completed`?/i.test(body); +} + +// --- 1. Task Integration documents the Phase Transition Rule ------------------- +{ + const hasRuleHeader = /Phase Transition Rule/.test(src); + tc('Task Integration section documents a "Phase Transition Rule"', hasRuleHeader); + + // The rule must mention completing predecessors AND the reason (prompt-context / + // pdca-status.json two-sources-of-truth). + const ruleBlock = (src.match(/### Phase Transition Rule[\s\S]*?(?=\n## )/) || [''])[0]; + tc('Phase Transition Rule tells the model to mark predecessors completed', + /completed/.test(ruleBlock) && /in_progress/.test(ruleBlock) && /blockedBy/.test(ruleBlock), + 'rule block missing completed/in_progress/blockedBy wording'); + tc('Phase Transition Rule explains the pdca-status.json / prompt-context rationale', + /pdca-status\.json/.test(ruleBlock) && /prompt context/i.test(ruleBlock), + 'rule block missing the two-sources-of-truth rationale'); +} + +// --- 2. Each advancing phase action embeds a completion instruction ------------ +{ + // action header prefix -> the predecessor phase label it must mention + const cases = [ + ['design', 'Plan'], + ['do', 'Design'], + ['analyze', 'Do'], + ['iterate', 'Check'], + ['qa', 'Check'], + ['report', 'QA'], + ['archive', 'Report'], + ]; + for (const [action, predLabel] of cases) { + const body = actionSection(action); + tc(`${action} action section is present`, body.length > 0); + tc(`${action} action instructs completing a predecessor Task (TaskUpdate→completed)`, + hasCompletionInstruction(body), 'no TaskUpdate/completed instruction found'); + tc(`${action} action names its predecessor phase Task [${predLabel}]`, + new RegExp('\\[' + predLabel + '(-N|-\\*)?\\]').test(body), + `expected a [${predLabel}] reference in the ${action} section`); + } +} + +// --- 3. Guard against silent regression of the creation-only pattern ---------- +{ + // Every "Create Task: `[X]`" step that advances the chain must be preceded in + // its own action by a completion instruction. We already assert per-action + // above; here we assert the fix wording marker exists at least 7 times + // (design, do, analyze, iterate, qa, report + archive terminal). + const markers = (src.match(/Complete (predecessor|the terminal) Task/g) || []).length; + tc('at least 7 explicit "Complete predecessor/terminal Task" steps exist', + markers >= 7, `found ${markers}`); +} + +console.log(`\nissue-137-predecessor-task-completion.test.js: ${pass} passed, ${fail} failed`); +if (failures.length) { + console.error('FAILURES:'); + for (const f of failures) console.error(` - ${f}`); + process.exit(1); +}