Spec: Prompt-Level Delivery Phase Flow Optimization

Context

Harness Intelligence currently reconstructs and carries the same delivery authority through several overlapping prompt surfaces. Full Delivery repeatedly routes broad state, worker briefs repeat source content, dependency-ready work can wait for unrelated workers, repair loops can repeat without new evidence, and Code Review can reload or repeat work that one frozen review epoch could share.

The optimized capability remains prompt-level. The user-selected native harness executes and coordinates work. Harness Intelligence supplies skill contracts, Context Pointers, compact packets and results, delegation policy, assurance gates, recovery rules, and measured admission criteria. It adds no Delivery executor or persistent delivery runtime.

This specification composes, but does not flatten, two retained leaf authorities:

• Project-Specific Executable Verification Capability owns the Project Verifier, Uncovered Surface and Uncovered Behavior recovery, executable behavior evidence, and the boundary between Verification and Code Review.
• Dynamic Implement Spec Execution Policy owns the Execution Frontier, Task Gates, Active Write Scopes, early draft pull-request visibility, applicable Architecture Checkpoints, and the default one-pass review policy.

This umbrella owns their end-to-end interaction across Full Delivery: compact continuity, common results, granular feedback, bounded recovery, cross-task handoff, review-lens aggregation, compatible rollout, legacy normalization, and performance admission.

Primary actors are the operator selecting a delivery entry mode, the parent orchestrator, scoped implementation workers, independent review lenses, and Harness maintainers evolving the shared skill contracts.

Non-Goals

• Create a Delivery executor, deterministic runtime, compiled kernel, scheduler, watcher, journal, outbox, lock, cache, or service.
• Replace the execution, concurrency, tool, or model facilities of the user-selected native harness.
• Let the parent perform implementation edits.
• Weaken or merge applicable TDD, architecture, runtime, UI, provider-readback, Verification, final acceptance, or Code Review gates.
• Move Verification, Project Verifier execution, or evidence freshness ownership into review-phase.
• Replace Code Review with Verification or Verification with Code Review.
• Create worker worktrees, worker branches, merger agents, or one pull request per Task.
• Bulk-rewrite historical plans, notes, handoffs, or retained review reports.
• Activate the accepted primary/challenger topology only after satisfying the unchanged AC-044..AC-048 assurance-constrained admission policy.
• Integrate external GitHub or Codex pull-request reviewers.
• Set a universal token, word, worker-count, retry-count, or wait-duration limit without supporting measurements.
• Define provider Epic, Story, or Task identities, implementation files, commands, worker assignments, or execution estimates.

Requirements Outcomes

OUT-001: Composed native-harness delivery authority

An operator can run one coherent delivery flow that satisfies both retained leaf capabilities while the native harness remains the executor and every authority boundary stays explicit.

OUT-002: Minimal trustworthy in-task continuity

Full Delivery carries only the current identities, Context Pointers, freshness, action, blocker, and stop condition needed for the next transition, with fail-closed resolution and cold reconstruction when trust changes.

OUT-003: Dependency-granular worker execution

The parent can validate each Task Result and immediately release newly eligible work without waiting for a full wave, while exclusive Active Write Scopes and all applicable gates remain authoritative.

OUT-004: Bounded recovery and cross-task handoff

A failed Task blocks only its dependent chain, useful repair proceeds only from new evidence, and a receiving task resumes from compact durable pointers through a cold route.

OUT-005: Single-epoch Code Review orchestration

One prepared frozen Review Packet supplies one comprehensive primary review covering five retained coverage obligations and one independent risk-focused challenger in parallel when capacity allows; the parent verifies and consolidates compact results into one retained report.

OUT-006: Assurance-preserving repair and completion

Verification remains inside implement-spec; Code Review remains readonly; ordinary repairs receive focused validation; only accepted high-risk change can trigger a bounded second Full Code Review Pass.

OUT-007: Compatible source-first adoption

All shared delivery contracts activate as one compatible canonical-source revision, Project Verifier lands as its own leaf scope in the same Harness change set, and valid legacy artifacts remain usable without historical rewrites.

OUT-008: Evidence-based optimization admission

