specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/scripts/bash/verify-cumulative-records.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+#
+# Cumulative-record verifier — a cross-round record must not live in an artifact that
+# some command REBUILDS WHOLESALE.
+#
+# Why this exists (plan.md → Constraint 11, FR-025): a record whose members accumulate
+# round over round derives its value from surviving. Put it in a container that a command
+# replaces wholesale and the accumulation is **silently destroyed** — the rebuild is a
+# successful `cp`, so every exit code in the chain is 0.
+#
+# ⚠️ **Measured, not hypothetical** (2026-09-19): the tool-defect baseline lived at the end
+# of `specs/checklists/requirements.md`, which `/specpro-qc` copies from its template on
+# every run. One run took that section from **10 rows → 0 rows** and the file from
+# **47086 B → 13216 B**, with no error anywhere. The list survived that long because the
+# deletion happened to go unnoticed.
+#
+# ⚠️ **The two facts that must both hold look contradictory and are not**: the quality
+# checklist MUST be rebuilt every run (its value is *this* run's verdict — FR-060), and the
+# regression baseline MUST accumulate (its value is the defects found across runs — FR-025).
+# ⇒ They must be **two artifacts**. Merging them uses one's property to destroy the other's,
+# which is exactly the measured shape above.
+#
+# ⚠️ **Both sides are DERIVED — there is no registry, and that is a design decision.**
+# An earlier version kept two hand-written registries (records; rebuild sites) *inside this
+# script*. That is not just a list that fails by omission: it makes the verifier
+# **unfixtureable**. A fixture would have to edit the script to plant a violation, and the
+# PowerShell twin under test is the one in the repository while the tree holds its own copy —
+# so an edit to one side's registry breaks parity, and the fixture can never be written.
+# ⇒ **The subject declares itself where it lives**:
+#     · a cross-round record says so in its own header: `**Cumulative**: …`
+#     · a wholesale rebuild is a `cp … "$VAR"` in `commands/`, which is what that act
+#       looks like here (an ordinary `cp .env.example .env` inside a quickstart example
+#       is not a rebuild — the destination is not a variable)
+# Fixtures are then plain data edits to the tree, and both twins read the same data.
+#
+# Usage:  scripts/bash/verify-cumulative-records.sh
+#         RECORDS_HOOK_BASE=<path> scripts/bash/verify-cumulative-records.sh   (fixtures)
+# Exit:   0 = no record sits on a rebuild path;  1 = at least one violation
+
+# ⚠️ NOT `set -e`: this script reads greps that are *expected* to miss.
+set -uo pipefail
+
+is_repo_root() { [ -d "$1/commands" ] && [ -d "$1/templates" ] && [ -d "$1/scripts" ]; }
+
+# Base resolution mirrors `verify-deployment.sh` (T180 / ISS-124): position-independent, and
+# the RESULT is tested rather than the method — the same source resolves correctly from the
+# repository root and from the deployed mirror, which sit at different depths.
+resolve_base() {
+    local cand here
+    if cand=$(git rev-parse --show-toplevel 2>/dev/null) && [ -n "$cand" ] && is_repo_root "$cand"; then
+        printf '%s' "$cand"; return 0
+    fi
+    here=$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+    for cand in "$here/../.." "$here/../../.."; do
+        cand=$(CDPATH="" cd "$cand" 2>/dev/null && pwd) || continue
+        is_repo_root "$cand" && { printf '%s' "$cand"; return 0; }
+    done
+    return 1
+}
+
+BASE="${RECORDS_HOOK_BASE:-}"
+if [ -n "$BASE" ]; then
+    BASE=$(CDPATH="" cd "$BASE" 2>/dev/null && pwd) || { echo "✗ RECORDS_HOOK_BASE does not resolve: $RECORDS_HOOK_BASE"; exit 1; }
+    is_repo_root "$BASE" || { echo "✗ RECORDS_HOOK_BASE is not a repository root: $BASE"; exit 1; }
+else
+    BASE=$(resolve_base) || { echo "✗ cannot locate the repository root"; exit 1; }
+fi
+
+HITS=0
+ok()   { echo "  ✓ $1"; }
+hit()  { echo "  ✗ $1"; HITS=$((HITS + 1)); }
+skip() { echo "  ⊘ $1"; }
+
+echo "Cumulative-record check: $BASE"
+
+# -----------------------------------------------------------------------------------------
+# 1. Records — every file under specs/ that declares itself cumulative
+# -----------------------------------------------------------------------------------------
+echo "  [1] cross-round records (self-declared: \`**Cumulative**: …\`)"
+RECORDS=""
+if [ -d "$BASE/specs" ]; then
+    RECORDS=$(grep -rlE '^\*\*Cumulative\*\*: ' "$BASE/specs" --include='*.md' 2>/dev/null \
+        | sed "s|^$BASE/||" | LC_ALL=C sort || true)
+fi
+if [ -z "$RECORDS" ]; then
+    # ⚠️ A SKIP, not a hit: this script ships with the tool, and a user project may legitimately
+    # have no cross-round record at all. ⚠️ The cost is real and stated: **un-declaring a record
+    # turns this check off for it** — which is why the declaration lives in the record's own
+    # header, where removing it is a visible edit to the record itself.
+    skip "no file under specs/ declares itself cumulative — nothing is proven"
+else
+    while IFS= read -r r; do
+        [ -n "$r" ] || continue
+        ok "record: $r"
+    done <<EOF
+$RECORDS
+EOF
+fi
+
+# -----------------------------------------------------------------------------------------
+# 2. Rebuild sites — a `cp` in commands/ whose destination is a shell variable
+# -----------------------------------------------------------------------------------------
+# ⚠️ The optional closing quote is load-bearing. The destination is written `"$VAR"`, so a
+# pattern anchored on the variable running bare to end-of-line finds **nothing** and this
+# check reports a clean skip while seeing no subject at all — a detection that cannot see
+# its own subject, which is the shape it exists to catch. Measured: the first version had
+# exactly that bug.
+REBUILD_RE='^[[:space:]]*cp[[:space:]]+.*\$[A-Za-z_][A-Za-z0-9_]*["'"'"']?[[:space:]]*$'
+echo "  [2] wholesale-rebuild sites (\`cp\` to a shell variable in commands/)"
+SITES=""
+if [ -d "$BASE/commands" ]; then
+    SITES=$(grep -nH -E "$REBUILD_RE" "$BASE"/commands/*.md 2>/dev/null || true)
+fi
+
+# The destination is a variable; resolve it to a path SUFFIX by reading that variable's
+# binding **in the same document** and dropping everything up to and including the last
+# `$VAR/` (then the leading variable name, by cutting at the first `/`). Only the suffix is
+# compared, so the binding's own base variable (`$SPECS_DIR`, `$REPO`) never has to be
+# resolved — the question is only "does the record live under there?".
+dest_suffix() {
+    local doc=$1 var=$2 binding
+    binding=$(grep -oE "^[[:space:]]*${var}=\"[^\"]*\"" "$BASE/$doc" 2>/dev/null | head -1)
+    [ -n "$binding" ] || { printf ''; return; }
+    binding=${binding#*=\"}
+    binding=${binding%\"}
+    binding=${binding##*\$}
+    printf '%s' "${binding#*/}"
+}
+
+SITE_N=0
+while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    SITE_N=$((SITE_N + 1))
+    # `grep -nH` emits `path:line:content` — split three ways; comparing the whole remainder
+    # would carry the line number and never match anything.
+    file=${entry%%:*}
+    rest=${entry#*:}
+    num=${rest%%:*}
+    text=${rest#*:}
+    text=${text#"${text%%[![:space:]]*}"}
+    rel=${file#"$BASE"/}
+    var=$(printf '%s' "$text" | grep -oE '\$[A-Za-z_][A-Za-z0-9_]*' | tail -1 | tr -d '$')
+    suffix=$(dest_suffix "$rel" "$var")
+    if [ -z "$suffix" ]; then
+        hit "rebuild site: cannot resolve \$$var in $rel:$num — nothing is proven about it"
+        continue
+    fi
+    ok "rebuild site: $rel:$num → $suffix"
+done <<EOF
+$SITES
+EOF
+if [ "$SITE_N" -eq 0 ]; then
+    skip "no \`cp … \$VAR\` line found in commands/ — nothing is proven about rebuild sites"
+fi
+
+# -----------------------------------------------------------------------------------------
+# 3. The proposition: no record sits where a rebuild lands
+# -----------------------------------------------------------------------------------------
+echo "  [3] no cross-round record sits on a rebuild path"
+CHECKED=0
+while IFS= read -r entry; do
+    [ -n "$entry" ] || continue
+    file=${entry%%:*}
+    rest=${entry#*:}
+    text=${rest#*:}
+    text=${text#"${text%%[![:space:]]*}"}
+    rel=${file#"$BASE"/}
+    var=$(printf '%s' "$text" | grep -oE '\$[A-Za-z_][A-Za-z0-9_]*' | tail -1 | tr -d '$')
+    suffix=$(dest_suffix "$rel" "$var")
+    [ -n "$suffix" ] || continue
+    while IFS= read -r r; do
+        [ -n "$r" ] || continue
+        CHECKED=$((CHECKED + 1))
+        case "$r" in
+            */"$suffix"|"$suffix")
+                hit "a cross-round record lives in an artifact rebuilt wholesale — $r (rebuilt by $rel)" ;;
+            *)
+                ok "not on a rebuild path: $r" ;;
+        esac
+    done <<EOF
+$RECORDS
+EOF
+done <<EOF
+$SITES
+EOF
+if [ "$CHECKED" -eq 0 ]; then
+    skip "no (record × rebuild site) pair to compare — nothing is proven"
+fi
+
+# -----------------------------------------------------------------------------------------
+# ⚠️ Coverage, stated rather than implied: the check is only as wide as its two derivations.
+#    · a record that does not declare itself is invisible here (see check 1)
+#    · a rebuild that is not `cp`-based, or whose destination is not a variable, is invisible
+#      here — e.g. a command that rewrites a file through `awk`/`sed` in place.
+#    Both are the "enumeration narrower than the distribution" shape. Widening either means
+#    widening the derivation, never adding a hand-written row.
+# -----------------------------------------------------------------------------------------
+echo
+if [ "$HITS" -gt 0 ]; then
+    echo "✗ cumulative records: $HITS violation(s)"
+    exit 1
+fi
+echo "✓ cumulative records: no record sits on a rebuild path"

specpro_cli/assets/scripts/bash/verify-deliverables-tracked.sh

@@ -0,0 +1,147 @@
+#!/bin/bash
+#
+# Deliverables-tracked verifier — every deliverable path must be tracked by git.
+#
+# Carrier for: specs/tasks.md -> T150 (carrying ISS-56 ②). The criterion is stated
+# there as: `git ls-files --error-unmatch <path>` holds for EVERY deliverable path.
+#
+# The three deliverable classes it checks (same task):
+#   ① paths named by the Location of each CHECKED task in specs/tasks.md
+#   ② source files under commands/ · templates/ · scripts/ (+ tools/ in this repo)
+#   ③ artifacts declared by the commands' `writes:` blocks — they land in the
+#      artifact repos (specs/ · docs/), so those repos are swept whole
+#
+# ⚠️ SCOPE IS THE SUBJECT, NOT THE WHOLE REPO (ISS-75): the old wording counted
+# ALL untracked-unignored files, which swept in root-level session transcripts
+# (handoff*.md) that are NOT deliverables. A criterion failing on non-subjects
+# invites "fix the criterion to match reality" — shape 1. So this verifier only
+# asserts INSIDE the deliverable dirs and the artifact repos; a root-level
+# transcript is out of scope by construction, not by exemption list.
+#
+# Class ① parsing is deliberately conservative: a backtick segment is checked
+# only when it is unambiguously a path (no spaces, no globs). Under-reporting is
+# accepted (the same discipline as the documented-snippet verifier); a false
+# accusation is not — the contract's stated failure mode is losing credibility.
+#
+# Bash 3.2 compatible by construction — no 4.0+ expansions, no associative arrays.
+# Read-only: nothing is written.
+#
+set -u
+
+REPO=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO" ]; then
+    echo "deliverables-tracked: not inside a git repository"
+    exit 1
+fi
+echo "deliverables-tracked: $REPO"
+FAIL=0
+
+# --- class ② — deliverable source dirs in THIS repo ------------------------
+SRC_DIRS="commands templates scripts tools"
+untracked=$(cd "$REPO" && git ls-files --others --exclude-standard -- $SRC_DIRS)
+if [ -n "$untracked" ]; then
+    FAIL=1
+    echo "✗ class ② — untracked files under deliverable source dirs ($SRC_DIRS):"
+    printf '%s\n' "$untracked" | sed 's/^/      /'
+else
+    echo "✓ class ② — source dirs ($SRC_DIRS): every file tracked"
+fi
+
+# --- class ③ — artifact repos (specs/ · docs/) ------------------------------
+for sub in specs docs; do
+    if [ -e "$REPO/$sub/.git" ]; then
+        u=$(git -C "$REPO/$sub" ls-files --others --exclude-standard)
+        if [ -n "$u" ]; then
+            FAIL=1
+            echo "✗ class ③ — untracked files in the $sub/ artifact repo:"
+            printf '%s\n' "$u" | sed 's/^/      /'
+        else
+            echo "✓ class ③ — artifact repo $sub/: every file tracked"
+        fi
+    fi
+done
+
+# --- class ① — Location paths named by CHECKED tasks ------------------------
+#
+# ⚠️ Judgment is THREE-CONDITIONED, and the reason is measured: backtick segments in
+# a task line include descriptions' code words (function names, flags, FR ids),
+# so "not tracked" alone accuses hundreds of non-paths — a false-accusation rate
+# that would destroy the criterion's credibility on its first run. The verdict
+# therefore needs the file to EXIST first, and (T254 / ISS-235) git to NOT be
+# deliberately ignoring it:
+#   tracked                    -> verified
+#   untracked BUT on disk      -> real violation (written, never committed)
+#   ignored BY DESIGN          -> skipped (a derived deploy mirror — `.claude/`,
+#                                 `.specpro/` — is gitignored on purpose; the
+#                                 deliverable is its source side, covered by the
+#                                 same Location's other path)
+#   not on disk at all         -> skipped (future deliverable / shorthand / note)
+TASKS="$REPO/specs/tasks.md"
+checked_n=0
+skipped_n=0
+if [ -f "$TASKS" ]; then
+    segments=$(sed -n 's/^- \[x\] T[0-9].*$/&/p' "$TASKS" | grep -oE '`[^`]+`' | tr -d '`')
+    while IFS= read -r seg; do
+        [ -z "$seg" ] && continue
+        case "$seg" in
+            *\ *)   skipped_n=$((skipped_n + 1)); continue ;;  # space -> prose/note
+            specs/*) repo_path="$REPO/specs"; rel=${seg#specs/} ;;
+            docs/*)  repo_path="$REPO/docs";  rel=${seg#docs/} ;;
+            /*)      skipped_n=$((skipped_n + 1)); continue ;;  # absolute
+            *)       repo_path="$REPO";        rel=$seg ;;
+        esac
+        # A segment that reduces to an empty path (`specs/` bare) is not a path —
+        # feeding it to git only produces a pathspec error on stderr (T254).
+        if [ -z "$rel" ]; then
+            skipped_n=$((skipped_n + 1))
+            continue
+        fi
+        # Brace expansion, one level: `x.{a,b}.md` -> prefix + each + suffix.
+        case "$rel" in
+            *\{*)
+                pre=${rel%%\{*}
+                tmp=${rel#*\{}
+                mid=${tmp%%\}*}
+                suf=${tmp#*\}}
+                for br in $(printf '%s' "$mid" | tr ',' ' '); do
+                    one="$pre$br$suf"
+                    if [ -z "$one" ]; then
+                        skipped_n=$((skipped_n + 1))
+                        continue
+                    fi
+                    if git -C "$repo_path" check-ignore -q -- "$one"; then
+                        skipped_n=$((skipped_n + 1))  # ignored by design: derived mirror, not a deliverable
+                    elif git -C "$repo_path" ls-files --error-unmatch -- "$one" >/dev/null 2>&1; then
+                        checked_n=$((checked_n + 1))
+                    elif [ -f "$repo_path/$one" ]; then
+                        FAIL=1
+                        echo "✗ class ① — task Location file exists but is NOT tracked: $seg (expanded: $one)"
+                    else
+                        skipped_n=$((skipped_n + 1))
+                    fi
+                done
+                continue
+                ;;
+        esac
+        if git -C "$repo_path" check-ignore -q -- "$rel"; then
+            skipped_n=$((skipped_n + 1))  # ignored by design: derived mirror, not a deliverable
+        elif git -C "$repo_path" ls-files --error-unmatch -- "$rel" >/dev/null 2>&1; then
+            checked_n=$((checked_n + 1))
+        elif [ -f "$repo_path/$rel" ]; then
+            FAIL=1
+            echo "✗ class ① — task Location file exists but is NOT tracked: $seg"
+        else
+            skipped_n=$((skipped_n + 1))
+        fi
+    done <<EOF
+$segments
+EOF
+    echo "✓ class ① — task Locations: $checked_n path(s) verified tracked · $skipped_n skipped (not on disk / not a path / ignored-by-design)"
+fi
+
+if [ "$FAIL" -eq 0 ]; then
+    echo "✓ deliverables-tracked: every deliverable path is tracked"
+    exit 0
+fi
+echo "✗ deliverables-tracked: untracked deliverables found — commit them or fix the criterion"
+exit 1

specpro_cli/assets/scripts/bash/verify-deployment.sh

@@ -0,0 +1,239 @@
+#!/bin/bash
+#
+# Deployment-drift verifier — every mirror group must match its source.
+#
+# Why this exists: 宪法 Q1 requires that "一份内容在多个位置存在时，它们不得在无人
+# 察觉的情况下分叉", and 宪法 1.1 requires that "命令与模板的改动与部署动作成对提交,
+# 不留'已改源未部署'的中间态". Before this script, the only thing enforcing either was
+# an instruction to run three `diff` commands by hand — and "记得跑" is not an enforcement
+# point. The enforcement point is `scripts/git-hooks/pre-commit` §3, which calls this.
+#
+# 核验强度按目标形态确定 (plan.md → Constraint 1), and the form is judged FIRST:
+#   same    — the mirror is a byte-for-byte copy  ⇒ diff -rq, zero output expected
+#   derived — the mirror is produced by a rule (e.g. the skills layout)  ⇒ "同一源 +
+#             同一基类 ⇒ 同一产出" is the criterion, and **it is not implemented here**
+#
+# ⚠️ A group whose form is `derived` FAILS, loudly. That is deliberate: the alternative
+# is to run a byte-comparison against a target that cannot be byte-equal, which reports
+# failure for a correct deployment — or to skip it, which reports success for an
+# unchecked one. A verifier that cannot check a group must say so, not pass it.
+#
+# ⚠️ A missing mirror FAILS too — never "skip". An absent group and a clean group are
+# indistinguishable in the output otherwise, which is the 空跑报绿 shape (ISS-83).
+#
+# Usage:  scripts/bash/verify-deployment.sh
+#         DEPLOY_HOOK_BASE=<path> scripts/bash/verify-deployment.sh   (verify a copy)
+# Exit:   0 = every group is in sync;  1 = at least one violation (details printed)
+
+# ⚠️ NOT `set -e`: this script's logic is driven by reading the exit codes of `diff`, and
+# `set -e` would end it before the reading happens (宪法 2.2.2, second carve-out — "其逻辑
+# 以退出码为输入的核验脚本").
+set -uo pipefail
+
+# The repository root is resolved from THIS script's location, not from the caller's cwd:
+# the pre-commit hook runs from the repo root, but a fixture case runs the script from a
+# temporary tree, and a cwd-relative base would then verify the wrong place (or nothing).
+# `DEPLOY_HOOK_BASE` overrides it for exactly that fixture case.
+#
+# ⚠️ **Position-independent, and the result is TESTED** (T180 / `ISS-124`): the previous
+# `dirname "${BASH_SOURCE[0]}"/../..` is correct only from the SOURCE layout — from the
+# deployed mirror (`.specpro/scripts/bash/…`) it lands one level short, on `.specpro`.
+# ⚠️ That failure is silent in the worst direction: a mirror table read against the
+# wrong tree still prints "✓ in sync", indistinguishable from a real pass. And this
+# script is the one the pre-commit hook calls, so the wrong tree is the likely one.
+#
+# Order: git (correct from BOTH positions) → the two candidate depths, each tested.
+# The sentinel tests the RESULT, not the method — including for an override, since an
+# override that names a non-root is exactly what it exists to catch.
+is_repo_root() { [ -d "$1/commands" ] && [ -d "$1/templates" ] && [ -d "$1/scripts" ]; }
+
+resolve_base() {
+    local cand here
+    if cand=$(git rev-parse --show-toplevel 2>/dev/null) && [ -n "$cand" ] && is_repo_root "$cand"; then
+        printf '%s' "$cand"; return 0
+    fi
+    here=$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+    for cand in "$here/../.." "$here/../../.."; do
+        cand=$(CDPATH="" cd "$cand" 2>/dev/null && pwd) || continue
+        is_repo_root "$cand" && { printf '%s' "$cand"; return 0; }
+    done
+    return 1
+}
+
+if [ -n "${DEPLOY_HOOK_BASE:-}" ]; then
+    BASE="$DEPLOY_HOOK_BASE"
+else
+    BASE=$(resolve_base) || BASE=''
+fi
+
+if ! is_repo_root "$BASE"; then
+    echo "✗ BASE is not a repository root: '${BASE:-<unresolved>}'" >&2
+    echo "  Expected it to contain commands/ , templates/ and scripts/ ." >&2
+    if [ -n "${DEPLOY_HOOK_BASE:-}" ]; then
+        echo "  Source: the DEPLOY_HOOK_BASE override." >&2
+    else
+        echo "  Source: auto-resolution (git toplevel, then the script's two possible depths)." >&2
+    fi
+    echo "  ⚠️ Every group below would be compared against a tree this script never read —" >&2
+    echo "     an absent mirror and an in-sync mirror are the same output otherwise." >&2
+    exit 1
+fi
+
+# --- the mirror table ---------------------------------------------------------------
+# 源 | 镜像 | 形态.  One row per group. The form column is the authority for the check
+# below — it is NOT guessed from the target's shape, because guessing turns a design
+# decision into a filesystem accident.
+PAIRS=(
+    "commands|.claude/skills|derived"
+    "templates|.specpro/templates|same"
+    "scripts/bash|.specpro/scripts/bash|same"
+)
+
+# --- the exclusion list, and why it is not a hidden default --------------------------
+# `scripts/` entries with no mirror are listed HERE, by name, with a reason. A directory
+# that is neither mirrored nor listed is a violation (§reverse below) — otherwise the
+# next un-mirrored directory joins silently, which is the same silent-uncoverage the
+# derived section list was removed to fix (ISS-88).
+#
+# ⚠️ `powershell` is here because the bootstrap instance does not need it: the mirror
+# exists so THIS repository can run its own toolchain, and this repository is not Windows.
+# The PowerShell implementations ship to user projects through the CLI's asset snapshot,
+# which has its own verifier (Constraint 4). ⇒ It is excluded by DECISION, not by neglect.
+EXCLUDED_IN_SCRIPTS="powershell git-hooks install-git-hooks.sh"
+
+FAIL=0
+echo "Deployment drift: $BASE"
+echo
+
+for pair in "${PAIRS[@]}"; do
+    src="${BASE}/${pair%%|*}"
+    rest="${pair#*|}"
+    dst="${BASE}/${rest%%|*}"
+    form="${rest##*|}"
+
+    printf "  [%s] %s → %s\n" "$form" "${pair%%|*}" "${rest%%|*}"
+
+    if [ ! -e "$src" ]; then
+        echo "    ✗ source does not exist: $src"
+        echo "      → the table names a group that is not there; fix the table or restore the source."
+        FAIL=1
+        continue
+    fi
+
+    # ⚠️ NOT `continue` / NOT `: ok`. A missing mirror is a violation, and saying so is
+    # the whole difference between a verifier and a decoration.
+    if [ ! -d "$dst" ]; then
+        echo "    ✗ mirror missing: $dst"
+        echo "      → deploy the source, or add the group to EXCLUDED_* by name with a reason."
+        echo "        A missing target MUST NOT be skipped: an absent group and a clean one look identical."
+        FAIL=1
+        continue
+    fi
+
+    if [ "$form" = "derived" ]; then
+        # Reproducible check (FR-007 / 宪法 1.1 T3): same source + same base class ⇒
+        # same output. The mirror is produced by THIS repo's install CLI, so the check
+        # runs that CLI twice from the CURRENT source into two temp dirs — the two
+        # outputs must agree byte-for-byte (determinism), and the mirror must equal the
+        # first (sync). A stale mirror therefore fails exactly like a drifted copy,
+        # which is the drift this gate exists to catch. Two installs, not one: a single
+        # install-vs-mirror comparison would silently accept a CLI that embeds
+        # timestamps or paths into its output.
+        #
+        # ⚠️ No installer ⇒ UNVERIFIED ⇒ FAIL. Never skip: an unchecked group that
+        # reports success is indistinguishable from a clean one.
+        py=""
+        for pycand in "$BASE/tools/install/.venv/bin/python" "$BASE/tools/install/.venv/Scripts/python.exe"; do
+            if [ -x "$pycand" ]; then py="$pycand"; break; fi
+        done
+        if [ -z "$py" ]; then
+            echo "    ✗ derived check cannot run: no install CLI venv under tools/install/."
+            echo "      → the derived mirror is produced by this repo's own CLI; without it this"
+            echo "        group is UNVERIFIED, and reporting success would be a false pass."
+            FAIL=1
+            continue
+        fi
+        tmp1=$(mktemp -d "${TMPDIR:-/tmp}/specpro-derived.XXXXXX") || tmp1=""
+        tmp2=$(mktemp -d "${TMPDIR:-/tmp}/specpro-derived.XXXXXX") || tmp2=""
+        if [ -z "$tmp1" ] || [ -z "$tmp2" ]; then
+            echo "    ✗ derived check cannot run: mktemp failed."
+            FAIL=1
+            continue
+        fi
+        inst_ok=1
+        ( cd "$BASE/tools/install" && "$py" -c "from specpro_cli.cli.entry import app; app()" init "$tmp1" --agent claude --source "$BASE" >/dev/null 2>&1 ) || inst_ok=0
+        ( cd "$BASE/tools/install" && "$py" -c "from specpro_cli.cli.entry import app; app()" init "$tmp2" --agent claude --source "$BASE" >/dev/null 2>&1 ) || inst_ok=0
+        if [ "$inst_ok" = 0 ] || [ ! -d "$tmp1/.claude/skills" ] || [ ! -d "$tmp2/.claude/skills" ]; then
+            echo "    ✗ derived check cannot run: the install CLI failed to produce .claude/skills."
+            echo "      → fix the CLI or its venv; until then this group is UNVERIFIED (never a silent pass)."
+            FAIL=1
+            rm -rf "$tmp1" "$tmp2"
+            continue
+        fi
+        if [ -n "$(diff -rq -x '.DS_Store' "$tmp1/.claude/skills" "$tmp2/.claude/skills" 2>&1)" ]; then
+            echo "    ✗ derived: two installs of the same source DISAGREE — output is not reproducible."
+            rm -rf "$tmp1" "$tmp2"
+            FAIL=1
+            continue
+        fi
+        drift=$(diff -rq -x '.DS_Store' "$tmp1/.claude/skills" "$dst" 2>&1)
+        # Normalize the temp prefix away: the drift lines must not depend on where the
+        # fresh install landed (bash and the PowerShell twin resolve different temp
+        # roots, and the parity contract is "same stdout").
+        drift=${drift//"$tmp1"/'<fresh-install>'}
+        rm -rf "$tmp1" "$tmp2"
+        if [ -n "$drift" ]; then
+            echo "    ✗ derived drift (mirror ≠ fresh install of the current source):"
+            echo "$drift" | sed 's/^/      /'
+            FAIL=1
+        else
+            echo "    ✓ derived: reproducible (2 installs agree) and in sync with the current source"
+        fi
+        continue
+    fi
+
+    drift=$(diff -rq -x '.DS_Store' "$src" "$dst" 2>&1)
+    if [ -n "$drift" ]; then
+        echo "    ✗ drift:"
+        echo "$drift" | sed 's/^/      /'
+        FAIL=1
+    else
+        echo "    ✓ byte-identical"
+    fi
+done
+
+# --- reverse assertion: nothing under scripts/ is silently unmirrored -----------------
+echo
+if [ -d "$BASE/scripts" ]; then
+    uncovered=""
+    for entry in "$BASE/scripts"/*; do
+        [ -e "$entry" ] || continue
+        name=$(basename "$entry")
+        case " $EXCLUDED_IN_SCRIPTS " in *" $name "*) continue ;; esac
+        covered=0
+        for pair in "${PAIRS[@]}"; do
+            case "${pair%%|*}" in "scripts/$name"*) covered=1 ;; esac
+        done
+        [ "$covered" = 0 ] && uncovered="$uncovered $name"
+    done
+    if [ -n "$uncovered" ]; then
+        echo "  ✗ scripts/ entries that are neither mirrored nor listed as excluded:"
+        printf '      %s\n' $uncovered
+        echo "      → add a mirror row, or add the name to EXCLUDED_IN_SCRIPTS with a reason."
+        echo "        Otherwise the next un-mirrored directory joins without anyone noticing."
+        FAIL=1
+    else
+        echo "  ✓ every scripts/ entry is either mirrored or listed as excluded"
+    fi
+fi
+
+# --- verdict --------------------------------------------------------------------------
+echo
+if [ "$FAIL" = 0 ]; then
+    echo "✓ deployment: every group is in sync"
+    exit 0
+else
+    echo "✗ deployment: VIOLATIONS FOUND (see above)"
+    echo "  → 宪法 1.1: 部署是该次落地的收尾动作 —— 源与镜像的差异不得跨提交存在。"
+    exit 1
+fi

specpro_cli/assets/scripts/bash/verify-frontmatter-yaml.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+#
+# Frontmatter-YAML verifier — every frontmatter block in commands/*.md MUST parse
+# as YAML. Carrier for: specs/tasks.md -> T152 (carrying ISS-59 ① · ISS-81).
+#
+# Why this exists: CLAUDE.md states the command topology is NOT prose but the
+# machine-readable `handoffs:` declarations — and the `writes:` ownership map
+# lives in the same frontmatter block. A frontmatter block that fails to parse
+# and a block that does not exist are INDISTINGUISHABLE to every executor
+# (shape 3: two states no mechanism tells apart, and nothing reports it).
+# The triggering instance was one unquoted colon in a `description:` — fixed
+# by hand, leaving "nothing checks the next one". This script is the check
+# for the next one.
+#
+# Scope (ISS-81 ruling, narrowing an over-broad original): "凡有 frontmatter
+# 的产物都必须可解析" — templates/ carry no frontmatter and are OUT of the scan
+# face. The deployed mirror .claude/skills/ (derived form since T090) is generated
+# from commands/ by the install CLI and held by the deployment verifier, so scanning
+# the source side covers both.
+#
+# Bash 3.2 compatible. Read-only. Requires python3 with PyYAML (the install CLI
+# is a Python package — a maintained checkout has both).
+#
+set -u
+
+REPO=$(git rev-parse --show-toplevel 2>/dev/null)
+if [ -z "$REPO" ]; then
+    echo "frontmatter-yaml: not inside a git repository"
+    exit 1
+fi
+
+COMMANDS_DIR="$REPO/commands"
+if [ ! -d "$COMMANDS_DIR" ]; then
+    echo "frontmatter-yaml: no commands/ directory at $REPO — nothing to scan"
+    exit 1
+fi
+
+python3 - "$COMMANDS_DIR" <<'PY'
+import glob
+import os
+import sys
+
+import yaml
+
+d = sys.argv[1]
+parsed = 0
+bad = []
+for f in sorted(glob.glob(os.path.join(d, '*.md'))):
+    with open(f, encoding='utf-8') as fh:
+        t = fh.read()
+    if not t.startswith('---'):
+        continue  # "凡有 frontmatter 的产物" — absent frontmatter is out of scope
+    parsed += 1
+    end = t.find('\n---', 3)
+    try:
+        yaml.safe_load(t[3:end])
+    except Exception as ex:
+        print(f"✗ {os.path.relpath(f, d)}: {str(ex).splitlines()[0]}")
+        bad.append(f)
+print(f"frontmatter-yaml: {parsed} frontmatter block(s) parsed · {len(bad)} failed")
+sys.exit(1 if bad else 0)
+PY
+exit $?