[lanhhoang]

Summary

Documentation gate for the 2026-10-13 architecture deepening proposal. Planning commits 06a7c29 (design + phase 1–3 extraction + execution module scaffolds) and 2a7fa53 (per-phase implementation plans with checkbox status); range master..HEAD is +636 over four new files under docs/superpowers/{specs,plans}/.

 docs/superpowers/specs/
+└── 2026-10-13-dcp-architecture-deepening-design.md   # 240 lines
    #  reduces caller-managed knowledge in three modules without
    #  changing DCP behavior: read-only reporting facts, branch
    #  restoration + checkpoints, compression-run execution +
    #  completion
    #  compatibility constraints pin snapshot v2, durable field
    #  names, fingerprints, owner-session statistics, repair
    #  behavior, host event order, approval/policy recheck order,
    #  and exception propagation

 docs/superpowers/plans/
+├── 2026-10-13-dcp-depth-phase-01-reporting.md          # 131 lines
+│   #  src/reporting.ts owns DcpContextFacts + readDcp{Context,Session,Lifetime}Facts
+│   #  consumers: context/stats/lifetime commands + buildDcpPanelModel
+│   #  lifetime scanning + display formatting stay with existing owners
+├── 2026-10-13-dcp-depth-phase-02-checkpoints.md        # 123 lines
+│   #  src/state/checkpoints.ts owns restoreBranch + persist
+│   #  holds the event-local force intent and last successful fingerprint
+│   #  restores through resetSessionState + codec; persist is a () => void seam
+│   #  consumed by Phase 3
+└── 2026-10-13-dcp-depth-phase-03-compression-execution.md   # 142 lines
    #  src/compress/execution.ts owns checkToolCall, execute, complete
    #  preserves the four rejection copy strings + precedence order
    #  requests checkpoint through persist() after every compression end
    #  delegates block/duration writes to compress/blocks.ts

Each phase plan in docs/superpowers/plans/2026-10-13-dcp-depth-phase-0[1-3]-*.md pins module paths, public operation names, integration points, and behavioral assertions for one atomic step, sharing the same global-constraints block carried from the 2026-10-12 architecture design:

phase 1: src/reporting.ts                    # shared read-only reporting facts for both adapters
phase 2: src/state/checkpoints.ts            # branch restoration + checkpoint owner with fingerprint memory
phase 3: src/compress/execution.ts           # compression-run policy, approval, timing, and completion

phase 1 — read-only reporting facts
  contextCommand / statsCommand / lifetimeCommand / buildDcpPanelModel
       │
       └── readDcpContextFacts(state, usage)
           readDcpSessionFacts(state)
           readDcpLifetimeFacts(loadedLifetime)   # lifetime scan still owned by persistence

phase 2 — branch restoration + checkpoints
  session_start                session_tree            operator callback            compaction
  shutdown                    compression end            context (pipeline end)
       │                           │                         │                         │
       └────────────── createDcpCheckpoints(host, state, config, warn) ────────────────┘
                                       │
                                       ├── restoreBranch("session-start" | "branch-navigation", ctx)
                                       │      ├── resetSessionState → current manualMode/permission defaults
                                       │      ├── reverse branch scan + parseDcpSnapshot + restoreDcpSnapshot
                                       │      └── store event-local force decision (clean / inherited / repair)
                                       │
                                       └── persist()
                                              ├── serializeDcpSnapshot + durableStateFingerprint
                                              ├── append only if changed (or stored force intent)
                                              └── advance fingerprint only on successful append

phase 3 — compression run execution + completion
  tool preflight (compress def)        direct execution (registered handler)        host compression_end
       │                                          │                                          │
       └──────────── createCompressionExecution(deps) ────────────── compress/blocks.ts ──────┘
                                       │
                                       ├── checkToolCall(ctx.model): config › model › subagent › permission
                                       ├── execute(mode, id, params, ctx, signal?):
                                       │      policy → permission → ask approval (native) →
                                       │      abort check → fresh policy check → timing start
                                       │      → handleCompress → onCompressed(result, ctx)
                                       └── complete({ toolCallId, toolName, isError? }):
                                              ignore non-compression; clear matching timing even on error;
                                              recordCompressionDuration via blocks.ts on success;
                                              persist() exactly once per compression end

