Epic: drain the bug queue by repairing domain boundaries

[robertDouglass]

Purpose

Drain the Spec Kitty bug queue by repairing the domain boundaries that keep producing symptom fixes.

This epic is based on a holistic survey of:

• 10 currently open bug issues as of 2026-05-05.
• 46 bug issues closed since 2026-04-21.
• Recent stabilization PRs including Stability & hygiene hardening (April 2026): merge / lane / intake / runtime / packages / sync / governance / e2e #803, Fix idempotent implementation start lifecycle #946, Release 3.2.0 workflow reliability #959, Stabilize implement-review-retrospect reliability #969, Stable 3.2.0 P0 CLI stabilization #972, and Fix 3.2.0 release blockers #981.
• The open cross-repo TeamSpace PR set: spec-kitty Add TeamSpace mission-state repair and dry-run #980, spec-kitty-saas chore(release): start semver GitHub-only releases for 2.x #150, spec-kitty-runtime refactor: extract Codex security logic and add comprehensive tests #19, and spec-kitty-tracker feat: Display version in banner on init screen #14.

The observed pattern is not random breakage. The queue clusters around a small number of domain seams where several command surfaces independently infer or mutate the same truth. That creates whack-a-mole behavior: one command is patched, then the invariant fails at the next boundary.

The goal is to make each domain invariant executable once, then route every CLI surface, JSON surface, dry-run, real execution path, dashboard reader, review gate, and sync side effect through it.

Core Architectural Diagnosis

Spec Kitty currently has too many places acting as if they own workflow truth:

• spec-kitty next
• spec-kitty agent action implement/review
• spec-kitty agent tasks move-task
• spec-kitty agent tasks status
• spec-kitty review
• spec-kitty merge --dry-run
• real spec-kitty merge
• dashboard/status materializers
• SaaS sync/final-sync fan-out
• release and mission-review gates

The alien-intelligence reading: these are not separate problems. They are projections of a few aggregates whose invariants are not yet centralized.

North Star Invariants

• A Work Package has exactly one lifecycle authority.
• A Review Cycle has exactly one artifact/verdict/pointer/override authority.
• Merge dry-run and real merge evaluate the same readiness object.
• Local state transitions and SaaS publication are separate outcomes with explicit failure classification.
• TeamSpace ingress accepts only canonical envelopes, and repair/import tooling proves that before live projection.
• Release review cannot silently skip a required gate for a newly created mission.
• Compatibility cleanup cannot use "green enough" test output to hide contract drift.

Open PR Intake: TeamSpace Cutover Set

These four PRs are open, non-draft, merge-clean, and green as of 2026-05-05. They should be treated as the current implementation front of the TeamSpace migration boundary, not duplicated by this epic.

• Add TeamSpace mission-state repair and dry-run #980: Add TeamSpace mission-state repair and dry-run. Head 01db3e0b. Adds doctor mission-state --fix, --teamspace-dry-run, canonical TeamSpace envelope synthesis, CLI sync expectation alignment, and 3.2.0rc2.
• Priivacy-ai/spec-kitty-saas#150: Enforce TeamSpace ingress event contracts. Head 342e77a5. Enforces canonical ingress, rejects historical/raw/legacy keys recursively, fixes 5.0.0 lane handoff, and hardens websocket test cleanup.
• Classify runtime logs for TeamSpace migration spec-kitty-runtime#19: Classify runtime logs for TeamSpace migration. Head ba167541. Establishes runtime logs as local side logs, not TeamSpace status authority or direct import payloads.
• Priivacy-ai/spec-kitty-tracker#14: Guard tracker TeamSpace mission payloads. Head 7fdde89. Ensures tracker egress stays on canonical mission_id and does not become rollout/import authority.

Open PR Follow-Up Queue

• Publish spec-kitty-events 5.0.0 for TeamSpace migration consumers spec-kitty-events#20: publish spec-kitty-events==5.0.0.
• Tighten spec-kitty-events dependency after 5.0.0 PyPI release #978: tighten CLI spec-kitty-events lower bound after 5.0.0 PyPI release.
• Coordinate the actual mission-state repair commit across active repositories #979: coordinate actual mission-state repair commits across active repositories.
• Priivacy-ai/spec-kitty-saas#149: remove transitional Git source override after 5.0.0 PyPI release.
• Priivacy-ai/spec-kitty-saas#151: stabilize websocket tests without Redis teardown suppression.
• Clear runtime strict mypy baseline exposed by TeamSpace migration helper spec-kitty-runtime#18: clear or intentionally baseline runtime strict mypy debt.