The optimized contracts become the default only after matched measurements show a Pareto improvement without assurance regression, or after an explicit retained human exception accepts the measured tradeoff.

Acceptance Criteria

• AC-001: Full Delivery runs through the user-selected native harness and creates no Delivery runtime, service, scheduler, journal, watcher, lock, or cache authority.
• Covers: OUT-001
• AC-002: Completion evidence traces every applicable acceptance criterion from both retained leaf specifications without copying or superseding their decision trails.
• Covers: OUT-001, OUT-007
• AC-003: implement-spec owns Project Verifier creation, repair, execution, evidence, and affected reruns; review-phase remains readonly Code Review.
• Covers: OUT-001, OUT-006
• AC-004: A Delivery Context Packet contains only delivery-goal and accepted-bounds identity, authoritative Context Pointers, branch/base/target identity, current phase and next action, active Task or review identity, relevant evidence freshness, exact blocker, and stop condition, plus any bounded Derived Context Excerpt permitted by AC-005.
• Covers: OUT-002
• AC-005: A Delivery Context Packet contains no full artifact body, full report, skill text, or command log; it may contain a bounded source-attributed Derived Context Excerpt or rationale when that avoids a predictable authority lookup, and each excerpt carries its source identity and freshness rule and remains non-authoritative.
• Covers: OUT-002, OUT-008
• AC-006: Only Full Delivery uses a continuing Delivery Context Packet loop; a direct phase, HITL checkpoint, standalone review, narrow resume, or closeout invocation emits one Phase Result and stops at its requested boundary.
• Covers: OUT-001, OUT-002
• AC-007: Same-task Full Delivery remains warm only while task, goal, accepted bounds, next-action authority, branch/base/target identity, and required evidence freshness still match.
• Covers: OUT-002
• AC-008: A new task, cross-task handoff, changed bounds, changed required authority, inconsistent Git target, stale evidence, or unresolved contradiction causes a cold route before further action.
• Covers: OUT-002, OUT-004
• AC-009: Every Context Pointer contains authority kind, stable locator, optional section or symbol selector, content or state identity, and the freshness rule its consumer checks.
• Covers: OUT-002
• AC-010: A missing, stale, malformed, or ambiguous Context Pointer stops its consumer before action; the parent may perform one bounded refresh from the named authority and proceeds only when exactly one current identity is proven.
• Covers: OUT-002, OUT-004
• AC-011: An unresolved Context Pointer returns blocked with the exact pointer and missing proof; no consumer invents content, chooses a near match, copies a broad authority set, or silently continues.
• Covers: OUT-002, OUT-004
• AC-012: Every Phase Result contains phase, one common outcome, authority or evidence created, changed facts, invalidated evidence, next eligible phase, exact blocker or stop reason, and only Context Pointers needed next.
• Covers: OUT-002
• AC-013: A Phase Result outcome is exactly complete, blocked, failed, skipped, or human_steering_required; phase-specific state and detailed rationale remain behind Context Pointers.
• Covers: OUT-002, OUT-004
• AC-014: A Task Result reports exactly ready_for_gate or blocked and includes only its scoped delta, validation evidence, changed paths, unresolved blocker, and relevant Context Pointers.
• Covers: OUT-003
• AC-015: Only the parent records a Task Gate outcome, exactly passed, repair_required, or blocked; a missing or malformed Task Result is blocked and never an inferred pass.
• Covers: OUT-003, OUT-004
• AC-016: After a Task Gate passes, the parent recomputes the Execution Frontier and dispatches every newly eligible Worker-worthy Task allowed by native capacity and disjoint Active Write Scopes without waiting for unrelated work; the parent also checks declared read dependencies and shared runtime resources against the Relevant Input Sets of active Tasks before dispatch.
• Covers: OUT-003
• AC-017: Shared PLAN.md and IMPLEMENTATION-NOTES.md reconciliation may finish after dependent dispatch but completes before an applicable Architecture Checkpoint or final acceptance.
• Covers: OUT-003, OUT-006
• AC-018: The parent alone updates shared plan and implementation-note summaries; scoped workers perform every implementation edit on the recorded current branch.
• Covers: OUT-003
• AC-019: When eligible work exceeds native capacity, priority is assumption-invalidating work, then longest remaining dependency chain, then unlock count, then plan order as the stable tie-break.
• Covers: OUT-003
• AC-020: Capacity one runs Worker-worthy Tasks and review lenses sequentially through unchanged contracts and gates.
• Covers: OUT-003, OUT-005
• AC-021: A harness without subagent capability returns blocked when delegated implementation is required; the parent does not absorb implementation edits.
• Covers: OUT-001, OUT-003
• AC-022: A blocked or repair-required Task blocks only its dependent chain; independent disjoint Tasks continue, and its Active Write Scope remains reserved until validated cleanup or one scoped repair worker takes ownership.
• Covers: OUT-003, OUT-004
• AC-023: Another scoped repair is eligible only when the latest Task Result or Task Gate supplies new actionable evidence; bounded diagnosis that discriminates between authorized hypotheses may continue to produce that evidence before another repair is attempted.
• Covers: OUT-004
• AC-024: A stagnant repeated repair, required scope redesign, weaker-gate request, changed requirement, missing access, or human decision returns human_steering_required through $handback; bounded authorized diagnosis may continue while it can discriminate between hypotheses and produce new evidence.
• Covers: OUT-004, OUT-006
• AC-025: A Delivery Handoff contains only delivery-goal and bounds identity, branch/base/target identity, current phase and next action, stable Context Pointers with identities, relevant provider identities, exact blocker, explicit unknowns, and at most one sentence explaining an unusual boundary with a rationale pointer.
• Covers: OUT-004
• AC-026: A Delivery Handoff never persists the Delivery Context Packet; every receiving task cold-routes from the handoff and current authorities.
• Covers: OUT-002, OUT-004
• AC-027: Recovery reuses only evidence whose identity and freshness still match and never duplicates a provider or repository mutation already proven complete.
• Covers: OUT-004, OUT-006
• AC-028: One prepared Review Packet freezes accepted bounds, normalized target, snapshot identity, governing source-set identity, applicable specification and plan pointers, skill guidance pointers, Verification evidence pointers, relevant dependency pointers, and delivery lineage for one Full Code Review Pass; reviewers inspect this shared factual input without a persuasion narrative.
• Covers: OUT-005
• AC-029: autoreview fills the comprehensive primary reviewer role and runs once against the prepared Review Packet, producing explicit outcomes for Standards, skill adherence, architecture, simplify, and Spec obligations; one independent risk-focused challenger runs against the same prepared facts in parallel when native capacity permits, without seeing primary conclusions. Larger changes may split independent risk areas into bounded challenger assignments when useful, with no fixed numeric cap.
• Covers: OUT-005
• AC-030: Every primary or challenger Review Lens Result contains reviewer identity, assigned coverage obligation or risk area, Review Packet identity, and one outcome: clean, findings, or incomplete. clean requires assigned coverage completed with no candidates; findings requires assigned coverage completed with candidates; incomplete names unavailable coverage, cause, and required follow-up and may retain candidates already found. Each candidate contains only location, evidence pointer, impact, proposed severity, proposed return route, and uncertainty. An incomplete result can never complete a pass.
• Covers: OUT-005
• AC-031: The parent groups duplicate candidates before investigation, verifies every underlying issue and accounts for every distinct claim, assigns stable finding IDs, confirms severity and return route, preserves primary versus challenger provenance, and alone assembles the retained report; no automatic parent discovery pass follows the reviewers.
• Covers: OUT-005
• AC-032: A semantic change to target, accepted bounds, or governing sources during an active review pass invalidates the Review Packet and restarts review; an accepted repair after a completed pass follows AC-034 or AC-035; a retention-only failure reuses the matching fresh local report without rerunning review lenses, and an interrupted or partial pass remains incomplete with its completed lens results explicitly accounted for.
• Covers: OUT-005, OUT-006
• AC-033: Normal delivery runs one Full Code Review Pass after implement-spec completes implementation, applicable Verification, shared-summary reconciliation, and final acceptance evidence.
• Covers: OUT-005, OUT-006
• AC-034: An ordinary accepted review repair runs Focused Repair Validation and reruns only Verification scenarios whose evidence the repair invalidated.
• Covers: OUT-006
• AC-035: A second Full Code Review Pass runs only when an accepted repair changes architecture, security or authorization, a public contract, runtime or deployment topology, or accepted scope.
• Covers: OUT-005, OUT-006
• AC-036: Delivery runs no more than two Full Code Review Passes for one delivery goal without explicit human direction.
• Covers: OUT-005, OUT-006
• AC-037: Applicable TDD, task checks, Architecture Checkpoints, runtime, UI, provider-readback, Verification, final acceptance, report retention, and Code Review evidence keep their existing completion authority.
• Covers: OUT-001, OUT-006
• AC-038: Canonical shared-source changes to delivery-phase, create-plan, implement-spec, review-phase, handoff, their required references, tests, and operator documentation activate as one compatible contract revision before Harness consumes them.
• Covers: OUT-007
• AC-039: Reusable skill work is committed and pushed from canonical Devpunks skills main, then Harness synchronization records and validates the exact source receipt before the optimized contracts activate.
• Covers: OUT-007
• AC-040: Project Verifier remains a separately traceable leaf module and planning scope but lands in the same Harness delivery change set as the compatible shared contract revision.
• Covers: OUT-001, OUT-007
• AC-041: New writes use the compact contracts; a cold route normalizes valid legacy plans, notes, handoffs, and retained review reports at read time without rewriting historical bytes or changing valid report identities and ordinals.
• Covers: OUT-002, OUT-004, OUT-007
• AC-042: When required authority cannot be reconstructed from a legacy artifact, the route returns blocked and names the missing proof.
• Covers: OUT-004, OUT-007
• AC-043: Contract validation rejects full embedded authority bodies, unsourced excerpts, unbounded narrative fields, and envelopes missing required identity, pointer, freshness, delta, blocker, or stop fields; bounded source-attributed Derived Context Excerpts are valid only with source identity, freshness, and an explicit non-authoritative marker.
• Covers: OUT-002, OUT-008
• AC-044: Controlled comparison covers small and medium Full Delivery, a skewed dependency graph, full versus pointer-based worker context, frozen review bundles with seeded defects, failed-task and handoff recovery, and Project Verifier coverage paths.
• Covers: OUT-008
• AC-045: Every fixture runs as three matched baseline and optimized pairs with the same goal, accepted artifacts, branch state, model, reasoning setting, tools, and injected delays; disagreement extends that fixture to five pairs and then returns inconclusive.
• Covers: OUT-008
• AC-046: Measurement records input, cached-input, noncached-input, output, and reasoning tokens; resumptions and compactions; loaded bytes; shell, provider, wait, spawn, and follow-up operations; root active elapsed time; and assurance outcomes.
• Covers: OUT-008
• AC-047: Review parity requires no missed seeded critical or high finding and equal-or-better per-axis recall, severity and route correctness, complete lens outcomes, unchanged target freshness, and valid retained-report evidence.
• Covers: OUT-005, OUT-008
• AC-048: Default activation requires a passing assurance-constrained Pareto result; failed or inconclusive evidence prevents activation unless an explicit retained human exception accepts the measured tradeoff.
• Covers: OUT-008
• AC-049: Context assembly selects trigger-specific instruction surfaces in three layers: always-loaded project facts and hard boundaries, selected workflow contracts required by the current action, and optional techniques loaded only when their trigger applies; a packet records the selected surface identities and freshness.
• Covers: OUT-002, OUT-007
• AC-050: The swarm-planner primitive within create-plan, the planning step of delivery-phase, records read dependencies, shared runtime resources, and evidence-stability inputs alongside Active Write Scopes; the owning execution and evidence gates recheck affected Relevant Input Sets and mark affected evidence or eligibility stale when an input changes, without introducing a lock service or execution engine.
• Covers: OUT-003, OUT-006
• AC-051: The umbrella composes the Project Verifier leaf contract for falsifiable observable claims, important negative or failure checks, matching proof reuse when conditions and evidence identity permit, and targeted retirement or supersession of obsolete Feature Map knowledge by reference to that leaf authority.
• Covers: OUT-001, OUT-006, OUT-007
• AC-052: Existing complete evidence from the same verified snapshot may be preserved when its identity, scope, and freshness still match; preservation records the reused evidence and does not bypass any newly applicable gate.
• Covers: OUT-005, OUT-006
• AC-053: The primary reviewer consumes the prepared frozen target, rules, evidence, and dependency pointers directly; it does not independently fetch or rediscover the target, and it emits an outcome for each of the five retained coverage obligations: Standards, skill adherence, architecture, simplify, and Spec.
• Covers: OUT-005
• AC-054: Review orchestration uses existing helpers for mechanical schema, identity, evidence-cardinality, serialization, and routing checks, and records those checks in the retained report without adding a Delivery engine, cache authority, lock, or persuasion narrative.
• Covers: OUT-005, OUT-007