The deepening revisits two earlier placements from the 2026-10-12 architecture design on purpose: the prior review kept approval/checkpoint orchestration and runtime timing in their current owners; this proposal concentrates them now that those owners have shipped and remaining caller-managed ordering is the bottleneck. Earlier codec, block-lifecycle, tool-selection, and guarded-action responsibilities are preserved untouched in every phase.

tests/ change set is zero for this branch; the planning rule from prior phase plans holds: implementation checkboxes are intentionally unchecked at plan-writing time, follow-up phase PRs ship the test changes with their source.

Evidence

This branch ships the planning artifacts only; no src/, tests/, docs/agents/, dcp.schema.json, package.json, CHANGELOG.md, README.md, or GLOSSARY.md was touched.

$ git diff --stat master..HEAD
 .../2026-10-13-dcp-depth-phase-01-reporting.md     | 131 +++++++++++
 .../2026-10-13-dcp-depth-phase-02-checkpoints.md   | 123 +++++++++++
 ...-13-dcp-depth-phase-03-compression-execution.md | 142 ++++++++++++
 ...2026-10-13-dcp-architecture-deepening-design.md | 240 +++++++++++++++++++++
 4 files changed, 636 insertions(+)

Implementation is gated on each follow-up phase PR; the documented planning baseline is 41da383 (master HEAD) with a fresh pnpm check recorded in the spec: formatting, lint, type checking, and 66 test files / 1,153 tests. A working-tree test run is not applicable to a docs-only change.

Each phase plan is independently shippable against its own scoped test files:

phase 1 checks: tests/reporting.test.ts (new)
               tests/commands-{context,stats,lifetime}.test.ts
               tests/panel-{model,render}.test.ts tests/panel.test.ts
               tests/commands-register.test.ts tests/sdk-contract.test.ts

phase 2 checks: tests/checkpoints.test.ts (new)
               tests/{index,persistence,state,pi-contract,sdk-contract}.test.ts
               tests/tool-selection.test.ts tests/dcp-actions.test.ts
               tests/compression-timing.test.ts tests/pipeline.test.ts

phase 3 checks: tests/compression-execution.test.ts (new)
               tests/compression-timing.test.ts (migrated)
               tests/{compress-permission,compression-blocks,compress-cycle}.test.ts
               tests/{index,pi-contract,sdk-contract}.test.ts
               tests/{compress-notification,notification-delivery}.test.ts
               tests/{compress-render,tool-selection,checkpoints}.test.ts

The review-focus tables in each plan carry the verification input/condition matrix that the implementation must satisfy — separation of text vs. dashboard percentage precision, zero counters vs. unavailable totals, fresh nested state on every read, append-failure retry + fingerprint retention, equal-fingerprint force-decision consumption, untimed-compression shutdown persistence, allow vs. ask abort semantics, and timing-zero + multi-block completion.

Merge Danger

Door: two-way

The change is documentation only and reverts cleanly: deleting the four new files in docs/superpowers/{specs,plans}/ returns the repository to its prior state with zero impact on src/, tests/, package.json, the snapshot codec, persistence ordering, model-visible compression text, pruning/compression algorithms, policy, tool selection, statistics calculations, the guarded executeDcpAction contract, native ui.confirm approval, the public ExtensionAPI surface, README, CHANGELOG, or any GitHub workflow. No snapshot version, durable field, schema, dependency, configuration option, release, or glossary term ships in this PR. Each follow-up phase PR is revertible on its own, and the design also states that revert ordering for the executable phases is "revert later dependent phases first."

Blast Radius: planning documentation

Touches only docs/superpowers/specs/ (one new deepening design) and docs/superpowers/plans/ (three new phase-1–3 plans), +636 lines. No production source, test, snapshot, schema, configuration, dependency, README, CHANGELOG, agent docs, GLOSSARY.md, or release workflow is modified, so no consumer of the published extension observes any behavior change. The only observable change is that a reviewer now has a four-document approved design that sequences future architecture deepening into three independently shippable phases with per-phase review/test focus, rollback notes, and an explicit revisit of the 12 October checkpoint-placement decision with its rationale.