Skip to content

refactor playbook: extend state machine to Steps 8-13 + stale-cache fix - #130

Open
lis186 wants to merge 10 commits into
feature/skill-slimfrom
feature/steps-8-13
Open

refactor playbook: extend state machine to Steps 8-13 + stale-cache fix#130
lis186 wants to merge 10 commits into
feature/skill-slimfrom
feature/steps-8-13

Conversation

@lis186

@lis186 lis186 commented Jul 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

What

Closes the "Playbook ends at Step 7" gap, fixes a real stale-cache bug, and integrates verification-principles into Steps 8-13.

1. fix: pilot-run.sh stale cross-language cache

cross-language.yaml was regenerated only when missing. A months-old cache silently fed stale counts into pilot reports — caught by refactor_harness fact-check on WordPress-iOS after updating the repo (3/5 claims failed; 100% pass after fix). Now regenerated whenever older than the last commit.

2. feat: Steps 8-13 state extension

  • state.sh: step keys 8_new_impl … 13_delete_legacy (shadow 9a/9b/9c share 9_swap); advance refuses past final step 13
  • init-state.sh + templates/state.yaml: schema 2.1 (old 2.0 state files unchanged through Step 7)
  • mode-dispatch.yaml: S8–S13 apply in all four modes
  • gate-postswap.sh (new): the Done-When grep signals from the SKILL.md tables become exit codes for Steps 8/12/13 (9-11 remain test-suite gates)
  • test-postswap.sh: 9-assertion self-check — state walk 7→13 + gate pass/fail in both directions (ALL PASS)
  • SKILL.md: tables point at the gate; new Gotchas section seeded with the stale-cache lesson

3. feat: verification-principles 整合 (Steps 8-13)

核心主張：「測試全綠只證沒變差，不證更好。」四個 commit：

0617d604 — Step 12 結構指標

  • gate-postswap.sh --step 12 接受 --impl-file，寫出 12_metrics.yaml（LOC、決策點 grep 代理、零引用數，before vs after）
  • 反向訊號（LOC >150%、決策點上升）印 ⚠️ REVIEW 但不影響 exit code
  • 文件同步：SKILL.md verification boundary 註記、兩張表 Step 12 row、workflow.md §4.3 護欄段、steps-8-13-by-mode.md 全 mode 註記

ecbd9007 — success_criteria 宣告 + goal_checks 回照

  • init-state.sh scaffold success_criteria（goal + checks[]）在 1_target.yaml 尾端
  • gate-postswap.sh Step 12 回照段：讀 success_criteria、逐條 bash -c 跑 verify、✓/✗ 寫進 12_metrics.yaml → goal_checks
  • 沿用 gate-contracts.sh 的 \" unescape 先例
  • workflow.md §1.5 Declare Success Criteria + SKILL.md Quick Start 同步

a6a9f25b — worked examples + retrospective prompt

  • workflow.md §1.5 加三個 template（拆職責/可測試性/去耦合）+ 紅燈指引
  • Step 12 印 retrospective prompt，寫 retrospective: pending 進 yaml

492f3283 — 補 goal-only unverified path 測試

  • Fable 驗證計畫指出的最大覆蓋缺口

4. docs: Plan A redo spec executed (was pending since 2026-05-05)

Ran E2E on WordPress-iOS (AztecPostViewController.swift, clean-context agent): Step 1 gate PASS — #28 fix verified (init-state.sh reuses prior pilot, no hand-edits, candidate locked). Step 2a PASS (67 zones). Step 2b blocked by /atlas.audit's gemini/codex CLI dependency — gemini CLI is dead for individuals as of 2026-07 (IneligibleTierError), so every real user now lands in degraded mode. Follow-up: replace external-CLI cross-validation with subagent-based blind review.

Verification

  • scripts/test-postswap.sh → ALL PASS (23/23)
  • refactor_harness FULL run: fact-check 100% ×3 codebases, injection 2/2
  • E2E smoke on WordPress-iOS per dev-notes/2026-05/2026-05-05-plan-a-redo-spec.md (record filled in)

🤖 Generated with Claude Code

Justin Lee and others added 10 commits July 7, 2026 12:53
Justin Lee @claude
fix(refactor): regenerate cross-language cache when older than last c…
1913597 
…ommit

Stale .sourceatlas/cross-language.yaml from a previous run silently fed
months-old counts into pilot reports (caught by harness fact-check on
WordPress-iOS after repo update: 3/5 claims failed).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee @claude
feat(refactor): extend state machine to Steps 8-13 with gate-postswap
fcedd31 
- state.sh: step keys 8_new_impl..13_delete_legacy (shadow 9a/9b/9c share
  9_swap); advance refuses past final step 13
- init-state.sh + templates/state.yaml: schema 2.1 adds six step entries
  (old 2.0 state files unchanged through Step 7)
- mode-dispatch.yaml: S8-S13 apply in every mode
- gate-postswap.sh: Done-When grep signals for Steps 8/12/13 as exit
  codes; SKILL.md tables now point at it
- test-postswap.sh: 9-assertion self-check (state walk 7-13 + gate
  pass/fail both directions)
- SKILL.md: Gotchas section seeded with the stale-cache lesson

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee @claude
docs(refactor): Plan A redo spec executed — Step 1 gate PASS on WordP…
ada5e62 
…ress-iOS