Integration Rule

Land these PRs as one coordinated cutover set, then run a post-merge import-readiness pass against the same repositories. The queue-draining work below should consume their new boundaries instead of creating parallel validators.

Workstream 0: TeamSpace Canonical Import Boundary

Domain Problem

TeamSpace launch introduces a hard boundary between historical local mission state and canonical SaaS projection. The open PR set repairs and guards that boundary, but the queue drain must treat the boundary as a product invariant after merge.

Issues And PRs Covered

• TeamSpace-safe historical mission-state migration and import readiness #920 TeamSpace-safe historical mission-state migration and import readiness.
• Add TeamSpace mission-state repair and dry-run #980 CLI repair and TeamSpace dry-run.
• Priivacy-ai/spec-kitty-saas#150 SaaS canonical ingress enforcement.
• Classify runtime logs for TeamSpace migration spec-kitty-runtime#19 runtime side-log classification.
• Priivacy-ai/spec-kitty-tracker#14 tracker legacy-key guard.
• Publish spec-kitty-events 5.0.0 for TeamSpace migration consumers spec-kitty-events#20 publish canonical event contract package.

Target Shape

The launch boundary has one explicit contract:

• CLI can repair and produce canonical envelopes.
• SaaS accepts only canonical envelopes.
• runtime logs are classified as local side logs, never status authority.
• tracker emits canonical mission payloads and does not own rollout/import semantics.
• spec-kitty-events==5.0.0 is the published shared contract.

Acceptance

• All four open PRs land against current main without semantic reroll.
• spec-kitty-events==5.0.0 is published and downstream Git source overrides are removed.
• doctor mission-state --audit --json, --fix, and --teamspace-dry-run --json are run on the selected active repositories.
• Generated repair manifests are reviewed before import/projection.
• SaaS ingress rejects raw historical rows, recursive forbidden legacy keys, missing build identity, and non-canonical envelopes.
• Runtime/tracker tests prove they are not TeamSpace status/import authorities.

Workstream 1: WorkPackageLifecycle Authority

Domain Problem

next, explicit agent action, move-task, dashboard/status, and merge currently infer claimability, readiness, and terminal state from overlapping but non-identical rules.

Open Issues Covered

• bug: spec-kitty next --json can miss claimable WPs available to explicit agent action #988 spec-kitty next --json can miss claimable WPs available to explicit agent action.
• Epic: 3.2.0 stabilization and release readiness #822 3.2.0 stabilization epic, insofar as it still depends on lifecycle correctness.
• EPIC: Tech/Functional Debt Remediation: 3.x development inconsistencies and behavioural problems #391 tech/functional debt epic, lifecycle subset.

Latent Regression Debt From Recently Closed Bugs

• agent tasks move-task: approval event silently dropped when run from subagent in worktree context #945 approval event silently dropped from worktree/subagent context.
• Fix idempotent implementation start lifecycle #946 idempotent implementation start lifecycle.
• bug: spec-kitty next reports discovery after finalized task board #961 next reported discovery after finalized task board.
• bug: approved task board shows 0/6 progress while percentage is 80% #966 approved task board had inconsistent progress semantics.
• spec-kitty agent tasks mark-status fails on missing checkbox task IDs even when subtasks are referenced #783 mark-status failed on missing checkbox task IDs.
• Review-claim codepath emits for_review → in_progress instead of for_review → in_review (FR-020 root cause) #622 review-claim emitted for_review -> in_progress instead of for_review -> in_review.
• bug: agent action implement cannot resolve a workspace for planning-artifact WPs #551 planning-artifact WPs could not resolve implementation workspace.
• Bug: top-level implement bypasses canonical status transition pipeline #540 top-level implement bypassed canonical status transition pipeline.

Target Shape

Introduce or harden a single WorkPackageLifecycle domain service that answers:

• What is the current state?
• What transitions are allowed?
• What actor may claim/review/approve?
• What is claimable next?
• What evidence is required?
• Which command surfaces may present or serialize this decision?

Acceptance

• next --json, agent action implement, agent action review, move-task, status board, and dashboard agree on claimable and blocked WPs for the same fixture.
• A multi-lane fixture with a later ready WP proves bug: spec-kitty next --json can miss claimable WPs available to explicit agent action #988 dead.
• Planning-artifact and lane-backed WPs use the same lifecycle decision API.
• No command writes WP lifecycle state except through the canonical transition pipeline.