Constraints

• Preserve every canonical term in the Delivery Phase Flow Optimization, Project Verification Capability, and Implement Spec Execution Policy glossaries.
• Preserve the two leaf specifications as independent authorities and retain their OUT-### and AC-### identities.
• Preserve one user-selected native harness and one parent orchestrator per delivery goal.
• Preserve one recorded current branch, disjoint Active Write Scopes, unrelated worktree changes, and provider identity and readback authority.
• Preserve one verify-behavior entrypoint and project-owned progressively disclosed Project Verifier content.
• Keep Delivery Context Packet and Review Packet disposable; neither becomes a durable authority. A bounded derived excerpt may be carried for lookup avoidance only with source identity plus freshness, and never supersedes its source.
• Keep warm and cold as routing-cost descriptions, not durable lifecycle states.
• Keep Verification, Code Review, and delivery repair as separate gates and evidence.
• Keep shared reusable skills source-first through the canonical Devpunks repository.
• Preserve explicit narrow entry-mode and HITL stop boundaries.
• Preserve retained review report bytes and valid delivery ordinals during compatibility normalization.
• Do not activate the optimized default from observational historical data alone.

Dependency Readiness

Ready:

• Project-Specific Executable Verification Capability at immutable commit b6f60a176862e196697ef3e9b3e24f6198b2031a, with its confirmed grill status.
• Dynamic Implement Spec Execution Policy at immutable commit 24a723bf4043c9011d31875151959653d4b83100, with its confirmed grill status.
• Prompt-level optimization decisions at confirmed grill status, closed decision log, and grounded research report.
• All listed commits are retained by origin/team/stefan/delivery-phase-optimization; their immutable GitHub blobs were read back before compilation.

