Work Packages: Charter Preflight Missing-Charter Advisory Mode
> Pre-merge correction (2026-08-16): Historical T005/T006 guidance was unsafe. Canonical missing/missing/(missing|built_in_only) state qualifies first; charter.md selects copy only. All next wrapper modes and implement emit stderr; dashboard persists; JSON stdout stays clean; charter.bundle remains lazy; remediation uses --no-from-interview. Red/green pairs: 4bc73dbc6→4493699b0, 3f5ab1082→3dc72aa04.
Inputs: Design documents from kitty-specs/charter-preflight-missing-charter-advisory-01M050PD/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/missing-charter-advisory-matrix.md, quickstart.md
Tests: Required — spec.md constraint C-003 and NFR-002 mandate regression test coverage; this repo's charter also requires tests for new functionality (DIR-005) and follows test-first-bug-fixing doctrine (write red, then green).
Organization: Fine-grained subtasks (Txxx) roll up into work packages (WPxx). Each work package must be 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).
- Subtasks are reference rows, not checkboxes: record completion with
spec-kitty agent tasks mark-status <Txxx> --status done.
Path Conventions
- Single project:
src/,tests/(this is a CLI/library fix inside the existingsrc/specify_cli/package — no new directories).
Work Package WP01: Missing-Charter Advisory Fix (Priority: P1) 🎯 MVP
Goal: Fix #3498 — wire canonical missing-stack advisory mode into the shared next/implement hook, select distinct legacy wording only after canonical qualification, and surface advisories on every consumer. Every stale/invalid/partial state keeps blocking regardless of charter.md. Independent Test: Run tests/specify_cli/charter_preflight/, tests/agent/cli/commands/test_next_preflight.py, tests/agent/cli/commands/test_implement_preflight.py, and tests/test_dashboard/test_dashboard_preflight.py — including identical canonical states with/without prose, stale/invalid residue with prose, stderr emission, and dashboard persistence. Prompt: /tasks/WP01-missing-charter-advisory-fix.md Requirement Refs: FR-001, FR-002, FR-003, FR-004, FR-005, NFR-001, NFR-002, C-001, C-002, C-003
Included Subtasks
T001 [P] Add runner-level regression tests to tests/specify_cli/charter_preflight/test_runner.py (canonical missing/built-in-only predicate, prose-only warning selection, stale/invalid residue non-regression) — write RED first T002 [P] Add hook-level regression tests to tests/agent/cli/commands/test_next_preflight.py (both advisory shapes now pass spec-kitty next) — write RED first T003 [P] Add hook-level regression tests to tests/agent/cli/commands/test_implement_preflight.py (both advisory shapes now pass spec-kitty implement) — write RED first T004 [P] Add/extend dashboard regression tests proving a passed legacy advisory is persisted/rendered by the command, not merely returned as metadata T005 Implement _is_optional_missing_charter_stack(), the legacy warning selector, and canonical-first advisory branch in runner.py — turns T001 green T006 Wire allow_missing_charter=True into run_preflight_or_abort(), emit advisory warnings to stderr, and persist passed advisories in the dashboard command — turns T002/T003/T004 green T007 Add a CHANGELOG.md entry documenting the behavior fix; run the full charter-preflight regression suite + mypy --strict + ruff check to confirm zero regressions; assign Priivacy-ai/spec-kitty#3498 to the Human-in-Charge (DIR-012)
Implementation Notes
- Follow test-first-bug-fixing: T001–T004 are written and confirmed RED (failing for the right reason — current code still blocks/lacks the predicate) before T005/T006 make them green.
- T005 before T006 — the hook wiring in T006 depends on the predicate/branch existing in the runner first.
- Resolve the contract exactly: canonical state fixes pass/block first;
charter.mdmay then choose legacy warning copy. Never consult prose to exempt stale/invalid/partial state.
Parallel Opportunities
- T001–T004 touch four independent test files and can be drafted in any order (marked
[P]).
Dependencies
- None (single work package for this mission).
Risks & Mitigations
- Risk: broadening the existing
_is_optional_missing_charter_fresh_project()predicate by accident → Mitigation: T001 includes an explicit non-regression assertion that the existing predicate's exact-match behavior is unchanged. - Risk: legacy-bundle detection adding unbounded filesystem I/O → Mitigation: NFR-001 caps it at one
Path.exists()check; T005 review must confirm no directory walk was introduced.
Dependency & Execution Summary
- Sequence: WP01 only — this mission is small and single-package by design (see plan.md Charter Check / C-002: fix must live in one shared implementation point, which collapses naturally into one WP).
- Parallelization: T001–T004 (test authoring across 4 files) are parallel-safe within WP01.
- MVP Scope: WP01 is the entire mission.
Requirements Coverage Summary
| Requirement ID | Covered By Work Package(s) |
|---|---|
| FR-001 | WP01 |
| FR-002 | WP01 |
| FR-003 | WP01 |
| FR-004 | WP01 |
| FR-005 | WP01 |
| NFR-001 | WP01 |
| NFR-002 | WP01 |
| C-001 | WP01 |
| C-002 | WP01 |
| C-003 | WP01 |
Subtask Index (Reference)
| Subtask ID | Summary | Work Package | Priority | Parallel? |
|---|---|---|---|---|
| T001 | Runner-level regression tests (red) | WP01 | P1 | Yes |
| T002 | next hook regression tests (red) | WP01 | P1 | Yes |
| T003 | implement hook regression tests (red) | WP01 | P1 | Yes |
| T004 | Dashboard warning-detail test | WP01 | P1 | Yes |
| T005 | Implement legacy-bundle predicate + warning in runner.py | WP01 | P1 | No |
| T006 | Wire allow_missing_charter=True into shared hook | WP01 | P1 | No |
| T007 | CHANGELOG entry + full regression run + HiC assignment | WP01 | P1 | No |