@xulthekl/team-flow 0.23.0 → 0.24.0

package/skills/workflow-start/SKILL.md

@@ -15,14 +15,14 @@ Do NOT invoke for: general coding tasks outside team-flow changes, casual questi
 
 ## States
 
-`exploring` → `specifying` → `bridging` → `approved-for-build` → `executing` → `closing`, with `debugging` side-path from `executing`, and `abandoned` as terminal. If a transition is ambiguous, run `npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime asset read docs/state-machine.md`.
+`exploring` → `specifying` → `bridging` → `approved-for-build` → `executing` → `closing`, with `debugging` side-path from `executing`, and `abandoned` as terminal. If a transition is ambiguous, run `npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime asset read docs/state-machine.md`.
 
 ## Initialization
 
-1. **Update check**: Run `npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime check-update`. Exit 0 → continue. Exit 1 → non-blocking upgrade reminder. Exit 2 → skip.
+1. **Update check**: Run `npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime check-update`. Exit 0 → continue. Exit 1 → non-blocking upgrade reminder. Exit 2 → skip.
 2. **Inspect change folder**: Check for `proposal.md`, `specs/`, `design.md`, `tasks.md`, `execution-contract.md`. Answer: Is the change fuzzy? Artifacts missing/unstable? Contract exist? User approved contract? Execution in progress or blocked? In verification/wrap-up?
-3. **Overlay recovery scan**: Run `npx --yes --package @xulthekl/team-flow@0.23.0 tf handoff list <change-dir> --json` and `npx --yes --package @xulthekl/team-flow@0.23.0 tf checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `npx --yes --package @xulthekl/team-flow@0.23.0 tf handoff resolve` before resuming the affected work. An `active` handoff is non-blocking side work. Show a non-stale checkpoint as recovery context; show a stale checkpoint only as historical evidence.
-4. **Execution-control recovery scan**: For `approved-for-build`, `executing`, `debugging`, or `closing`, run `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution show <change-dir> --json`. Treat only `current: true` plus `waves[].eligible: true` as permission to start a wave; report plan revision, mode, next eligible wave, and every wave's receipt/blockers. A missing, invalid, or stale plan blocks implementation and routes to `build-executor`; do not infer progress from chat history.
+3. **Overlay recovery scan**: Run `npx --yes --package @xulthekl/team-flow@0.24.0 tf handoff list <change-dir> --json` and `npx --yes --package @xulthekl/team-flow@0.24.0 tf checkpoint list <change-dir> --json`. A `result-ready` handoff requires explicit review and `npx --yes --package @xulthekl/team-flow@0.24.0 tf handoff resolve` before resuming the affected work. An `active` handoff is non-blocking side work. Show a non-stale checkpoint as recovery context; show a stale checkpoint only as historical evidence.
+4. **Execution-control recovery scan**: For `approved-for-build`, `executing`, `debugging`, or `closing`, run `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution show <change-dir> --json`. Treat only `current: true` plus `waves[].eligible: true` as permission to start a wave; report plan revision, mode, next eligible wave, and every wave's receipt/blockers. A missing, invalid, or stale plan blocks implementation and routes to `build-executor`; do not infer progress from chat history.
 
 ## DP-0: User Confirmation Gate
 
@@ -36,17 +36,17 @@ Ask (manual path): change name + one-sentence intent, known constraints, related
 
 After confirmation:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_decisions "<summary>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_result confirmed
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_confirmed true
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 
 Config-aware routing: check `artifacts.order` and `artifacts.skip` from project config.
 
 ## Mode Detection
 
-If workflow is `auto`/`null`/unset: run `npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime infer <change-dir>`. Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger). Persist with `npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <dir> workflow <mode>`.
+If workflow is `auto`/`null`/unset: run `npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime infer <change-dir>`. Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger). Persist with `npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <dir> workflow <mode>`.
 
 Validate mode against artifact content. If hotfix/tweak criteria not met → upgrade to `full` and output reason. Don't overwrite explicit mode unless user asks.
 
@@ -59,19 +59,19 @@ Change is fuzzy, scope unclear, comparing options, no stable change name.
 Guard: `arch_design_decision` in `.team-flow.yaml` is `null` → must run before spec-writer. Dispatch `architecture-design` as sub-agent; after return, run reasonableness check and write yaml. Full protocol in `references/routing-rules.md`「Route to architecture-design」.
 
 ### Route to spec-writer
-Guard: `npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
+Guard: `npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK. **arch_design_decision must not be null** → fail = BLOCK (v0.9 §26). User knows what they want, artifacts missing/incomplete.
 
 ### Route to contract-builder
 Guard: `... check <dir> specifying bridging --json` → fail = BLOCK. Artifacts exist, implementation requested, contract missing/stale. Include `DP-3: 契约批准`.
 
 ### Route to build-executor
-Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK.
+Contract exists and approved, contract matches artifacts. Include `DP-4: 执行模式选择`: propose waves, run `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution recommend <change-dir> [--wave ...]`, show the user every available mode plus evidence and the recommendation, then obtain a clear selection. The command saves a current receipt; before the first implementation edit, `build-executor` must run `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution plan <change-dir> --mode <selected> --confirm ...` (and `--acknowledge-recommendation` when the selected mode differs from the recommendation) using matching artifacts, contract, and waves, then `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution show <change-dir> --json`; report the saved revision, selected mode, recommendation alignment, ordered waves, and actual concurrent-dispatch capability. A revision must repeat recommend and confirmation. Do not transition to `executing` until `show` reports `current: true`; then run `... check <dir> approved-for-build executing --json` → fail = BLOCK.
 
 ### Route to bug-investigator
 Execution hit blockage: test failure, unexpected behavior, build error, task cannot proceed. After debugging, route back to build-executor.
 
 ### Route to code-reviewer
-The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
+The current planned wave is implemented and ready for spec-compliance + code-quality verification. A reviewer must write an `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>` receipt before any dependent wave or closing transition.
 
 ### Route to release-archivist
 Guard: `... check <dir> executing closing --json` → fail = BLOCK. Implementation complete, verification complete/nearly complete. Include `DP-7: 归档确认`.
@@ -90,10 +90,10 @@ uncertainty. Do not create a prototype handoff or enter a prototype worktree
 until the user confirms. After confirmation:
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf handoff create <change-dir> \
+npx --yes --package @xulthekl/team-flow@0.24.0 tf handoff create <change-dir> \
   --type prototype --objective "<confirmed objective>" \
   --expected-output "<expected evidence>" --acceptance "<completion criterion>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf isolate <change-dir> prototype-<handoff-id>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf isolate <change-dir> prototype-<handoff-id>
 ```
 
 Never suggest or enter this route automatically for backend, CLI, configuration,
