specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.analyze.md

@@ -0,0 +1,1102 @@
+---
+description: Perform comprehensive cross-artifact consistency and quality analysis with trend tracking capabilities
+writes:
+  # This command's write surface: only what it produces AS THE PRODUCER of that
+  # (artifact, unit) pair. A write this command makes on a non-producer path is a
+  # boundary violation by definition (FR-051) and MUST NOT be declared here.
+  # The full ownership map is the UNION of every command's writes: block.
+  - artifact: specs/implement_issues.md
+    unit: "each stage section ([specify]/[plan]/[tasks]/[test-plan]/[constitution]) -> appended ISS-NNN entries; the top statistics table"
+  - artifact: specs/analysis/analysis-[timestamp].md
+    unit: "whole file - one timestamped report per run (--persist only)"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — read-only over the artifacts** ⚠️ [settled 2026-09-13]:
+
+This command **never regenerates a design artifact**. It reads `spec.md` / `plan.md` / `tasks.md` / `test-tasks.md` / `contracts/**` and reports; the shared rerun rule (*detect the artifact; absent → initial, present → incremental*) applies to the commands that **write** those artifacts, not here.
+
+**Its only writes** (see Operating Constraints):
+| Write | Rule |
+|-------|------|
+| Append entries to `specs/implement_issues.md` | **Append only** — never rewrite the file. ⚠️ **Appending into another command's section is NOT a violation — it is this ledger's routing act** (`ISS-92` / `T174`): the Routing table below exists precisely to decide *which* section a finding belongs to. What is forbidden is **marking** another section's entries `[x]` — 登记即路由（不限分区）· 标记限于本分区 |
+| `specs/analysis/` results (only with `--persist`) | New timestamped artefact per run; adds, never replaces |
+
+Anything else — including "fixing" a finding it reported — belongs to the owning `--review-issues` run.
+
+> **Why a shared rule rather than per-command courtesy**: nine of the twelve non-implementation commands already had some protection, but each wrote it its own way, and three had none — not by decision, but because the discipline had no shared carrier. The rule everywhere else is: **detect the artifact; absent → initial, present → incremental; overwriting requires explicit AND re-confirmed intent.** This command's read-only posture means it never triggers the third clause.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/specpro-tasks` has successfully produced a complete `tasks.md`.
+
+## Command Options ✨ ENHANCED
+
+**Mode Selection**:
+- `--incremental` 🆕: Only analyze items whose `[specify:…]` 段是 `create`／`update`（其余按 Lifecycle 的取值跳过）。⚠️ 本节此前写的是 `SpecStatus=Draft/Modified (skip Stable)`（`T174`）—— **`Draft`／`Stable` 不在 Lifecycle 的取值表里**（那是 `create|update|delete|processed|deprecated`）⇒ 照它过滤**在本仓库的任何产物上都匹配不到**，于是「增量」与「全量」同形，而**没有任何东西会报错**。
+- `--summary` 🆕: Show condensed summary report only
+- `--detail` 🆕: Show detailed analysis report (default)
+- `--persist` 🆕: Save analysis results to specs/analysis/ for trend tracking
+
+**Examples**:
+```bash
+/specpro-analyze                    # Read-only, full analysis
+/specpro-analyze --incremental       # Only analyze changed items
+/specpro-analyze --summary           # Quick summary
+/specpro-analyze --persist           # Save for trend tracking
+```
+
+## Operating Constraints
+
+**Default Mode (READ-ONLY, with one narrow write)**: Do **not** modify the analyzed artifacts — `spec.md`, `plan.md`, `tasks.md`, `specs/contracts/**`, or any source file. Output a structured analysis report; offer an optional remediation plan (the user must explicitly approve before any follow-up editing commands are invoked).
+
+The **single exception** is Step 7 (Finding Registration), which appends entries to `specs/implement_issues.md`. That file is the loop's queue, not an analyzed artifact: a finding that is not recorded there cannot be consumed by the stage that owns the fix, and the manual transcription it would otherwise require is where findings lose their specifics. Recording what was found is analysis; changing what was found to be wrong belongs to the owning `--review-issues` run.
+
+**There is no auto-fix mode** ⚠️ [settled 2026-09-18, `ISS-141` / `T184`]: this command **reports**; it does not repair. Its write surface is the ledger and `specs/analysis/` — `spec.md` / `plan.md` / `tasks.md` are **not** among them, so "apply the fix here" was a boundary violation **by definition** (FR-051), not a matter of permission. Declaring it unavailable is therefore not a narrowing of what this command may do; it is the correction of a claim that was never true.
+>
+> ⚠️ **And the rule is not merely formal.** A finding is fixed by the command that **owns** the artifact, in that command's `--review-issues` run. A judge that repairs what it judged has spent its verdict — the repair would then be exempt from the very check that produced it (**Constitution, Principle III**; the same root cause as the test loop's rule that the test used for re-verification may not itself be edited).
+
+**Constitution Authority**: The project constitution (`specs/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/specpro-analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specpro/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+**Detection of operation mode** ✨ NEW:
+
+**Step 1a: Parse user-provided flags**:
+- Check for `--incremental` flag: Set INCREMENTAL_MODE=true
+- Check for `--summary` flag: Set SUMMARY_MODE=true
+- Check for `--persist` flag: Set PERSIST_MODE=true
+
+**Step 1b: Interactive mode selection (if no flags provided)** ✨ ENHANCED:
+
+If `$ARGUMENTS` is empty (no user flags), detect context and prompt for mode selection:
+
+```markdown
+## 📊 Analysis Mode Selection
+
+No analysis mode specified. Please choose the appropriate mode:
+
+**Context Detection**:
+- Previous analyses exist: [YES/NO]
+- Recent changes detected: [N modified items]
+- Analysis history: [N analyses available]
+
+---
+
+### Mode Options:
+
+**1. Standard Analysis** (Recommended for first-time or comprehensive check)
+- Full analysis of all artifacts
+- All 16 detection passes (A–P)
+- Detailed report with findings
+- No automatic fixes
+- Time: ~25 seconds
+- Use when: You want a complete quality check
+
+**2. Quick Summary** 🆕 (Recommended for fast status check)
+- Condensed summary report only
+- Overall quality score
+- Issue counts by severity
+- Top 3 next actions
+- Time: ~10 seconds
+- Use when: You need a quick status overview
+
+**3. Incremental Analysis** (Recommended if you have recent changes)
+- Only analyze modified items (N items changed)
+- 60-80% faster than full analysis
+- All detection passes applied to changes only
+- Time: ~5-10 seconds
+- Use when: You've made small updates since last analysis
+
+**4. Analysis with Trend Tracking** (Recommended for quality monitoring)
+- Full analysis + save results for trend tracking
+- Stores in `specs/analysis/`
+- Generates quality trend over time
+- Integrates with `/specpro-status` dashboard
+- Time: ~25 seconds
+- Use when: You want to track quality improvements over time
+
+**5. Custom Mode** (Advanced users)
+- Specify custom combination of flags
+- Examples: --incremental --summary, --persist --summary
+- Use when: You know exactly what you need
+
+---
+
+Your choice (1-6):
+```
+
+**Step 1c: Execute selected mode**:
+
+After user selection:
+
+- **Choice 1**: Set no flags (standard full analysis)
+- **Choice 2**: Set SUMMARY_MODE=true
+- **Choice 3**: Set INCREMENTAL_MODE=true
+- **Choice 4**: Set PERSIST_MODE=true
+- **Choice 5**: Ask user for custom flags, or show flag reference:
+  ```markdown
+  **Available Flags**:
+  --incremental   Only analyze modified items (60-80% faster)
+  --summary       Show condensed summary only
+  --persist       Save results for trend tracking
+
+  **Examples**:
+  /specpro-analyze --persist --summary
+  /specpro-analyze --incremental --summary
+
+  Enter your custom flags (or leave empty for standard analysis):
+  ```
+
+**Step 1d: Smart recommendation** 🆕:
+
+Before showing the mode selection, provide intelligent recommendation based on context:
+
+```markdown
+**AI Recommendation**: [Mode Name]
+
+**Reason**: [Why this mode is recommended based on current context]
+
+Examples:
+- "This is your first analysis → Standard Analysis (1)"
+- "You have 3 modified items → Incremental Analysis (3)"
+- "You have 2 prior analyses → Trend Tracking (4)"
+```
+
+**Context Detection Rules**:
+- **First-time analysis** (no `specs/analysis/` directory): Recommend Standard Analysis
+- **Recent changes**（`[specify:update]` 的条目 > 0）: Recommend Incremental Analysis
+- **Previous issues found** (last analysis has HIGH/CRITICAL): Recommend Standard Analysis — the previous findings are the subject to **re-measure**, not to repair here. ⚠️ The repair belongs to the artifact's **owning** command, in its `--review-issues` run (`ISS-141`)
+- **Multiple analyses exist** (>2 analyses in `specs/analysis/`): Recommend Trend Tracking
+- **Large specification** (>200 requirements): Recommend Summary or Incremental
+
+### 2. Load Artifacts (Progressive Disclosure) ✨ ENHANCED with Lifecycle filtering
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements (filter by SpecStatus if INCREMENTAL_MODE=true)
+- Non-Functional Requirements (filter by SpecStatus if INCREMENTAL_MODE=true)
+- User Stories (filter by SpecStatus if INCREMENTAL_MODE=true)
+- Edge Cases (if present)
+
+**Lifecycle-Aware Filtering** 🆕 (if INCREMENTAL_MODE=true):
+- Only load items whose `[specify:…]` 是 `create` 或 `update`
+- Skip everything else — ⚠️ **the skip set is the complement of the line above; do not write a second predicate for it.** This line used to read `Skip items with SpecStatus=Stable`: `Stable` is **not a value in the Lifecycle vocabulary**, so the predicate selected **nothing**, skipped nothing, and read as a working filter（`T174` 词汇族）—— and it also contradicted the line above it, which already defines the loaded set. ⚠️ **`[specify:processed]` is not the fix either**: that value has **no writer anywhere in the tree**（`ISS-220`）⇒ a predicate over it matches nothing. The set is defined by `[specify:…]` ∈ {`create`,`update`} alone.
+- Filter by `[tasks:…]`（取值同 Lifecycle 表；跳过 `processed`／`deprecated`）
+- This enables fast incremental analysis of only changed items
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Technical constraints
+
+> ⚠️ **No `Phases` entry here** (settled 2026-09-13): this list states what the audit actually extracts, and the Phases/Implementation Plan section is **human-read plan information** with no machine consumer — declaring it here told the reader the audit used something it never read. Do not re-add an entry unless a pass genuinely consumes it.
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `specs/constitution.md` for principle validation
+
+**From checklists/** (if exists) 🆕:
+- Load checklists/requirements.md for quality status
+- Load checklists/*.md for additional quality gates
+
+**From test-tasks.md (if exists)** 🆕:
+- Coverage matrix (FR × layer × task ID × status × rationale); note the status enum: `pending-impl`/`manual`/`not-applicable`/`deprecated` are planning verdicts, `not-started`/`in-progress`/`completed` are execution states
+- Test task IDs (INF/IT/CE/AE prefixes) and completion state (`[ ]`/`[x]`); `[DELETED]`-marked tasks are stale entries awaiting physical removal by test-plan
+- **Matrix Change Log + Test-plan Runs log**: the processing record — the most recent entries tell which FRs were last re-processed; used by Pass J staleness detection
+- If missing: record "test coverage matrix not built" for Pass J (recommend running `/specpro-test-plan`)
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+- **Test task mapping** 🆕: Map test tasks to implementation tasks for Test-First validation
+- **Test coverage matrix** 🆕: From specs/test-tasks.md (if present), map each FR to its coverage cells (unit / integration / component E2E / app E2E) with task IDs, status, and rationale; FRs absent from the matrix count as untracked
+
+### 4. Detection Passes (Token-Efficient Analysis) ✨ ENHANCED
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+**⚠️ The pass count MUST equal the enumeration — and here is the check** (`T147` / `ISS-52`):
+
+任何声称"N 个检测通道"的地方，其 N MUST 等于本文档 `^#### [A-Z]\. ` 的枚举条数。**可复跑**：
+
+```bash
+[ "$(grep -cE '^#### [A-Z]\. ' commands/specpro.analyze.md)" = "16" ] || echo "通道数与枚举不符"
+grep -nE 'All [0-9]+ detection|检测通道' commands/specpro.analyze.md   # 逐处核它印的数
+```
+
+⚠️ **为什么这条要写在这里**：该数此前**声称 15 而实为 14**（直到新增 Pass O 才凑巧对上）——**新增或删除一条通道时，唯一该被更新的那个数字没有任何东西比对**。⚠️ **示例自身用行首锚**（`TOOL-009`）：一个无锚的示例会被照抄，然后数进正文里提到通道的行。
+
+#### A. Duplication Detection
+
+- (MEDIUM) Identify near-duplicate requirements — consolidation improves quality but breaks nothing; never a gate-level finding
+- (MEDIUM) Mark lower-quality phrasing for consolidation — same rationale
+
+#### B. Ambiguity Detection
+
+- (MEDIUM) Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria — meaning exists but is unmeasured; `/specpro-clarify` can resolve it
+- (HIGH) Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.) — a placeholder is a requirement that cannot be executed or accepted; it fails the completeness gate, not just its polish
+
+#### C. Underspecification
+
+- (HIGH) Requirements with verbs but missing object or measurable outcome — nothing to accept against; the acceptance step has no input
+- (MEDIUM) User stories missing acceptance criteria alignment — scenarios exist downstream but drift risk is real, not certain
+- (HIGH) Tasks referencing files or components not defined in spec/plan — the task has no home; the same shape that stranded the install work when `plan.md` named no test tree
+
+#### D. Constitution Alignment
+
+- (CRITICAL) Any requirement or plan element conflicting with a MUST principle — per this command's own Constitution Authority clause: constitution conflicts are automatically CRITICAL
+- (HIGH) Missing mandated sections or quality gates from constitution — the mandated artifact is absent, so every downstream stage runs without a control it is required to have
+
+#### E. Coverage Gaps
+
+**⚠️ Two independent coverage dimensions — do NOT report one under the other's name** ⚠️:
+
+"Coverage" names two different things in this project, and they are measured against different artifacts with different owners. A number for one is NOT evidence about the other, and a run that reports only one of them will read as "coverage is fine" while the other is wide open:
+
+| Dimension | Question | Artifact measured | Planned by |
+|-----------|----------|-------------------|------------|
+| **Task coverage** | Does every FR/SR have an implementing task? | `tasks.md` — `T-nnn` references to FR IDs | `/specpro-tasks` |
+| **Test-matrix coverage** | Does every FR have a row in the coverage matrix? | `specs/test-tasks.md` — matrix rows | `/specpro-test-plan` |
+
+Report **both**, by name, as separate numbers.
+
+**Task coverage** (the original rule):
+- (HIGH) Requirements with zero associated tasks — report the **count and the FR list**, not only a total. Rationale (measured): a coverage figure of 100% once stood next to ~80 FRs with no task; untasked FRs make "complete" unfalsifiable
+- (MEDIUM) Tasks with no mapped requirement/story — work without a requirement behind it cannot be verified against anything
+- (MEDIUM) Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+**Test-matrix coverage**: covered by Pass J (matrix staleness / FRs missing from the matrix). Do not fold its numbers into this pass's, and do not let a clean matrix (e.g. "168/168 rows") stand in for task coverage — the two can differ by half the FR set. **Worked instance (2026-09-10)**: the matrix read 168/168 = 100% while task coverage was 88/168 = 52%; the run reported "zero-coverage FRs: 0" from the matrix figure and registered nothing, leaving ~80 FRs with no task and no finding. A finding here is only as good as the artifact it was measured on — name the artifact in the finding's evidence.
+
+**Legacy caveat — a Lifecycle field may be stale DATA in this project** ⚠️: a field that is constant across every item means the field was **never maintained by its owning command in this project** — it is a **data-state observation, NOT a verdict on the field's semantics or on the mechanism**.
+Worked instance: this project's `[plan:*]`/`[tasks:*]` are `processed` on all items because the spec was written wholesale (`05590ee`, 2026-01-26) **before** the task system existed — for a project that runs the workflow in order, the same fields carry real discrimination and driving the per-layer increment off them is **correct usage**. Decisive counter-evidence in the same file: `[specify:*]` **does** discriminate (171 `processed` + 8 `update`, matching the last two spec revisions) — same mechanism, same file, and the leg the mechanism actually maintained is correct.
+So: report the constancy as **stale data** (a project-level annotation), and never generalise it into a rule that the field is useless or that filtering on it is forbidden. **Do not derive task coverage from it** — coverage is a measurement (Pass E's carrier test), a different question from "which items are queued for processing".
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+**Lifecycle marker vs measured reality** 🆕 — a marker asserting a state the artifacts do not show:
+- An FR/SR marked `[tasks:processed]` (or `[plan:processed]`) with **no carrier** — see the carrier test below
+- Any Lifecycle field that is **constant across every item** — report it as **stale data in this project** (the owning command has never run against these items), **not** as a defect of the field or of the mechanism. State which leg is affected and, as counter-evidence, whether the *other* legs still discriminate (measured 2026-09-13: `[plan:*]`/`[tasks:*]` constant on 172/172 while `[specify:*]` discriminates 171/8 — so the mechanism is sound and the constancy is this project's initialisation order, not a mechanism failure)
+- Report the **count and the ID list**; a bare percentage hides whether the set is coherent
+
+**Carrier test — what counts as "this FR's work is accounted for"**: a zero-`tasks.md`-reference FR is NOT automatically a gap. Check all three routes before reporting one, and **state in the evidence which route carries it**:
+
+| Route | Carrier | Example |
+|-------|---------|---------|
+| Planned task | a `T-nnn` in `tasks.md` that references the FR | — |
+| Test-layer delivery | an `IT/CE/AE` task in `specs/test-tasks.md` whose row/annotation names the FR | FR-027 → IT-009 `[x]` + CE-002 re-verify PASS |
+| Fix-task delivery | an `FT-xxx` in `specs/fix-tasks.md` that delivered the behaviour | FR-027 → FT-020 (NewFBSize(-223) fix, real-peer driven) |
+
+An FR with **none** of the three is a genuine coverage gap; an FR carried by route 2 or 3 is a **different, narrower** finding — typically a missing *unit* layer, which is reported as such (severity MEDIUM, routed per the table in "Finding Registration"). FR-027 is the worked instance: fully carried by routes 2+3, its only real gap being the unit layer.
+
+#### G. Test-First Compliance Detection 🆕
+
+**Purpose**: Verify Constitution Article IV (Risk-Based Quality Assurance) compliance
+
+**Detection Rules**:
+- **High-Risk Module Violations** (CRITICAL):
+  * Protocol implementations without test tasks before implementation tasks
+  * Cryptography/security modules without test tasks
+  * Network transport modules without test tasks
+  * ⚠️ **PRECONDITION — read this BEFORE the ordering rule below** (`T154` / `ISS-74` ②; user ruling 2026-09-20):
+    * **The ordering criterion only applies to projects whose verification is *pre-emptive*** — i.e. a **test suite** that can genuinely be written and run **before** the implementation exists (unit/integration tests against a spec).
+    * **It does NOT apply to a project whose verification is *post-hoc*** — where the check is a **command that verifies an artifact's existence or consistency** (`diff -rq` · a `grep` reverse-lookup · a verifier script that reads the produced file). ⚠️ **A command that verifies whether an artifact exists cannot be sequenced before that artifact is produced** — so on such a project this rule is **structurally unsatisfiable**, and reporting it as CRITICAL is a **false failure that blocks the pipeline**.
+    * **How to decide** — from the project's own material, not from taste: if the `[Quality]` tasks' verification commands are of the "**re-run this check on the artifact**" form, the project is post-hoc ⇒ **do not read the ordering; report this pass as `N/A` (with that one-line reason) instead of a verdict**.
+    * ⚠️ **Measured instance (this repository)**: `FR-002` is HIGH-RISK; its verification task `T033` sits **after** the implementation tasks `T018`/`T019` — by the letter of the rule that is CRITICAL, and `/specpro-implement`'s Step 2b **blocks** on CRITICAL.
+  * Check task ordering: Test tasks should appear before or alongside implementation tasks **— subject to the precondition above**
+
+- **Medium-Risk Module Violations** (HIGH):
+  * Business logic without test tasks
+  * Data models/repositories without test tasks
+  * Platform API bindings without test tasks
+
+- **Validation**:
+  * Map each implementation task to related test tasks
+  * Check if test task appears before implementation task in tasks.md
+  * Flag high-risk modules missing test coverage
+
+**Example Detection**:
+```markdown
+- FR-xxx "Wire Protocol Handler" (High-Risk: Protocol implementation)
+  Plan.md: Protocol handler implementation
+  Tasks.md: ❌ No test tasks found before implementation task
+  Constitution: Article IV requires Test-First for high-risk modules
+  Severity: CRITICAL
+  Recommendation: Add protocol handler test tasks before implementation
+```
+
+#### H. Performance Metrics Loss Detection 🆕
+
+**Purpose**: Ensure performance requirements from spec.md are preserved in plan.md and tasks.md
+
+**Detection Rules**:
+- Extract performance metrics from spec.md NFRs (e.g., "<500ms latency", "30-60 FPS")
+- Check plan.md for performance design addressing these metrics
+- Check tasks.md for performance-related tasks (profiling, optimization, benchmarking)
+- **Severity**: HIGH if critical performance metrics missing from plan/tasks
+
+**Example Detection**:
+```markdown
+- NFR-xxx "Screen update latency < 500ms"
+  Spec.md: "<500ms end-to-end latency"
+  Plan.md: ⚠️ No performance strategy found
+  Tasks.md: ❌ No performance measurement tasks
+  Severity: HIGH
+  Recommendation: Add performance monitoring tasks to tasks.md
+```
+
+#### I. Checklist Utilization Detection 🆕
+
+**Purpose**: Verify that quality checklist findings are addressed in plan/tasks
+
+**Detection Rules**:
+- Load checklists/requirements.md if exists
+- Extract the checklist's **own** fields — `**Status**: PASS|BLOCK` · `**Passed**` · `**Failed**` · per-item `**Status**: x|⊘ Skipped|✗ Failed`. ⚠️ 本节此前写的是 `Extract ❌ FAIL and ⚠️ WARNING items`（`T174`）—— **那两个字符串没有任何生产者**，而 `⚠️ WARNING` 这一档在模板里**根本不存在**（只有三种取值）⇒ 照它提取恒为空，而空读起来像「没有失败项」。
+- For each `✗ Failed` item — ⚠️ **the set is the one the line above extracts**; `❌ FAIL`／`⚠️ WARNING` are not values this checklist can carry（`T174`）:
+  * Search plan.md for design addressing the issue
+  * Search tasks.md for tasks addressing the issue
+  * Flag if unaddressed
+
+**Example Detection**:
+```markdown
+- Checklist: "Protocol implementation test-first" (`**Status**: ✗ Failed`)
+  Constitution: Article IV requires >90% test coverage
+  Plan.md: ⚠️ No test strategy found
+  Tasks.md: ⚠️ No test tasks for protocol modules
+  Severity: CRITICAL
+  Recommendation: Add test strategy to plan.md and test tasks to tasks.md
+```
+
+#### J. Test Matrix Gap Detection 🆕
+
+**Purpose**: Verify high-level test coverage (integration / component E2E / app E2E) is planned for the FR full set via `specs/test-tasks.md`
+
+**Detection Rules**:
+- **Matrix not built** (specs/test-tasks.md missing, MEDIUM):
+  * No coverage matrix exists for any FR
+  * Recommendation: Run `/specpro-test-plan` to generate the coverage matrix and high-level test tasks
+
+- **Zero-coverage FRs** (apply ONLY to rows in execution states not-started/in-progress):
+  * FR appears in spec.md but has NO row in the coverage matrix (MEDIUM)
+  * FR has a matrix row but ALL of IT/CE/AE cells are empty/rationale-only with no task ID (HIGH if the FR belongs to a HIGH-RISK module per plan.md → CRITICAL; otherwise MEDIUM)
+  * ⚠️ Do NOT count planning-verdict rows as gaps: `pending-impl` (no implementation component — by design no tasks), `manual` (manual coverage via /specpro-manual-test), `not-applicable` (unit coverage sufficient), `deprecated` (FR deleted from spec)
+  * ⚠️ The `pending-impl` exemption applies ONLY to zero-coverage alerts within THIS Pass. Platform/feature-tier gaps *behind* a pending-impl row (e.g. the platform a full-tier FR claims has no registered build target at all) are NOT excused — Pass K surfaces them as grounding findings
+
+- **Single-layer coverage of HIGH-RISK modules** (HIGH):
+  * Protocol / cryptography / network transport modules whose FRs have only unit coverage (tasks.md) and no integration (IT) or component E2E (CE) task
+  * These modules require at least one integration-level test per Constitution Article IV risk-based quality assurance
+
+- **Cross-platform constraint anchored to a single-platform scenario** (HIGH):
+  * FR text claims "all platforms" / "cross-platform" / enumerates platforms (e.g. Android, iOS, Desktop), but its only covered cell is a scenario (AE/CE/IT) that exercises ONE platform
+  * A single-platform assembly scenario can never satisfy a multi-platform claim — the FR reads as covered while the unclaimed-in-test platforms stay invisible
+  * Recommendation: anchor the FR to a per-platform coverage set (one cell/scenario per claimed `full`-tier platform), or split the FR per platform
+
+- **Stale matrix rows**:
+  * Matrix row references tasks that no longer exist in test-tasks.md, or FR IDs that no longer exist in spec.md (LOW)
+  * **Change-log staleness** 🆕 (MEDIUM): FR has SpecStatus = create/update in spec.md, but its most recent Matrix Change Log entry predates that spec change (or the FR has no change-log entry at all beyond the initial create) — the matrix has not re-processed a changed FR; the matrix is out of sync with the spec. Recommendation: run `/specpro-test-plan` (incremental mode re-processes exactly these change-log-drifted FRs)
+  * Tasks marked `[DELETED]` still physically present: informational only (removal happens on a later test-plan pass), NOT a finding by itself
+
+**Example Detection**:
+```markdown
+- FR-xxx "Wire Protocol Handler" (High-Risk: Protocol implementation)
+  test-tasks.md: ❌ No matrix row for FR-xxx
+  Severity: HIGH
+  Recommendation: Run /specpro-test-plan to register FR-xxx in the coverage matrix
+
+- FR-xxx "Wire Protocol Handshake" (High-Risk: Protocol implementation)
+  Matrix: unit ✅ (tasks.md T-xxx), integration ❌ (no IT task), CE ❌ (no CE task)
+  Severity: HIGH - single-layer coverage for protocol module without integration test
+  Recommendation: Run /specpro-test-plan (incremental) to add IT/CE coverage
+
+- FR-xxx "Connection Profile Management"
+  spec.md: SpecStatus=update (v1.1); Matrix Change Log: no FR-xxx entry after initial create
+  Severity: MEDIUM - matrix out of sync with spec (change-log staleness)
+  Recommendation: Run /specpro-test-plan (incremental) — its change-log-driven scope re-processes FR-xxx
+```
+
+#### K. Platform Grounding Check 🆕
+
+**Purpose**: Mechanically verify that every platform the planning artifacts CLAIM is actually grounded in the build — plan claims vs. registered build targets vs. source-set reality. Closes the class of gap where claims live in documents, builds live in code, and no gate cross-checks the two (the FR-xxx/FR-yyy mobile-gap class).
+
+**Detection Steps** (mechanical; run ALL):
+
+1. **Extract claimed platforms** from plan.md Target Platform (+ any tier annotation). Per claimed platform record its tier: `full` (all features), `restricted` (basic feature set — the claim MUST cite the spec clause defining the boundary), `planned`/`deferred` (explicitly not current delivery). An unannotated claim defaults to `full`.
+
+2. **Extract grounded evidence** from the build:
+   * `settings.gradle.kts` `include(...)`: application module per platform (e.g. `:desktop-app`, `:android-app`, `:ios-app`)
+   * Per-module build scripts: registered compilation targets (`jvm()`, `androidTarget()`, `androidApplication`, `iosX64()`/`iosArm64()`/`iosSimulatorArm64()`, Kotlin/Native targets)
+   * Entry-product existence: `AndroidManifest.xml`, Xcode project / iOS app entry, desktop `main` entry
+   * Source-set census: platform source directories (`androidMain/`, `iosMain/`, ...) and whether they belong to a REGISTERED compilation target
+
+3. **Compare and report**:
+   * **Claimed `full` platform with no registered target / no app module / no entry product** (CRITICAL): the claim is invisible to every execution gate (compile, test, manual) — target registration is the precondition for any gate to see the platform at all. Matrix `pending-impl` status does NOT excuse this finding
+   * **Claimed `restricted` platform without a boundary clause** (HIGH): spec must define the restricted feature set (which FRs are in scope on that platform); task/contract text citing an unwritten constraint ("per <X> constraints" with no spec anchor) is evidence of this finding
+   * **Claimed platform neither grounded nor explicitly marked `planned`/`deferred`** (HIGH): undocumented claim — ground it, downgrade the claim, or annotate `deferred`
+   * **Orphan source sets** (HIGH): platform source files exist but belong to NO registered compilation target — dead code that silently passes every compile/test gate; any `[x]` on tasks that wrote such files is unverified
+   * **Tier coverage mismatch** (MEDIUM): FRs listed in a restricted-tier boundary clause but absent from the matrix (or vice versa)
+
+**Example Detection**:
+```markdown
+- plan.md Target Platform: "Android 5.0+ (full), iOS 12+ (full), Desktop (full)"
+  Build evidence: settings.gradle.kts includes `:desktop-app` only; core registers `jvm` target only;
+    core/src/androidMain (3 files) + core/src/iosMain (3 files) belong to NO registered target
+  Severity: CRITICAL — Android/iOS claimed full with zero grounding; 6 orphan source files
+  Recommendation: ground the claims (register targets + app modules) or restate the claim
+    (tier downgrade / `deferred` annotation); then re-verify the `[x]` state of platform-actual tasks
+```
+
+#### L. Protocol Consistency Audit 🌐 [CONDITIONAL — wire-format / protocol modules only]
+
+**Activation**: decided by the **Activation Gate** (`.specpro/templates/protocol-golden-bytes-guide.md` §6) — triggers T1–T5. Run alongside the other active passes (A–K, M, N, O) when the verdict is ACTIVE or ACTIVE-WITH-GAPS. A verdict of NOT-ACTIVE is itself audited by L6 rather than silently accepted.
+
+- **L1 — Same-semantics branch scan**: detect byte-length / packing / stream-semantics branches duplicated across a decoder or encoder family. After a fix is applied to one such branch, its siblings MUST be scanned. Finding pattern: several functions in the same file carry same-semantics branches whose values disagree. (Historical shape: a decoder family carried N such branches; a fix touched N−1 and missed one, which stayed latent for months.)
+- **L2 — Verification-method semantic audit**: whether the verification technique used by a protocol test matches the semantics of the stream under test. A one-shot full-buffer decode reporting `incomplete` against a continuous stream is a false-defect pattern; an `incomplete` / `truncated` verdict MUST first rule out a method-semantics mismatch.
+- **L3 — Protocol-point coverage audit**: the field/branch-level protocol-point inventory (see `.specpro/templates/protocol-golden-bytes-guide.md` §1) checked 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**: golden bytes and expected test values MUST carry a source layer (specification / reference implementation / captured stream) plus the protocol version they were derived from. Unlabelled, or sourced from the implementation under test, is a finding — that is the self-confirming loop.
+- **L5 — Peer-behaviour assertion audit**: every test expectation that asserts a peer behaves in a particular way MUST trace to a row in the Peer Diversity Registry in `specs/test-tasks.md`. An assertion with no registered row is a finding — unmeasured peer behaviour MUST NOT be frozen into an expectation. If the registry section is absent altogether, report it once as a single finding rather than per assertion.
+- **L6 — Activation audit**: whether the Activation Gate (§6) was decided correctly and recorded. L1–L5 audit what happens *after* activation; none of them can see a stage that never activated — an unactivated stage produces no artifacts to audit, and the audit of its absence is indistinguishable from a feature with no protocol content. Detection:
+  * **Missed activation** (HIGH): the artifacts carry a gate trigger (T1–T5) but the stage that owns it recorded no verdict and produced no artifacts. The verdict is missing, not the trigger — re-derive the trigger mechanically from the artifact text and report the mismatch.
+  * **Unrecorded verdict** (MEDIUM): artifacts or gaps exist, but no verdict row (§6.4) — the work is not attributable and the next stage cannot consume it.
+  * **Verdict discrepancy across stages** (MEDIUM): one stage recorded NOT-ACTIVE while a later stage both found a trigger and produced artifacts, or the reverse. The later stage's silent override is the failure; either way the discrepancy is reportable.
+  * **Fabricated anchor** (HIGH, overlaps L4): an anchor annotated with a source layer it cannot have come from — in particular, a byte sequence present without any reachable source (a §6.3 GAP recorded as though covered). L4 catches "the implementation under test" as a source; L6 catches "no source at all, presented as anchored".
+- See `.specpro/templates/protocol-golden-bytes-guide.md` §4 and §6 for the lateral-audit criteria and the activation verdict / GAP format in full.
+
+#### M. Shared-Layer Boundary Audit 🌐 [CONDITIONAL — only when the constitution carries a shared-code / multiplatform / core-logic principle]
+
+**Activation**: run alongside the other active passes (A–L, N, O) when the constitution contains a principle mandating that some category of code (business logic / core protocol / data model) live in a shared module. This pass exists because the constitution's shared-code mandate is otherwise unenforced: Pass D checks constitution *alignment* in prose, but a layered-architecture description names layers without saying which concrete source set each layer owns — so a module can sit in a platform-only source set while every artifact still reads as compliant.
+
+**The failure shape** (why prose alignment never catches it): two components with the same architectural role land in different source sets, because placement follows whichever directory is nearest at implementation time. Nothing in the artifacts contradicts: the layer diagram still shows the component, the FRs are still covered, the tests still pass — the tests simply run on the one platform the code was placed for. The gap only becomes visible when a second platform tries to consume the layer.
+
+**Detection — three mechanical checks**:
+
+- **M1 — Shared-corpus gap** (CRITICAL): a code category the constitution mandates as shared is present ONLY in a platform-specific source set, with no equivalent in the shared set. Derive the mandated categories from the constitution's own wording; locate the corresponding packages; compare against the build's source-set registration. The requirement is not "the code exists somewhere" but "it lives in the corpus set" — a shared-mandated layer in a platform-only set is unreachable from the other platforms by construction.
+- **M2 — Transport coupling of a shared layer** (CRITICAL): a shared-mandated handler's construction path requires a transport-layer object (a live socket, connection, session, or client holder) — i.e. it cannot be constructed without a real network. This is the mechanism behind a recurring false diagnosis: the coupling forces every verification end-to-end, end-to-end verification inherits timing coupling, and the resulting intermittent failures get attributed to test flakiness rather than to the missing independent-testability boundary.
+- **M3 — Platform-capability leak into a shared layer** (CRITICAL): a shared-set file imports a platform-specific API (a platform dialect's I/O, compression, image, or crypto module) with no corresponding expect/actual declaration. The code compiles for the author's platform and fails only when a second platform is built — often on a machine the author is not running.
+- **Declaration absent** (MEDIUM): the constitution carries a shared-code principle but plan.md has no Shared/Platform Boundary Declaration subsection, so M1–M3 have no declared boundary to check against. Report this once, not per check.
+
+**Relationship to Pass K**: K compares *platform claims* against build target registration; M compares *shared-code claims* against source-set placement. They share the "claims live in documents, reality lives in the build" shape but audit different claim classes — a project can pass K and fail M.
+
+**Not covered by this pass**: whether the placement is *desirable* (that is a design decision), and code that no constitutional principle claims as shared (its placement is free).
+
+#### N. Contract-Fact Source Audit 🌐 [CONDITIONAL — only when `specs/contracts/` exists]
+
+**Activation**: run alongside the other active passes (A–M, O) when the feature has contracts under `specs/contracts/`. This pass exists because a contract is the one artifact that is **read as authority but never itself verified**: an assertion inside it is not evaluated, it is copied. Downstream tests, implementations and reviews inherit its values. A wrong value therefore propagates with the full weight of a specification behind it — and, unlike a missing value, nothing prompts anyone to check it.
+
+**The failure shape**: a contract value was wrong for an extended period, citing nothing; nothing reported it. The reader had no way to distinguish "read from an authoritative source" from "recalled". This generalises beyond protocol values — every asserted fact in a contract has this property.
+
+**How to tell whether a fact is attributed** — attribution is an **inline marker immediately above the fact block** (per the contract content rules), not a collected sources section:
+
+```markdown
+> Source: <L1 standard §<section> | L2 <implementation> <version> [<file/section>] | L3 <capture: peer + version>>
+```
+
+| Observation | Verdict |
+|-------------|---------|
+| Marker directly above the fact block, resolving to a section or a versioned implementation | attributed — no finding |
+| No marker above the block | **N1** |
+| Marker present but names only the protocol, or a versionless implementation | **N1a** |
+| Block attributed only by pointing at a sibling contract whose own blocks carry no markers | **N1b** |
+| Prose, reasoning, design rationale, API signatures | not a fact — no marker needed, no finding |
+| A `## Sources` / “fact sources” table at the end of the file | **not attribution** — it separates fact from source, which is where drift lives. Treat the facts it claims to cover as unattributed |
+
+**Detection — the checks**:
+
+- **N1 — Unattributed assertion** (HIGH): a contract states a fact about how the world is (a type code, field width, bit allocation, wire order, version-dependent behaviour, or an "is/is not supported" claim) with no source marker above it. The requirement is that the fact be checkable without trusting the author. A design choice (API signature, decomposition, naming, which codes this implementation advertises) needs no attribution — do not report those.
+- **N1a — Attribution that does not resolve** (HIGH): an attribution is present but does not reach a checkable place. The common form is a **bare protocol name or version** — it identifies *which protocol*, not *which part of it* or *how it was read*; a reader given only that still has to re-derive the claim from the whole document. The attribution MUST resolve to a section of the standard, or to a named implementation **with its version**. A named implementation without a version is the same failure in a different costume: it cannot be checked against the version the claim was actually read from.
+- **N1b — Unaudited cross-reference** (HIGH): the fact is sourced by pointing at another contract, but the referenced section does not itself carry resolving attributions. A cross-reference is a legitimate source **only when the referenced section is itself audited** — otherwise the chain merely relocates the unverified claim, and two contracts citing each other can appear fully sourced while nothing is resolved. Resolve the chain to its terminus; a terminus with no attribution is the finding.
+- **N2 — Source cannot support the claim** (HIGH): the cited source, by its own nature, does not cover what is asserted — e.g. the base standard is cited for a sub-encoding layout the standard does not define. A standard citation for something the standard omits is not a stronger source; it is a wrong one. Where the standard is silent, the attribution MUST point at an authoritative implementation, named with its version.
+- **N3 — Implementation as its own witness** (HIGH, overlaps L4): the fact is asserted from the implementing code under audit. The implementation cannot witness its own correctness — this is the self-confirming loop in contract clothing. Third-party sources only.
+- **N4 — Unmeasured peer-behaviour claim** (HIGH, overlaps L5): a claim that a named peer requires, tolerates, or rejects something, with no measured row in the Peer Diversity Registry. Such an item MUST be recorded as unverified rather than asserted.
+
+**Discrimination note**: N1 must compare **value and semantic label together**, not value alone. A contract entry and the implementation can agree on a number while disagreeing on what it means — the same numeric code labelled as one encoding in the contract and a different one in the code. A pure numeric diff misses exactly this, and it is the most dangerous variant: the value looks confirmed.
+
+**Relationship to adjacent passes**: L4/L5 are the protocol-scoped versions of N3/N4; N applies to any contract asserting external facts. Pass F checks whether artifacts *agree with each other*; N checks whether an assertion is *right*, and whether its reader has any way to find out. Pass M compares shared-code claims against source-set placement; N compares asserted facts against their cited sources.
+
+**Where findings go**: this pass reports only — it does not edit contracts. Register contract findings in the `[plan]` section of `specs/implement_issues.md`; `/specpro-plan --review-issues` owns `specs/contracts/` and applies the corrections, because a contract is a plan-phase artifact and its source attributions are resolved against the spec's lifecycle state. Reporting a contract finding without a route leaves the artifact stating a value the audit has already shown to be unsupported.
+
+**Not covered**: design choices (no external fact to source), and whether a correctly-attributed value is *desirable*.
+
+#### O. Anti-Coupling Scan
+
+**Activation**: run alongside the other active passes (A–N) on **every** analysis. Unlike L/M/N this pass has no activation condition: the coupling it looks for can be introduced by any edit, and the editor is precisely the party who cannot see it.
+
+**What it looks for**: specpro's own distributed assets (`commands/` · `templates/` · `scripts/`) carrying traces of the **host project** they were first developed against. Those assets ship to every user, so a host-specific trace ships with them.
+
+**Coverage — three classes, and all three are required.** A scan covering two of them is not "partial credit"; the uncovered class is the finding:
+
+- **Numeric identifiers** — an `FR-` / `T` / `ISS-` / `D-` identifier and its siblings. ⚠️ **Written here as the prefix form, never as a real identifier**: a rule that forbids identifiers in shipped assets would itself be an instance of the leak if it demonstrated the form with one — the same self-reference trap as a keyword table that lists a keyword it must not match. ⚠️ An identifier means nothing outside the repository that allocated it, so a reference to one is a reference to a document the reader does not have.
+- **Host technology stack** — framework, language, tool and build-plugin names, **with versions**. A pinned version is specific to one project's stack even when the technology is not.
+- **Host module and class names** — the project's own source paths, package names, and type names.
+
+⚠️ **All three are scoped to the HOST project.** specpro citing its own requirements and its own modules is provenance; citing another project's is leakage.
+
+⚠️ Constitution clause 1.3 names "*module names, package names, platform names, business terms*". That enumerates the **third** class plus the bare project name, and stops there. The first two classes are in scope **because they leak the same way and nothing else catches them** — which is exactly why the enumeration, not the clause, is the part that has to be maintained.
+
+**Cases enter as SHAPES, never as instances — in ALL THREE classes** (FR-053). ⚠️ **The scope is the whole pass, not the first class** (`T179` / `ISS-123`, 形态 10「一般规则只以实例形式存在」): each class entry above ends in a prohibition, and **a prohibition demonstrated with an instance of what it forbids is itself an instance of it** — an identifier rule that quotes a real identifier, a stack rule that names a pinned framework, a module rule that names a class. Measured: the two implementations of this scan once carried the same sentence twice — one wrote the **rule** ("a hardcoded host term here would BE the leak it exists to find"), the other wrote the **instance** (the actual terms) — and **only the instance-bearing side was itself a leak, while the scan caught it**. The mechanism worked; the rule was under-scoped. ⇒ State each rule so the next instance is recognisable *by shape*: *"N same-shaped branches in a family, a fix touching N−1, latent for months"* is usable; *"the defect at <that one issue>"* is not — and mechanically substituting a placeholder for the value deletes the shape along with it. **The transferable part is the shape, not the example.**
+
+**The pattern table is a maintained asset, not a one-off script.** When a host-specific trace is found, the fix has **two** halves: remove the trace, **and** add the pattern that would have caught it. Without the second half the same class re-enters on the next edit.
+
+**Execution** ⚠️ [settled 2026-09-18]: run `.specpro/scripts/bash/check-anti-coupling.sh` from the repository root. It prints its hits by class and exits non-zero when it finds any; hits are **file-level**, so locating the line is the running step's job when filling the table below. The three classes are covered by **two different mechanisms**, and the difference decides what "maintaining the table" means for each:
+
+- **Class 1 (identifiers) is DERIVED, never listed.** "Foreign" means "not allocated by this project", and a project already records its own numbers — so the scan reads each prefix's range from the artifact that **allocates** it. ⚠️ It must not read the range from every artifact that *mentions* it: a file that quotes foreign identifiers while instructing their removal feeds its own maximum back into the measurement, and a range that has absorbed the very identifiers it should catch is blind. The measurer must not be fed the thing being measured.
+- **Classes 2 and 3 are patterns, and the patterns live in `specs/anti-coupling-patterns.txt`** — a PROJECT artifact, deliberately outside the distributed assets. It names the host project's stack and domain terms, which is exactly what this pass forbids *inside* `commands/` `templates/` `scripts/`; a shipped file carrying those strings would itself be the leak it exists to find. The scanner reads them from there, so nothing under `scripts/` knows them.
+
+⚠️ **A class with no patterns is a finding, not a skip.** Pass O requires all three, so the scan fails when a class has no patterns — including when the table is absent altogether — rather than reporting the two it managed to check. A project adopting this pass creates its own table; until it does, the scan names the uncovered class instead of passing silently.
+
+⚠️ **A pattern earns its place by a measurement, and the scan must be seen to fail.** A pattern that nothing in the assets matches is how a table grows decorative, so add one only on a real hit. And a scan that has only ever reported clean is indistinguishable from one that cannot report anything: put a known trace back into a shipped asset and confirm the scan names it — the same discipline Pass L6 applies to its own assertions.
+
+**Findings**:
+- **O1 — Foreign numeric identifier in a distributed asset** (HIGH): an `FR-` / `T` / `ISS-` / `D-` identifier **belonging to a project other than specpro itself** appears in a shipped file.
+  ⚠️ **The scoping word is "foreign", and the first application of this rule is why.** A bare "any identifier" formulation also flags specpro's **own** requirement citations (`FR-053` and friends), which are **provenance, not leakage**: they say which requirement an instruction implements, resolvable by anyone holding the tool's own spec, and meaningless-to-a-user in a way that is harmless. Constitution clause 1.3 draws the same line — it forbids *the host project's* concrete names.
+  **The judging question**: *whose specification defines this number?* If it is not specpro's, the reader cannot resolve it from anything they received. A number above this document's own range is the mechanical tell; an identifier that is in range but carries a **host-specific gloss** ("FR-027 is the worked instance: …") is the one that needs a reader to notice.
+- **O2 — Host technology stack named in a distributed asset** (HIGH): a framework, language or tool name with a version, or a build-plugin name, appears in a shipped file.
+- **O3 — Host module or class name in a distributed asset** (HIGH): a path, package or type name belonging to the host project appears in a shipped file.
+- **O4 — Case recorded by identifier instead of by shape** (MEDIUM): a rule whose value is its transferability is stated via an identifier, so it cannot be applied anywhere else.
+
+**Where findings go**: this pass **reports only** — it does not edit the assets. The fix is a tool-source change, so register in the `[tasks]` section of `specs/implement_issues.md`. A finding registered without a route is indistinguishable from one never reported.
+
+**Not covered**: host content that is not a trace. The assets may legitimately describe the host project's *conventions* in abstract terms ("when a shared layer depends on a platform capability…"); what is forbidden is naming the concrete project.
+
+**Relationship to adjacent passes**: Pass D checks the assets against the constitution *in prose*; this pass checks whether the assets carry a **different project's fingerprint**. Clause 1.3 is the rule; this pass is its enumeration — and the enumeration is what was incomplete.
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality, Test-First violations for high-risk modules, zero-coverage HIGH-RISK-module FRs in the test matrix (Pass J), platform claimed `full` with zero build grounding (Pass K), constitution-mandated shared code present only in a platform-specific source set (Pass M1), a shared-mandated handler whose construction requires a live network object (Pass M2), a platform-specific API imported into a shared layer with no expect/actual declaration (Pass M3)
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion, Test-First violations for medium-risk modules, performance metrics loss, unaddressed checklist FAIL items, zero-coverage FRs or single-layer coverage of protocol/crypto/network modules in the test matrix (Pass J), an FR with **zero task coverage and no carrier on any of Pass F's three routes** — its delivery is unaccounted for (Pass E), cross-platform constraint anchored to a single-platform scenario (Pass J), orphan platform source sets / undocumented platform claims / `restricted` tier missing boundary clause (Pass K), same-semantics branch duplicated across a codec family with a sibling left unfixed (Pass L1), spec anchor sourced from the implementation under test or carrying no source-layer annotation (Pass L4), a contract stating a fact about how the world is with no source layer and version, citing a source that cannot cover the claim, asserting the fact from the implementing code itself, or claiming peer behaviour with no measured registry row (Pass N1–N4), gate trigger present but activation never recorded and no artifacts produced — missed activation, or a byte sequence presented as anchored with no reachable source (Pass L6), a numeric identifier, a pinned technology name, or a host module/class name present in a distributed asset (Pass O1–O3 — it ships to every user and is meaningless in the next repository)
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case, test matrix not built / FRs missing from matrix / zero-coverage LOW-or-MEDIUM-risk FRs / change-log staleness (matrix out of sync with spec SpecStatus changes) (Pass J), an FR carried by a test-layer or fix-task route but lacking its **unit** layer (Pass E/F — the narrow finding, not a coverage hole), a Lifecycle field that is `processed` on **every** item and therefore carries no information while downstream logic filters on it (Pass F), verification method mismatched to the semantics of the stream under test (Pass L2), protocol point with no test coverage (Pass L3), peer-behaviour assertion with no entry in the Peer Diversity Registry (Pass L5), activation verdict unrecorded for a stage that has protocol rules (the criterion is `.specpro/templates/protocol-golden-bytes-guide.md` §6.4 — *“A stage with protocol rules and no verdict row is a finding regardless of whether the artifacts happen to exist.”*; ⚠️ **the artifact's existence is not a premise of the finding** — reading it as one narrowed the criterion to stages that had already produced artifacts, which is precisely the stage that no longer needs the check), or a verdict discrepancy across stages — one stage NOT-ACTIVE while another produced protocol artifacts (Pass L6, the two non-HIGH verdicts), a shared-code constitution principle with no Shared/Platform Boundary Declaration in plan.md, leaving the boundary unauditable (Pass M)
+  ⚠️ **这里此前有两条相邻的 `**MEDIUM**:` 条目，第二条是第一条的真子集**（`T207` / `ISS-167`，2026-09-19 删除）。删的是**短的那条**，判据不是长度 —— 三条它缺的子句**各自在别处有承载**，逐条核过：**Pass E/F 的窄发现**在 §4 的 Pass E 里整条写着（含严重度与 FR-027 那个实例）；**Pass F 的「恒定字段」**在同节的 stale-data 观察里、并在 Finding Registration 的路由表里有一行；**Pass M 的边界声明**在 Pass M 自己的表里。⇒ **删掉短的不会丢任何东西，删掉长的会丢一处**。⚠️ 两份并存的代价不是难看：`T185` 改的那个短语**在两条里各出现一次**，只改一条会让它的核验在两轮之间读数为非零 —— 同一事实的第二个来源，已分叉，而分叉不报错（宪法 Q2）。
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order, stale matrix rows (dangling task/FR references) (Pass J)
+
+### 6. Report Generation ✨ ENHANCED with multiple modes
+
+**Report Mode Selection**:
+- If SUMMARY_MODE=true: Generate summary report only
+- Else (default): Generate detailed report
+
+**缺陷状态的表述规则** ⚠️ [FR-050 —— 本段在两个命令里**逐字相同**（`specpro.status.md` · `specpro.analyze.md`）；改一处 MUST 同轮改另一处，否则它就是它所防的那种分叉（形态 3）]
+
+**任何「有没有缺陷」的陈述 MUST 表述为「无已知缺陷」，MUST NOT 表述为「无缺陷」。** 两者是不同的断言，只有前者可核验：
+
+| 表述 | 它声称什么 | 可否核验 |
+|---|---|---|
+| **无已知缺陷** | **登记表中每一个形态都已对它跑过检出，且已知实例为零** | ✅ 可核验 —— 重跑检出即得结论 |
+| **无缺陷** | 一个关于**未被检视的那一部分**的断言 | ❌ 不可核验 —— 没有人对它做过测量 |
+
+**定义即判据**：只有当**每一个形态都已被检出过**（没有一个落 `⊘`）**且命中数为零**时，才可以表述为「无已知缺陷」；否则 MUST 写出未检视的那部分。
+
+⚠️ **MUST 随附覆盖声明**：任何缺陷状态陈述 MUST 声明**所覆盖的范围** —— 哪些形态检出过、哪些**没能检出**（`⊘`）。⚠️ **「没有提到」与「没有欠账」是两句不同的话，而前者与「忘了看」无从区分**（`FR-036` 对覆盖主张施加的是同一条纪律：**声称通过而基线未覆盖，不构成通过**）。
+
+⚠️ **工具侧报告用英文，同一断言照此对应**：`no known instance` ✅ / `no defects` · `defect-free` ❌。两个形态说的是**同一件事**，只在语言上不同 —— 若只钉住中文那一侧，英文报告会**照旧声称「无缺陷」而没有任何东西报错**（形态 3）。
+
+**机制（可复跑的形态）**：`scripts/bash/verify-shapes.sh`（PowerShell 对等：`scripts/powershell/verify-shapes.ps1`）就是这条判据的载体 —— 收尾报告给出 `N hit`（已知实例数）与 `M not executable`（没跑起来的组数）。**命中数不为零 ⇒ 不得表述为「无已知缺陷」；有 `⊘` ⇒ MUST 连带声明那一部分未证实，而不是干净。**
+
+#### Summary Report Mode (if --summary flag present)
+
+```markdown
+
+#### P. Feature Registry Consistency 🆕 [v0.23 · FR-018]
+
+**Purpose**: 检出 feature 登记文件与磁盘目录的**双向不一致**与缺件。Consumers: 路由表(`[tasks]` — 实现修复归任务)。
+
+- **P1 在册无目录**(MEDIUM): `specs/features.md` 含 `fNNN` 行,但 `specs/fNNN-*/` 目录不存在 → 登记失真,状态总览会漏报
+- **P2 有目录未在册**(MEDIUM): `specs/f[0-9][0-9][0-9]-*/` 目录存在但登记文件无对应行 → 目录游离,进度/缺件对它不可见
+- **P3 缺件**(MEDIUM): 目录内缺 `spec.md`/`plan.md`/`tasks.md` 任一项 → 列出缺失项(对照 FR-016 链路)
+- **P4 status 越值**(LOW): 登记行 `status` ∉ {`active`, `delivered`, `deprecated`} → 字段取值漂移
+
+**检出方式**(可复跑): 以 `specs/features.md` 的行集合与 `specs/` 下 `f[0-9][0-9][0-9]-*` 目录集合做双向 diff;目录内按三产物存在性核缺件。
+
+## 📊 Analysis Summary
+
+**Quality** (from the checklist): [**Status**: PASS|BLOCK] — [N/M passed]   ← 取清单真实的两个字段，不取一个它从不产出的「分数」
+**Ready for Implement**: ✅ Yes | ⚠️ Warnings | ❌ No
+
+**Critical Issues**: N
+**High Issues**: N
+**Medium Issues**: N
+**Low Issues**: N
+
+**Coverage**: X% (Y of Z requirements have tasks)
+
+**Recommendation**: [PROCEED | FIX CRITICAL | ADDRESS WARNINGS]
+
+**Defect status** (FR-050 — the wording rule above): [**无已知缺陷** — <N> shapes all exercised, 0 hits
+| <N> known instance(s)
+| ⚠️ **coverage incomplete** — <M> shape(s) could not be exercised at all, so that part is
+  **unproven, NOT clean**]
+⚠️ May be written as 「无已知缺陷」 **only** when every shape was exercised AND hits = 0. `Total Issues: 0`
+here is a count of findings **on the artifacts**, not a statement about the tool's defects — the two are
+different claims and only the second has a coverage declaration behind it.
+
+**Next Steps**:
+[Top 3 recommended actions]
+```
+
+#### Detailed Report Mode (default)
+
+```markdown
+## 🔍 Specification Analysis Report
+
+**Generated**: [Timestamp]
+**Analysis Mode**: [Full | Incremental]
+**Artifacts Analyzed**: spec.md, plan.md, tasks.md, constitution.md
+
+**Executive Summary**:
+- Total Issues: N (CRITICAL: M, HIGH: P, MEDIUM: Q, LOW: R)
+- Coverage: X% (Y of Z requirements have tasks)
+- Constitution Violations: N
+- Test-First Violations: N (High-Risk: M, Medium-Risk: P)
+- Test Matrix Gaps: N (zero-coverage FRs: M, matrix not built: yes/no)
+
+---
+
+### Findings Table
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+| G1 | Test-First | CRITICAL | tasks.md:L45-50 | Protocol handler missing test tasks | Add test tasks before implementation |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+---
+
+### Task Coverage Summary Table
+
+**Dimension: TASK coverage — measured on `tasks.md`** ⚠️. Every row is decided by whether `tasks.md` carries the FR, not by the matrix (that is the next-but-one table's job, measured on `specs/test-tasks.md`) and **not** by `spec.md`'s `[tasks:processed]` field, which is wholesale-seeded and constant across all items — see Pass E's legacy caveat. When an FR shows "No", run Pass F's **carrier test** before calling it a gap and record which route carries it.
+
+| Requirement Key | Has Task? | Task IDs | Carried by (if no task) | Notes |
+|-----------------|-----------|----------|-------------------------|-------|
+| user-upload-file | ✅ Yes | T-xxx, T-yyy | — | Well covered |
+| FR-027 resolution-change | ❌ No | - | IT-009 + CE-002 (test-tasks.md) · FT-020 (fix-tasks.md) | Carried by routes 2+3 → unit layer only |
+
+---
+
+### Test-First Compliance Analysis 🆕
+
+| Module | Risk Level | Test Tasks | Implementation Tasks | Status |
+|--------|------------|------------|----------------------|--------|
+| Wire Protocol Handler | High | 0 | 3 | ❌ CRITICAL - Missing tests |
+| Crypto Module | High | 2 | 2 | ✅ PASS - Tests before implementation |
+| User Repository | Medium | 0 | 1 | ⚠️ HIGH - Recommended tests |
+
+---
+
+### Test Matrix Gap Analysis 🆕
+
+**Dimension: TEST-MATRIX coverage — measured on `specs/test-tasks.md`** ⚠️. A clean matrix (`168/168 rows`) is **not** evidence about task coverage — the two were measured 100% vs 52% on 2026-09-10. State the artifact in any finding derived from this table.
+
+<!-- Render only when specs/test-tasks.md exists; otherwise emit one row:
+     "Matrix | - | - | - | ⚠️ MEDIUM - not built | Run /specpro-test-plan" -->
+
+| FR | Risk Level | Unit | IT | CE | AE | Status |
+|----|------------|------|----|----|----|--------|
+| FR-xxx Wire Protocol Handshake | High | tasks.md T-xxx | IT-001 ✅ | ❌ none | AE-001 | ⚠️ HIGH - no component E2E |
+| FR-xxx Decode Flow | High | core/src XxxDecoderTest | IT-002 ✅ | ❌ none | ❌ none | 🟡 MEDIUM - IT covered, no CE/AE |
+<!-- ⚠️ 本行此前写的是 `🔴 CRITICAL`，而**它自己的规则**说：只有「**全部** IT/CE/AE 格都为空」
+     且该 FR 属 HIGH-RISK 才是 CRITICAL，**否则 MEDIUM**（`T174`）。这一行的 IT 格是 `IT-002 ✅`
+     —— **不是全空** ⇒ 按规则就是 MEDIUM。示例与规则相反，而示例是照抄者会跟的那一个。 -->
+| FR-xxx UI Layout | Low | - (pure UI) | - (pure UI) | - (app-level) | AE-003 | ✅ Covered (rationale documented) |
+
+---
+
+### Performance Metrics Tracking 🆕
+
+| Performance Requirement | Plan.md | Tasks.md | Status |
+|-------------------------|---------|----------|--------|
+| <500ms latency | ✅ Addressed | ❌ No measurement tasks | ⚠️ HIGH |
+
+---
+
+### Protocol Consistency Analysis 🆕 (Pass L — render only when activated)
+
+| Check | Finding | Location | Status |
+|-------|---------|----------|--------|
+| L1 Same-semantics branches | Same-shaped byte-counting branch appears in N functions; a fix touched N−1 | `XxxCodec.kt:L120, L204, …` | 🔴 HIGH - 1 branch unfixed |
+| L2 Verification-method semantics | Continuous stream verified with a one-shot full-buffer decode | `XxxTest.kt:L88` | ⚠️ MEDIUM - false-defect risk |
+| L3 Protocol-point coverage | Extension-chain path has no test case | inventory §1, row 2 | ⚠️ MEDIUM - low-frequency path uncovered |
+| L4 Anchor source | Expected bytes derived from the implementation under test, no source layer | `XxxTest.kt:L41` | 🔴 HIGH - self-confirming loop |
+| L5 Peer-behaviour assertion | Test expects a peer quirk that has no row in Peer Diversity Registry | `XxxTest.kt:L112` | ⚠️ MEDIUM - unmeasured behaviour frozen into expectation |
+| L6 Activation verdict | Gate trigger present (T3: codec source) but no verdict row and no inventory/anchors produced | `plan.md` design section | 🔴 HIGH - missed activation, audit cannot see the stage |
+
+---
+
+### Shared-Layer Boundary Analysis 🆕 (Pass M — render only when the constitution carries a shared-code principle)
+
+| Check | Finding | Location | Status |
+|-------|---------|----------|--------|
+| M1 Shared-corpus gap | Constitution mandates the protocol layer shared; it exists only in a platform-specific source set | `core/src/jvmMain/.../protocol/` | 🔴 HIGH - unreachable from other platforms by construction |
+| M2 Transport coupling | Handler's construction requires a live connection object; cannot be built without a real network | `XxxDecoder.kt:L33` | 🔴 HIGH - forces end-to-end verification, timing coupling misread as flakiness |
+| M3 Platform-capability leak | Shared-set file imports a platform-specific compression/image API with no expect/actual | `XxxCodec.kt:L12` | 🔴 HIGH - compiles for one platform, fails on the next build |
+| M4 Declaration absent | Shared-code principle present, no Shared/Platform Boundary Declaration in plan.md | `plan.md` Architecture | ⚠️ MEDIUM - boundary unauditable |
+
+---
+
+### Contract-Fact Source Analysis 🆕 (Pass N — render only when specs/contracts/ exists)
+
+| Check | Finding | Location | Status |
+|-------|---------|----------|--------|
+| N1 Unattributed assertion | Contract states a type code / bit allocation / wire order with no source layer and version; the reader cannot check it without trusting the author | `contracts/xxx.md:L88` | 🔴 HIGH - unchecked fact reads as authority |
+| N1a Attribution does not resolve | Attribution names only the protocol (or an unversioned implementation), so the reader still has to re-derive the claim | `contracts/xxx.md:L90` | 🔴 HIGH - attribution present but hollow |
+| N1b Unaudited cross-reference | Fact sources a sibling contract that carries no resolving attributions — the chain relocates the claim instead of resolving it | `contracts/xxx.md:L94` | 🔴 HIGH - apparent source, no terminus |
+| N2 Source cannot support the claim | Base standard cited for a sub-encoding layout the standard does not define | `contracts/xxx.md:L92` | 🔴 HIGH - wrong source is not a weaker source |
+| N3 Implementation as its own witness | Fact asserted from the implementing code under audit | `contracts/xxx.md:L96` | 🔴 HIGH - self-confirming loop |
+| N4 Unmeasured peer-behaviour claim | "Peer X requires/rejects Y" with no measured row in the Peer Diversity Registry | `contracts/xxx.md:L101` | 🔴 HIGH - unmeasured behaviour asserted as fact |
+
+---
+
+### Anti-Coupling Analysis (Pass O)
+
+| Check | Finding | Location | Status |
+|-------|---------|----------|--------|
+| O1 Numeric identifier | A shipped asset references `FR-…` / `T…` / `ISS-…`; a reader in another repository cannot resolve it | `commands/xxx.md:L42` | 🔴 HIGH - ships to every user |
+| O2 Host technology stack | A framework/language/tool name with a version, or a build-plugin name, in a shipped asset | `templates/xxx.md:L17` | 🔴 HIGH - one project's stack, everyone's copy |
+| O3 Host module or class | A host project path, package or type name in a shipped asset | `scripts/xxx.sh:L88` | 🔴 HIGH - another project's fingerprint |
+| O4 Case by identifier | A rule whose value is transferability is stated via an identifier, so it cannot be applied elsewhere | `commands/xxx.md:L120` | 🟡 MEDIUM - the shape is lost with the number |
+
+---
+
+### Constitution Alignment Issues
+
+[List any constitution MUST violations with article references]
+
+---
+
+### Unmapped Tasks
+
+[List tasks with no clear requirement/story mapping]
+
+---
+
+### Detailed Metrics
+
+**Requirements**: Total | Functional | Non-Functional
+**Tasks**: Total | By Phase (Setup, Tests, Core, Integration, Polish)
+**Coverage**: X% (requirements with >=1 task)
+**Ambiguity Count**: N vague adjectives, N placeholders
+**Duplication Count**: N near-duplicates
+**Critical Issues Count**: N
+**Constitution Violations**: N
+**Test-First Violations**: N (High-Risk: M, Medium-Risk: P)
+**Test Matrix Gaps**: N (zero-coverage FRs: M, single-layer HIGH-RISK modules: K, matrix not built: yes/no)
+```
+
+### 7. Finding Registration 🆕 (write, but ONLY the issue file)
+
+**Naming gate — before you invent an identifier or a location** ⚠️ (FR-054): look it up first in the **existing** vocabulary. "Existing" means a table that is already there, not one this run invents.
+
+**The test is wiring, not style.** An identifier outside the vocabulary has **no channel, no consumer and no check**: a requirement nobody can dispatch (no `--review-issues` recognises the number), a parameter nobody implemented, a location nobody reads. That three-part shape is not introduced here — it is the same invariant the ledger contract states for its sections (`specs/contracts/ledger.md` → `## Sections and their consumers`), and it is **FR-021's vocabulary discipline applied to every identifier and location**, including this design's own numbering (`FR-` / `T` / `ISS-` / `D-`).
+
+⚠️ **Scope note**: the gate for *defect shapes* is Step 1 of the routing rules below; this paragraph is its **general form**. A rule that exists only as one instance is not a rule — the next identifier invented somewhere else will not be seen by it.
+
+⚠️ **Each vocabulary table states its own channel, consumer and check; this paragraph deliberately does not restate them.** A restatement is a second source, and two sources of one fact diverge without reporting.
+
+**The mechanical check** (Constraint 9 ①): `grep` the identifier against the table that would own it. **No hit means you are not naming it — you are inventing a channel**, and an invented channel has no consumer. The act is then **"extend that table"**, not "write the name here" — and the extension MUST land with its channel, consumer and check **in the same round**.
+
+**Why this step exists**: a report is transient — it lives in the terminal and is gone when the session ends.
+   - **Tool defects route through the ledger, not a side registry** ⚠️ [T089 · FR-023]: if the defect you found is in **specpro itself** (this project's command documents, templates, or support scripts — when a project bootstraps specpro, those **are** the project's product), route it by ONE criterion: **does spec.md already demand the corrected behavior?**
+     1. **Not demanded yet** → establish the requirement FIRST: register a `[specify]` entry naming the tool-source file and the missing requirement. `/specpro-specify --review-issues` amends spec.md; the fix then flows down the chain ([plan] → [tasks]) and returns as an executable task. Bypassing the requirement layer produces a task backed by no requirement — and a task with no requirement behind it cannot be verified against anything.
+     2. **Already demanded** → the requirement exists and the tool fails it: register a `[tasks]` entry naming the tool-source file. `/specpro-implement` discharges it by executing a task whose Location names that file — the same single entry tool source has always had.
+   - **Why no side registry** ⚠️: a defect written to a file no command consumes is indistinguishable from one never reported (FR-023 — a record only human convention reads does not satisfy routing). The former side registry was absorbed into the spec chain and deleted (`T089`); where history needs its entry IDs, cite them as 「原 TOOL-0NN」 — a historical label, never a live pointer.
+ The only artifact the next stage can actually consume is an entry in `specs/implement_issues.md`. Without this step the loop is referenced but not wired: Pass N tells the reader to register contract findings in `[plan]`, `/specpro-plan --review-issues` reads that section, and no step in this command writes it. The conversion then happens by hand (or not at all), and each manual transcription is a place where a finding's specifics are lost.
+
+**Scope — what this step writes, and what it must not touch**:
+
+| Writes | Never writes |
+|--------|--------------|
+| `specs/implement_issues.md` — append entries, update the statistics table (**its own row only** — seven commands declare this artifact) | `spec.md`, `plan.md`, `tasks.md`, `specs/contracts/**`, any source file |
+
+This is the **single exception** to this command's read-only default, and it is deliberately narrow: analysis may record what it found; changing the artifacts stays with the stage that owns them. If a finding needs an artifact change, that change happens when the owning `--review-issues` run consumes the entry — not here.
+
+**Which findings get registered**:
+
+- Register **CRITICAL / HIGH / MEDIUM**. Do not register LOW (style, minor redundancy) — it would dilute the queue.
+- **Deduplicate — two separate checks, both required**:
+  1. *Content*: scan the target section for an existing entry naming the same artifact + location + shape. If one exists (pending or resolved), **do not add a duplicate** — this keeps repeated `analyze` runs idempotent. If the finding is the same shape at a new location, extend the existing entry rather than opening a second one.
+  2. *Identifier*: scan the **whole file**, not just the target section, for the highest `ISS-NNN` in use, and allocate the next free number. Sections are appended concurrently by more than one workflow — an ID that is free in your target section may already be taken elsewhere in the same file, and a collision silently merges two unrelated findings under one number.
+
+  A run that skips check 2 produces exactly the failure this step exists to prevent: the new entry looks registered, but a later `--review-issues` pass will match the number against the wrong finding.
+- **Skip already-registered situations**: a finding that merely restates an existing pending entry's subject is not new information. A finding whose root cause is already covered by an entry should be noted inside that entry, not registered separately.
+
+**Routing — by which stage owns the fix**, not by which pass emitted the finding.
+
+⚠️ **This table is the SINGLE SOURCE OF TRUTH for that routing decision** (FR-055). Other
+artifacts reference it; none restates it. A restatement is a second source, and two
+sources of the same fact diverge without reporting — which is the failure FR-055 exists
+to remove, so "tidy duplicate" is not a fix here.
+
+**Step 0 — the pre-exclusion, which is NOT a row in the table below.** Before consulting
+any destination, ask: **is this an execution deviation** — did a command simply not do
+what was already written for it? If yes, **fix it in place and register nothing.** It is
+not a destination, it is the *absence* of one; giving it a row would create a section
+whose consumer nobody can name, violating Principle II ("an artifact no downstream
+consumer reads should not be generated"). The other three questions only apply after
+this one answers *no*.
+
+**Step 1 — the gate for tool defects.** A defect in specpro's own source
+(`commands/` · `templates/` · `scripts/`) is first checked against **FR-047's shape
+register**. ⚠️ **The comparison is per shape, one at a time, against that shape's own
+criterion** (FR-047 / FR-049) — not a glance at the register to see which entry "looks
+closest":
+
+1. **Read both halves.** `spec.md` → FR-047 carries the shapes and what each one *is*;
+   `plan.md` → Constraint 7 carries the detection table — how each is detected and what
+   counts as a hit. ⚠️ **The statement alone is not enough**: a shape whose detection
+   method you have not read cannot be ruled in or out, only guessed at.
+2. **Test the finding against each shape's criterion in turn**, and record the verdict per
+   shape — in or out, and why. ⚠️ **"It resembles shape N" is not a verdict.** "It
+   satisfies shape N's detection, and shape N's check would fire on it" is.
+3. **A finding that satisfies no shape's criterion is registered for `[specify]`** so a
+   **new shape** is added (FR-049). ⚠️ **It MUST NOT be absorbed into the nearest existing
+   shape** — from the register's side an absorption is indistinguishable from a defect that
+   was fixed, which is exactly how the register stops meaning anything.
+4. ⚠️ **What that `[specify]` entry MUST carry** — this is FR-049's own acceptance
+   (`spec.md` → US10): the candidate shape described as **a criterion a command could
+   evaluate** — what counts as an instance, what counts as a hit, and what a re-run would
+   look for. ⚠️ **A shape that cannot be turned into a criterion is not a shape, it is a
+   container** — and a register that admits containers *is* the container it exists to
+   replace.
+
+Only once the finding is placed in an existing shape does the table below decide where it
+goes.
+
+| The finding is about… | Register in | Consumed by |
+|-----------------------|-------------|-------------|
+| Requirement content — missing / unclear / conflicting FR or US text, a requirement's protocol specification gaps, the spec's own coverage of a mandated section | `[specify]` | `/specpro-specify --review-issues` |
+| Design, architecture, or a contract under `specs/contracts/` — design gaps, anchor/model defects, load-bearing assumptions that proved false, contract facts with no supportable source | `[plan]` | `/specpro-plan --review-issues` |
+| Task descriptions, ordering, dependencies, **a missing task** (Pass E: an FR with no carrier on any route), or a defect in the product of a `tasks.md` task — **including test-infrastructure work dispatched there as `[Quality]` tasks** (e.g. the codec test-matrix / golden-fixture / test-host family, planned by `/specpro-plan` + `/specpro-tasks`) | `[tasks]` | `/specpro-tasks --review-issues` |
+| A `spec.md` **Lifecycle field whose DATA is stale in this project** (Pass F) — e.g. constant across every item because it was seeded before the mechanism existed, or a `processed` marker with no work behind it. Register as a **project-level data annotation**, never as a mechanism-level prohibition | `[specify]` | `/specpro-specify --review-issues` |
+| Planning errors in `specs/test-tasks.md` — coverage-matrix rows (missing / stale / verdict wrong), INF/IT/CE/AE task content, Location grounding, task↔matrix annotation mismatch; or a defect in the product of a `test-tasks.md` task | `[test-plan]` | `/specpro-test-plan` (incremental run) |
+| The **constitution** itself is wrong or missing a clause — a principle that no longer matches the practice it governs, a carve-out written narrower than its intent, a governance rule with no enforcement point | `[constitution]` | `/specpro-constitution --review-issues` |
+
+When a finding spans stages, register it **where the fix lands**. A missing verdict left by an earlier stage belongs to the stage that should have produced it, not to the stage that noticed it.
+
+**Test-infrastructure defects route by the artifact that planned the infrastructure** ⚠️: do not send them to `[tasks]` by default. A verification harness that cannot terminate is a `[tasks]` finding when that harness is the product of a `tasks.md` task, and a `[test-plan]` finding when it is the product of a `test-tasks.md` task. Misrouting it files the finding where its planner will never read it.
+
+**Entry shape**:
+
+```markdown
+- [ ] ISS-NNN: <what is wrong, one line> (source: /specpro-analyze <date>, <Pass id>)
+  **Evidence**: <anchor — an FR / US / T identifier or a section heading — + the quoted text it points at>
+  **Recommendation**: <what the consuming stage should do>
+```
+
+- The **source** line is mandatory — it is what lets a later reader tell an analyzed finding from a guessed one.
+- **Evidence must be re-runnable — and durable** (`FR-022`): cite an **anchor that survives edits to the artifact** (a requirement / story / task identifier, or a section heading) **together with the quoted text** it points at. A line number MAY accompany the anchor but **MUST NOT stand alone** (⚠️ this line used to read *"a path with a line number, or a command and its observed output"*, which made the line number sufficient — `T107`): the artifacts under analysis are **continuously evolving**, so one insertion shifts every line below it, and **a stale line number does not error** — it opens on someone else's text while the reader takes it as evidence. A **command plus its observed output** stays valid: it re-derives the state rather than pointing into it.
+  ⚠️ **The failure this replaces is not hypothetical**: the finding that produced this rule (`T107`) cited `analyze.md:817` and `:812`; by the time it was executed those two sites had moved to `:898` and `:893` — a reader following the recorded numbers lands on unrelated text, and nothing reports it.
+
+**Entry placement**: append the new entry to the **end of its own section**, never to the end of the file. The file's statistics block sits at the top for exactly this reason — "append to the end" then lands inside the last section. Adding or duplicating a section header instead splits the section, and the orphaned part is silently skipped by every consumer run. If the target section does not exist yet (e.g. `[test-plan]` before the first test-execution finding), create the section **at the end of the file but BEFORE the end-of-file sentinel** (the trailing `<!-- ⚠️ … -->` comment on the file's last line — never place a section after it) with its one-line scope description, following the existing sections' shape.
+
+**Statistics**: after appending, update the `[N] → [N+1]` count and the pending-items column of the statistics table at the **top** of `implement_issues.md`; add the section's row if it is not there yet.
+
+**Edit order and idempotency check** ⚠️ [a silent false-skip, observed 2026-09-13]: write the **entry body first** (into its own section), then the derived summaries (statistics table + `Last Updated`) — never the reverse. A derived summary written first introduces the new ID into the file's text before the entry exists, so an idempotency guard that greps the file for that ID falsely concludes "already present" and **skips the entry**, while the summaries still claim it landed. For the same reason the guard MUST match the entry body's **line-start pattern**, never a full-text keyword search:
+```bash
+grep -qE '^- \[[x ]\] ISS-<N>:' specs/implement_issues.md   # correct — matches an ENTRY, not a mention
+# grep -q 'ISS-<N>' …                                        # wrong — also matches the statistics Pending-Items column, the Last Updated line, cross-references
+```
+`.specpro/scripts/bash/verify-ledger.sh` reports the resulting inconsistency as a count mismatch — but only if it is run, and by then the entry is already missing.
+
+**Verify mechanically after writing** ⚠️: run `.specpro/scripts/bash/verify-ledger.sh`. One pass checks all of the above — section membership of every entry (nothing past the sentinel), statistics-vs-actual counts per section, and the single trailing newline. It exits non-zero and names the offending entry on any violation. A pre-commit hook enforces the same check, so a violation blocks the commit rather than being discovered later.
+
+**Never mark an entry `[x]`** ⚠️: registration is routing, resolution belongs to the owning stage. `[specify]` / `[plan]` / `[tasks]` are resolved by their `--review-issues` runs; **`[test-plan]` has no `--review-issues` flag** — it is resolved by the next incremental `/specpro-test-plan` run, which is also the only party that may check it off.
+
+**Report**: list what was registered (IDs + target sections) in the report's Next Actions block, so the user sees the queue change rather than discovering it later.
+
+**When nothing is found**: if a pass produced no CRITICAL/HIGH/MEDIUM finding, register nothing and say so — an empty run is a valid result, not a failure to produce entries.
+
+### 8. Execution Summary 🆕 (Performance tracking)
+
+Track and report execution time breakdown:
+
+```markdown
+## ⏱️ Execution Summary
+
+**Total Time**: [T_total]s
+
+**Performance Breakdown**:
+┌──────────────────────────┬─────────┬──────────┬─────────┐
+│ Phase                    │ Time    │ %        │ Status  │
+├──────────────────────────┼─────────┼──────────┼─────────┤
+│ Context Initialization    │ [T1]    │ [P1]%    │ ⚡ Fast │
+│ Artifact Loading         │ [T2]    │ [P2]%    │ ⚡ Fast │
+│ Lifecycle Filtering      │ [T3]    │ [P3]%    │ ⚡ Cached│
+│ Detection Passes         │ [T4]    │ [P4]%    │         │
+│ ├─ Duplication Detection │ [T4a]   │ [P4a]%   │         │
+│ ├─ Ambiguity Detection   │ [T4b]   │ [P4b]%   │         │
+│ ├─ Test-First Check      │ [T4c]   │ [P4c]%   │ 🆕      │
+│ ├─ Test Matrix Gaps      │ [T4e]   │ [P4e]%   │ 🆕      │
+│ └─ Performance Metrics   │ [T4d]   │ [P4d]%   │ 🆕      │
+│ Severity Assignment      │ [T5]    │ [P5]%    │         │
+│ Report Generation        │ [T6]    │ [P6]%    │         │
+│ Persistence (if enabled) │ [T7]    │ [P7]%    │ 🆕      │
+└──────────────────────────┴─────────┴──────────┴─────────┘
+
+**Optimization Opportunities**:
+- [List slowest phases and suggestions]
+```
+
+### 9. Result Persistence 🆕 (if --persist flag present)
+
+**Purpose**: Save analysis results for trend tracking and specpro.status integration
+
+**Persistence Location**: `specs/analysis/analysis-[timestamp].md`
+
+**File Format**:
+````markdown
+# Analysis Report - [FEATURE_NAME]
+
+**Generated**: [Timestamp]
+**Analysis ID**: [UUID]
+**Spec Version**: [from spec.md]
+**Analysis Mode**: [Full | Incremental]
+
+## Executive Summary
+
+[Same as detailed report]
+
+## Detailed Findings
+
+[Same as detailed report]
+
+## Metrics Snapshot
+
+```json
+{
+  "timestamp": "[ISO8601]",
+  "analysis_id": "[UUID]",
+  "total_issues": N,
+  "critical": M,
+  "high": P,
+  "medium": Q,
+  "low": R,
+  "coverage_percent": X,
+  "test_first_violations": {
+    "high_risk": M,
+    "medium_risk": P
+  },
+  "test_matrix": {
+    "built": true,
+    "frs_tracked": N,
+    "zero_coverage_frs": M,
+    "single_layer_high_risk_modules": K,
+    "test_tasks_completed": A,
+    "test_tasks_total": B
+  }
+}
+```
+
+## Trend Analysis 🆕 (if previous analyses exist)
+
+Compare with previous analysis results:
+- Track issue count trends (improving/worsening)
+- Track coverage percentage trends
+- Identify recurring issues
+- Measure quality improvement over time
+
+**Example**:
+```markdown
+## Quality Trend
+
+| Date | Critical | High | Medium | Low | Coverage % | Trend |
+|------|----------|------|--------|-----|------------|-------|
+| 2026-01-28 | 5 | 12 | 8 | 3 | 65% | - |
+| 2026-01-29 | 2 | 8 | 6 | 4 | 78% | ✅ Improving |
+| 2026-01-30 | 0 | 3 | 4 | 2 | 85% | ✅ Improving |
+
+**Improvement**: -5 critical issues, +13% coverage in 2 days
+```
+````
+
+### 10. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/specpro-implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions, and **name the OWNER of each artifact the finding touches** — this command does not repair (`ISS-141`). Examples: "Run `/specpro-plan --review-issues` to adjust the architecture", "Run `/specpro-tasks --review-issues` to add coverage for 'performance-metrics'", "Run `/specpro-specify --review-issues` for a requirement-level finding"
+
+### 11. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?"
+
+⚠️ **Suggest, never apply.** What this step produces is a proposal for the artifact's **owning** command to carry out in its `--review-issues` run — not an edit this command makes (`ISS-141`).
+
+### 12. Integration with specpro.status 🆕
+
+If PERSIST_MODE=true the saved analysis file is read back by `/specpro-status`. ⚠️ **Name only what that command actually parses** — a claim here describes a consumer, so an unbacked one reads as a working integration (`T230` / `ISS-203`). Verified against `commands/specpro.status.md` → `Step 6.7`, which reads exactly these and renders them in the dashboard:
+- Quality trend visualization — the artifact's `## Quality Trend` table, rendered verbatim
+- Test-First compliance monitoring — `"high_risk"` / `"medium_risk"`, rendered as the risk-level violation counts
+- Severity counts and coverage — `"critical"` / `"high"` / `"medium"` / `"low"` / `"coverage_percent"`
+
+⚠️ **Two entries were removed, not because they were stale but because nothing consumed them**: `constitution_violations` and `performance_metrics_missing` were written into the Metrics Snapshot but **no command read them** (not the dashboard, not the trend comparison — the trend table's columns are date / severities / coverage only). A promise with no consumer is the same defect as a mechanism with no enforcement point. **如果将来要接它们，先给它们一个真的解析点，再写回这一行** —— 不要先把承诺写回来。
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+- **Lifecycle-aware filtering**: Incremental mode only analyzes changed items
+
+### Analysis Guidelines
+
+- **Always READ-ONLY over the analyzed artifacts** (the ledger and `specs/analysis/` are the only things this command writes)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+  ⚠️ "Zero" here means **no known instance among the subjects this run examined** — it MUST NOT be
+  written as 「无缺陷」 (FR-050). Carry the coverage declaration: what was scanned, and what was NOT.
+
+
+