description: "Work package task list template for mission implementation"

Work Packages: CI Health: Charter-Path Hotfix + Arch-Adversarial Shard

Inputs: Design documents from /kitty-specs/ci-health-charter-path-and-arch-shard-01KWRTB2/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md (no contracts/ — this mission has no API surface)

Tests: This mission is test-infrastructure work — every WP includes tests as its actual deliverable (structural/architectural guards), not optional add-ons.

Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package is independently deliverable and testable.

Prompt Files: Each work package references a matching prompt file in /tasks/ generated by /spec-kitty.tasks.

Subtask Format: [Txxx] [P?] Description

  • [P] indicates the subtask can proceed in parallel (different files/components).

Path Conventions

  • Single project: src/, tests/, .github/workflows/, docs/ — no web/mobile split. This mission touches no src/ product code.

Work Package WP01: Docs charter-path hotfix (Priority: P0)

Goal: Remove the last memory/charter.md reference from the guarded doc roots so fast-tests-docs goes green on every open PR. Independent Test: pytest tests/docs/test_current_charter_paths.py -q passes. Prompt: /tasks/WP01-docs-charter-path-hotfix.md Requirement Refs: FR-001, FR-002

Included Subtasks

  • ✅ T001 Fix the stale memory/charter.md reference in docs/guides/contributing.md:394 to reference the canonical .kittify/charter/charter.md
  • ✅ T002 Run test_current_docs_do_not_publish_memory_charter_path and re-confirm (via the guard itself, not inspection) zero offenders across all four guarded roots

Implementation Notes

  • Single-line, mechanically verified fix. No design decisions remain — R1 in research.md already confirmed this is the sole offender.

Parallel Opportunities

  • Fully independent of WP02/WP03 — different files, no shared surface. Can run in its own lane concurrently with both.

Dependencies

  • None (independent of WP02/WP03).

Risks & Mitigations

  • None material. Risk of a second undiscovered offender is mitigated by re-running the guard itself rather than trusting the single known line.

Work Package WP02: Arch-shard marker taxonomy + assignment table (Priority: P0)

Goal: Introduce the arch_shard_1/2/3 pytest markers, the single-source module/dir → shard assignment table, and the completeness guard proving every test under the 4 arch-pole roots gets exactly one shard marker. Independent Test: pytest tests/architectural/test_arch_shard_marker_completeness.py -q passes; the three shard-reproduction commands in quickstart.md each collect a non-overlapping subset whose union equals the pre-split universe. Prompt: /tasks/WP02-arch-shard-marker-taxonomy.md Requirement Refs: FR-004, FR-005