Workstream 2: ReviewCycle As A Real Aggregate

Domain Problem

Recent fixes created a narrow review-cycle boundary, but current open issues show the boundary is still too file-shaped. Review artifact creation, verdicts, pointers, overrides, status transitions, dry-run gates, real merge gates, and fix-mode prompt loading must all share one domain model.

Open Issues Covered

• bug: review-cycle artifact generation can wrap prior cycle frontmatter/body #990 review-cycle artifact generation can wrap prior cycle frontmatter/body.
• bug: merge dry-run misses review artifact consistency failures #991 merge dry-run misses review artifact consistency failures.

Latent Regression Debt From Recently Closed Bugs

• bug: stale rejected verdict in review-cycle-N.md is not validated against WP lane state #904 stale rejected review-cycle verdict was not validated against approved/done state.
• bug: review-cycle artifacts can be written without required YAML frontmatter #963 review-cycle artifacts could be written without YAML frontmatter.
• bug: move-task rejection from in_review can fail without explicit review_result #960 rejection from in_review could fail without structured review_result.
• bug: rejection feedback pointer can persist as feedback:// instead of review-cycle:// #962 rejection feedback pointer persisted as feedback:// instead of review-cycle://.
• Review prompt generation can cross-contaminate missions via temp-file collision #949 review prompt generation could cross-contaminate missions via temp-file collision.
• Review prompt diff base uses stale mission branch name and fails with ambiguous revision #950 review prompt diff base could use stale/generated branch names.
• spec-kitty CLI: re-running agent action implement auto-inflates the review-cycle counter #676 re-running agent action implement auto-inflated review-cycle counter.

Target Shape

Promote the review boundary from "rejected artifact helper" to ReviewCycle / ReviewDecision aggregate:

• artifact write is generated from structured data only;
• artifact parser validates identity, cycle number, verdict, body, and provenance;
• latest verdict and status lane consistency are evaluated once;
• overrides are explicit domain events, not textual patch-ups;
• all references are canonical review-cycle://;
• approved/rejected/override states are all first-class, not special cases.

Acceptance

• A new review cycle cannot embed or wrap a prior cycle body/frontmatter.
• move-task, fix-mode prompt loading, review, merge --dry-run, and real merge use the same ReviewCycleConsistency evaluator.
• merge --dry-run --json reports REJECTED_REVIEW_ARTIFACT_CONFLICT whenever real merge would.
• Legacy feedback:// remains readable only as a migration compatibility path and never persists on new transitions.

Workstream 3: MergeReadiness Parity

Domain Problem

Dry-run and real merge have repeatedly diverged. Fixing one missing preflight at a time is a symptom pattern.

Open Issues Covered

• bug: merge dry-run misses review artifact consistency failures #991 merge dry-run misses review artifact consistency failures.
• Epic: 3.2.0 stabilization and release readiness #822 stable release gate items related to merge readiness.

Latent Regression Debt From Recently Closed Bugs

• merge dry-run should catch missing mission branch prerequisite #976 dry-run missed missing mission branch prerequisite.
• Mission merge leaves audit work only on divergent local main, forcing manual PR branch reconstruction #953 merge left audit work only on divergent local main.
• bug: spec-kitty merge --abort does not clear the merge lock file #903 merge abort did not clear merge lock file.
• bug(merge): WPs should transition to 'done' automatically after spec-kitty merge completes #716 merge should transition WPs to done.
• spec-kitty merge: post-merge invariant treats untracked files as HEAD divergence #675 post-merge invariant treated untracked files as HEAD divergence.
• bug(P0): spec-kitty merge silently loses status events when resolving status.events.jsonl conflict — all WPs revert to Planned #574 merge silently lost status events during conflict resolution.

Target Shape

Create a single MergeReadiness.evaluate() decision object used by both dry-run and real merge.

The decision should include:

• missing mission branch;
• stale target branch;
• sparse checkout guard;
• review artifact conflicts;
• lane/worktree state;
• status.events consistency;
• post-merge done-transition plan;
• lock/abort recovery status;
• JSON-stable diagnostic codes and remediation.

Acceptance

• Dry-run and real merge share one evaluator and one test fixture matrix.
• Every blocker real merge can raise is asserted in dry-run JSON.
• Real merge performs no irreversible git mutation before readiness passes.
• Merge abort/lock recovery is covered as part of the same readiness/recovery model.

Workstream 4: SyncPublication And Auth/Teamspace Classification

Domain Problem