@@ -107,7 +107,7 @@ work.
 - **Hotfix**: Route to contract-builder (minimal), skip need-explorer + spec-writer, guard check `exploring bridging --workflow hotfix`, then `bridging -> approved-for-build`, after DP-3 → build-executor (recommend, show, and confirm an execution mode), after → release-archivist (lightweight). Hotfix may skip `proposal.md`, `design.md`, `tasks.md`, and `specs/`, but it still requires a fresh minimal `execution-contract.md`, DP-3 approval, and a current execution plan before build. **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门，快速判定是否涉及架构变更（hotfix 可能正是架构缺陷导致）
 - **Tweak**: Route to build-executor (direct edit), skip need-explorer + spec-writer + contract-builder, guard check `exploring approved-for-build --workflow tweak`, after → release-archivist (lightweight). **architecture-design 不豁免**（v0.9 §26）：同样过 architecture-design 子代理判断门
 
-Post-transition: 💡 `npx --yes --package @xulthekl/team-flow@0.23.0 tf inject <change-dir>` to update phase-guard artifacts.
+Post-transition: 💡 `npx --yes --package @xulthekl/team-flow@0.24.0 tf inject <change-dir>` to update phase-guard artifacts.
 
 ## Staleness Detection
 
@@ -124,7 +124,7 @@ Use content inspection, not timestamps.
 ## Guardrails
 
 - No implementation before planning artifacts or contract exist
-- No implementation for full/hotfix without a current `npx --yes --package @xulthekl/team-flow@0.23.0 tf execution plan`; no state transition based on an unverified DP-4 string
+- No implementation for full/hotfix without a current `npx --yes --package @xulthekl/team-flow@0.24.0 tf execution plan`; no state transition based on an unverified DP-4 string
 - No "continue" without state inspection
 - No implementation past stale contract
 - No implementation past bug without investigation