Branch/Base Intent

• Intended parent/base: origin/main.
• Unified child branch: team/stefan/delivery-phase-optimization.
• Pull request: #196, one draft pull request containing the retained leaf authorities, umbrella specification, later synchronized shared contracts, Project Verifier implementation, and Harness-owned integration work.
• Reusable skill implementation originates on canonical /Users/stefan/Desktop/repos/wearedevpunks-skills main, is pushed there, and is synchronized into the unified Harness branch with its exact receipt.
• Implementation workers share the unified current branch through disjoint Active Write Scopes; no worker branch, worker worktree, or merger-agent stack is intended.

Accepted Technical Decisions

Delivery continuity

• Build a disposable Delivery Context Packet once per valid Full Delivery task and update it only from Phase Results.
• Resolve details progressively through typed Context Pointers and fail closed after one bounded parent refresh.
• Use one common Phase Result contract across delivery phases while preserving phase-specific durable state behind pointers.
• Keep direct, HITL, standalone, narrow resume, and closeout entry modes bounded to one result and stop.

Worker control

• Use Task Results as worker returns and parent-owned Task Gates as the sole dependency-release authority.
• Recompute the Execution Frontier after each Task Gate instead of scheduling in completion waves.
• Reserve Active Write Scope through failure cleanup or one repair-worker transfer.
• Prioritize assumption-invalidating and critical-path work when native capacity is constrained.
• Reconcile shared summaries off the dependency-release critical path but before cumulative checkpoints and finalization.