Local command success and SaaS sync publication are separate outcomes, but bugs show they are sometimes conflated, hidden, or misclassified.

Open Issues Covered

• sync now misclassifies teamspace ingress rejection as server_error #889 sync now misclassifies teamspace ingress rejection as server_error.

Latent Regression Debt From Recently Closed Bugs

• Successful agent state transitions still leak SaaS final-sync errors #952 successful local state transitions leaked SaaS final-sync errors.
• CLI: suppress cosmetic final-sync/shutdown errors after successful agent mission create #735 final sync/shutdown errors after successful mission create.
• Sync: persist structured body-upload failures and stop collapsing 400s to bad_request: unknown #746 body-upload failures collapsed to bad_request: unknown.
• Sync/Auth: queue scoping still uses legacy credentials path instead of authenticated session state #745 queue scoping used legacy credentials path.
• Sync: skip zero-byte planning artifacts from dossier body upload #744 zero-byte planning artifacts uploaded/skipped incorrectly.
• P0: spec-kitty agent mission setup-plan hangs indefinitely on unix-socket / websockets read; zombie processes block subsequent calls #936 websocket/unix-socket hang and zombie processes.

Target Shape

Create a SyncPublication outcome model:

• local mutation result;
• publication attempted/not attempted;
• retryable vs non-retryable classification;
• auth/teamspace failure reason;
• queue mutation policy;
• user remediation;
• JSON/stderr separation.

Acceptance

• 401/403 teamspace/auth failures are never server_error.
• Batch-level auth/teamspace failures do not increment per-event retry counts.
• sync doctor detects missing Private Teamspace before sync now drains.
• Successful local state transitions keep stdout/JSON clean while exposing non-fatal sync publication failures on stderr/log channels.
• SaaS-enabled smoke uses SPEC_KITTY_ENABLE_SAAS_SYNC=1 on this machine.

Workstream 5: ReleaseEvidence And Review Gates

Domain Problem

Release and mission-review gates sometimes report pass/skip rather than enforcing a domain invariant. That hides missing evidence.

Open Issues Covered

• bug: new missions without baseline_merge_commit skip dead-code review #989 new missions without baseline_merge_commit skip dead-code review.
• mypy strict gate fails on current baseline #971 mypy strict gate fails on current baseline.
• Resolve automated CI workflow duplication -> release readiness vs CI-quality #662 CI workflow duplication between release-readiness and CI-quality.

Latent Regression Debt From Recently Closed Bugs

• Cross-repo E2E contract_drift_caught fails with uv-managed nested stdlib venv #975 E2E contract drift scenario failed before product behavior due to nested stdlib venv.
• bug: status test suite can hang in bootstrap and emit tests #967 status tests could hang.
• [Dev tooling] Loosen Python pin and restore strict mypy for mission-step contracts #805 strict mypy for mission-step contracts.
• status store rejects mission-level DecisionPoint events in status.events.jsonl #830 status store rejected mission-level DecisionPoint events.
• bug: --agent colon-string silently discards model/profile/role in AgentAssignment #833 --agent colon string silently discarded model/profile/role.
• Clean up retired checklist command leftovers #968 retired checklist leftovers.
• bug: generated spec-kitty skill files can miss YAML frontmatter #964 generated SKILL.md missing frontmatter.

Target Shape

Create a ReleaseEvidence contract:

• new missions must have baseline_merge_commit or fail with repair guidance;
• legacy compatibility skips must be explicitly scoped and machine-readable;
• type-check gate is either green or explicitly narrowed with a documented rationale;
• CI-quality and release-readiness have non-overlapping responsibilities;
• E2E environment exceptions are preflight-classified before product assertions.

Acceptance

• spec-kitty review fails or repairs when a new mission lacks baseline_merge_commit.
• Legacy missions get a distinct diagnostic code, not a generic pass-with-warning.
• Strict mypy release gate is either green or intentionally scoped with an issue-backed contract.
• CI release-readiness consumes CI-quality outputs instead of duplicating broad test execution.
• Cross-repo E2E harness preflights runner compatibility before product assertions.

Workstream 6: Input/Upgrade/Encoding Boundary Hygiene

Domain Problem

Some older queue items are not part of the current release firefight but point to the same pattern: implicit file/content assumptions made at many call sites.

Open Issues Covered

• Encoding mixups: stop assuming UTF-8 by default and record encoding decisions at lifecycle boundaries #644 encoding mixups: stop assuming UTF-8 by default and record encoding decisions.
• EPIC: Tech/Functional Debt Remediation: 3.x development inconsistencies and behavioural problems #391 tech/functional debt remediation, input/upgrade subset.