package/skills/workflow-start/references/routing-rules.md

@@ -32,17 +32,17 @@ artifacts:                       # required 时必填
 - `null`（未判定）→ **BLOCK**
 
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> arch_design_decision "<required|skipped>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> arch_design_reason "<reason>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> arch_design_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_decision "<required|skipped>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_reason "<reason>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 # if required:
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> arch_design_artifacts "architecture/architecture.md,architecture/database.md,architecture/api.md"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> arch_design_artifacts "architecture/architecture.md,architecture/database.md,architecture/api.md"
 ```
 
 **hotfix / tweak 不豁免**：同样过 architecture-design 子代理判断门。
 
 ## Route to spec-writer
-Guard: `npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK.
+Guard: `npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime guard check <dir> exploring specifying --json` → fail = BLOCK.
 **arch_design_decision must not be null** → fail = BLOCK（architecture-design gate not passed，v0.9 §26）。
 User knows what they want, artifacts missing/incomplete.
 
@@ -55,12 +55,12 @@ Contract exists and approved, contract matches artifacts. Include DP-4: 执行
 
 Propose waves, run:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf execution recommend <change-dir> [--wave ...]
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution recommend <change-dir> [--wave ...]
 ```
 Show every available mode plus evidence and recommendation, obtain clear selection. Then:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf execution plan <change-dir> --mode <selected> --confirm ...
-npx --yes --package @xulthekl/team-flow@0.23.0 tf execution show <change-dir> --json
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution plan <change-dir> --mode <selected> --confirm ...
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution show <change-dir> --json
 ```
 Do not transition to `executing` until `show` reports `current: true`.
 Guard: `... check <dir> approved-for-build executing --json` → fail = BLOCK.
@@ -71,7 +71,7 @@ Execution hit blockage: test failure, unexpected behavior, build error. After de
 ## Route to code-reviewer
 Current planned wave implemented and ready for review. Reviewer must write:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf execution review <change-dir> --wave <id> --base <sha> --head <sha> --report <path> --verdict <pass|fail>
 ```
 
 ## Route to release-archivist
@@ -93,10 +93,10 @@ User explicitly requests, bug-investigator escalates after 3+ failures AND user
 
 When the user's brief explicitly contains UI/screen/interaction/layout/UX uncertainty, ask once whether a prototype would reduce uncertainty. After confirmation:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf handoff create <change-dir> \
+npx --yes --package @xulthekl/team-flow@0.24.0 tf handoff create <change-dir> \
   --type prototype --objective "<confirmed objective>" \
   --expected-output "<expected evidence>" --acceptance "<completion criterion>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf isolate <change-dir> prototype-<handoff-id>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf isolate <change-dir> prototype-<handoff-id>
 ```
 Never suggest for backend/CLI/config/internal-refactor work. Never pass `--force`.
 
@@ -130,17 +130,17 @@ else:
 
 After confirmation:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_decisions "<summary>"
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_result confirmed
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_confirmed true
-npx --yes --package @xulthekl/team-flow@0.23.0 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_decisions "<summary>"
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_result confirmed
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_confirmed true
+npx --yes --package @xulthekl/team-flow@0.24.0 tf state set <change-dir> dp_0_timestamp $(date -u +%Y-%m-%dT%H:%M:%SZ)
 ```
 
 ## Mode Detection
 
 If workflow is `auto`/`null`/unset:
 ```bash