Review control

• Freeze one Review Packet for one review epoch.
• Run autoreview once as the comprehensive primary reviewer and one independent risk-focused challenger against the same prepared frozen facts; account for all five retained coverage obligations through the primary outcome set.
• Keep review-lens output compact and candidate-only; keep verification, deduplication, final severity, routing, identifiers, and report assembly parent-owned.
• Restart review only after semantic-input change. Reuse fresh report bytes through retention-only failure.
• Default to one Full Code Review Pass, Focused Repair Validation for ordinary repair, and at most one risk-triggered second pass without explicit human direction.

Compatibility and admission

• Roll every cross-skill producer and consumer as one compatible canonical-source revision.
• Normalize valid legacy artifacts at read time and never bulk-migrate retained history.
• Enforce compactness through required structure and forbidden payload classes before considering numeric budgets.
• Admit the optimized default only through the accepted matched-run Pareto and assurance-parity contract.

Accepted Testing Decisions

• Prove every compact contract accepts all required fields and rejects copied authority, unbounded narrative payloads, missing identities, and missing freshness rules.
• Prove warm continuation, every cold-route trigger, one-refresh pointer recovery, and exact blocked evidence.
• Prove a fast prerequisite releases its dependent while an unrelated slow Task remains active.
• Prove failed Task Gate containment, independent progress, scope reservation, cleanup, and one repair-worker ownership.
• Prove constrained priority order, capacity-one sequential behavior, and capability-zero implementation blockage.
• Prove parent-only shared-summary mutation and reconciliation before Architecture Checkpoints and finalization.
• Prove Delivery Handoff excludes the Delivery Context Packet and causes a receiving task cold route without duplicate mutation.
• Prove the primary and challenger consume one prepared frozen Review Packet, preserve independence, and return valid clean, findings, or incomplete results; incomplete or interrupted coverage is never treated as clean or complete.
• Prove parent verification, deduplication, stable finding identifiers, final severity, return routes, and retained report assembly.
• Prove semantic change invalidation, retention-only reuse, one default pass, focused repair proof, affected Verification reruns, risk-triggered second pass, and the two-pass ceiling.
• Prove implement-spec still owns Project Verifier coverage creation, repair, execution, and evidence while review-phase stays readonly.
• Prove legacy plans, notes, handoffs, and valid retained reports normalize without byte rewrite or ordinal change; incomplete authority blocks.
• Prove exact canonical-source receipt and producer-consumer compatibility before Harness activation.
• Run the accepted five controlled experiment fixtures with matched identities, three-to-five pair rule, complete metric capture, seeded review defects, assurance parity, and explicit passed, failed, or inconclusive admission.