Latent Regression Debt From Recently Closed Bugs

• bug(intake): no file size cap — read_text() on arbitrarily large .md files can OOM #722 intake file size cap.
• bug(intake): directory expansion follows symlinks — symlink escape into arbitrary files #721 intake symlink escape.
• bug(intake): scan_for_plans does not verify resolved paths stay within cwd (path traversal) #720 intake path traversal.
• spec-kitty upgrade silently deletes user-customized commands and skills #674 upgrade silently deleted customized commands/skills.
• [Bug] Gemini CLI shims are generated in Markdown instead of TOML #673 Gemini CLI shims generated in Markdown instead of TOML.
• Checked-in .kittify/overrides tree is mostly dead under current runtime resolution #760 checked-in .kittify/overrides mostly dead under current runtime resolution.
• Bug: require_main_repo misses external git worktrees outside .worktrees/ #541 require_main_repo missed external worktrees.
• Research: find_repo_root() resolves to worktree root when called from inside a worktree — status events and config writes land in wrong location #539 worktree root resolution could misroute status/config writes.
• Bug: implement can leave uncommitted mechanical changes in main planning checkout #542 implement could dirty main planning checkout.

Target Shape

Make input and persisted artifact boundaries explicit:

• all external text ingestion passes through encoding/provenance policy;
• all path expansion passes through containment policy;
• all generated command/skill files pass through host-specific schema validators;
• all worktree-vs-main repo resolution uses git topology, not path naming;
• all upgrade destructive actions require preserved customization policy.

Acceptance

• One lifecycle chokepoint and regression fixture for encoding provenance.
• Intake, upgrade, and generated-artifact paths use shared containment/atomic-write helpers.
• Worktree/main resolution has a contract fixture covering managed and external worktrees.

Queue Drain Order

Phase -1: Land The Green TeamSpace PR Set

• Land Publish spec-kitty-events 5.0.0 for TeamSpace migration consumers spec-kitty-events#20 or confirm the exact release-blocking publication sequence.
• Land Add TeamSpace mission-state repair and dry-run #980, Priivacy-ai/spec-kitty-saas#150, Classify runtime logs for TeamSpace migration spec-kitty-runtime#19, and Priivacy-ai/spec-kitty-tracker#14 as a coordinated cutover set.
• Remove transitional Git source overrides and tighten package ranges via Tighten spec-kitty-events dependency after 5.0.0 PyPI release #978 and Priivacy-ai/spec-kitty-saas#149.
• Run the real repository repair coordination from Coordinate the actual mission-state repair commit across active repositories #979.
• File any post-merge failures under Workstream 0, not as one-off TeamSpace cleanup.

Phase 0: Safety Rail

• Add a cross-surface fixture harness that can run the same mission state through next, agent action, move-task, status, dashboard scanner, review, merge --dry-run, and real merge preflight.
• Establish diagnostic-code inventory for lifecycle, review, merge, sync, and release evidence blockers.

Phase 1: Stop Active Release Bleeding

• Workstream 3: merge dry-run parity for bug: merge dry-run misses review artifact consistency failures #991.
• Workstream 2: review-cycle artifact generation isolation for bug: review-cycle artifact generation can wrap prior cycle frontmatter/body #990.
• Workstream 1: next --json claimability parity for bug: spec-kitty next --json can miss claimable WPs available to explicit agent action #988.
• Workstream 5: baseline_merge_commit handling for bug: new missions without baseline_merge_commit skip dead-code review #989.
• Workstream 4: sync 403/teamspace classification for sync now misclassifies teamspace ingress rejection as server_error #889.
• Workstream 5: mypy strict release gate mypy strict gate fails on current baseline #971.

Phase 2: Collapse Symptom Families

• Promote review-cycle aggregate beyond rejected-only helper.
• Promote merge readiness to a shared dry-run/real evaluator.
• Promote work-package lifecycle decisioning to a single domain service consumed by all command surfaces.
• Promote sync publication outcomes to explicit local-result plus remote-publication-result objects.

Phase 3: Drain Older Boundary Debt

• Encoding mixups: stop assuming UTF-8 by default and record encoding decisions at lifecycle boundaries #644 encoding/provenance narrowed to one lifecycle chokepoint plus regression fixture.
• Resolve automated CI workflow duplication -> release readiness vs CI-quality #662 CI duplication resolved by contract between CI-quality and release-readiness.
• EPIC: Tech/Functional Debt Remediation: 3.x development inconsistencies and behavioural problems #391 reduced by closing or refiling stale umbrella debt into bounded context issues.