-npx --yes --package @xulthekl/team-flow@0.23.0 tf runtime infer <change-dir>
+npx --yes --package @xulthekl/team-flow@0.24.0 tf runtime infer <change-dir>
 ```
 Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **tweak** (≤4 tasks, config/doc only), **full** (anything larger).
 
@@ -152,4 +152,4 @@ Inference: **hotfix** (≤2 tasks, ≤2 files, no schema/API/new modules), **twe
 - **Brief drift (advisory, v0.9)**: change-brief.md 的 `plan_hash` 与当前 plan.md 不一致 → 提示回 orchestrator 重新分发；**不**阻断、**不**进 artifacts_hash、**不**混入上述三条产物互查
 
 ## Post-transition
-💡 `npx --yes --package @xulthekl/team-flow@0.23.0 tf inject <change-dir>` to update phase-guard artifacts.
+💡 `npx --yes --package @xulthekl/team-flow@0.24.0 tf inject <change-dir>` to update phase-guard artifacts.

package/tests/lib/guard-compound-captured.test.mjs

@@ -0,0 +1,92 @@
+// tests/lib/guard-compound-captured.test.mjs
+// v0.24.0: compound-captured guard — executing:closing must require learnings.md
+// or explicit compound_skipped=true in state.
+
+import { describe, it, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+// Import the check function directly for unit-level testing.
+const { checkCompoundCaptured } = await import(
+  join(ROOT, 'scripts', 'guard', 'checks', 'compound-captured.mjs')
+);
+
+function makeDir(prefix) {
+  return mkdtempSync(join(tmpdir(), `tf-compound-${prefix}-`));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+describe('compound-captured guard', () => {
+  describe('learnings.md existence', () => {
+    let dir;
+    before(() => { dir = makeDir('learnings'); });
+    after(() => cleanup(dir));
+
+    it('SHALL fail when no learnings.md and no compound_skipped', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+      assert.ok(result.failures.length > 0);
+      assert.match(result.failures[0], /Compound capture missing/);
+    });
+
+    it('SHALL pass when learnings.md exists and is non-empty', () => {
+      writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+
+    it('SHALL fail when learnings.md exists but is empty', () => {
+      writeFileSync(join(dir, 'learnings.md'), '');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+      assert.match(result.failures[0], /empty/);
+    });
+  });
+
+  describe('compound_skipped explicit opt-out', () => {
+    let dir;
+    before(() => { dir = makeDir('skip'); });
+    after(() => cleanup(dir));
+
+    it('SHALL pass when compound_skipped=true and no learnings.md', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\ncompound_skipped: true\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+
+    it('SHALL fail when compound_skipped=false (not opted out)', () => {
+      writeFileSync(join(dir, '.team-flow.yaml'), 'state: executing\nworkflow: full\ncompound_skipped: false\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+    });
+  });
+
+  describe('no state file (backward compatibility)', () => {
+    let dir;
+    before(() => { dir = makeDir('no-state'); });
+    after(() => cleanup(dir));
+
+    it('SHALL fail when no state file and no learnings.md', () => {
+      // No .team-flow.yaml, no learnings.md — guard should still fail
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, false);
+    });
+
+    it('SHALL pass when no state file but learnings.md exists', () => {
+      writeFileSync(join(dir, 'learnings.md'), '# Learnings\nContent.\n');
+      const result = checkCompoundCaptured(dir);
+      assert.equal(result.pass, true);
+    });
+  });
+});

package/tests/lib/guard-specs-merged.test.mjs

@@ -27,6 +27,8 @@ function makeChangeDir(withDelta) {
     ? '## ADDED Requirements\n\n### Requirement: New\n\nThe system SHALL do new.\n\n#### Scenario: New\n- **WHEN** x\n- **THEN** y\n'
     : '## Requirements\n\n### Requirement: Existing\n\nThe system SHALL exist.\n\n#### Scenario: Existing\n- **WHEN** a\n- **THEN** b\n';
   writeFileSync(join(dir, 'specs', 'test.md'), specsContent);
+  // v0.24.0: compound-captured dimension requires learnings.md
+  writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
   initializeGitRepository(dir);
   return dir;
 }

package/tests/lib/guard-tests-passing.test.mjs

@@ -25,6 +25,8 @@ function makeChangeDir() {
   writeFileSync(join(dir, 'tasks.md'), '# Tasks\n\n- [x] Task 1\n- [x] Task 2\n');
   writeFileSync(join(dir, 'specs', 'test.md'), '## ADDED Requirements\n\n### Requirement: Test\n\nThe system SHALL test.\n\n#### Scenario: Test\n- **WHEN** test\n- **THEN** test\n');
   writeFileSync(join(dir, 'execution-contract.md'), '# Execution Contract\n\n## Intent Lock\nTest.\n');
+  // v0.24.0: compound-captured dimension requires learnings.md
+  writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nTest.\n');
   initializeGitRepository(dir);
   return dir;
 }

package/tests/lib/guard.test.mjs

@@ -312,6 +312,8 @@ describe('guard: execution control records', () => {
   function recordPassingClosingPrerequisites() {
     runNodeScript(CLI_PATH, ['state', 'set', dir, 'test_result', 'pass: unit tests']);
     runNodeScript(CLI_PATH, ['state', 'set', dir, 'spec_merged', 'true']);
+    // v0.24.0: compound-captured dimension requires learnings.md (or explicit skip)
+    writeFileSync(join(dir, 'learnings.md'), '# Session Learnings\n\n## Lesson 1\nCaptured during guard test.\n');
   }
 
   function writeReviewReport(name, content = 'Review completed without blocking findings.\n') {

package/tests/lib/solutions-capture.test.mjs

@@ -0,0 +1,108 @@
+// tests/lib/solutions-capture.test.mjs
+// Tests for scripts/lib/solutions-capture.mjs — compound capture mechanism
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: captureRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-capture.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-capture-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+describe('solutions-capture', () => {
+  let dir;
+
+  beforeEach(() => {
+    dir = makeDir();
+  });
+
+  after(() => {
+    // Clean up all temp dirs
+    cleanup(dir);
+  });
+
+  it('creates experience file in correct phase directory', () => {
+    const result = captureRun({
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high',
+      summary: 'OAuth token refresh fails silently', dir,
+    });
+
+    assert.equal(result.phase, 'prd');
+    assert.equal(result.severity, 'high');
+    assert.match(result.file, /^prd\/\d{4}-\d{2}-\d{2}-.*\.md$/);
+
+    // Verify file exists and has frontmatter
+    const filePath = join(dir, result.file);
+    assert.ok(existsSync(filePath), 'experience file should exist');
+    const content = readFileSync(filePath, 'utf-8');
+    assert.match(content, /^---\nphase: prd\n/);
+    assert.match(content, /domain: auth/);
+    assert.match(content, /type: pitfall/);
+    assert.match(content, /severity: high/);
+  });
+
+  it('creates INDEX.md from scratch when missing', () => {
+    captureRun({
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium',
+      summary: 'Parallel test execution race condition', dir,
+    });
+
+    const indexPath = join(dir, 'INDEX.md');
+    assert.ok(existsSync(indexPath), 'INDEX.md should be created');
+    const content = readFileSync(indexPath, 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /parallel test execution/i);
+  });
+
+  it('appends to existing INDEX.md', () => {
+    captureRun({ phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', summary: 'First issue', dir });
+    captureRun({ phase: 'spec', domain: 'api', type: 'insight', severity: 'low', summary: 'Second issue', dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /First issue/);
+    assert.match(content, /Second issue/);
+  });
+
+  it('handles Chinese characters in summary (slugify)', () => {
+    const result = captureRun({
+      phase: 'review', domain: 'frontend', type: 'pitfall', severity: 'high',
+      summary: '中文标题测试特殊字符', dir,
+    });
+
+    assert.ok(result.file.includes('review/'), 'file should be in review phase');
+    assert.ok(existsSync(join(dir, result.file)), 'file with Chinese slug should exist');
+  });
+
+  it('uses cross-phase as default when no phase specified', () => {
+    const result = captureRun({ dir });
+    assert.equal(result.phase, 'cross-phase');
+    assert.equal(result.domain, 'general');
+    assert.equal(result.severity, 'medium');
+  });
+
+  it('rejects invalid phase', () => {
+    // capture calls process.exit(1) on invalid phase
+    // We test by checking that the function does not create files
+    const origExit = process.exit;
+    let exitCode = null;
+    process.exit = (code) => { exitCode = code; };
+    try {
+      captureRun({ phase: 'invalid-phase', dir });
+    } catch { /* ignore */ }
+    process.exit = origExit;
+    assert.equal(exitCode, 1, 'should exit with code 1 for invalid phase');
+  });
+});

package/tests/lib/solutions-index-gen.test.mjs

@@ -0,0 +1,147 @@
+// tests/lib/solutions-index-gen.test.mjs
+// Tests for scripts/lib/solutions-index-gen.mjs — full INDEX.md rebuild
+
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, existsSync, rmSync, mkdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const ROOT = join(__dirname, '..', '..');
+
+const { run: indexGenRun } = await import(join(ROOT, 'scripts', 'lib', 'solutions-index-gen.mjs'));
+
+function makeDir() {
+  return mkdtempSync(join(tmpdir(), 'tf-sol-indexgen-'));
+}
+
+function cleanup(dir) {
+  if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+}
+
+function writeEntry(dir, phase, filename, fm) {
+  const phaseDir = join(dir, phase);
+  mkdirSync(phaseDir, { recursive: true });
+  const fmLines = Object.entries(fm).map(([k, v]) => `${k}: ${v}`).join('\n');
+  writeFileSync(join(phaseDir, filename), `---\n${fmLines}\n---\n\n${fm.summary || 'Body text'}\n`, 'utf-8');
+}
+
+describe('solutions-index-gen', () => {
+  let dir;
+
+  beforeEach(() => { dir = makeDir(); });
+  after(() => { cleanup(dir); });
+
+  it('rebuilds INDEX.md from phase directories', () => {
+    writeEntry(dir, 'prd', '2026-07-01-auth-issue.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'build', '2026-07-02-ci-pattern.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    assert.match(content, /auth-issue/);
+    assert.match(content, /ci-pattern/);
+  });
+
+  it('sorts by severity descending (high before medium before low)', () => {
+    writeEntry(dir, 'prd', 'low.md', {
+      phase: 'prd', domain: 'd1', type: 'pitfall', severity: 'low', date: '2026-07-03',
+    });
+    writeEntry(dir, 'prd', 'high.md', {
+      phase: 'prd', domain: 'd2', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'medium.md', {
+      phase: 'prd', domain: 'd3', type: 'pitfall', severity: 'medium', date: '2026-07-02',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const highPos = content.indexOf('d2');
+    const medPos = content.indexOf('d3');
+    const lowPos = content.indexOf('d1');
+    assert.ok(highPos < medPos, 'high should appear before medium');
+    assert.ok(medPos < lowPos, 'medium should appear before low');
+  });
+
+  it('sorts by date descending within same severity', () => {
+    writeEntry(dir, 'prd', 'older.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-01',
+    });
+    writeEntry(dir, 'prd', 'newer.md', {
+      phase: 'prd', domain: 'auth', type: 'pitfall', severity: 'high', date: '2026-07-15',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const newerPos = content.indexOf('2026-07-15');
+    const olderPos = content.indexOf('2026-07-01');
+    assert.ok(newerPos < olderPos, 'newer date should appear before older date');
+  });
+
+  it('scans all 7 phase directories', () => {
+    const phases = ['prd', 'plan', 'prototype', 'spec', 'build', 'review', 'cross-phase'];
+    for (const phase of phases) {
+      writeEntry(dir, phase, `2026-07-01-${phase}-entry.md`, {
+        phase, domain: 'general', type: 'insight', severity: 'medium', date: '2026-07-01',
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    for (const phase of phases) {
+      assert.match(content, new RegExp(phase), `INDEX should contain ${phase} entries`);
+    }
+  });
+
+  it('skips non-.md files', () => {
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    writeFileSync(join(dir, 'build', 'readme.txt'), 'Not a markdown file', 'utf-8');
+    writeEntry(dir, 'build', '2026-07-01-real.md', {
+      phase: 'build', domain: 'ci', type: 'pattern', severity: 'high', date: '2026-07-01',
+    });
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.doesNotMatch(content, /readme\.txt/);
+    assert.match(content, /real\.md/);
+  });
+
+  it('truncates to 150 entries (drops lowest priority)', () => {
+    // Create 155 entries (all high severity, varying dates)
+    mkdirSync(join(dir, 'build'), { recursive: true });
+    for (let i = 0; i < 155; i++) {
+      const day = String((i % 28) + 1).padStart(2, '0');
+      writeEntry(dir, 'build', `entry-${String(i).padStart(3, '0')}.md`, {
+        phase: 'build', domain: `d${i}`, type: 'pattern', severity: 'high', date: `2026-07-${day}`,
+      });
+    }
+
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 150, 'INDEX should be truncated to 150 entries');
+  });
+
+  it('handles empty solutions directory', () => {
+    // No phase directories exist
+    indexGenRun({ dir });
+
+    const content = readFileSync(join(dir, 'INDEX.md'), 'utf-8');
+    assert.match(content, /# Solutions Index/);
+    const dataLines = content.split('\n').filter(l => l.startsWith('|') && !l.startsWith('| date') && !l.startsWith('|--'));
+    assert.equal(dataLines.length, 0);
+  });
+});