specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/scripts/git-hooks/pre-commit

@@ -0,0 +1,243 @@
+#!/bin/bash
+#
+# pre-commit: block commits that would leave specs/implement_issues.md in a
+# structurally invalid state.
+#
+# Why this exists (2026-09-12): the ledger is position-structured, and the
+# failure mode is SILENT — a misfiled entry looks registered, the statistics
+# table looks plausible, nothing errors. An instruction telling writers to
+# self-check cannot reach a session that is already running (it does not
+# re-read its command file), so the check has to be enforced at a point every
+# writer must pass through. A commit is that point.
+#
+# Installed by: scripts/install-git-hooks.sh   (git hooks are not versioned —
+# the hook SOURCE lives here so a fresh clone installs the same check)
+# Bypass (deliberate, e.g. committing a known-broken WIP state): git commit --no-verify
+#
+# Scope: exits immediately unless the LEDGER itself is staged, so it costs
+# nothing on unrelated commits.
+#
+# ⚠️ **Two-repository layout** (adapted 2026-09-17 — the original assumed the
+# ledger and `.specpro/` share a repository, which is false here): `specs/` is
+# its own repository and is gitignored by the root one, so the staged path is
+# `implement_issues.md` when the hook runs inside `specs/` and
+# `specs/implement_issues.md` when it runs in a single-repository layout. Both
+# are recognised, and the verifier is located relative to the repository root
+# rather than assumed to be a sibling.
+
+set -e
+
+root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+cd "$root" || exit 0
+
+staged=$(git diff --cached --name-only)
+
+# ---------------------------------------------------------------------------
+# Second check: the shape register and the shape-detection table must agree.
+#
+# `spec.md` -> FR-047 carries the register (judgement criteria — the single
+# source); `plan.md` -> Constraint 7 carries the detection table (the same
+# shape numbers, plus HOW each is detected — a plan-layer decision, FR-048).
+# Two views of one fact, and nothing compared them: the register grew to 11 in
+# v0.17 while the detection table sat at 10 until a human noticed.
+#
+# The assertion below is the one written into Constraint 7 itself; this is its
+# enforcement point. Keep the two in step — if the assertion changes, change
+# this with it.
+# ---------------------------------------------------------------------------
+shape_sync_needed=0
+for cand in specs/spec.md spec.md; do
+    echo "$staged" | grep -qx "$cand" && shape_sync_needed=1
+done
+for cand in specs/plan.md plan.md; do
+    echo "$staged" | grep -qx "$cand" && shape_sync_needed=1
+done
+
+if [ "$shape_sync_needed" = 1 ]; then
+    spec_f=""; plan_f=""
+    for cand in "$root/specs/spec.md" "$root/spec.md"; do
+        [ -f "$cand" ] && { spec_f="$cand"; break; }
+    done
+    for cand in "$root/specs/plan.md" "$root/plan.md"; do
+        [ -f "$cand" ] && { plan_f="$cand"; break; }
+    done
+    if [ -n "$spec_f" ] && [ -n "$plan_f" ]; then
+        drift=$(diff \
+            <(grep -oE '^    \| \*\*[0-9]+\*\*' "$spec_f" | grep -oE '[0-9]+' | sort -n) \
+            <(grep -oE '^\| \*\*[0-9]+\*\*' "$plan_f" | grep -oE '[0-9]+' | sort -n) || true)
+        if [ -n "$drift" ]; then
+            echo "✗ Commit blocked: the shape register and the shape-detection table disagree." >&2
+            echo "    register  : $spec_f  (FR-047)" >&2
+            echo "    detection : $plan_f  (Constraint 7)" >&2
+            echo "$drift" | sed 's/^/    /' >&2
+            echo "" >&2
+            echo "  Two views of one fact. Add the missing row to the detection table" >&2
+            echo "  (with its 落点), or remove the one whose shape is gone. Bypass with" >&2
+            echo "  git commit --no-verify if the drift is deliberate and in progress." >&2
+            exit 1
+        fi
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Third check: the deployment mirror must match its source.
+#
+# 宪法 1.1 requires that "命令与模板的改动与部署动作成对提交, 不留'已改源未部署'的
+# 中间态"; 宪法 Q1 requires that "一份内容在多个位置存在时，它们不得在无人察觉的情况
+# 下分叉". Both name the same act — deploy before committing — and this is where that
+# act is enforced. Until this section existed, the only thing enforcing either was an
+# instruction to run three `diff` commands by hand, which is a discipline, not a gate.
+#
+# ⚠️ Conditional, like the two checks around it: it runs only when a mirrored path is
+# staged, so an unrelated commit pays nothing.
+#
+# ⚠️ Placed BEFORE the ledger check's early exit. That exit returns for every commit
+# that does not touch the ledger — which is most of them — so a section below it would
+# never run for exactly the commits this check is for.
+# ---------------------------------------------------------------------------
+deploy_check_needed=0
+for cand in commands/ templates/ scripts/; do
+    echo "$staged" | grep -q "^${cand}" && deploy_check_needed=1
+done
+
+if [ "$deploy_check_needed" = 1 ]; then
+    deploy_verifier=""
+    for cand in scripts/bash/verify-deployment.sh .specpro/scripts/bash/verify-deployment.sh; do
+        [ -f "$cand" ] && { deploy_verifier="$cand"; break; }
+    done
+    if [ -z "$deploy_verifier" ]; then
+        echo "✗ Commit blocked: a mirrored path is staged, but verify-deployment.sh was not found." >&2
+        echo "    Looked for: scripts/bash/verify-deployment.sh" >&2
+        echo "    → a check that cannot run MUST NOT report as passing." >&2
+        exit 1
+    fi
+    if ! bash "$deploy_verifier"; then
+        cat >&2 <<'EOF'
+
+────────────────────────────────────────────────────────────────────────
+✗ Commit blocked: the deployment mirror is out of sync with its source.
+
+宪法 1.1: 命令与模板的改动与部署动作成对提交，不留"已改源未部署"的中间态。
+宪法 Q1 : 多副本不得在无人察觉的情况下分叉。
+
+    Fix: deploy the changed source first —
+           commands/    → .claude/skills/   (CLI install: tools/install/.venv/bin/python
+                                              -c "from specpro_cli.cli.entry import app; app()"
+                                              init . --agent claude --source .)
+           templates/   → .specpro/templates/
+           scripts/bash/→ .specpro/scripts/bash/
+         then re-stage and commit.
+    Bypass deliberately with: git commit --no-verify
+────────────────────────────────────────────────────────────────────────
+EOF
+        exit 1
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# Fourth check: a cross-round record must not sit on a wholesale-rebuild path.
+#
+# plan.md → Constraint 11 (`FR-025`) requires it, and its `**强制点**:` line names
+# `scripts/bash/verify-cumulative-records.sh`. ⚠️ Until this section existed that
+# line named a script **nothing ran** — which is the very shape the section below
+# exists to stop: a constraint whose enforcement point is a *statement* rather
+# than a *gate*. The failure it guards is silent by construction — the rebuild is
+# a successful `cp`, so every exit code in the chain is 0 while the record's
+# contents are gone (measured 2026-09-19: a baseline section went 10 rows → 0).
+#
+# ⚠️ Conditional, like the checks around it: it runs only when a path that can
+# carry EITHER side is staged — `commands/` (where the rebuild sites live) or
+# `specs/` (where cross-round records live). An unrelated commit pays nothing.
+#
+# ⚠️ Placed BEFORE the ledger check's early exit below, for the reason stated
+# there: a section placed after it would never run for most commits.
+#
+# ⚠️ The verifier declares both sides itself (a record says `**Cumulative**:` in
+# its own header; a rebuild is a `cp` to a shell variable in `commands/`), so this
+# section adds no registry — it only supplies the thing that was missing.
+# ---------------------------------------------------------------------------
+records_check_needed=0
+for cand in commands/ specs/; do
+    echo "$staged" | grep -q "^${cand}" && records_check_needed=1
+done
+
+if [ "$records_check_needed" = 1 ]; then
+    records_verifier=""
+    for cand in scripts/bash/verify-cumulative-records.sh .specpro/scripts/bash/verify-cumulative-records.sh; do
+        [ -f "$cand" ] && { records_verifier="$cand"; break; }
+    done
+    if [ -z "$records_verifier" ]; then
+        echo "✗ Commit blocked: commands/ or specs/ is staged, but verify-cumulative-records.sh was not found." >&2
+        echo "    Looked for: scripts/bash/verify-cumulative-records.sh" >&2
+        echo "    → a check that cannot run MUST NOT report as passing." >&2
+        exit 1
+    fi
+    if ! bash "$records_verifier"; then
+        cat >&2 <<'EOF'
+
+────────────────────────────────────────────────────────────────────────
+✗ Commit blocked: a cross-round record sits on a wholesale-rebuild path.
+
+plan.md → Constraint 11: 一份跨轮累积的记录 MUST 住在没有任何命令每轮重建的
+产物里 —— 容器每轮重建 ⇒ 累积的内容静默消失，而没有任何一步会报错。
+
+    Fix: move the record out of the rebuilt artifact (the verifier's hit line
+         names both the record and the command that rebuilds it), then
+         re-stage and commit.
+
+    Why this is a gate and not a note: a record's value IS its accumulation,
+    and a rebuild destroys it with exit code 0 — nothing else would say so.
+    Bypass deliberately with: git commit --no-verify
+────────────────────────────────────────────────────────────────────────
+EOF
+        exit 1
+    fi
+fi
+
+# ---------------------------------------------------------------------------
+# First check: the ledger's own structural invariants.
+# ---------------------------------------------------------------------------
+ledger_rel=""
+case "$staged" in
+    *implement_issues.md*)
+        for cand in specs/implement_issues.md implement_issues.md; do
+            if echo "$staged" | grep -qx "$cand"; then ledger_rel="$cand"; break; fi
+        done
+        ;;
+esac
+[ -z "$ledger_rel" ] && exit 0
+
+# Locate the verifier. It lives beside `.specpro/` — in the specs repository
+# that is the PARENT directory, not a sibling.
+verifier=""
+for cand in .specpro/scripts/bash/verify-ledger.sh ../.specpro/scripts/bash/verify-ledger.sh; do
+    if [ -x "$cand" ]; then verifier="$cand"; break; fi
+done
+if [ -z "$verifier" ]; then
+    echo "pre-commit: verify-ledger.sh not found — skipping ledger check" >&2
+    exit 0
+fi
+
+if ! LEDGER="$root/$ledger_rel" "$verifier"; then
+    cat >&2 <<'EOF'
+
+────────────────────────────────────────────────────────────────────────
+✗ Commit blocked: specs/implement_issues.md failed its structural checks.
+
+The violations are listed above. In short, the ledger's invariants are:
+  · every issue entry sits INSIDE one of its '## [...] Phase Issues'
+    sections — never appended to the end of the file
+  · every entry's block carries exactly ONE `**Related**:` line, and every
+    field line lies inside some entry's block
+  · the statistics table at the top matches the actual per-section counts
+  · the file ends with exactly one newline
+
+The section entries are authoritative; the statistics table is derived.
+Fix the file and re-stage it, or bypass deliberately with:
+    git commit --no-verify
+────────────────────────────────────────────────────────────────────────
+EOF
+    exit 1
+fi
+
+exit 0