Definition Of Done

• All current open bug issues listed above are closed or explicitly moved to a successor epic with a current repro and deferral rationale.
• Each recently fixed bug family has at least one cross-boundary regression test that proves the invariant at the next boundary, not only at the original symptom boundary.
• The TeamSpace cutover PR set is either landed and post-merge verified, or explicitly split with launch-blocking rationale.
• No release-blocking command reports success while silently skipping a required new-mission gate.
• Dry-run output is a faithful serialization of the same domain decision real execution uses.
• SaaS sync publication failures cannot be mistaken for local mutation failures, and local mutation success cannot hide a non-retryable publication blocker.
• The final smoke includes local mode and SaaS-enabled mode with SPEC_KITTY_ENABLE_SAAS_SYNC=1.

Non-Goals

• This epic should not become a product expansion vehicle.
• Do not rewrite the CLI surface wholesale.
• Do not close old issues merely because this epic references them.
• Do not add broad suppressions, skips, or compatibility fallbacks unless they are typed, diagnosed, and issue-backed.

Suggested Labels

bug, workflow, release, epic

[stijn-dejongh]

Quick impression: the description and direction of the issue is valid, and the bug queue is accurate. The work should start by reshaping the domain contracts and entry-points, then using the bug queue as a code-level acceptance criterium to validate the architectural direction we are taking.

Draining the queue is the objective/goal, the immediate concern is reshaping the code to make this easier and avoid regressions in the future.

[stijn-dejongh]

Adding some forensic backing from the recent CaaCS audit (architecture/audits/2026-05-spec-kitty-caacs.md, multi-window expansion architecture/audits/2026-05-11-findings-vs-issues-update.md) that lines up with this epic's diagnosis and may help calibrate Phase 0 / Phase 1 sequencing.

Where the audit converges with this epic

The audit's F2 finding is: the src/specify_cli/cli/commands/agent/{tasks,workflow,mission}.py cluster is the unambiguous structural-remediation target. Concretely:

• agent/tasks.py: 3746 SLOC, F-rated complexity, finalize_tasks CC=160, move_task CC=139.
• agent/workflow.py: F-rated, status CC=87, review CC=84.
• agent/mission.py: 2314 SLOC, map_requirements CC=74; finalize_tasks lives here despite the name.
• 45 co-changes between tasks.py and workflow.py in the trailing year (top temporal-coupling pair in src/).
• The cluster sits in the top-5 of both full-history and 4-month velocity-adjusted refactor-candidate lists — i.e., it is urgent under any time window.

That is the file-level shape underneath the "too many command surfaces own the same truth" diagnosis in the body. The audit therefore supports the comment from 2026-05-07: reshape the entry-points first, then drain the queue as acceptance.

Where the audit adds evidence the epic does not have

• F15 (audit): the F2 cluster ships without test updates in ~70% of commits (tasks.py 29.9% test:src ratio, workflow.py 27.3%, mission.py 31.6%). This is direct quantitative justification for Phase 0's "cross-surface fixture harness" requirement — the harness needs to exist before Phase 1 lands real workstream changes, otherwise lifecycle regressions ship invisibly. Worth promoting from "Phase 0 nice-to-have" to "Phase 0 blocker".
• F1 / bus factor (audit): 89.5% single-author concentration in src/. The doctrine artifact this epic produces (North Star Invariants → executable domain services) is the canonical mitigation; the epic implicitly addresses bus factor by lowering it from the file level to the aggregate level. Worth naming explicitly under "Non-Goals" or DoD.
• Brownfield paradigm (brownfield-onboarding.paradigm.yaml, DM-D): prescribes documenting the current contract before reshaping it. The epic specifies the target shape per workstream but does not require a transfer artifact for the current shape. Adding a one-paragraph "current contract" preamble per workstream would make rollback decisions cheaper.

Suggested low-touch refinements

• Add to Phase 0 acceptance: "Phase 1 workstreams may not land until the cross-surface fixture harness rejects at least one currently-passing F2-cluster test." (Forces real harness, not aspirational.)
• Tag W1/W2/W3 acceptance bullets with the specific F2-cluster file they touch, so the DoD is auditable at file level too, not only at command-surface level.

Happy to keep this here as audit context; not a blocker.

(Full audit and supporting docs land in PR #1019.)