Verification Seams

• Delivery router output and Phase Result transitions prove packet continuity, validity checks, entry-mode stops, and cold reconstruction.
• Context Pointer resolver output proves identity, freshness, bounded refresh, and exact blocked state.
• Parent Task Gate and Execution Frontier traces prove immediate dependency release, failure containment, priority, capacity behavior, and write-scope ownership.
• Shared plan and implementation-note histories prove parent-only mutation and reconciliation before cumulative gates.
• verify-behavior and Project Verifier evidence prove Uncovered Surface and Uncovered Behavior recovery remains inside implement-spec.
• Review Packet hashes, per-lens results, retained report bytes, and delivery ordinal prove one frozen review epoch and retention-only reuse.
• Focused repair evidence and affected Verification records prove ordinary repair does not trigger a second full pass.
• Canonical Devpunks commit, Harness sync receipt, and pull-request tree prove atomic source-first rollout.
• Before-and-after legacy artifact bytes and normalized projections prove read-time compatibility without migration.
• Retained benchmark report proves matched identity, complete metrics, assurance parity, Pareto outcome, and default-admission decision.

Parked Decisions

• Integrated five-lens reviewer is superseded by the R6 comprehensive primary reviewer. The risk-focused challenger is now accepted under AC-029; no future requirements decision is required for this topology.
• External GitHub or Codex pull-request reviewer integration. Owner: Harness maintainers. Resume trigger: explicit request to combine external reviewer findings with the delivery review budget.
• Numeric token, latency, worker-count, retry-count, or wait-duration defaults. Owner: Harness maintainers. Resume trigger: repeated matched-run distributions justify a concrete bound without assurance loss.
• Additional brainstorm experiments comparing task-adaptive delegation, hybrid excerpts, reduced instruction surfaces, or verifier maintenance cost. Owner: Harness maintainers. Resume trigger: explicit later requirements decision; these do not modify AC-044..AC-048.

Decision Log