specpro_cli/assets/scripts/install-git-hooks.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+#
+# Install this repository's git hooks. **Git hooks are not versioned**, so a
+# fresh clone has none — the sources live under `scripts/git-hooks/` and this
+# script is what makes them real. Run it once per clone.
+#
+# Why a script rather than a README line: seven command documents state that a
+# pre-commit hook enforces `verify-ledger.sh` ("a violation blocks the commit
+# rather than being discovered later"). That claim was **false** — no hook
+# existed and nothing installed one — so every reader who skipped the manual
+# check did so with a clear conscience, which is exactly the failure the
+# sentence promised to prevent. A check that is *assumed* to exist and does not
+# is worse than no check at all.
+#
+# Covers BOTH repositories: the root one (tool source) and `specs/` (its own
+# repository — the ledger lives there, so the ledger hook matters most there).
+#
+# Usage:  scripts/install-git-hooks.sh [--check]
+#         --check  report installation state without changing anything
+# Exit:   0 = all hooks installed (or, with --check, all already installed)
+
+set -e
+
+root=$(git rev-parse --show-toplevel 2>/dev/null) || {
+    echo "✗ not inside a git repository" >&2
+    exit 1
+}
+cd "$root"
+
+CHECK=0
+[ "${1:-}" = "--check" ] && CHECK=1
+
+src="$root/scripts/git-hooks/pre-commit"
+[ -f "$src" ] || { echo "✗ hook source missing: $src" >&2; exit 1; }
+
+# Repositories that should carry the hook. `specs/` is its own repository and
+# is gitignored by the root one — both are listed explicitly because "install
+# where the ledger is" and "install where the tool is" are different questions.
+repos="$root"
+[ -d "$root/specs/.git" ] && repos="$repos $root/specs"
+
+missing=0
+for repo in $repos; do
+    dst="$repo/.git/hooks/pre-commit"
+    if [ -f "$dst" ] && cmp -s "$src" "$dst"; then
+        echo "  ✓ up to date: $dst"
+        continue
+    fi
+    if [ "$CHECK" = 1 ]; then
+        echo "  ✗ not installed (or stale): $dst"
+        missing=$((missing + 1))
+        continue
+    fi
+    mkdir -p "$repo/.git/hooks"
+    cp "$src" "$dst"
+    chmod +x "$dst"
+    echo "  ✓ installed: $dst"
+done
+
+if [ "$CHECK" = 1 ] && [ "$missing" -gt 0 ]; then
+    echo ""
+    echo "✗ $missing hook(s) missing — run scripts/install-git-hooks.sh" >&2
+    exit 1
+fi
+
+echo ""
+echo "✓ git hooks ready. Bypass a deliberate commit with: git commit --no-verify"

