specpro-cli 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,376 @@
+#!/bin/bash
+#
+# Ledger Integrity Verification Script
+# Verifies specs/implement_issues.md structural invariants.
+#
+# Why this exists (2026-09-12): the ledger is a POSITION-STRUCTURED file —
+# an entry's section is decided purely by where it sits in the file. Every
+# writer that "appends" therefore silently depends on which section happens
+# to be last, and that fact changes as sections are added. Observed failure:
+# ISS-049 (a [tasks]-side finding) was appended to the END OF THE FILE and
+# landed in [test-plan], whose consumer has no mandate to act on it — the
+# entry looked registered, the statistics table looked plausible, nothing
+# errored. Two statistics drifts were found in the same review, also silent.
+#
+# Invariants checked:
+#   1. The four phase sections exist, in canonical order
+#   2. Every issue entry belongs to one of those sections (nothing orphaned
+#      outside a section — the "appended past the sentinel" signature)
+#   3. The statistics table row for each section matches its actual entry count
+#   4. Pending-Items names only entries that exist as pending entries
+#   5. The file ends with exactly one newline (append-based writers rely on it;
+#      a missing trailing newline fuses the next entry onto the previous line)
+#   6. Every entry block carries exactly ONE Related line, and every field line
+#      lies INSIDE some entry block. A block runs to the nearest of: the next
+#      entry, the next section heading, the sentinel. Both directions matter —
+#      a tail split off into the next block and a tail written past a boundary
+#      are the same defect seen from two sides.
+#
+# Usage:  .specpro/scripts/bash/verify-ledger.sh
+#         LEDGER=<path> .specpro/scripts/bash/verify-ledger.sh   (verify a copy — used by its own tests)
+# Exit:   0 = all invariants hold;  1 = at least one violation (details printed)
+
+set -uo pipefail
+
+LEDGER="${LEDGER:-specs/implement_issues.md}"
+# The contract is resolved RELATIVE TO THE LEDGER, not to a fixed path: in the
+# two-repository layout this script runs from the root repo (ledger at
+# specs/implement_issues.md) AND from inside the specs repo (ledger at
+# implement_issues.md), and a hardcoded specs/contracts/... resolves to nothing
+# in the second case — where the verifier then refuses to run at all. The hook
+# caught exactly that on the first commit after this change.
+CONTRACT="${CONTRACT:-$(dirname "$LEDGER")/contracts/ledger.md}"
+
+# --- 0. the section list is DERIVED, not transcribed -------------------------
+# `## Sections and their consumers` in the contract is the single source for which
+# sections exist, in what order. This array used to be a hand-copied duplicate of
+# that table, and the two diverged exactly the way two sources of one fact do: the
+# contract gained a row for a section the ledger did not have yet, and **nothing
+# reported it** — invariant #1 was violated for as long as that lasted. A copy is
+# not a check; deriving one from the other is.
+SECTIONS=()
+if [ -f "$CONTRACT" ]; then
+    while IFS= read -r s; do
+        # Table rows look like: | `<name>` | <consumer> | <what it does> |
+        [ -n "$s" ] && SECTIONS+=("$s")
+    done < <(sed -n '/^## Sections and their consumers/,/^## /p' "$CONTRACT" \
+             | sed -n 's/^| `\[\([a-z-]*\)\]`.*/\1/p')
+fi
+
+if [ "${#SECTIONS[@]}" -eq 0 ]; then
+    # ⚠️ An empty list is NOT "nothing to check": every section-level check below
+    # would then pass vacuously, and that is indistinguishable from a clean ledger.
+    echo "✗ could not derive the section list from $CONTRACT" >&2
+    echo "   A verifier with no sections to check reports success without checking anything." >&2
+    echo "   Fix: run from the repository root, or set CONTRACT=<path to the ledger contract>." >&2
+    exit 1
+fi
+
+FAIL=0
+
+# --- 0b. and the comparison runs BOTH ways -----------------------------------
+# Deriving the list closes "the contract names a section the ledger lacks". It does
+# NOT close the reverse: a section present in the ledger but absent from the contract
+# is simply never iterated, so it is never checked — and the run still reports clean.
+# That is the same silent-uncoverage the derived list was meant to remove, one
+# direction over.
+if [ -f "$LEDGER" ]; then
+    in_ledger=$(grep -oE '^## \[[a-z-]+\] Phase Issues$' "$LEDGER" | sed 's/^## \[\([a-z-]*\)\].*/\1/' | sort -u)
+    in_contract=$(printf '%s\n' "${SECTIONS[@]}" | sort -u)
+    undeclared=$(comm -23 <(printf '%s\n' "$in_ledger") <(printf '%s\n' "$in_contract"))
+    if [ -n "$undeclared" ]; then
+        echo "✗ section(s) present in the ledger but absent from the contract's table:" >&2
+        printf '    %s\n' $undeclared >&2
+        echo "    → nothing checks them: the verifier iterates the contract's list." >&2
+        echo "      Add the row to $CONTRACT (with its consumer), or remove the section." >&2
+        exit 1
+    fi
+fi
+
+if [ ! -f "$LEDGER" ]; then
+    echo "✗ $LEDGER not found (run from the repository root)" >&2
+    exit 1
+fi
+
+echo "Ledger integrity: $LEDGER"
+echo
+
+# --- 1. sections exist, in canonical order -----------------------------------
+seen=""
+order_ok=1
+for s in "${SECTIONS[@]}"; do
+    line=$(grep -n "^## \[$s\] Phase Issues$" "$LEDGER" | head -1 | cut -d: -f1)
+    if [ -z "$line" ]; then
+        echo "✗ missing section: ## [$s] Phase Issues"
+        FAIL=1; order_ok=0
+    else
+        seen="$seen $line"
+        printf "  ✓ [%-9s] heading at line %s\n" "$s" "$line"
+    fi
+done
+if [ "$order_ok" = 1 ]; then
+    sorted=$(echo $seen | tr ' ' '\n' | sort -n | tr '\n' ' ')
+    [ "$(echo $seen)" = "${sorted% }" ] || { echo "✗ sections are not in canonical order"; FAIL=1; }
+fi
+
+# --- 2. no orphaned entries (entry outside every section) --------------------
+# An entry is orphaned when it appears after the last section's heading but
+# outside it — in practice: appended after the end-of-file sentinel.
+last_heading=$(grep -n "^## \[.*\] Phase Issues$" "$LEDGER" | tail -1 | cut -d: -f1)
+sentinel=$(grep -n "^-->$" "$LEDGER" | tail -1 | cut -d: -f1)
+if [ -n "$sentinel" ] && [ -n "$last_heading" ] && [ "$sentinel" -gt "$last_heading" ]; then
+    orphan=$(awk -v s="$sentinel" 'NR>s && /^- \[[ x]\] ISS-/' "$LEDGER")
+    if [ -n "$orphan" ]; then
+        echo "✗ orphaned entry after the end-of-file sentinel (line $sentinel):"
+        echo "$orphan" | cut -c1-90 | sed 's/^/      /'
+        echo "      → it belongs to no section; move it into its own section"
+        FAIL=1
+    else
+        echo "  ✓ no entries appended past the end-of-file sentinel"
+    fi
+fi
+
+# --- 3. statistics table matches actual counts -------------------------------
+echo
+for s in "${SECTIONS[@]}"; do
+    h=$(grep -n "^## \[$s\] Phase Issues$" "$LEDGER" | head -1 | cut -d: -f1)
+    [ -z "$h" ] && continue
+    # Section body runs until the next '## [' heading, the end-of-file sentinel,
+    # or EOF — whichever comes first. Stopping at the sentinel matters: content
+    # appended past it is orphaned and must NOT be counted as part of the last
+    # section (otherwise one misfiling is reported twice, as an orphan AND as a
+    # count mismatch, and the count mismatch points at the wrong section).
+    next=$(awk -v s="$h" 'NR>s && (/^## \[/ || /^-->$/){print NR; exit}' "$LEDGER")
+    if [ -n "$next" ]; then
+        body=$(awk -v a="$h" -v b="$next" 'NR>a && NR<b' "$LEDGER")
+    else
+        body=$(awk -v a="$h" 'NR>a' "$LEDGER")
+    fi
+    res=$(echo "$body" | grep -c "^- \[x\] ISS-")
+    pen=$(echo "$body" | grep -c "^- \[ \] ISS-")
+    tot=$((res + pen))
+    row=$(grep "^| \[$s\]" "$LEDGER" | head -1)
+    t_tot=$(echo "$row" | awk -F'|' '{gsub(/ /,"",$3); print $3}')
+    t_res=$(echo "$row" | awk -F'|' '{gsub(/ /,"",$4); print $4}')
+    t_pen=$(echo "$row" | awk -F'|' '{gsub(/ /,"",$5); print $5}')
+    if [ "$tot" = "$t_tot" ] && [ "$res" = "$t_res" ] && [ "$pen" = "$t_pen" ]; then
+        printf "  ✓ [%-9s] actual %s/%s/%s = table\n" "$s" "$tot" "$res" "$pen"
+    else
+        printf "  ✗ [%-9s] actual %s/%s/%s  ≠  table %s/%s/%s\n" "$s" "$tot" "$res" "$pen" "$t_tot" "$t_res" "$t_pen"
+        # Direction matters — the two directions have different root causes and
+        # different correct fixes. Telling the reader to "fix the table" is the
+        # wrong advice for the over-count direction (observed 2026-09-13): there
+        # the entry was never written, and the fix is to write it.
+        if [ "$t_tot" -gt "$tot" ] 2>/dev/null; then
+            echo "      → table EXCEEDS the section by $((t_tot - tot)): the summary claims entries that do not exist."
+            echo "        Signature of a SKIPPED WRITE — most often an idempotency guard that searched"
+            echo "        the whole file for the ID and matched a mention (the statistics Pending-Items"
+            echo "        column, the Last Updated line, a cross-reference) instead of the entry itself."
+            echo "        Fix: write the missing entry body (and confirm the guard matches '^- \\[[x ]\\] ISS-<N>:' )."
+        elif [ "$t_tot" -lt "$tot" ] 2>/dev/null; then
+            echo "      → section EXCEEDS the table by $((tot - t_tot)): the derived summary was not updated."
+            echo "        Fix: update the table (the section entries are authoritative)."
+        else
+            echo "      → counts agree but the resolved/pending split differs; reconcile against the section."
+        fi
+        FAIL=1
+    fi
+done
+
+# --- 4. Pending-Items column names only entries that exist -------------------
+# ID-level check, independent of the counts: every ID listed in a section's
+# Pending-Items column must exist as a pending entry in THAT section. This is
+# the direct signature of the skipped-write defect — a summary naming an entry
+# that was never written. Counts can coincide (one skipped + one un-bumped
+# elsewhere) while this still fails, so it is not redundant with check 3.
+echo
+for s in "${SECTIONS[@]}"; do
+    h=$(grep -n "^## \[$s\] Phase Issues$" "$LEDGER" | head -1 | cut -d: -f1)
+    [ -z "$h" ] && continue
+    next=$(awk -v s="$h" 'NR>s && (/^## \[/ || /^-->$/){print NR; exit}' "$LEDGER")
+    if [ -n "$next" ]; then
+        body=$(awk -v a="$h" -v b="$next" 'NR>a && NR<b' "$LEDGER")
+    else
+        body=$(awk -v a="$h" 'NR>a' "$LEDGER")
+    fi
+    named=$(grep "^| \[$s\]" "$LEDGER" | head -1 | awk -F'|' '{print $6}' | grep -oE 'ISS-[0-9]+' | sort -u)
+    if [ -z "$named" ]; then
+        printf "  ✓ [%-9s] Pending-Items column names no IDs\n" "$s"
+        continue
+    fi
+    miss=""
+    for id in $named; do
+        # A herestring, not a pipe. Under `pipefail`, `echo "$body" | grep -q …` can
+        # return 141: grep exits early on a match, echo takes SIGPIPE writing the rest,
+        # and the pipeline's status then reports failure. An entry that IS present reads
+        # as missing — and only sometimes, because the race is decided by scheduling.
+        # A verdict that is not a function of the input is not a verdict.
+        grep -qE "^- \[ \] ${id}:" <<<"$body" || miss="$miss $id"
+    done
+    if [ -z "$miss" ]; then
+        printf "  ✓ [%-9s] every named pending ID exists as an entry\n" "$s"
+    else
+        printf "  ✗ [%-9s] Pending-Items names %s but no such pending entry exists in this section\n" "$s" "$miss"
+        echo "      → the summary names an entry the file does not contain — a skipped or lost write,"
+        echo "        not a formatting slip. Write the entry body, or correct the column if it was over-bumped."
+        FAIL=1
+    fi
+done
+
+# --- 4b. a completed hand-off names an entry that EXISTS in its target section --------
+# ISS-110 / ISS-93 / ISS-90 ③: a decision whose closing line was "hand this to
+# /specpro-tasks --review-issues" created no `[tasks]` entry — so that command read an
+# EMPTY queue and exited having done nothing, while the decision read as complete. The
+# channel was never the problem (登记即路由 — any command may append to any section);
+# what was missing was the OBLIGATION to write the entry, and a point where its absence
+# stops something. This is that point.
+#
+# ⚠️ **The anchor is a LINE-START form, never a full-text match** (TOOL-009). The ledger is
+# full of prose ABOUT hand-offs — this very comment is an example — and a check that
+# matched a mention would fire on the discussion instead of the act. The form is fixed by
+# the rule in `commands/specpro.plan.md`, and it is fixed precisely so this can be judged
+# mechanically: an intention scattered through prose has no shape to test.
+#
+# ⚠️ **Only `[x]` entries are checked.** A `[ ]` entry has not handed anything off yet;
+# demanding its target exist would punish the correct order of work.
+#
+# ⚠️ The arrow is the literal `→`. It is part of the anchor, not decoration: a rule that
+# can be written three ways cannot be found by one pattern.
+echo
+handoffs=$(awk '
+    /^- \[[ x]\] ISS-[0-9]+:/            { cur = $0 }
+    /^  \*\*移交\*\*: \[[a-z-]+\] → ISS-[0-9]+/ { if (cur ~ /^- \[x\]/) print NR "\t" cur "\t" $0 }
+' "$LEDGER")
+
+if [ -z "$handoffs" ]; then
+    echo "  ✓ no completed entry carries a hand-off line (nothing to resolve)"
+else
+    bad=0
+    while IFS="$(printf '\t')" read -r lineno entry_line handoff_line; do
+        target=$(printf '%s' "$handoff_line" | sed -E 's/.*\[([a-z-]+)\].*/\1/')
+        hid=$(printf '%s' "$handoff_line" | grep -oE 'ISS-[0-9]+' | head -1)
+        src=$(printf '%s' "$entry_line" | grep -oE 'ISS-[0-9]+' | head -1)
+
+        # (a) the target must be a partition the contract actually defines. A hand-off to
+        # a partition nobody consumes is a dead end wearing a route's clothes (Q2).
+        if ! printf '%s\n' "${SECTIONS[@]}" | grep -qx "$target"; then
+            printf "  ✗ hand-off at line %s targets [%s], which the contract does not define\n" "$lineno" "$target"
+            echo "      → the named partition has no consumer; a hand-off there is a dead end."
+            bad=1
+            continue
+        fi
+
+        # (b) the named entry must exist IN THAT SECTION. Not "somewhere in the file" —
+        # the whole point of a section is that a specific consumer reads it.
+        h=$(grep -n "^## \[$target\] Phase Issues$" "$LEDGER" | head -1 | cut -d: -f1)
+        next=$(awk -v s="$h" 'NR>s && (/^## \[/ || /^-->$/){print NR; exit}' "$LEDGER")
+        if [ -n "$next" ]; then
+            body=$(awk -v a="$h" -v b="$next" 'NR>a && NR<b' "$LEDGER")
+        else
+            body=$(awk -v a="$h" 'NR>a' "$LEDGER")
+        fi
+        # A herestring rather than a pipe — see check 4's note on SIGPIPE under `pipefail`.
+        if grep -qE "^- \[[ x]\] ${hid}:" <<<"$body"; then
+            printf "  ✓ hand-off %s → [%s] %s resolves\n" "$src" "$target" "$hid"
+        else
+            printf "  ✗ hand-off at line %s names %s in [%s], but no such entry exists there\n" \
+                   "$lineno" "$hid" "$target"
+            echo "      → the decision says the work moved; the target section says nothing arrived."
+            echo "        Register the entry in that section (登记即路由), or drop the hand-off line."
+            bad=1
+        fi
+    done <<EOF
+$handoffs
+EOF
+    [ "$bad" = 0 ] || FAIL=1
+fi
+
+# --- 5. exactly one trailing newline ----------------------------------------
+echo
+if [ -z "$(tail -c 1 "$LEDGER")" ] && [ -n "$(tail -c 2 "$LEDGER" | head -c 1)" ]; then
+    echo "  ✓ single trailing newline"
+else
+    echo "  ✗ file does not end with exactly one newline"
+    echo "      → append-based writers will fuse the next entry onto the previous line"
+    FAIL=1
+fi
+
+# --- 6. every entry block is bounded, and carries exactly one tail --------
+# The ledger is position-structured at TWO levels: an entry is decided by
+# position within a section, and a section by position within the file. The
+# checks above see neither: a misplaced tail changes no count, and check 2
+# looks only at entry HEADERS. Observed three times — twice a `**Resolution**`
+# landed past the end-of-file sentinel, once past a SECTION boundary. Same
+# writer bug, different boundary; each time every check above reported OK.
+echo
+if ! BOUND=$(awk '
+    function flush_block() {
+        if (entry == "") return
+        if (rel != 1 || res > 1) printf "BLOCK|%s|%d|%d\n", eid, rel, res
+    }
+    /^- \[[ x]\] ISS-/ {
+        flush_block()
+        entry = $0; rel = 0; res = 0
+        eid = (match($0, /ISS-[0-9]+/)) ? substr($0, RSTART, RLENGTH) : "?"
+        next
+    }
+    /^## \[/ || /^-->/ { flush_block(); entry = ""; next }
+    /^  \*\*Related\*\*:/    { if (entry == "") printf "STRAY|%d|Related\n", NR; else rel++ }
+    /^  \*\*Resolution\*\*/ { if (entry == "") printf "STRAY|%d|Resolution\n", NR; else res++ }
+    END { flush_block() }
+' "$LEDGER"); then
+    echo "  ✗ the block-bounds check itself could not be evaluated (awk returned non-zero)"
+    echo "      → a check that fails to run must NOT report as passing: an empty result"
+    echo "        from a broken expression is indistinguishable from a clean ledger."
+    FAIL=1
+elif [ -z "$BOUND" ]; then
+    echo "  ✓ every entry block is bounded and carries exactly one Related line"
+else
+    while IFS='|' read -r kind a b c; do
+        [ -z "$kind" ] && continue
+        if [ "$kind" = "BLOCK" ]; then
+            printf "  ✗ %s: block carries Related=%s Resolution=%s (want 1 and <=1)\n" "$a" "$b" "$c"
+            echo "      → the block does not end where it should: a tail line was split off,"
+            echo "        or a foreign line was absorbed."
+        else
+            printf "  ✗ line %s carries a %s OUTSIDE any entry block\n" "$a" "$b"
+            echo "      → a field line was written past a boundary; it belongs to no entry,"
+            echo "        so no reader will ever attribute it correctly."
+        fi
+    done <<< "$BOUND"
+    FAIL=1
+fi
+
+# --- 7. entry IDs are globally unique ---------------------------------------
+# Why this exists (T206 / ISS-166): every consumer ADDRESSES an entry by its ID —
+# `grep -qE '^- \[[x ]\] ISS-<N>:'` is the marking form this repo documents. Two entries
+# sharing one make that address name neither of them, and NOTHING ELSE reports it: the
+# statistics table still reconciles (bump the count and it agrees), the section checks
+# still pass, the sentinel still holds. The collision is silent until someone reads the
+# whole file — the failure TOOL-011 recorded for its own numbering, in a file that has
+# since been retired while this one inherited none of it.
+#
+# ⚠️ `sort -n`, never `sort`: the IDs are variable width, so `ISS-100` sorts BEFORE
+# `ISS-97` lexicographically. That is also why "take the next number" must use a numeric
+# sort — see the same note in commands/specpro.implement.md.
+echo
+DUP=$(grep -oE '^- \[[x ]\] ISS-[0-9]+:' "$LEDGER" | grep -oE '[0-9]+' | sort -n | uniq -d)
+if [ -z "$DUP" ]; then
+    echo "  ✓ entry IDs are unique"
+else
+    echo "  ✗ these entry IDs are used more than once:$(printf ' %s' $DUP)"
+    echo "      → an ID is how a --review-issues run ADDRESSES an entry; two entries"
+    echo "        sharing one mean the address names neither of them, and the counts"
+    echo "        still reconcile, so nothing else would have reported this."
+    FAIL=1
+fi
+
+# --- verdict -----------------------------------------------------------------
+echo
+if [ "$FAIL" = 0 ]; then
+    echo "✓ ledger integrity: all invariants hold"
+    exit 0
+else
+    echo "✗ ledger integrity: VIOLATIONS FOUND (see above)"
+    exit 1
+fi