#28 fix verified E2E: init-state.sh reuses prior pilot report without
state.yaml, no hand-edits, schema 2.1, candidate locked. Step 2b blocked
by /atlas.audit external-CLI dependency (gemini CLI dead as of 2026-07)
— tracked as follow-up.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee @claude
feat(audit,seam): replace gemini with agy; subagent fallback replaces…
88781e5 
… degraded mode

gemini CLI is dead for individual accounts (IneligibleTierError, 2026-07).
Reviewer policy is now: blind scan = agy CLI, adversarial = codex CLI;
either missing or failing at runtime falls back to a fresh-context Claude
subagent with the identical prompt — independence comes from the clean
context, not the vendor. The pipeline never blocks, so the entire
degraded-mode machinery (prompt files for manual execution) is deleted.

- audit/seam SKILL.md: reviewer resolution, fallback rules, reviewers:
  field in outputs; Task added to allowed-tools; seam description gains
  when-to-use triggers; CONFIRM_RATIO 30-70% relabeled as unvalidated
  reference heuristic
- seam/refactor workflow.md: gemini sections rewritten as blind-scan with
  agy Option A / subagent Option B; vendor-neutral artifact names
  (3_seams_blind.md, adversary-output.md); audit_mode degraded → subagent

Verified live: refactor_harness grading now runs GRADERS=(agy claude) —
agy graded all 3 pilots successfully (~15s each).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee
fix(refactor): Group C battle scars from express E2E full walk (Steps…
84c763b 
… 1-13)

First real run on a Dynamic-group target (express lib/response.js) — nine
script fixes, two documented gaps, all gates now pass end to end:

- detect-zones/pilot-run: kill 'grep -c || echo 0' double-zero (9 sites);
  zero-marker guard now works (the JS norm, previously never exercised)
- init-step2a: synthesize whole-file zone when detect-zones finds none
- gate-contracts/gate-seams/gate-step7: unescape YAML \" in extracted
  verification_grep rules (three copies of the same extraction bug)
- gate-step7: re-run as Step 10 verification no longer regresses
  current_step 10 -> 8 (only advances when current_step <= 7)
- gate-postswap: language-group dispatch for dynamic languages — Steps
  8/13 check module-path require refs instead of bare common-word class
  names ('response' matched ServerResponse and prose); Step 12 handles
  Group C no-adapter-class by design; adapter-name regex anchored to
  line start (was matching 'class exists' inside a comment)
- state.sh: set-status gains --audit-mode full|subagent (workflow requires
  recording it; Rule 15 forbids hand-edits; there was no API)
- SKILL.md: +9 gotchas (agy --add-dir, reviewer CLI death mid-playbook,
  quote-free verification_grep, mocha vs jest for Group C, audit --zone
  interop gap, etc.)
- dev-notes: full scar list for the express E2E run

Verified: test-postswap.sh ALL PASS (Group A unregressed); express walk
reached 13_delete_legacy: verified with npm test green (1258).
Justin Lee @claude
fix(refactor): frontmatter --step range 1-7 → 1-13
2372f36 
argument-hint and description didn't reflect that Steps 8-13 are
tracked by state.sh and verified by gate-postswap.sh since fcedd31.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Justin Lee @claude
feat(refactor): Step 12 記錄結構指標作為改善證據
0617d60 
「測試全綠」只證明無回歸,不證明更好。gate-postswap --step 12
新增 [--impl-file] 並寫出 12_metrics.yaml(LOC、決策點 grep 代理、
零引用數,before vs after);反向訊號印 ⚠️ REVIEW 但不影響 exit
code——指標是證據,方向判斷留給人。

文件同步:SKILL.md 加 verification boundary 註記 + 兩張表 Step 12
row、workflow.md §4.3 加「characterization tests 是護欄,寫得出
fail-on-old 是警訊」、steps-8-13-by-mode.md 加全 mode 共用註記。

self-test 16 case ALL PASS(既有 9 case 不變綠)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee @claude
feat(refactor): Step 1 宣告 success_criteria,Step 12 機器回照
ecbd900 
「先寫紅」的指標版:動手前在 1_target.yaml 宣告這次重構的
「更好」定義(goal + 可機器驗的 checks),Step 12 gate-postswap
逐條跑 verify 並將 ✓/✗ 寫進 12_metrics.yaml → goal_checks。
未達成的宣告判準大聲印出但不改 exit code——達成與否是人的判決。

- init-state.sh scaffold success_criteria(空 = 靜默,向後相容)
- gate-postswap.sh 回照段沿用 gate-contracts.sh 的 \" unescape 先例
- templates/1_target.yaml 註明這是唯一允許事後手填的區塊
- workflow.md §1.5 說明宣告時機與 verify 規則慣例
- SKILL.md verification boundary 補 goal_checks

self-test 20 assertions ALL PASS(既有 16 個不變綠)。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Justin Lee @claude
feat(refactor): worked examples + retrospective prompt
a6a9f25 
§1.5 加三個 success_criteria template（拆職責/可測試性/去耦合）
和紅燈指引（宣告後立刻跑,應該 fail）。Step 12 尾端印 retrospective
prompt 並寫 pending 進 12_metrics.yaml,由 LLM 向使用者確認後更新
為 yes/no/deferred。

self-test 21 assertions ALL PASS（+1 retrospective 斷言）。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Justin Lee @claude
test(refactor): 補 goal-only unverified path 測試
492f328 
Fable 驗證計畫指出「goal 非空 + checks 空 → unverified: true」是
最常見使用模式但零覆蓋。補兩條斷言釘住這條 path。

self-test 23 assertions ALL PASS。

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@lis186