specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/templates/protocol-golden-bytes-guide.md

@@ -0,0 +1,195 @@
+# Protocol Golden Bytes Guide
+
+**Purpose**: Shared reference for the protocol codec module rules used across specpro workflows — protocol-point inventory, golden-bytes spec anchoring, and verification-method semantic review.
+
+**Applies to**: modules that implement a wire format (encode/decode), parse protocol messages, or interoperate with a protocol peer. Non-protocol modules are unaffected by this guide.
+
+---
+
+## 1. Protocol Point Inventory — field- and branch-level enumeration
+
+Protocol-point granularity MUST drill down to **fields and branches**, not stop at message types. Message-level tests can pass while the defect sits in one parameter branch.
+
+Inventory format (one row per protocol point):
+
+| Protocol point | Semantics | Branches / boundaries | Anchor source | Test coverage |
+|----------------|-----------|----------------------|---------------|---------------|
+| Payload byte count | How many stream bytes a payload occupies | Parameter-dependent branch table (bit depth × pixel format, etc.) | Reference implementation + captured stream | Matrix cases ×N |
+| Run-length extension chain | Semantics of a multi-byte continuation chain | Per-byte accumulation vs continuation marker (differs per protocol) | Specification + observed implementation behaviour | Property tests |
+| ⤷ encoding of this row | Described by **byte-level example, never prose** — "skip the marker byte" and "accumulate the marker value" describe **different** streams | — | — | — |
+| Control-byte bit semantics | Bit allocation for flag / index / palette size | Top-bit dispatch; index width varies with palette size | Specification | Matrix cases |
+| Stream lifecycle | Continuous single stream vs per-message independent stream | Decoder reuse across rectangles / frames | Specification + reference implementation | Incremental-context cases |
+| Peer diversity | Differences between peer implementations | Optional fields present or absent; compile-time options; environment-dependent behaviours | Measured inventory (guessing forbidden) | Environment annotations |
+
+> **What the `Test coverage` column means — read this before filling it.** It states the **coverage method** the row requires: the testing *means* suited to that protocol point's shape (matrix cases for bit packing, property tests for extension chains, incremental-context cases for stream lifecycle, environment annotations for peer divergences). It is a **design specification**, fixed when the row is written — it does **not** change as tests are added.
+>
+> **What it is NOT — two things that look like coverage and belong elsewhere:**
+> - **Coverage status** (which points are covered *right now*) belongs to the **test matrix** (`specs/test-tasks.md`), derived by scanning the **actual** test assets. An upstream stage MUST NOT record it here: its source of truth is downstream, so the upstream stage would have no way to keep it current — a status written upstream is stale the moment the next test is added, and downstream consumers would act on the stale value.
+> - **Anchor reachability** (whether this row's anchor source could be reached) **is** a plan-layer fact and **does** belong here — an unreachable anchor is recorded as a **GAP** (§6.3), because only the stage that did the anchoring knows whether the source was reachable.
+>
+> Writing a ✅/⚠️/❌ status into this column is the failure this note prevents: it mixes a downstream fact into an upstream artifact, producing a snapshot that no one can maintain.
+
+**Byte-level example — an extension chain (run-length encoding, run length = value + 1)**:
+
+```
+run of 300 px  →  0xFF 0x2C      ... 1 + 255, then + 45      →  256 + 44 = 300
+run of 511 px  →  0xFF 0xFE      ... 1 + 255, then + 255     →  256 + 255 = 511
+run of 512 px  →  0xFF 0xFF 0x00 ... 1 + 255, then + 256     →  256 + 256 = 512
+```
+
+Two readings of the marker that produce **different streams**:
+
+- **accumulate** (correct): each `0xFF` adds 255/256 and the chain continues while the marker repeats.
+- **skip** (wrong): `0xFF` is a no-op that is skipped, and the next byte is the total. The run reads 0 for the third example and the stream desynchronises.
+
+Neither reading is derivable from the phrase "255 extension chain" — the inventory row MUST carry the example, not the phrase. A run whose length lands exactly on the marker boundary (511, 512) is the discriminating case and MUST be in the matrix.
+
+**Rule**: For protocol modules the inventory MUST be produced in the design section of `plan.md`, and every point MUST be mapped to test coverage in the matrix tasks of `tasks.md`. That mapping is the input for the coverage audit (§4, L3).
+
+---
+
+## 2. Golden Bytes — three-layer cross-anchoring
+
+**Golden bytes** = a manually derived, **known-correct byte sequence**, used as a two-way spec anchor: the encoder's output must equal it, and the decoder must accept it. Every anchor MUST be annotated by source layer.
+
+| Layer | Source | What it anchors | Known limitation |
+|-------|--------|-----------------|------------------|
+| **L1** Specification | RFC / protocol extension documents | Top-level structure, field order | Frequently omits bit-level detail of sub-encodings |
+| **L2** Reference implementation | Source of an independent implementation | Bit-level semantics | Behaviour specific to that implementation version |
+| **L3** Captured stream | Wire bytes captured from a real peer | Final arbitration (derived spec vs actual output) | Environment-dependent |
+
+**Rules**:
+
+- Every anchor MUST record **both** its source layer **and the protocol / peer version it was derived from**. An anchor without a version is not usable against a second version of the same protocol.
+- When the three layers conflict, L3 (measured) wins; write the corrected understanding back into the L1/L2 notes.
+- **Forbidden**: using the **output of the implementation under test** as a spec anchor. That is a self-confirming loop — the implementation's own bug is mirrored back as "correct".
+- For continuous-stream formats, segmented verification MUST use a **reuse-style decode path** (feed each segment into a persistent decoder). Reporting `incomplete` from a one-shot full-buffer decode is a **normal artefact** of a continuous stream, not defect evidence. The verification method must match the stream semantics **before** any defect conclusion is drawn.
+
+---
+
+## 3. Test Matrix — the standard four-part shape for codec modules
+
+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`, compared against the golden anchor byte by byte. Catches ordering and formatting regressions.
+3. **Shared golden-bytes fixture**: all anchors are constructed in one place and shared by the encoder and decoder matrices, so the two directions lock each other.
+4. **Property-test extension**: randomized content / length / combinations, with a fixed seed and a failure output that reproduces the failing parameters (§3.2). Covers what hand-written matrices miss — extension chains, cross-tile boundaries, non-divisible sizes.
+
+**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 not an answer; it is the shape of the next latent defect. This item is **MUST**, not optional: an error path with no decided behaviour is an untested branch that merely has not been reached yet.
+
+### 3.1 Two sets of samples, both anchored
+
+The decoder set and the encoder set are separate deliverables and **both** are anchored by §2:
+
+- **Decoder samples**: bytes → pixels. The golden bytes are the anchor; assert the decoded pixels against the recorded expectation.
+- **Encoder samples**: pixels → bytes. The anchor is the **expected byte stream**, and it comes from the same three layers as any other anchor.
+
+The frequent mistake sits in the second set: the encoder's expectation gets filled in with **the implementation's own output**, or with a byte stream produced by a sibling component of the same implementation. That is the §2 self-confirming loop wearing a different hat — the test compares the implementation to itself, and every assertion passes by construction.
+
+- A round-trip test (`encode → decode → compare pixels`) is a **regression guard, not a consistency proof**. Encoder and decoder are two faces of one implementation: they can share a mistaken reading of the protocol and still round-trip perfectly. Round-trip MUST NOT be counted as coverage for a protocol point that has no anchored byte-level case.
+
+### 3.2 Property tests carry their reproduction parameters
+
+Randomised content / length / colour count / sub-encoding selection, with:
+
+- a **fixed seed** recorded alongside the test;
+- on failure, output of the **parameters that reproduce it** — seed, dimensions, tile content descriptor, sub-encoding.
+
+Without the second item a failure is not attributable, and an unattributable failure in a randomised suite gets re-run until it passes. That is how a randomised suite silently stops reporting defects.
+
+A property test is also the cheapest home for the cases a hand-written matrix is tempted to skip — extension chains, cross-tile boundaries, sizes that do not divide evenly. When the matrix sample table "avoids" a protocol point because the bytes are awkward to write by hand, that point belongs in the property suite, not in the gap.
+
+**Implementation notes**:
+
+- **Decide the verification path — and therefore the test host — before writing a single case.** A table-driven matrix hosted end-to-end (real socket, real handshake, real message loop) inherits timing coupling that has nothing to do with the protocol: connect races, consume-window competition, timeout tuning under load. The symptom is a suite that alternates PASS/FAIL across runs with no code change, which destroys its value as a regression guard because a failure no longer means anything. Feed the codec layer **directly** first — no network, no handshake, no threads, no timeouts — so the matrix measures protocol behaviour and nothing else. End-to-end and real-peer cases belong in the outer layers (see **Layering** above), doing conformance spot-checks.
+- A mock peer's consume loop MUST **block until the target message arrives**. A silent-exit window is unreliable under load: when the client's message is slow to arrive the loop exits early, producing a **zero-frame artefact** that looks like a real defect.
+- Teardown between tests MUST leave no server / client / thread residue — a lingering socket poisons later cases.
+- For event-driven protocols (request → ack + asynchronous event), mind the sync/async semantics: an ack is not the event.
+
+---
+
+## 4. Lateral Audit Rules — criteria for `analyze` Pass L
+
+- **L1 — Same-semantics branch scan**: after fixing a byte-counting / packing / stream-semantics defect in one function, scan sibling functions in the same family for the same-shaped branch. Missing one leaves the defect latent. General shape of the failure: a family carries N same-semantics branches, the fix touches N−1.
+- **L2 — Verification-method semantic audit**: does the verification technique match the semantics of the stream under test? An `incomplete` / `truncated` verdict MUST first rule out a method-semantics mismatch before it is treated as defect evidence.
+- **L3 — Protocol-point coverage audit**: check the protocol-point inventory (§1) point by point against test coverage. A low-frequency path (incremental small payloads, extension chains, non-divisible sizes) with no coverage is a finding.
+- **L4 — Anchor-source audit**: every golden byte and expected test value MUST carry its source layer (§2). Unlabelled, or sourced from the implementation under test, is a finding.
+- **L5 — Peer-behaviour assertion audit**: every expectation that asserts how a peer behaves MUST trace to a row in the **Peer Diversity Registry** (§1, last row) — the closed set of *measured* peer behaviours, held in `specs/test-tasks.md`. An assertion with no registered row is a finding: unmeasured peer behaviour MUST NOT be frozen into an expectation. "Not in the registry" and "not measured" mean the same thing, which is why the registry must stay closed and authoritative rather than being a free-form appendix.
+
+---
+
+**Layering**: items 1–4 are in-memory, network-free, and MUST all pass. Real-peer tests (a real server, a real capture) sit in the integration / E2E layers and are **conformance spot-checks** — they confirm that the mock-layer protocol model matches the real world. They are not the place to find byte-level defects: a black-box peer shows a wrong picture, not a wrong byte, and the defect being hunted lives at a byte offset the black box cannot display.
+
+## 5. Sample Management — anchors are versioned assets
+
+- **Every sample row carries its source layer (§2) and the protocol / peer version it was derived from.** An anchor with no version is unusable against the next version of the same protocol.
+- **Sample files (binary or hex text) are version-controlled with the code.** A sample that lives only in a developer's scratch directory is not a regression guard.
+- **Every golden case traces back to a requirement ID** (FR / US / protocol-point row). Without that link the coverage audit (§4, L3) and the matrix mapping (§3 items 1–4) have nothing to walk — they can only confirm that cases exist, not that the required points are covered.
+- **The inventory is a living artifact.** A protocol point discovered mid-execution is written back to the inventory, and the sample table is extended in the same change; otherwise the matrix silently falls behind the protocol model. A point that has no coverage yet is **kept as an empty row** — an empty cell is the audit's input, and deleting the row is how coverage gaps become invisible.
+
+## 6. Activation Gate — deciding whether this module is in scope
+
+Every workflow that carries protocol rules activates **conditionally**. The condition is the weak link: judged afresh by each workflow, in prose, it drifts — one stage decides "protocol module", another decides "not really", and the rules quietly stop applying. This section replaces prose judgement with a **decidable verdict that is itself an artifact**.
+
+**Rule — activation is a product, not a recollection.** A stage that could plausibly be in scope MUST emit one of two things:
+
+- the protocol artifacts required by that stage (§1 inventory, §2 anchors, §3 matrix, §5 samples), **or**
+- an explicit **not-active** verdict with its trigger evidence.
+
+Producing neither is not a third option; it is the failure this gate exists to catch.
+
+### 6.1 Triggers — mechanical, not interpretive
+
+The gate opens when **any** trigger is observable in the artifacts the stage reads:
+
+| # | Trigger | Observable at |
+|---|---------|---------------|
+| T1 | A requirement's text contains a byte-level protocol anchor — message layout, field widths, control-byte semantics, packing order, encoding identifiers | FR text |
+| T2 | A requirement names an external protocol / wire format / extension document | FR text |
+| T3 | The design encodes or decodes a byte stream (serialiser, parser, codec, tile/message framing) | design section / source tree |
+| T4 | The design interoperates with a peer process or device over a wire format | design / contract |
+| T5 | A test or mock emits or asserts on raw bytes | test tasks / test source |
+
+A single trigger is sufficient. "Partially protocol" is not a category — a requirement that touches one wire field is in scope for that field.
+
+**Do not infer the gate from the presence of a network, a socket, or a client/server split.** Those are transport concerns; a module can be network-facing and carry no wire format, and it can be wire-format-bearing with no network at all. Trigger T3/T5 are about bytes, not about I/O.
+
+### 6.2 Verdicts — three states, all recorded
+
+| Verdict | Meaning | What this stage MUST output |
+|---------|---------|------------------------------|
+| **ACTIVE** | ≥1 trigger present, required sources reachable | The full artifact set for the stage |
+| **ACTIVE-WITH-GAPS** | ≥1 trigger present, but a required anchor source is unreachable | The artifact set, with every unreachable item recorded as **GAP** (§6.3) |
+| **NOT-ACTIVE** | No trigger present | A one-line verdict with the trigger scan result |
+
+**ACTIVE-WITH-GAPS is a first-class outcome, not a failure.** It records reality. What is forbidden is presenting a gap as covered — or filling it with plausible-looking content.
+
+**Propagation**: downstream stages **consume** the upstream verdict; they do not re-judge it. If a later stage finds a trigger the earlier stage missed, it does not silently override — it records the discrepancy, which is a finding for the coverage audit (§4).
+
+### 6.3 GAP — how to state an unreachable anchor
+
+An unreachable anchor is recorded, never invented:
+
+| Column | Content |
+|--------|---------|
+| Protocol point | The row from §1 |
+| Missing layer | Which of L1 / L2 / L3 cannot be reached |
+| Why | e.g. "L1 document does not specify sub-encoding bit layout" |
+| Acquisition path | What would provide it — reference source at a named version, a capture from a named peer |
+
+**Forbidden**: writing a byte sequence that was not derived from a named source layer, annotated as if it were. A fabricated anchor passes every format check, enters the fixture, and silently corrupts both directions of the matrix — this is §2's self-confirming loop in its most durable form, because the fabricated value then outlives the session that produced it.
+
+### 6.4 Verdict record
+
+Wherever this guide is consumed, the verdict is written down in this shape:
+
+| Stage | Verdict | Trigger | Evidence | Artifacts / Gaps |
+|-------|---------|---------|----------|------------------|
+| plan | ACTIVE | T3, T1 | `XxxCodec.decodeRect` dispatch; FR-012 | inventory §1 · anchors: L1 ✔ L2 ✔ L3 GAP (no capture) |
+
+The row is what the coverage audit (§4) reads. A stage with protocol rules and no verdict row is a finding regardless of whether the artifacts happen to exist.
+
+## 7. Structural Defences — implementation side
+
+- **Single source of truth for same-semantics branches.** Byte-length and packing semantics MUST NOT be duplicated across multiple functions in a when/switch family — converge them into one helper.
+- **No per-tile or per-message state in decoder member variables.** It leaks across instances. State that genuinely must be shared between callers belongs in a host-side anchor, not inside the decoder.
+- **Do not transfer a fix's lesson to another encoder by default.** Stream semantics may be opposite — a continuous single stream in one codec, an independent per-rectangle stream in another. Verify before generalizing.

specpro_cli/assets/templates/requirements-template.md

@@ -0,0 +1,356 @@
+# Specification Quality Checklist: [FEATURE NAME]
+
+**Purpose**: Validate `spec.md`: must contain only functional specifications; implementation details are not allowed.
+**Created**: [DATE]
+**Spec Version**: [VERSION]
+**Validation Scope**: [Full | Incremental]
+**QC Command**: /specpro-qc
+
+> ⚠️ **This template defines the CURRENT run's outcome and nothing else.** The produced
+> file is replaced wholesale on every invocation, so **nothing may be accumulated in it**
+> and no cross-run record may be kept there — anything this template cannot produce is
+> deleted by the next run, silently. Cross-run records belong in an artifact that is not
+> rebuilt (see `specs/audit/`).
+
+---
+
+## Overall Status
+
+> ⚠️ **`/specpro-qc` OVERWRITES all four values below on every run** (`T225` / `ISS-193`) — the
+> three bracketed ones **and** `**Total Items**`. So on a *produced* checklist these are
+> numbers, and they are **re-derived from the per-item rows**, never copied from the counters.
+> ⇒ **The literal `11` on this line is the AUTHORING-TIME criterion count** — it is what a
+> reader of the *template* (e.g. `/specpro-tasks` §3.e, which points here for the count) sees.
+> **Adding or retiring a criterion MUST update it in the same round**; a template that says 11
+> while carrying 12 criteria would hand that reader a count nothing computes — which is the
+> shape this whole block was fixed to remove.
+
+**Status**: [PASS | BLOCK]
+**Total Items**: 11
+**Passed**: [X]
+**Failed**: [Y]
+
+**If BLOCK**: Cannot proceed to plan/tasks/implement until all items pass.
+
+### 条目状态取值 ⚠️ [四个命令的门禁读此字段]
+
+条目行形如 `- [ ] **Status**: <取值>`。**门禁按此处的「取值」判定完成度，不按复选框**——复选框与「跳过」在字面上完全同形（模板即 `- [ ]`），只看它会把诚实跳过读成未完成。
+
+**取值必须是该字段的全部内容**——任何解释写在**下一行**，不要缀在取值之后：
+
+```markdown
+- [ ] **Status**: ⊘ Skipped
+  （本项对本项目不适用，理由：……）        ← 解释在下一行，不参与判定
+```
+
+> **为什么要求取值独占该行**：若允许取值后跟散文，判定就只能退化为"取值是否出现"——那么 `**Status**: 未做，别当成 x` 这类文本里出现的 `x` 会被读成通过。**判定要有牙，取值就不能有歧义。**
+
+| 取值 | 含义 | 门禁 |
+|---|---|---|
+| `x` | 通过 | 不阻塞 |
+| `⊘ Skipped` | **诚实跳过**——按检查定义无可推导来源、或判据对本项目不适用；**不计通过也不计失败** | **不阻塞** |
+| `✗ Failed` | 不通过 | **阻塞** |
+| 空白，或此表之外的取值 | **未完成** | **阻塞** |
+
+> **为什么单列一档「跳过」**：此前它写作 `[ ]` 加自由文本，与「未做」无法区分，四个命令的门禁因此把**诚实跳过**读成**未完成**并硬阻塞（工具缺陷 #10）。**跳过是一个诚实的结论，不是一笔欠账**——把两者混为一谈，等于诱导执行方用假通过去绕过门禁。
+
+---
+
+## P0: Content Quality (Blocking)
+
+### CQ001: No implementation details
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated keyword search
+
+**Fail Keywords**: React, Vue, Angular, SQL, PostgreSQL, MongoDB, MySQL, Redis, REST, GraphQL, HTTP, TCP, UDP, async/await, await, coroutine, class, function, def, public, private, interface, abstract, extends, implements
+
+**Result**: [Zero / N] implementation details found
+
+**Action**: [Auto-fix: Remove implementation details OR convert to functional description]
+
+**Examples**:
+  ❌ "System uses React for UI rendering"
+  ✅ "System provides responsive web interface"
+
+---
+
+<!-- ⚠️ **One Content-Quality criterion was RETIRED here** (2026-09-19, `T197`; the item
+     count went 12 → 11). Its subject was *technical performance metrics in spec.md*, and
+     its premise was false: **a performance metric is a REQUIREMENT, not an implementation
+     detail** — "how you achieve it" is the implementation detail, and that is the two
+     criteria around this comment's territory. It forbade the very input the downstream
+     chain reads (plan's Performance Goals, contracts' Performance Requirements, analyze's
+     Pass H, test-plan's `Performance:` fields), so a spec carrying a legitimate target
+     could never pass QC. It was **not** re-scoped: a narrower version would have
+     duplicated the criterion below, which already owns "requirements are functional,
+     not technical".
+     ⚠️ The retired criterion is NOT named or quoted here — a value written into prose is
+     indistinguishable from a current one to a mechanical reader (the Change Summary note
+     above states the rule). Its trace is git history, not this comment. -->
+
+### CQ003: Requirements are functional, not technical
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Semi-automated
+
+**Check**: Do FRs describe WHAT the system does, not HOW?
+
+**Result**: [All / Some] FRs are functional
+
+**Action**: [Add to clarifications.md if unclear]
+
+**Examples**:
+  ✅ "System MUST support remote desktop viewing" (functional)
+  ✅ "System MUST provide plugin architecture" (functional)
+  ❌ "System MUST use async I/O for network operations" (technical - HOW)
+  ❌ "System MUST implement the wire protocol using coroutines" (technical - HOW)
+
+⚠️ **What this criterion owns, and what `Semi-automated` therefore means here** (`T201`,
+2026-09-19): **a numeric target is a requirement; naming the METHOD that attains it is the
+implementation detail.** So `System MUST use async I/O to reach 60 FPS` fails this
+criterion — not because of the number, but because of the method. The criterion previously
+matched **none** of its frames on that sentence, and no other criterion did either, so the
+shape had no checker at all.
+
+⚠️ **Its detector is a partial one, and that is stated rather than implied.** The frames are
+**enumerations**, and an enumeration is narrower than the ways the shape gets written. The
+method-bound frame is constrained by **shape** (a method carries a slash — `async I/O`,
+`HTTP/2`) rather than by a list of outcome verbs, precisely because a verb list is the
+narrower-and-pays-for-it shape this repository has already rejected. A method spelled
+without a slash ("a thread pool") is **not** matched.
+
+⇒ **A `x` here means "nothing in the covered shapes fired", never "no implementation detail
+exists".** The uncovered remainder is **human review** — that is what `Semi-automated`
+declares, and reading a pass as clean is reading it as more than it is (`FR-036`: 声称通过
+而基线未覆盖，不构成通过).
+
+---
+
+## P0: Completeness (Blocking)
+
+### CP001: All mandatory sections completed
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated check
+
+**Required Sections** — the artifacts this criterion enforces carry the *same* set, written
+the way the spec actually spells them. ⚠️ This list used to read `Overview` / `User Scenarios
+& Testing` / **`Functional Requirements`** while `check_cp001` held a *different* array and
+`templates/spec-template.md` — the file that produces `spec.md` — defined no `Overview` at
+all. **A criterion with two sources has no source**; the template's own `*(mandatory)*`
+markers are the one that counts, and the check derives from them (FR-041):
+
+  - ✅ `## Overview`
+  - ✅ `## User Scenarios & Testing`
+  - ✅ `## Requirements` (the container; the FR entries live under `### Functional
+    Requirements` inside it — the earlier `Functional Requirements` here named the
+    sub-heading while the check looked for a top-level one, so the two never matched)
+
+**Result**: [All / Some] sections present
+
+**Action**: [Manual: Add missing sections]
+
+---
+
+### CP002: Every User Story has Acceptance Scenarios
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated check
+
+**Check**: Does each User Story have Given-When-Then scenarios?
+
+**Result**: [All / Some] US have scenarios
+
+**Missing**: [List of US without scenarios]
+
+**Action**: [Add to clarifications.md]
+
+**Example**:
+  ```markdown
+  ### US1 - [Title]
+  **Acceptance Scenarios**:
+  1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+  2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+  ```
+
+---
+
+### CP003: Acceptance Scenarios are functional (not technical)
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Semi-automated
+
+**Check**: Do scenarios verify functionality, not performance?
+
+**Fail Pattern**: Scenarios containing performance metrics like "within \d+ms", "\d+ FPS"
+
+**Result**: [All / Some] scenarios are functional
+
+**Action**: [Auto-fix: Remove performance metrics]
+
+**Examples**:
+  ✅ "Given the app is running, When user enters server address, Then connection is established"
+  ❌ "Given a remote viewing session, When screen changes, Then updates show within 200ms"
+
+---
+
+## P1: Consistency (High Priority)
+
+### CS001: User Stories are internally consistent
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated contradiction detection
+
+**Check**: Any contradictions between User Stories?
+
+**Result**: [No / Some] contradictions found
+
+**Action**: [Manual: Requires intervention]
+
+**Example Conflict**:
+  - US1: "System MUST support offline mode"
+  - US2: "System MUST require always-on connection"
+  → Contradiction detected
+
+---
+
+### CS002: Functional Requirements are internally consistent
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated contradiction detection
+
+**Check**: Any contradictions between FRs?
+
+**Result**: [No / Some] contradictions found
+
+**Action**: [Manual: Requires intervention]
+
+**Example Conflict**:
+  - FR-xxx: "System MUST store data locally"
+  - FR-xxx: "System MUST NOT use local storage"
+  → Contradiction detected
+
+---
+
+### CS003: US → FR mapping is complete
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated traceability check
+
+**Check**: Does every User Story have associated FRs?
+
+**Result**: [All / Some] US have associated FRs
+
+**Orphan US**: [List of US without FRs]
+
+**Action**: [Add to clarifications.md]
+
+---
+
+### CS004: Identifier references resolve to definitions
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated reference integrity check
+
+**Check**: Does every identifier mentioned in spec.md (FR-nnn mentions, "(per X-nnn)" attributions) resolve to a definition in this document?
+
+**Dangling References**: [List of unresolved identifiers]
+
+**Action**: [Add to clarifications.md]
+
+---
+
+## P1: Traceability (High Priority)
+
+### TR001: Constitution constraints documented
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Semi-automated (domain detection + Constitution matching)
+
+**Method**:
+  1. Identify feature domains from spec.md (network, security, protocol, etc.)
+  2. Search Constitution for matching principles
+  3. Verify FRs include Constitution requirements
+
+**Matched Domains**: [List of domains]
+**Matched Principles**: [List of Constitution principles]
+
+**Result**: [All / Some] applicable constraints documented
+
+**Missing**: [List of missing Constitution constraints]
+
+**Action**: [Add to clarifications.md]
+
+---
+
+### TR002: External dependencies identified
+
+- [ ] **Status**: [x | ⊘ Skipped | ✗ Failed]
+
+**Validation**: Automated keyword search — ⚠️ **over a labelled vocabulary only**
+
+**Check**: Are external dependencies documented?
+
+**Result**: [All / Some] dependencies documented
+
+**Missing**: [List of missing dependencies]
+
+**Action**: [Add to clarifications.md]
+
+⚠️ **The scan recognises a dependency only when the spec LABELS it** (`外部` / `第三方` /
+`external <noun>` / `third-party`). **An unlabelled functional name is not recognised** —
+including the examples above, which carry no such label. When nothing is recognised the
+criterion reports `⊘ not decidable by this scan`, **not** "no external dependencies": the two
+are different statements and only the first is true (ISS-150). ⇒ **Unlabelled names are
+covered by human review, not by this criterion** — do not read a `⊘` here as a clean result.
+
+**Examples** — ⚠️ **these MUST name the functional layer**, not the implementation stack.
+The entries here used to name a **protocol**, a **library** and a **cipher suite** — i.e.
+exactly the layer `FR-040` forbids this criterion from judging, and the opposite of where the
+source was moved. ⇒ **each was rewritten to name the outside thing, not the mechanism.**
+⚠️ **The removed values are deliberately NOT quoted here** — a value sitting in prose is
+indistinguishable from a current one to any mechanical reader, and to a human scanning the
+file it reads as present (the rule stated in `spec-template.md`'s Change Summary note).
+**A dependency is the outside thing the product talks to, not the mechanism it talks with** —
+the mechanism may be replaced without the dependency changing:
+
+  - "the payment gateway the checkout flow calls"
+  - "the identity provider users sign in through"
+  - "the object store exports are written to"
+
+**Where it is written**: the spec's `## External Dependencies` section
+(`templates/spec-template.md`), which is `*(if applicable)*` — a feature with no outside
+system simply omits it.
+
+---
+
+**Validator**: specpro-qc
+
+---
+
+<!-- End-of-file sentinel: everything above belongs to a section, and a row added
+     after the `-->` line below belongs to none — which is the condition this
+     makes visible ("position decides ownership" with no boundary marker fails
+     silently: the misfiled row still looks filed).
+
+     ⚠️ **Nothing is inserted before it any more.** Until 2026-09-19 a per-run row was
+     written here; that row is gone with the rest of the cross-run content (`FR-060`),
+     and with it the only writer that ever used this sentinel. **The sentinel itself
+     stays, and it is still correct** — it marks "the tagged content ends here", which
+     is exactly what a boundary marker is for. `plan.md` → Constraint 7 cites it as a
+     working example of one, and deleting it would invalidate that row.
+
+     NOTE: the closer of this comment is deliberately NOT alone on its line — a bare
+     `-->` line here would itself read as a second sentinel. -->
+-->