Issue 215 Direct Planning Research
Task boundaries, verification commands, and external cache contracts for the approved direct plan
Issue 215 Direct Planning Research
The user approved Q1–Q13 and requested a direct plan without SPEC.md. This report records readonly planning discovery at 1ee7f8b72f8fe116ad74aa15923238d3b985c751. It supplements the safety/performance report and shared-cache report.
Research lanes
Three existing readonly agents were reused. planner_consistency inspected shared desired state, update orchestration, output, and test ownership. staging_failures inspected candidate preparation, installation, cache identities, and transport seams. lint_bootstrap inspected Turbo entrypoints, trusted access, and proof gaps. The coordinator checked scripts, pinned versions, official API/source material, and synthesized this report. No lane changed source or ran product tests.
Findings
| Finding | Primary evidence | Planning consequence |
|---|---|---|
| The large updater owns repeated plans, observations, application, and result assembly. | apps/cli/src/update/run.ts (runUpdate, previewScaffold, preliminary/final materialization) | Give orchestration and its tests one integration owner. |
| Shared desired-state logic and scaffold output already have testable boundaries. | features/scaffold-state/{lifecycle,compile,reconcile,model}.ts, scaffold/output.ts, their tests | Fix scaffold/check/update parity at that boundary; avoid three selectors. |
Baseline resolution happens before runUpdate. | platform/feature-application-operations.ts:334–380 | First progress belongs at command entry, before baseline work; runtime events alone cannot fix startup silence. |
| Candidate preparation, install, patch, lint, and findings currently share one module. | runtime/scripts.ts:133–147,652–956,959–1040 | One owner changes scripts.ts and scripts.test.ts per wave; cache/remote modules can be disjoint. |
| Existing fingerprints are partial witnesses. Default subprocess environment is ambient. | runtime/scripts.ts (childEnvironment, fingerprintLiveState, manifestFingerprint) | Separate mutation protection from complete cache identity; unknown inputs force fresh validation. |
| Local executable links must remain contained, and Effect patching mutates installed content. | runtime/scripts.ts:276–308,692–721; existing isolation tests | Restore private writable installations; validate links after relocation; publish only after successful approved patching. |
| No updater remote upload/download adapter exists. | baseline/resolve.ts; .github/actions/turbo-cache/action.yml; cache-trust-policy.mjs | Add an optional adapter to the existing signed artifact provider. Baseline endpoints remain release authority, not mutable cache storage. |
| Turbo runtime/capability hash names lack producers on normal entrypoints. | package.json, turbo.json, scripts/behavior-contract/run-ci-verification.mjs | Establish consistent identities before invoking Turbo locally and in CI. |
| Root cache-policy tests are Bun tests outside CLI Vitest. | scripts/behavior-contract/{cache-trust,affected-verification}.test.ts; apps/cli/vitest.config.ts | Wire their execution explicitly; CLI tests do not cover them. |
| Outer archive lookup and inner task identity differ. | .github/actions/turbo-cache/cache-trust-policy.mjs | Keep fallback archive restoration safe; do not remove SHA from archive keys as a substitute for task identity work. |
| Generated runbooks have a source writer. | apps/wiki/scripts/sync-content.mjs | Edit docs/runbooks/*; regenerate wiki copies. |
Paths in the first six rows are relative to apps/cli/src unless fully qualified.
External contracts checked
Context7 and web-search tools were unavailable. The coordinator retrieved official documentation and version-pinned upstream source directly over HTTPS on 2026-09-16.
- Turbo remote caching: local use is optional; remote access uses authentication/team linkage; artifact signatures use
TURBO_REMOTE_CACHE_SIGNATURE_KEY; invalid signatures become misses. Logs are artifacts and require redaction. - Turbo Remote Cache OpenAPI: artifact status, HEAD/GET/PUT endpoints; upload is a gzip-compressed tarball with signature metadata. The documentation identifies v8 endpoints as compatible with Turbo releases. This supports an adapter to the existing service, not a new backend.
- Turbo 2.9.14 signature source: pinned
bun.lockresolves 2.9.14. Its HMAC uses artifact hash, canonical team ID, then artifact body, with a 32-byte minimum key. Current upstream main uses a different signature message format. Implement against the pinned version and retain protocol vectors; do not copy current-main signing blindly. - Bun install: frozen installs enforce lock/manifest consistency; isolated installs use a central package store and links. Current documentation includes behavior newer than repository-pinned Bun 1.3.5; prove exact behavior with that binary before relying on pruning, relocation, or frozen-without-lock details. Preserve
--ignore-scriptsand the existing explicit approved patch path. - Effect source: resolved through
opensrc path Effect-TS/effectto the global source cache.effect/Cachesupports bounded in-process deduplication and exit-aware TTL. It does not supply a durable cross-process artifact store, atomic filesystem publication, or remote archive integrity. Retain existing Promise/process seams where appropriate; do not introduce a service for pure hashing.
Corrections and limits
CLI validation uses the package-owned bun run --cwd apps/cli check-types and check scripts, confirmed by structured package JSON inspection. Wiki content checking uses bun run --cwd apps/wiki check:content; generation uses node apps/wiki/scripts/sync-content.mjs because there is no sync:content alias. A readiness failure is not valid behavioral RED evidence.
Existing built-CLI tests require a fresh apps/cli/dist/index.js. The current environment previously failed on missing packaged baseline assets and incompatible dependency fallback. No successful end-to-end updater timing is established. GitHub cache setup and generic hit counts do not prove remote artifact restoration; local authentication and provider policy remain delivery evidence to collect.
Synthesis
The plan can start six disjoint component tasks, then join cache execution, production composition, and command verification. Optional remote transport has its own contract and tests. A separate delivery proof must demonstrate artifact-specific reuse across trusted contexts with local caches absent, plus meaningful invalidation and access denial. There are no unresolved product decisions; unavailable runtime or provider access must be reported as a delivery blocker rather than converted to an assumed success.