specpro_cli/assets/scripts/powershell/check-anti-coupling.ps1

@@ -0,0 +1,249 @@
+#!/usr/bin/env pwsh
+#
+# Anti-coupling scan — PowerShell twin of scripts/bash/check-anti-coupling.sh.
+#
+# Same stdout, same stderr, same exit code (FR-008). Pass O, made runnable.
+#
+# ⚠️ **The patterns are NOT in this file, and that is the design.** This script is a
+# distributed asset: a hardcoded host term here would BE the leak it exists to find
+# (O3), and the same for a pinned framework name (O2). Patterns live in a project-side
+# file (`specs/anti-coupling-patterns.txt`), which ships to nobody. Class 1 needs no
+# list at all — foreign numeric identifiers are DERIVED, since "foreign" means exactly
+# "not allocated by this project".
+
+# Repository root — resolved POSITION-INDEPENDENTLY, then TESTED (T180 / ISS-124).
+#
+# ⚠️ The previous form was `$PSScriptRoot/../..`, which is correct only from the SOURCE
+# layout. From the deployed mirror (`.specpro/scripts/bash/…`) it lands one level short,
+# on `.specpro` — and every path below then names a tree that does not exist. The
+# failure is silent in the worst direction: a scan over a tree it never read still
+# prints `✓ none`, indistinguishable from a clean one.
+#
+# ⚠️ The sentinel tests the RESULT, not the method — including for an override.
+function Test-RepoRoot([string]$p) {
+    (Test-Path (Join-Path $p 'commands')) -and
+    (Test-Path (Join-Path $p 'templates')) -and
+    (Test-Path (Join-Path $p 'scripts'))
+}
+
+# ⚠️ Two sentinels, and which one applies depends on WHO named the base (T205 / ISS-165).
+# Not a relaxation of the guard: it is the guard asking the right question in each case.
+#   * auto-resolution answers "is this a repository root?" — the three-directory shape is
+#     the evidence, and it must hold because the script CHOSE the directory.
+#   * an explicit override answers "can I read what I am about to scan?" — the caller has
+#     already named the tree, and what this scanner reads is `commands/` and `specs/`.
+#     Demanding `templates/` and `scripts/` here asks about directories it never opens.
+# Measured before the split: the fixtures build exactly `commands/` and `specs/`, so all of
+# them were refused before the scan — three unit tests red while the real repository (which
+# has all three) stayed green. A guard whose subjects can no longer be exercised is not a
+# stronger guard.
+function Test-ScannableBase([string]$p) {
+    $p -and (Test-Path (Join-Path $p 'commands')) -and (Test-Path (Join-Path $p 'specs'))
+}
+function Resolve-Base {
+    $t = git rev-parse --show-toplevel 2>$null
+    if ($t -and (Test-RepoRoot $t)) { return $t }
+    foreach ($cand in @((Join-Path $PSScriptRoot '..' '..'), (Join-Path $PSScriptRoot '..' '..' '..'))) {
+        if (Test-Path $cand) {
+            $p = (Resolve-Path $cand).Path
+            if (Test-RepoRoot $p) { return $p }
+        }
+    }
+    return $null
+}
+
+$Base = if ($env:ANTI_COUPLING_BASE) { $env:ANTI_COUPLING_BASE } else { Resolve-Base }
+
+# The sentinel is chosen by the base's SOURCE, and the message names the one that ran — a
+# reader told to expect `templates/` when the failing check never looks at it would go add a
+# directory that changes nothing.
+$sentinelOk = if ($env:ANTI_COUPLING_BASE) { Test-ScannableBase $Base } else { Test-RepoRoot $Base }
+$expect = if ($env:ANTI_COUPLING_BASE) { 'commands/ and specs/ (what this scanner reads)' }
+          else { 'commands/ , templates/ and scripts/ (a repository root)' }
+if (-not $sentinelOk) {
+    $shown = if ($Base) { $Base } else { '<unresolved>' }
+    [Console]::Error.WriteLine("✗ BASE is not usable: '$shown'")
+    [Console]::Error.WriteLine("  Expected it to contain $expect .")
+    if ($env:ANTI_COUPLING_BASE) {
+        [Console]::Error.WriteLine("  Source: the ANTI_COUPLING_BASE override.")
+    } else {
+        [Console]::Error.WriteLine("  Source: auto-resolution (git toplevel, then the script's two possible depths).")
+    }
+    [Console]::Error.WriteLine("  ⚠️ Every finding below would be derived from a tree this script never read —")
+    [Console]::Error.WriteLine("     an absent subject and a clean subject are the same output otherwise.")
+    exit 1
+}
+
+$Assets = if ($env:ANTI_COUPLING_ASSETS) { $env:ANTI_COUPLING_ASSETS -split '\s+' }
+          else { @('commands', 'templates', 'scripts') }
+$Patterns = if ($env:ANTI_COUPLING_PATTERNS) { $env:ANTI_COUPLING_PATTERNS }
+            else { Join-Path $Base 'specs/anti-coupling-patterns.txt' }
+$OwnSpec = if ($env:ANTI_COUPLING_OWN_SPEC) { $env:ANTI_COUPLING_OWN_SPEC }
+           else { Join-Path $Base 'specs/spec.md' }
+$OwnTasks = if ($env:ANTI_COUPLING_OWN_TASKS) { $env:ANTI_COUPLING_OWN_TASKS }
+            else { Join-Path $Base 'specs/tasks.md' }
+$OwnLedger = if ($env:ANTI_COUPLING_OWN_LEDGER) { $env:ANTI_COUPLING_OWN_LEDGER }
+             else { Join-Path $Base 'specs/implement_issues.md' }
+
+$Fail = 0
+Write-Output "Anti-coupling scan: $Base"
+Write-Output ""
+
+$AssetPaths = @($Assets | ForEach-Object { Join-Path $Base $_ } | Where-Object { Test-Path -LiteralPath $_ -PathType Container })
+
+# --- class 1: foreign numeric identifiers (DERIVED, not listed) ----------------------
+# ⚠️ The criterion is O1's own wording: "A number above this document's own range is the
+# mechanical tell" — a RANGE test, not a set difference.
+#
+# ⚠️ **Each prefix's range comes from the artifact that ALLOCATES it**, never from every
+# artifact that mentions it. `tasks.md` quotes the foreign identifiers it must fix, so
+# reading the FR range from it made the maximum come out at 145 instead of 57 — and a
+# range that has absorbed the very identifiers it should catch leaves the class blind.
+# The measurer must not be fed the thing being measured.
+Write-Output "  [1/3] foreign numeric identifiers (range-derived from $OwnSpec + tasks)"
+
+function Get-OwnSource([string]$Prefix) {
+    switch ($Prefix) {
+        'FR' { return $OwnSpec }
+        'US' { return $OwnSpec }
+        'T'  { return $OwnTasks }
+        'ISS' { return $OwnLedger }
+        'D'  { return $OwnSpec }
+    }
+}
+
+$DerivedAny = 0
+$Foreign = @()
+foreach ($prefix in @('FR', 'US', 'T', 'ISS', 'D')) {
+    $src = Get-OwnSource $prefix
+    if (-not (Test-Path -LiteralPath $src -PathType Leaf)) { continue }
+    $nums = @([regex]::Matches((Get-Content -LiteralPath $src -Raw), "\b$prefix-([0-9]+)") |
+        ForEach-Object { [int]$_.Groups[1].Value })
+    if ($nums.Count -eq 0) { continue }
+    # ⚠️ `Measure-Object` yields a DOUBLE even for integer input, and a double is not
+    # valid for the `{2:D3}` integer format specifier below ("Format specifier was invalid").
+    $max = [int](($nums | Measure-Object -Maximum).Maximum)
+    $DerivedAny = 1
+
+    # ⚠️ **The file name is part of the finding** (ISS-116 / T165). A report line that names
+    # the identifier but not where it lives is half-delivered — classes 2 and 3 both print
+    # the file, and this one did not.
+    #
+    # ⚠️ **The deduplication is on the COMPOSED string**, not on the identifier: the same
+    # foreign number legitimately appears in two files, and uniqueness over the id alone
+    # collapses them into one, hiding the second location.
+    foreach ($p in $AssetPaths) {
+        foreach ($f in Get-ChildItem -LiteralPath $p -Recurse -File) {
+            $text = Get-Content -LiteralPath $f.FullName -Raw
+            # Relative to the base, with forward slashes — the Bash side prints
+            # `${file#$BASE/}`, and a backslash would be a stdout difference, not a style one.
+            $rel = $f.FullName.Substring($Base.Length).TrimStart('/', '\').Replace('\', '/')
+            foreach ($m in [regex]::Matches($text, "\b$prefix-([0-9]+)")) {
+                $n = [int]$m.Groups[1].Value
+                if ($n -gt $max) {
+                    $Foreign += ("{0} ({1} max={2:D3}) {3}" -f $m.Value, $prefix, $max, $rel)
+                }
+            }
+        }
+    }
+}
+# ⚠️ Ordinal, not culture-aware: the Bash side sorts with `LC_ALL=C`, and a culture-sensitive
+# comparison orders punctuation and case differently — a correct set in a different order is
+# still a different stdout, and the parity contract is byte equality (FR-008).
+$Foreign = @($Foreign | Sort-Object -Unique -Culture '')
+
+if ($DerivedAny -eq 0) {
+    Write-Output "    ✗ could not derive this project's own identifier ranges from $OwnSpec / $OwnTasks"
+    Write-Output "      → with no range to compare against, EVERY identifier reads as foreign (noise)"
+    Write-Output "        or none does (a silent pass). A scan that cannot tell its own numbers from"
+    Write-Output "        a foreign one MUST NOT report clean."
+    $Fail = 1
+} elseif ($Foreign.Count -gt 0) {
+    Write-Output "    ✗ identifiers above this project's own range, in shipped assets:"
+    foreach ($x in $Foreign) { Write-Output "        $x" }
+    Write-Output "        → a reader outside this repository cannot resolve them (O1, HIGH)."
+    $Fail = 1
+} else {
+    Write-Output "    ✓ none"
+}
+
+# --- classes 2 and 3: declared patterns ---------------------------------------------
+function Test-Class([string]$tag, [string]$label, [string]$severity) {
+    if (-not (Test-Path -LiteralPath $Patterns -PathType Leaf)) {
+        Write-Output "    ✗ patterns file not found: $Patterns"
+        $script:Fail = 1
+        return
+    }
+    $declared = @(Get-Content -LiteralPath $Patterns | Where-Object { $_ -match "^$tag\|" })
+    if ($declared.Count -eq 0) {
+        Write-Output "    ✗ no patterns declared for this class in $Patterns"
+        Write-Output "        → Pass O requires all three classes; an uncovered class is the finding,"
+        Write-Output "          not a gap to note and move past."
+        $script:Fail = 1
+        return
+    }
+    # ⚠️ **A hit is a FINDING unless the pattern file lists it as reviewed** (T200).
+    # The patterns are a coarse word filter; a match cannot tell a worked example from a
+    # parallel list of alternatives, and `T177` triaged this class's hits into both. The
+    # triage is recorded in the pattern file as `reviewed::<class>::<regex>::<file>::<why>`,
+    # so the classification is an INPUT the reviewer can see and change — never a silent
+    # relaxation. Removing an entry restores its finding.
+    $hits = @()
+    $reviewedHits = @()
+    foreach ($line in $declared) {
+        $parts = $line -split '\|'
+        $regex = $parts[1]; $why = $parts[2]
+        foreach ($p in $AssetPaths) {
+            foreach ($f in Get-ChildItem -LiteralPath $p -Recurse -File) {
+                $text = Get-Content -LiteralPath $f.FullName -Raw
+                if ([regex]::IsMatch($text, $regex)) {
+                    $rel = $f.FullName.Substring($Base.Length).TrimStart('\', '/')
+                    $marker = "reviewed::${tag}::${regex}::${rel}::"
+                    if (Select-String -LiteralPath $Patterns -SimpleMatch -Pattern $marker -Quiet) {
+                        $reviewedHits += "        ($why) $rel"
+                    } else {
+                        $hits += "        ($why) $rel"
+                    }
+                }
+            }
+        }
+    }
+    if ($reviewedHits.Count -gt 0) {
+        Write-Output "    ⊘ reviewed generic reference(s) — NOT findings, each with its reason in"
+        Write-Output "      $Patterns (remove an entry to restore it as a finding):"
+        [System.Array]::Sort($reviewedHits, [System.StringComparer]::Ordinal)
+        foreach ($h in $reviewedHits) { Write-Output "  $h" }
+    }
+    if ($hits.Count -gt 0) {
+        Write-Output "    ✗ $label present in shipped assets ($severity):"
+        # ⚠️ ORDINAL sort, not Sort-Object's default culture-aware comparison: the bash
+        # twin sorts with `sort`, and two correct orderings that disagree are a parity
+        # failure. Same set, different order, different stdout.
+        [System.Array]::Sort($hits, [System.StringComparer]::Ordinal)
+        foreach ($h in $hits) { Write-Output "  $h" }
+        $script:Fail = 1
+    } else {
+        # ⚠️ Reported even when the ⊘ block above is present: "no findings" and "nothing was
+        # scanned" must not look alike, and the reviewed set is disclosed rather than hidden.
+        Write-Output "    ✓ none"
+    }
+}
+
+Write-Output "  [2/3] host technology stack (patterns from $Patterns)"
+Test-Class 'tech' 'host technology stack' 'O2, HIGH'
+
+Write-Output "  [3/3] host business terms and module names (patterns from $Patterns)"
+Test-Class 'term' 'host business term / module name' 'O3, HIGH'
+
+Write-Output ""
+if ($Fail -eq 0) {
+    Write-Output "✓ anti-coupling: no findings across all three classes"
+    exit 0
+} else {
+    Write-Output "✗ anti-coupling: FINDINGS (see above)"
+    Write-Output "  → Pass O reports only; the fix is a tool-source change. Register it in the"
+    Write-Output "    [tasks] section of specs/implement_issues.md — a finding without a route is"
+    Write-Output "    indistinguishable from one never reported. And the fix has TWO halves: remove"
+    Write-Output "    the trace, AND add the pattern that would have caught it."
+    exit 1
+}