specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/templates/plan-overview-template.md

@@ -0,0 +1,150 @@
+# Implementation Plan Template (Human-Read)
+
+**Filled by**: `/specpro-plan`. Filename: `specs/plan-overview.md`.
+**Companion**: `plan-template.md` — the machine-read half, written to `specs/plan.md`.
+
+> **This file is the human-read half.** For people; *sufficient useful information is enough.*
+> **No command reads it** — and **no command may reference its section names** (`/specpro-implement` loads only from `plan.md`, and never this file). Keeping the two halves in separate files is what makes "implement does not read the human half" a structural fact rather than a convention.
+> **Every section MUST open with a one-line `*Purpose · Consumers*` note** — for these sections the consumer will normally be "humans"; write that plainly rather than inventing a machine consumer. No status bits, no checkboxes.
+
+---
+
+> No machine consumers in this part. **Sufficient useful information is enough.** No status bits, no checkboxes.
+
+## Summary
+
+*Purpose: an orientation for a human reader — what this is and how it will be built · Consumers: **humans***
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## System Overview
+
+*Purpose: the runtime component-stack view, for a human reader · Consumers: **humans***
+
+> **View semantics**: this is the **runtime component stack** view. The Part I `## Architecture → ### Layered Architecture` is the **source-set ownership** view. They answer different questions and MUST NOT be applied to each other.
+
+[Provide high-level architecture diagram or description. Example:]
+
+```
+[Layer/Component architecture showing major subsystems and their relationships]
+```
+
+**Architecture Summary**: [2-3 sentences describing core architecture pattern (e.g., microkernel + plugins, layered, microservices)]
+
+## Constitution Check
+
+*Purpose: the gate record — which principles the design satisfies, and which gaps are tracked · Consumers: **humans** (the FR-level risk list is NOT here — it lives in Part I `Quality Targets → Risk Classification`, which is what `tasks` §4.j-2 reads)*
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+*See: Step 4.0: Constitution Gate Evaluation, Step 4.1: Re-evaluate Constitution Check*
+
+[Gates determined based on constitution file — one row per principle: status (PASS / PARTIAL / FAIL) + what it rests on. State explicitly when a principle is satisfied **at the design level** but has a tracked **integration-level** gap.]
+
+## Implementation Plan
+
+*Purpose: human-readable plan information — the schedule, milestones, risks, and the per-phase acceptance criteria with their judges · Consumers: **humans** (no command reads this section; `user-manual` is explicitly forbidden from sourcing it)*
+
+> **Currency**: the estimates, milestones and risks below are **point-in-time judgements**, not current progress. Authoritative progress is the `tasks.md` Task Summary; pending issues are in `implement_issues.md`.
+
+### Phase Overview
+
+*Purpose: phases with goals, deliverables, estimates and dependencies · Consumers: humans*
+
+[Define major development phases with goals, deliverables, and dependencies]
+
+| Phase | Name | Goal | Key Deliverables | Estimate | Dependencies |
+|-------|------|------|------------------|----------|--------------|
+| 0 | [Name] | [Primary objective] | [Major outputs] | [Weeks] | [What must come first] |
+| 1 | [Name] | [As above] | [As above] | [As above] | [As above] |
+| 2 | [Name] | [As above] | [As above] | [As above] | [As above] |
+
+**Total Estimate**: [Sum of estimates] weeks
+
+### Phase Acceptance Criteria and Judges
+
+*Purpose: each acceptance criterion names its JUDGE; the judge holds the state in its own artifact · Consumers: humans (the criteria's authority — `implement`/`test-plan` judge from their own artifacts, not from this table)*
+
+> **This replaces the old per-phase checkbox lists.** A criterion is **not** a status bit: it carries **no checkbox**, and **every criterion MUST name its JUDGE** — the command or role that decides it. The judge holds the state in its own artifact; **this file does not carry acceptance state**.
+>
+> **Do not write a criterion that has no judge.** If you cannot name who decides it, the criterion is not yet a criterion — it is a gap. Record it as such (a `[plan]` issue) rather than leaving an unjudgeable line here.
+
+| Phase | Criterion | Judge | State lives in |
+|-------|-----------|-------|----------------|
+| [N] | [what must hold] | [`/specpro-implement` coverage acceptance · `/specpro-test-plan` → `test-implement` · `/specpro-plan` own step · **TBD**] | [artifact] |
+
+### Key Activities
+
+*Purpose: what happens in each phase, as an activity description · Consumers: humans*
+
+[Numbered list of what happens in each phase. **No checkboxes** — this is an activity description, not a task queue. Do NOT use the `[x]/[ ]` of any deliverable to decide what to skip: activity gating is decided by the `lifecycle_cache` FR state, not by anything in this file.]
+
+### Dependencies and Critical Path
+
+*Purpose: the phase dependency graph and the critical path · Consumers: humans*
+
+[Visual dependency graph or table]
+
+```
+[Dependency graph showing phase relationships and critical path]
+```
+
+**Critical Path**: [The sequence of phases that determines minimum project duration]
+
+**Critical Path Duration**: [Weeks]
+
+**Parallel Opportunities**: [Phases that can run in parallel]
+
+### Risk Management
+
+*Purpose: point-in-time risk judgement and mitigations · Consumers: humans*
+
+#### Technical Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk description] | [High/Med/Low] | [Severity] | [Action to reduce risk] |
+
+#### Project Risks
+[As above for project-level risks]
+
+#### Quality Risks
+[As above for quality risks]
+
+### Milestones
+
+*Purpose: the timeline view — milestones, targets and deliverables (criteria are pointed at, not restated) · Consumers: humans*
+
+| Milestone | Target | Deliverables | Criteria (pointer) |
+|-----------|--------|--------------|--------------------|
+| [Milestone 1] | [Date/Phase] | [What's delivered] | See "Phase Acceptance Criteria and Judges" · Phase [N] |
+| [Milestone 2] | [As above] | [As above] | [As above] |
+
+> **Do not restate the criteria here.** Their single authority is the **Phase Acceptance Criteria and Judges** table above — which also names each criterion's judge. This section keeps the **timeline** and the deliverables; duplicating criteria here creates a second copy with no judge attached, and the two drift.
+
+## Documentation Layout
+
+*Purpose: where this feature's documentation artifacts land — a human navigation aid · Consumers: humans — `tasks`' Location grounding covers code and test paths only, it does not read this section; **the authoritative list is whatever `specs/` actually contains** (this is a point-in-time expectation, not kept in sync with later additions)*
+
+```text
+specs/
+├── spec.md              # Feature specification
+├── plan.md              # This file (/specpro-plan command output)
+├── research.md          # Phase 0 output - Technology decisions
+├── data-model.md        # Phase 1 output - Core entities
+├── scenarios.md         # Phase 1 output (initial run only) - Acceptance test scenarios; refresh with /specpro-scenarios
+├── quickstart.md        # Phase 1 output - Developer quickstart guide
+├── contracts/           # Phase 1 output - API contracts
+└── tasks.md             # Phase 2 output (/specpro-tasks command - NOT created by /specpro-plan)
+```
+
+## Complexity Tracking
+
+*Purpose: the justification record for design complexity — constitutional violations **and** architectural decisions that rejected a simpler alternative · Consumers: **humans** (this is also where a technology/architecture change is recorded — see the change-propagation rule in `/specpro-plan`)*
+
+> **Fill when there is a constitutional violation to justify, OR a design decision that rejected a simpler alternative.** The section name is deliberately wider than "violations": a decision to take the more complex route belongs here too, because the question it answers is the same — *why wasn't the simpler alternative enough?*
+>
+> **No violations and no such decision** → omit the section, or write `Not applicable`.
+
+| Violation / Decision | Why Needed | Simpler Alternative Rejected Because |
+|----------------------|------------|--------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

specpro_cli/assets/templates/plan-template.md

@@ -0,0 +1,387 @@
+# Implementation Plan Template (Machine-Read)
+
+**Filled by**: `/specpro-plan`. Filename: `specs/plan.md`.
+**Companion**: `plan-overview-template.md` — the human-read half, written to `specs/plan-overview.md`.
+
+> **This file is the machine-read half.** Downstream specpro commands extract from it **by section**; it MUST be mechanically parseable. **No task checkboxes, no progress status, no decision narrative.**
+> **Every section MUST open with a one-line `*Purpose · Consumers*` note** — name the command and the step, say what is done with it, and cover **sub-sections too** (the per-subsection extractions read them). If a section has no machine consumer it belongs in the companion file, not here.
+> Anything "to be done" MUST carry an FR anchor or live in a task queue (`tasks.md` / `test-tasks.md` / `fix-tasks.md`) — **never here**.
+
+---
+
+## Technical Context
+
+*Purpose: fix the tech stack and platform boundary so downstream can generate scaffolding and ground file paths · Consumers: `tasks` (§4.a extraction · Location grounding) · `implement` (§7.a load) · `qc` (terminology list) · `user-manual` (leakage scan) · `analyze` (Target Platform tier claims)*
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]
+  - **Key Features**: [Key capabilities of this language, e.g., "Type-safe nullability, first-class coroutines"]
+  - **See**: research.md Section: [Language section name] (if detailed analysis exists)
+
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]
+  - **Key Features**: [List 2-4 key capabilities for each major dependency]
+    * [Dependency 1]: [Key capability 1], [Key capability 2]
+    * [Dependency 2]: [Key capability 1], [Key capability 2]
+  - **See**: research.md Section: [Dependency section name] (if detailed analysis exists)
+
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]
+  - **Key Features**: [Key capabilities if applicable]
+  - **See**: research.md Section: [Storage section name] (if detailed analysis exists)
+
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]
+  - **Key Features**: [Key testing capabilities if applicable]
+  - **See**: research.md Section: [Testing section name] (if detailed analysis exists)
+
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Quality Targets
+
+*Purpose: the project's quality thresholds — what downstream reads to generate test tasks and judge coverage · Consumers: `tasks` (§4.j-1 coverage numbers · §4.j-2 FR risk classification) · `implement` (§14 coverage acceptance — **authoritative**) · `test-plan` (layer-assignment aggressiveness)*
+
+### Project Type Classification
+
+*Purpose: state which project class this is — it selects the coverage tier · Consumers: `tasks` §4.j-1*
+
+**Project Type**: [MVP / Personal Application / Enterprise Application / Platform Application / Financial Application / Medical Application]
+
+**Rationale**:
+- [Why this project type was chosen]
+- [Impact of bugs/failures on users]
+- [Stability and reliability requirements]
+
+**Impact on Quality Standards**:
+- [How project type influences coverage targets]
+- [Trade-offs between velocity and quality]
+
+### Risk-Based Coverage Targets
+
+*Purpose: the coverage thresholds and test approach per risk level (the number source) · Consumers: `tasks` §4.j-1 · `implement` §14 (authoritative acceptance threshold) · `test-plan`*
+
+| Risk Level | Coverage Target | Test Approach | Example Modules |
+|------------|----------------|---------------|-----------------|
+| **HIGH-RISK** | **>XX%** | MANDATORY | [List high-risk modules from Constitution Check] |
+| **MEDIUM-RISK** | **>YY%** | RECOMMENDED | [List medium-risk modules] |
+| **LOW-RISK** | **Optional** | Manual testing acceptable | [List low-risk modules] |
+
+**Coverage Target Selection Guide** — ⚠️ **the numbers are NOT restated here** (`T242` / `ISS-215`):
+
+- **Where the defaults come from**: the constitution's **Quality Assurance Matrix** (one row per project type). That matrix is the **single source**; `/specpro-constitution` computes the project's targets from it.
+- **What this stage does**: `/specpro-plan` **classifies the project's modules** by risk level, then **copies that project's targets** from the constitution into the table above (replacing `>XX%` / `>YY%`).
+- ⇒ Fill the table from `specs/constitution.md`; **do not fill it from a list here.**
+
+⚠️ This block used to carry its own six-row list of percentages, and the two lists had **already diverged in five of six rows** (e.g. Platform: 90/70/0 here vs 95/85/50 in the matrix) — the measured consequence of the same fact kept in two places. A second copy is not a convenience; it is a source that drifts without reporting.
+
+### Risk Classification
+
+*Purpose: assign each FR to a risk level · Consumers: `tasks` §4.j-2 (per-FR classification) · §4.j-3 (risk annotation on generated tasks)*
+
+> This subsection replaces the old `## Constitution Check → §IV` compliance list: the FR-level risk enumeration is a **machine input**, not a compliance statement, and it belongs next to the coverage table it pairs with.
+
+| Risk level | Verification | FR list |
+|------------|-----------|---------|
+| **HIGH-RISK** | MANDATORY | [FR-xxx, FR-yyy …] |
+| **MEDIUM-RISK** | RECOMMENDED | [FR-xxx …] |
+| **LOW-RISK** | OPTIONAL | [FR-xxx …] |
+
+**The `Verification` column's meaning** ⚠️ (`T153` / `ISS-74` — matched to the instantiated `plan.md`, which renames it for the reason below):
+
+- **It is the *grade of the verification obligation*, and its content is the `Test Approach` column of the table above** — `MANDATORY` = every mechanism of that FR needs **one re-runnable verification** (preferring a verification script under `scripts/`, shipped with a fixture set; a hand-runnable command is the *floor*); `RECOMMENDED` / `OPTIONAL` step down the same way. **Do not restate the content here** — a second copy of the same fact diverges from its source without reporting (`FR-025`).
+- ⚠️ **It does NOT mean ordering.** A verification of the form "does this artifact exist / is it consistent" is **runnable only after** the artifact exists, so a reader taking this column to mean *"test tasks come before implementation tasks"* holds a criterion that is **structurally unsatisfiable** in a project like this one.
+- **Why the column was renamed** (it used to be `Test-First`): that term had **no definition** in the project, and a definition added alongside would be **skimmed past — a renamed column is not.**
+
+
+- **HIGH-RISK** — protocol implementations · cryptography/security · network transport · critical data operations
+- **MEDIUM-RISK** — business logic and service orchestration · data models and repositories · platform API bindings
+- **LOW-RISK** — UI components · utilities and helpers · dev tools
+
+### Constitution Compliance
+
+*Purpose: carry the written derivation chain "these targets come from Constitution Article IV" · Consumers: **cited as a premise, not read as a field** — `tasks` §4.j states its basis as "plan.md Quality Targets (which derive from Constitution Article IV)", and this subsection is that derivation; changing it changes the legitimacy of the downstream test tasks*
+
+**Constitution Reference**: Article IV (Risk-Based Quality Assurance)
+
+**Alignment**:
+- ✅ Coverage targets proportional to module risk level
+- ✅ HIGH-RISK modules: MANDATORY — every mechanism needs a re-runnable verification, with >XX% coverage where measurable
+- ✅ MEDIUM-RISK modules: RECOMMENDED, with >YY% coverage where measurable
+- ✅ LOW-RISK modules: Testing OPTIONAL (manual acceptable)
+
+### Quality Validation Strategy
+
+*Purpose: how quality is measured and where the gates sit · Consumers: `implement` §14 (reads the whole `Quality Targets` section, this subsection included)*
+
+**Per User Story Phase**:
+- Generate test tasks based on FR risk level
+- Annotate implementation tasks with risk level and coverage requirement
+- Add quality checkpoint to verify coverage targets met
+
+**Measurement**:
+- Code coverage measured via [coverage tool: JaCoCo/Istanbul/Coverage.py]
+- Scenario automation measured via test scenario count (target: 85-90% of scenarios)
+- Both dimensions tracked independently
+
+**Quality Gates**:
+- HIGH-RISK FRs must achieve >XX% coverage before merge
+- MEDIUM-RISK FRs recommended >YY% coverage before merge
+- All tests must pass (unit, integration, contract)
+
+## Architecture
+
+*Purpose: the source-set ownership view — which layer owns which code, what the constraints are, and the field/branch-level protocol spec · Consumers: `tasks` (§4.i-1..i-4 per-subsection task generation: patterns→component tasks · layers→expect/actual + constraint-validation tasks · interactions→mechanism tasks · constraints→`[Quality]` validation tasks) · `analyze` (Pass M boundary audit · Pass L protocol audit) · `implement` (architecture reference)*
+
+> **View semantics**: this section is the **source-set ownership** view. The Part II `## System Overview` is the **runtime component-stack** view. They answer different questions and MUST NOT be applied to each other.
+
+### Layered Architecture
+
+*Purpose: each layer's ownership, contents and MUST/MUST NOT constraints · Consumers: `tasks` §4.i-2 (per-layer expect/actual tasks + constraint-validation tasks)*
+
+[Define the major layers and their responsibilities]
+
+#### Layer 1: [Name] (e.g., Platform/Presentation Layer)
+**Responsibilities**:
+- [What this layer handles]
+- [Key concerns]
+
+**Contains**: [Specific components]
+
+**Constraints**:
+- ✅ [Must/Must not constraints]
+
+#### Layer 2: [Name] (e.g., Business/Domain Layer)
+**Responsibilities**: [As above]
+
+**Contains**: [As above]
+
+**Constraints**: [As above]
+
+### Component Interaction
+
+*Purpose: the component interaction patterns and their constraints · Consumers: `tasks` §4.i-3 (per-pattern mechanism tasks + constraint-validation tasks)*
+
+[Define how major components interact]
+
+#### [Interaction Pattern] (e.g., Plugin → Core)
+```
+[Flow diagram or sequence description]
+```
+
+**Key Interaction**: [Description of the interaction pattern]
+
+**Constraints**:
+- ✅ [Must/Must not constraints]
+
+### Architecture Patterns
+
+*Purpose: the architecture patterns and what each provides · Consumers: `tasks` §4.i-1 (per-pattern component tasks)*
+
+[CRITICAL: Keep patterns concise - NO detailed Problem/Solution/Trade-offs. Those belong in research.md]
+
+#### Pattern 1: [Pattern Name]
+**Description**: [Brief description of the pattern]
+
+**Key Points**:
+- [What this pattern provides]
+- [How it's used in the architecture]
+
+**See**: research.md Section [X] for detailed analysis
+
+#### Pattern 2: [Pattern Name]
+**Description**: [Brief description]
+
+**Key Points**:
+- [What this pattern provides]
+- [How it's used]
+
+**See**: research.md Section [Y] for detailed analysis
+
+### Critical Constraints
+
+*Purpose: the quantified architecture-level constraints and their impact · Consumers: `tasks` §4.i-4 (per-constraint `[Quality]` validation tasks)*
+
+[Define architecture-level constraints that affect design]
+
+#### Constraint 1: [Name]
+**Requirement**: [Specific constraint with metrics]
+
+**Architecture Impact**: [How this constraint shapes the architecture]
+
+### Shared/Platform Boundary Declaration [only when the constitution carries a shared-code / multiplatform / core-logic principle]
+
+*Purpose: make the code-ownership boundary a checkable product — a layering diagram names layers but not the source set each layer OWNS · Consumers: `analyze` Pass M1–M4 (audits this table against the build's source-set registration)*
+
+[State, per constitutional principle, which categories of code MUST live in the shared source set and which belong to platform-specific sets. This table is what makes the boundary auditable: a scope claimed without a corpus set or a path cannot be checked against the build.]
+
+| Planned home | Constitutional basis | Category | Owning layer | Corpus set (mandatory shared set; platform sets that may extend it) | Path pattern |
+|--------------|---------------------|----------|--------------|---------------------------------------------------------------------|--------------|
+| [Name] | Principle [N] | protocol / business logic / data model / platform abstraction | shared / platform-specific | `commonMain`; platform sets: [list] | `core/src/commonMain/...` |
+
+**Dependency boundary the shared layer MUST honour**: [What the shared layer must not depend on — e.g. a protocol layer must not depend on a transport-layer object such as a live socket, connection, or session holder. A handler taking one cannot be constructed without a real network, which forces every verification end-to-end.]
+
+**Platform abstractions required**: [Capabilities the shared layer consumes from the platform — compression, image codec, file system, crypto — each declared as an expect/actual pair: declaration in the corpus set, implementations in the platform sets.]
+
+### Shared-Layer Relocation Design [only when the boundary declaration and the build disagree]
+
+*Purpose: turn the boundary declaration above into an executable migration design — the declaration states where code MUST live; this states what to move, in what order, and what depends on it · Consumers: `analyze` (Pass M boundary audit) · `tasks` (the dispatch breakdown → `[Quality]` tasks)*
+
+> **When this section is needed**: the declaration is the *intent*; a Pass M audit compares it against the build's actual source-set registration. When they disagree — shared-mandated code sitting in a platform-only source set, a handler whose construction requires a live transport object, a platform dialect imported into a shared file — the declaration alone says nothing about **how to get from here to there**. That gap is what this section fills. No disagreement → omit the section.
+
+**Design decisions the declaration does not cover** — record them here as explicit rulings, each with its rejected alternative:
+- **Dependency shape**: what a shared-layer component MUST NOT take as a construction dependency (e.g. a protocol handler must not take a live socket / connection / session holder — a handler that does cannot be constructed without a real network, which forces every verification end-to-end).
+- **Platform abstractions**: the capabilities the shared layer consumes, each as an expect/actual pair.
+
+**Migration plan**: the ordered steps, each stating what moves, from where to where, what depends on it, and how the move is verified.
+
+**Rulings**: decisions taken along the way — a mechanism correction, a sunset condition, a dispatch resolution. Each records: what was decided · what was rejected · why · and the evidence.
+
+**Dispatch breakdown**: which work items this design produces, for `/specpro-tasks` to turn into tasks. ⚠️ **The items here are NOT task IDs** — do not invent an ID prefix; `/specpro-tasks` assigns `T-nnn`. These items carry no FR in the usual sense (they are design-level work), so the FR-driven generation path does not apply to them.
+
+### Protocol Codec Design Artifacts [only when the Activation Gate is ACTIVE or ACTIVE-WITH-GAPS]
+
+*Purpose: field/branch-level protocol spec + the activation verdict record — the anchor set the test matrix and the coverage audit are built from · Consumers: `tasks` (Protocol Codec Module Rules: each GAP row → explicit task or explicit deferral · each protocol point → the four-part matrix) · `implement` (reads the §6.4 verdict) · `analyze` (Pass L3 per-point coverage audit · Pass L6 verdict-and-anchor presence)*
+
+**Verdict record (§6.4)**:
+
+| Stage | Verdict | Trigger | Evidence | Artifacts / Gaps |
+|-------|---------|---------|----------|------------------|
+| [stage] | [ACTIVE / ACTIVE-WITH-GAPS / NOT-ACTIVE] | [T1..T5] | [code anchor + FR] | [inventory · anchors L1/L2/L3 · gaps] |
+
+#### Protocol-Point Inventory — field/branch-level enumeration (§1)
+
+| Protocol point | Semantics | Branches / boundaries | Anchor source | Coverage method |
+|----------------|-----------|----------------------|---------------|-----------------|
+| [point] | [what it means] | [branch table] | [L1/L2/L3 + version] | [matrix cases / property tests / incremental-context cases / environment annotations] |
+
+> **One row per protocol point — granularity is the branch, not the message type.**
+> **The last column states the coverage METHOD this point requires** (the testing *means* suited to its shape) — a design specification, fixed when the row is written. It is **NOT** a coverage status: which points are covered *right now* is a downstream fact (the actual test assets) and MUST NOT be recorded here — an upstream status has no way to stay current and downstream consumers would act on a stale value. **Unreachable anchor sources ARE recorded here**, as a GAP — that is a plan-layer fact.
+
+#### Golden-Bytes Strategy — three-layer cross-anchoring (§2)
+
+[L1 specification (structure) → L2 reference-implementation source (bit-level semantics) → L3 captured stream (final arbitration). Every anchor records its source layer and protocol version; when layers conflict, L3 wins and the corrected understanding is written back. A source that cannot be reached is a GAP (§6.3) — never an invented byte sequence.]
+
+#### Test Matrix — codec-layer test infrastructure (§3)
+
+*Purpose: the design decisions behind the systematic codec test matrix — the four-part shape, its admissibility rule, and where it lands · Consumers: `tasks` (Protocol Codec Module Rules — each protocol point maps to this matrix)*
+
+**The four parts** (guide §3):
+1. **Decode matrix** — message/tile type × full-frame vs incremental context × parameters; assert byte-by-byte or pixel-by-pixel.
+2. **Encode reverse matrix** — `encoder(pixels) → bytes` against the golden anchor, byte by byte.
+3. **Shared golden-bytes fixture** — all anchors constructed in one place, shared by the encoder and decoder matrices so the two directions lock each other.
+4. **Property-test extension** — randomized content/length/colour count, **fixed seed**, and on failure the **parameters that reproduce it**.
+
+**Error paths are part of the matrix** — truncated stream, invalid control byte, over-long run, out-of-range index: each MUST have a decided expected behaviour (reject vs tolerate). "Unspecified" is the shape of the next latent defect.
+
+**Admissibility rule for anything promoted into the shared fixture** ⚠️: every anchor MUST first pass the three-layer check of §2 — it states its source layer (L1 specification / L2 reference implementation / L3 captured stream) and the protocol version, or it is recorded as a GAP (§6.3). **A constructor whose semantics were derived from the behaviour of the implementation under test MUST NOT be promoted**: generalising it copies the same misreading into both the encoder and the decoder side, so every assertion passes by construction (the self-confirming loop, §3.1).
+
+**Why this subsection exists**: two byte-count defects in one project stayed latent for months precisely because no systematic matrix covered their tile-type × context × bpp combination — static full-frame tests naturally skip low-frequency paths.
+
+#### Stream-Semantics Comparison — multi-encoder stream semantics (MANDATORY when one client speaks several encoders)
+
+[Continuous single stream vs per-message independent stream. Its purpose is to stop a fix's lesson from being carried across codecs whose semantics are opposite.]
+
+## Project Structure
+
+*Purpose: the repository-wide module layout — which kind of code lives in which module, so downstream task Locations can be grounded · Consumers: `tasks` (§4.j-4 Location grounding: the Location MUST point at the project's real test source set) · `implement` (§7.a)*
+
+> **Granularity**: to the **directory and path-pattern** level. **MUST NOT enumerate individual file names** — file names are an implementation choice.
+> **Single authority**: the shared/platform boundary lives in `### Shared/Platform Boundary Declaration` (the only authority — audited by Pass M). **This section records repository module layout only** and MUST NOT restate the boundary.
+> **Currency**: this is the **point-in-time placement convention**; once implementation lands, the authoritative placement is the **build config and the actual repository**. Downstream Location grounding MUST check build config and existing sibling files first.
+
+
+### Source Code (repository root)
+
+*Purpose: repository module layout — which kind of code lives in which module · Consumers: `tasks` §4.j-4 (Location grounding) · `implement` §7.a*
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+
+# [REMOVE IF UNUSED] Option 4: Separated test modules (when test types need independent CI execution)
+# Each tests/<type>-test/ is an independent build module registered in the workspace manifest.
+# The tests/ parent build script holds shared test config (framework, logging, coverage)
+# and provides a merged coverage report task.
+tests/
+├── unit-test/              # fast, mock-based, run on every commit
+├── contract-test/          # API contract verification, run on every PR
+├── integration-test/       # component integration using mocks, CI-friendly (<30s per suite)
+└── e2e-test/               # real external systems, may require containers, nightly runs
+
+# Multi-target expansion of Option 4:
+core/                        # multi-target plugin module → per-target source sets
+└── src/
+    ├── commonMain/kotlin/   # shared code
+    ├── commonTest/kotlin/   # shared tests     (multi-target plugin ONLY)
+    └── jvmTest/kotlin/      # one target's tests (multi-target plugin ONLY)
+
+tests/                       # test modules use a plain single-target plugin → standard source sets
+├── unit-test/src/test/kotlin/         # ✅ src/test/kotlin (NOT src/jvmTest/kotlin —
+│                                      #    that source set only exists under the
+│                                      #    multi-target plugin; reusing it here →
+│                                      #    NO-SOURCE or build error)
+├── contract-test/src/test/kotlin/
+├── integration-test/src/test/kotlin/
+└── e2e-test/src/test/kotlin/
+```
+
+<!--
+  ⚠️ Test directory rules (from real build failures):
+  1. Follow the build system's OWN standard source directory for each module's build type
+     (do NOT copy source-set names from sibling modules built with a different plugin type;
+     e.g., KMP modules use src/jvmTest/kotlin, plain JVM modules use src/test/kotlin)
+  2. Register every test module in the workspace manifest (e.g., settings.gradle.kts
+     include(":tests:integration-test")), or it is invisible to the build
+  3. Do not re-declare build plugin versions inside submodules
+     (e.g., kotlin("jvm") WITHOUT version — root already declares it)
+  4. Do not mix test framework adapters of different engine generations in one module
+     (e.g., kotlin-test-junit + kotlin-test-junit5 together → capability conflict)
+-->
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+---