Included Subtasks

  • ✅ T003 Register arch_shard_1, arch_shard_2, arch_shard_3 markers in pytest.ini (the single source of truth per test_marker_registry_single_source.py, #2034)
  • ✅ T004 Create tests/_arch_shard_map.py — the single-source module-stem/whole-directory → shard-number table, seeded from the concrete 216/215/215 split in data-model.md
  • ✅ T005 Author tests/architectural/test_arch_shard_marker_completeness.py RED-first against today's topology (no markers exist yet) — asserts every test collected under tests/{adversarial,architectural,architecture,lint} carries exactly one arch_shard_N marker and that the union equals the full pre-split selection
  • ✅ T006 [P] Extend the existing pytest_collection_modifyitems hook in tests/conftest.py (around line 198 — do NOT add a second same-named function, pytest only permits one per conftest module) to apply the arch_shard_N marker from the T004 table, scoped strictly to items collected under the 4 pole roots
  • ✅ T007 Run the three shard-reproduction commands from quickstart.md locally and confirm T005's guard goes GREEN

Implementation Notes

  • T004/T006 are the load-bearing pair: the table is pure data, the hook is the one place that reads it. Keep the hook read-only over the table (no mutation).
  • T005 must be authored to FAIL before T004/T006 land (red-first discipline, charter Standing Order 4) — write it first, watch it fail for the right reason (no arch_shard_* marks exist), then let T004/T006 turn it green.
  • If a new test file appears under the 4 pole roots that isn't in the T004 table, T005 must fail loudly (an assignment gap), not silently pass — this is the completeness guarantee.

Parallel Opportunities

  • T003 and T004 can proceed in parallel (different files). T006 is marked [P] relative to T005's authoring (the RED test can be written while the hook is being built, as long as T005 lands red first) but T006 must land before T007's verification.

Dependencies

  • None (independent of WP01). WP03 depends on this WP.

Risks & Mitigations

  • Marker registration must land as ROUTED-BY-MARKER in test_marker_job_completeness.py's live re-derivation (a CI job selecting -m arch_shard_N in WP03 makes this automatic) — no hand-edit of that test's ledger is expected, but confirm at WP03 time.
  • Do not leak arch_shard_N marks onto tests outside the 4 pole roots — scope the hook's file-path check tightly.

Work Package WP03: Arch-adversarial matrix split + partition guards (Priority: P0)

Goal: Expand the arch-adversarial CI job from 1 to 3 matrix legs selecting by arch_shard_N marker, extend the structural guards so the partition (union = full universe, no drops, no double-counts) is asserted by construction, update the committed CI-topology timings fixture, and record the FR-008/SC-005 acceptance verification for issue #2397 — closing the gate-unmask gap the post-plan brownfield squad found in test_shard_universe_bounded.py, and fixing the two literal-shard-name pins the same squad found in test_ci_quality_path_filters.py. Independent Test: All commands in quickstart.md's "Verify the partition invariants" and "Verify the workflow still stays de-serialized/group-less" sections pass; the arch-adversarial job in a CI run shows 3 parallel matrix legs. Prompt: /tasks/WP03-arch-adversarial-matrix-split.md Requirement Refs: FR-003, FR-004, FR-005, FR-006, FR-007, FR-008

Included Subtasks

  • □ T008 Expand .github/workflows/ci-quality.yml's arch-adversarial job strategy.matrix.include from the single architectural shard to arch_shard_1/arch_shard_2/arch_shard_3, updating both the full-selection and docs-only-trim -m expressions to AND with the shard marker, while preserving if: always(), no needs: edge, and no dorny filter if:
  • □ T009 Generalize tests/architectural/test_shard_universe_bounded.py (extend _CATCH_ALL_SUBSTR or add a sibling assertion) so the union/no-double-count invariant also covers arch-adversarial — author/adjust RED-first against the pre-T008 single-shard topology
  • □ T010 [P] Update the two literal-shard-name pins in tests/architectural/test_ci_quality_path_filters.py (~line 239 entry["shard"] == "architectural", ~line 291 "architectural" in arch_shards) to check for {"arch_shard_1","arch_shard_2","arch_shard_3"} instead, re-pinning the same behavioral invariants (parity ratchet in-scope of the always-on pole; extracted arch shard still exists)
  • □ T011 [P] Run tests/release/test_coverage_topology_ownership.py against the updated workflow and confirm it passes unmodified (per R4, it is shard-label-agnostic); fix the minimal gap only if it does not
  • □ T012 Full local verification: every command in quickstart.md, plus test_arch_pole_deserialized.py and test_docs_scoped_arch_coverage.py, all green
  • □ T013 [P] Update tests/release/ci_topology_timings_postshrink.json (FR-007) to record the 3-shard split as the new canonical shape, retiring the "#2397 still open" framing while keeping historical numbers intact
  • □ T014 Write kitty-specs/ci-health-charter-path-and-arch-shard-01KWRTB2/acceptance-record.md (FR-008/SC-005) — re-verify and record each of issue #2397's 5 invariant-safety criteria against T012's real results

Implementation Notes

  • T008 is the functional change; T009/T010/T011 are the guards that prove it didn't silently drop/double-count/re-serialize/re-couple to a filter group. Land them together — T008 without T009/T010 ships FR-005 gate-unmasked (see Charter Check in plan.md).
  • Reuse the coverage artifact naming already in place (coverage-arch-adversarial-${{ matrix.shard }}.xml, arch-adversarial-${{ matrix.shard }}-reports) — only the matrix.shard values change.

Parallel Opportunities

  • T010 and T011 are independent of T009 and of each other (different files) — [P].

Dependencies

  • Depends on WP02 (needs arch_shard_1/2/3 to exist as real, collected markers before the workflow can select by them).

Risks & Mitigations

  • Regression risk: accidentally re-adding a dorny filter if: or a needs: edge would silently re-enter JOB_GROUPS/fast-lane serialization — mitigated by T012 re-running test_arch_pole_deserialized.py and test_docs_scoped_arch_coverage.py explicitly.
  • _CATCH_ALL_SUBSTR generalization (T009) could accidentally widen scope to unrelated jobs if done carelessly — scope the change to add arch-adversarial specifically, not to loosen the substring match generically.

Dependency & Execution Summary

  • Sequence: WP01 (independent) ‖ WP02 → WP03.
  • Parallelization: WP01 can run in its own lane fully concurrently with WP02/WP03. WP02 must complete (markers + table + hook) before WP03 (workflow matrix) starts.
  • MVP Scope: All three WPs are required — this mission has no partial-value slice; Concern A (WP01) and Concern B (WP02+WP03) are both P0 fixes for a currently-red/slow main.

Requirements Coverage Summary

Requirement IDCovered By Work Package(s)
FR-001WP01
FR-002WP01
FR-003WP03
FR-004WP02, WP03
FR-005WP02, WP03
FR-006WP03
FR-007WP03
FR-008WP03

Subtask Index (Reference)

Subtask IDSummaryWork PackagePriorityParallel?
T001Fix stale charter path in contributing.mdWP01P0No
T002Verify docs guard, zero offendersWP01P0No
T003Register arch_shard_1/2/3 markersWP02P0Yes
T004Create tests/_arch_shard_map.pyWP02P0Yes
T005Author completeness guard RED-firstWP02P0No
T006Extend collection hook in tests/conftest.pyWP02P0Yes
T007Local shard-reproduction verificationWP02P0No
T008Expand arch-adversarial matrix to 3 shardsWP03P0No
T009Generalize shard-universe-bounded guardWP03P0No
T010Fix pinned shard-name assertionsWP03P0Yes
T011Confirm coverage-topology-ownership guardWP03P0Yes
T012Full local + guard-suite verificationWP03P0No
T013Update CI-topology timings fixture (FR-007)WP03P0Yes
T014Write #2397 acceptance record (FR-008)WP03P0No