Checklists

requirements.md

Specification Quality Checklist: Unified Charter Bundle and Read Chokepoint

Purpose: Validate specification completeness and quality before proceeding to /spec-kitty.plan Created: 2026-04-14 Design-review revised: 2026-04-14 (three P1/P2 findings corrected — see below) Feature: spec.md Mission ID: 01KP5Q2G4Z39ZVRX2FY3NWXZQW Tracking issue: Priivacy-ai/spec-kitty#464

Content Quality

  • ✅ No implementation details leak into user-scenario or requirement narrative beyond what the architecture authority already commits to (the spec names Python modules, filenames, and line numbers where the existing code is the subject of the change — intentional for a refactor/excision tranche, matches Phase 1 house style, and required by the #393 bulk-edit guardrail pattern).
  • ✅ Focused on operator and contributor value (fresh clone works without manual sync; worktrees transparently see main-checkout charter; readers are freshness-safe by construction).
  • ✅ Written so a technical stakeholder familiar with the architecture doc and listed issues can evaluate without external context.
  • ✅ All mandatory sections completed.

Requirement Completeness

  • ✅ No [NEEDS CLARIFICATION] markers remain.
  • ✅ Requirements are testable and unambiguous.
  • ✅ Requirement types are separated into Functional (FR-001..FR-016), Non-Functional (NFR-001..NFR-006), and Constraints (C-001..C-012).
  • ✅ IDs are unique across FR-###, NFR-###, and C-### entries.
  • ✅ All requirement rows include a non-empty Status value.
  • ✅ Non-functional requirements include measurable thresholds.
  • ✅ Success criteria are measurable (12 explicit pass conditions).
  • ✅ Success criteria are technology-grounded where a refactor demands it and user-focused where an operator cares.
  • ✅ All acceptance scenarios are defined (7 scenarios).
  • ✅ Edge cases are identified (8 cases).
  • ✅ Scope is clearly bounded (Goals, Non-Goals, Out of Scope sections itemized).
  • ✅ Dependencies and assumptions are identified.

Feature Readiness

  • ✅ All functional requirements have clear acceptance criteria traceable to Success Criteria entries.
  • ✅ User scenarios cover primary flows.
  • ✅ Feature meets measurable outcomes defined in Success Criteria (Gates 1–4 of issue #464 each map to a numbered Success Criterion).
  • ✅ No implementation detail leaks into behavior contracts beyond what the architecture already prescribes as authoritative.

Cross-Mission Alignment

  • ✅ Phase 1 baseline (#627 / db451b8f) is cited as a precondition and not reopened.
  • ✅ Phase 0 baseline (DRG schema, merged-graph validator) is cited as a precondition and not reopened (C-005).
  • ✅ #361 dashboard typed contracts named as regression safety net for WP2.3 (C-010, FR-014).
  • ✅ #393 bulk-edit guardrail mandated per WP boundary (C-002, FR-015).
  • ✅ Migration filename deviation from issue #464 (m_3_2_0_unified_bundle.py → m_3_2_3_unified_bundle.py) documented (C-008, FR-008).
  • ✅ Package duplication deferred per user Q3=B (C-003, Non-Goals).
  • ✅ Worktree memory/AGENTS sharing preserved as documented-intentional (C-011); original #339 symlink proposal explicitly superseded by canonical-root resolution.
  • ✅ Manifest v1.0.0 scope limited to sync()-produced files (C-012); references.yaml and context-state.json explicitly deferred.

Design-Review Corrections (2026-04-14)

Three P1/P2 findings from design review have been fully addressed. Each resulted in scope/algorithm corrections across the spec, plan, research, data-model, contracts, and quickstart.

  • ✅ P1 #1 (worktree symlink scope): spec's FR-005 ("delete lines 478–532") removed. Scenario 2 reframed to reader behavior. Success Criteria 2 and 7 rewritten. Risks table updated. FR-016 grep invariants no longer sweep for shutil.copytree / os.symlink targeting .kittify/memory / .kittify/AGENTS.md. New C-011 pins the symlink block as out-of-scope. Plan §WP2.3 step F removed; WP2.3 Step G (occurrence artifact) includes action: leave for lines 478–532. Plan D-14 records the rationale.
  • ✅ P1 #2 (manifest scope): v1.0.0 derived_files narrowed to [governance.yaml, directives.yaml, metadata.yaml] — the three files src/charter/sync.py :: sync() materializes per _SYNC_OUTPUT_FILES at src/charter/sync.py:32-36. references.yaml (compiler pipeline, src/charter/compiler.py:169-196) and context-state.json (runtime state, src/charter/context.py:385-398) removed from v1.0.0. New C-012 pins the narrowing. contracts/bundle-manifest.schema.yaml, contracts/chokepoint.contract.md, contracts/bundle-validate-cli.contract.md, contracts/migration-report.schema.json, data-model.md, and the FR-004 / FR-009 / FR-012 language all narrowed. bundle validate CLI surfaces out-of-scope files as informational warnings. Plan D-13 records the rationale.
  • ✅ P2 #3 (resolver algorithm): contracts/canonical-root-resolver.contract.md rewritten with explicit six-step algorithm including file-input normalization, relative-vs-absolute stdout resolution via (cwd / stdout).resolve(), and explicit .git/-interior detection in step 5. Behavioral matrix re-verified row-by-row against git rev-parse --git-common-dir actual output (.git, ../../.git, ., or absolute-path depending on invocation). Plan D-2 updated to note the algorithm correction. Research R-2 table corrected with verified stdout shapes.

Notes

  • Every FR-### that triggers a cross-repo or cross-package edit carries an explicit file-path cluster in "Likely File Clusters" — the plan phase leans on these clusters directly.
  • Baseline capture for FR-014 (pre-wp23-dashboard-typed.json) is a first-step deliverable within WP2.3 and must execute on pre-WP2.3 main to be authoritative.
  • The AST-walk test (FR-011) and the bundle contract test (FR-012) are the two principal proofs that the chokepoint is actually enforced and the v1.0.0 manifest actually holds.
  • The occurrence artifacts are mission-owned; each WP cannot merge without its artifact's "to-change" set going empty on disk. WP2.3's occurrence artifact must include explicit leave entries for src/specify_cli/core/worktree.py:478-532 (C-011), src/charter/compiler.py:169-196 (C-012), and src/charter/context.py:385-398 (C-012).
  • Items marked [x] passed validation at spec revision time (2026-04-14 after design-review corrections). All corrections are recorded in a commit message and in the "Design-Review Corrections" section above; no [NEEDS CLARIFICATION] markers were emitted.