task-pipeline-skill 1.85.2 → 1.86.3

package/plugins/task-pipeline/skills/task-pipeline/scripts/packet.py

@@ -0,0 +1,400 @@
+#!/usr/bin/env python3
+"""Validate an execution packet — the family's versioned task/context contract.
+
+`execution-packet.schema.json` states the shape; this script is the
+dependency-free runtime half every consumer runs BEFORE acting on a packet
+(CTX-01). Python stdlib only, like everything else here: a validator that
+needs a package install is a validator half the hosts never run.
+
+    python3 scripts/packet.py validate <packet.json>   # exit 0 clean, 1 rejected
+    python3 scripts/packet.py canon <packet.json>      # canonical bytes digest
+    python3 scripts/packet.py validate-result <envelope.json> \\
+        [--current-revision N] [--current-fence F]     # the answer half (CTX-01.02)
+
+Three rejections are the contract's whole point, each watched failing in
+`test/audit_regressions/ctx-01.01.py`:
+
+* an UNKNOWN MANDATORY MAJOR — a consumer that does not know
+  `execution-packet/9` must refuse the packet, not skim the fields it likes;
+* a MISSING REF/DIGEST — an input or baseline without its sha256 cannot be
+  checked fresh, and stale context must block, never silently pass;
+* an UNBOUND DECISION — a decision named without address+digest is a rumour,
+  and two agents reading rumours build two different things from one plan.
+
+Round-trip: `canon` serializes with sorted keys and stable separators, so the
+same packet always hashes the same — the id a receipt can carry.
+
+The RESULT half (`execution-result.schema.json`) answers with an AttemptGrant
+and a ResultEnvelope, and two rejections carry that contract's whole point:
+a bare boolean is NOT a grant (it names no issuer, revision or fence), and a
+candidate built against an older revision than the current one is STALE — it
+re-plans, it never lands as current. A grant whose fence the authority has
+since superseded is rejected the same way.
+"""
+import hashlib
+import json
+import re
+import sys
+
+KNOWN_MAJORS = {1}
+SHA_RE = re.compile(r"^[0-9a-f]{64}$")
+EDIT_MODES = {"Edit", "Create", "Create_or_extend"}
+DEP_KINDS = {"data", "control", "resource"}
+
+
+OUTPUT_KINDS = {"artifact", "report", "decision", "metric"}
+
+
+def _ref_problems(ref, where, need_id=False):
+    out = []
+    if not isinstance(ref, dict):
+        return [f"{where}: not an object"]
+    if need_id and not ref.get("id"):
+        out.append(f"{where}: decision without an id")
+    if not ref.get("address"):
+        out.append(f"{where}: missing address — a ref that points nowhere")
+    sha = ref.get("sha256", "")
+    if not sha:
+        out.append(f"{where}: missing sha256 digest — freshness cannot be checked, "
+                   "so this blocks dispatch")
+    elif not SHA_RE.match(str(sha)):
+        out.append(f"{where}: sha256 is not 64 hex chars")
+    return out
+
+
+def problems(packet):
+    """Every reason this packet must not dispatch. Empty list = valid."""
+    out = []
+    if not isinstance(packet, dict):
+        return ["the packet is not a JSON object"]
+
+    version = str(packet.get("schema_version", ""))
+    m = re.match(r"^execution-packet/(\d+)$", version)
+    if not m:
+        out.append(f"schema_version {version!r} is not 'execution-packet/<major>' — "
+                   "a packet without a mandatory version is unversioned, rejected")
+    elif int(m.group(1)) not in KNOWN_MAJORS:
+        out.append(f"schema_version major {m.group(1)} is unknown to this consumer "
+                   f"(knows: {sorted(KNOWN_MAJORS)}) — rejected, never skimmed; "
+                   "upgrade the consumer or re-issue the packet at a known major")
+
+    for field in ("id", "module", "intent"):
+        if not packet.get(field):
+            out.append(f"missing {field}")
+
+    inputs = packet.get("inputs")
+    if not isinstance(inputs, list):
+        out.append("inputs must be a list (empty is allowed, absent is not)")
+    else:
+        for i, ref in enumerate(inputs):
+            out.extend(_ref_problems(ref, f"inputs[{i}]"))
+
+    decisions = packet.get("decision_refs")
+    if not isinstance(decisions, list):
+        out.append("decision_refs must be a list (empty is allowed, absent is not)")
+    else:
+        for i, ref in enumerate(decisions):
+            out.extend(_ref_problems(ref, f"decision_refs[{i}]", need_id=True))
+
+    scope = packet.get("source_scope")
+    if not isinstance(scope, dict) or not isinstance(scope.get("edit_targets"), list):
+        out.append("source_scope.edit_targets must be a list — a packet that names no "
+                   "files it may touch has an unbounded blast radius")
+    else:
+        for i, t in enumerate(scope["edit_targets"]):
+            where = f"source_scope.edit_targets[{i}]"
+            if not isinstance(t, dict) or not t.get("address"):
+                out.append(f"{where}: missing address")
+                continue
+            mode = t.get("mode")
+            if mode not in EDIT_MODES:
+                out.append(f"{where}: mode {mode!r} is not one of {sorted(EDIT_MODES)}")
+            if mode == "Edit":
+                sha = t.get("baseline_sha256", "")
+                if not sha:
+                    out.append(f"{where}: an Edit target without baseline_sha256 — "
+                               "'the source moved under the plan' would be undetectable")
+                elif not SHA_RE.match(str(sha)):
+                    out.append(f"{where}: baseline_sha256 is not 64 hex chars")
+
+    budgets = packet.get("budgets")
+    if not isinstance(budgets, dict) or not budgets:
+        out.append("budgets must carry at least one bound")
+    else:
+        cb = budgets.get("context_bytes")
+        if cb is not None and (not isinstance(cb, int) or cb < 1):
+            out.append("budgets.context_bytes must be a positive integer")
+
+    seen_edges = set()
+    for i, dep in enumerate(packet.get("dependencies") or []):
+        where = f"dependencies[{i}]"
+        if not isinstance(dep, dict) or not dep.get("task_id"):
+            out.append(f"{where}: missing task_id")
+            continue
+        if dep.get("kind") not in DEP_KINDS:
+            out.append(f"{where}: kind {dep.get('kind')!r} is not one of {sorted(DEP_KINDS)}")
+        if not dep.get("rationale"):
+            out.append(f"{where}: missing rationale — an edge nobody can explain is an "
+                       "edge nobody dares remove or trust")
+        edge = (dep["task_id"], dep.get("kind"))
+        if edge in seen_edges:
+            out.append(f"{where}: duplicate edge to {dep['task_id']} ({dep.get('kind')})")
+        seen_edges.add(edge)
+        # A CONTROL edge with no satisfaction is VALID and PRESERVED: ordering is
+        # its whole payload. Only data/resource edges owe a satisfaction.
+        if dep.get("kind") in ("data", "resource") and not dep.get("satisfaction"):
+            out.append(f"{where}: a {dep['kind']} edge without satisfaction — what would "
+                       "mark it met? A control edge may omit this; a payload edge may not")
+
+    return out
+
+
+RESULT_MAJORS = {1}
+CHECK_STATUSES = {"PASS", "FAIL", "ERROR", "NOT_RUN"}
+EVIDENCE_CLASSES = {"fact", "defect", "unknown_effect"}
+RESULT_STATUSES = {"completed", "partial", "blocked", "abandoned"}
+
+
+def result_problems(env, current_revision=None, current_fence=None):
+    """Every reason this envelope must not land. Empty list = valid."""
+    out = []
+    if not isinstance(env, dict):
+        return ["the envelope is not a JSON object"]
+
+    version = str(env.get("schema_version", ""))
+    m = re.match(r"^execution-result/(\d+)$", version)
+    if not m:
+        out.append(f"schema_version {version!r} is not 'execution-result/<major>' — rejected")
+    elif int(m.group(1)) not in RESULT_MAJORS:
+        out.append(f"schema_version major {m.group(1)} is unknown to this consumer "
+                   f"(knows: {sorted(RESULT_MAJORS)}) — rejected, never skimmed")
+
+    grant = env.get("grant")
+    if isinstance(grant, bool) or grant is None or not isinstance(grant, dict):
+        out.append(f"grant is {grant!r} — a boolean confirmation is not a grant: it names "
+                   "no issuer, no revision, no fence; nothing a later reader could check")
+    else:
+        for field in ("grant_id", "packet_id", "holder"):
+            if not grant.get(field):
+                out.append(f"grant.{field} is missing")
+        for field in ("revision", "fence"):
+            if not isinstance(grant.get(field), int):
+                out.append(f"grant.{field} must be an integer — the grant is checkable "
+                           "or it is not a grant")
+        if env.get("packet_id") and grant.get("packet_id") \
+                and env["packet_id"] != grant["packet_id"]:
+            out.append("the envelope and its grant name different packets")
+        if current_fence is not None and isinstance(grant.get("fence"), int) \
+                and grant["fence"] < current_fence:
+            out.append(f"grant fence {grant['fence']} is superseded (current {current_fence}) "
+                       "— exclusivity was lost mid-flight; this result must not land")
+
+    rev = env.get("built_against_revision")
+    if not isinstance(rev, int):
+        out.append("built_against_revision must be an integer")
+    elif current_revision is not None and rev < current_revision:
+        out.append(f"STALE candidate: built against revision {rev}, current is "
+                   f"{current_revision} — re-plan, never land as current")
+
+    cand = env.get("candidate")
+    if not isinstance(cand, dict) or not isinstance(cand.get("changed"), list):
+        out.append("candidate.changed must be a list of content-addressed paths")
+    else:
+        for i, row in enumerate(cand["changed"]):
+            if not isinstance(row, dict) or not row.get("address"):
+                out.append(f"candidate.changed[{i}]: missing address")
+            elif not SHA_RE.match(str(row.get("sha256", ""))):
+                out.append(f"candidate.changed[{i}]: missing or malformed sha256")
+
+    checks = env.get("checks")
+    failing = 0
+    if not isinstance(checks, list):
+        out.append("checks must be a list (empty is allowed, absent is not)")
+    else:
+        for i, c in enumerate(checks):
+            if not isinstance(c, dict) or not c.get("name") or not c.get("command"):
+                out.append(f"checks[{i}]: needs name and command — an unnamed check "
+                           "cannot be re-run")
+                continue
+            if c.get("status") not in CHECK_STATUSES:
+                out.append(f"checks[{i}]: status {c.get('status')!r} is not one of "
+                           f"{sorted(CHECK_STATUSES)} — NOT_RUN is a status, not a gap")
+            elif c["status"] in ("FAIL", "ERROR"):
+                failing += 1
+
+    for i, row in enumerate(env.get("evidence") or []):
+        if not isinstance(row, dict) or row.get("class") not in EVIDENCE_CLASSES:
+            out.append(f"evidence[{i}]: class must be one of {sorted(EVIDENCE_CLASSES)} — "
+                       "fact, defect and unknown effect are three verdicts, never blended")
+
+    secretish = re.compile(r"(?i)^(?:.*[_-])?(token|secret|password|passwd|api[_-]?key|"
+                           r"apikey|credential|authorization|cookie|private[_-]?key)s?$")
+    for i, row in enumerate(env.get("outputs") or []):
+        if not isinstance(row, dict) or not row.get("name") or not row.get("address"):
+            out.append(f"outputs[{i}]: needs name, kind, address, sha256 — an untyped "
+                       "output cannot be consumed by digest")
+            continue
+        if row.get("kind") not in OUTPUT_KINDS:
+            out.append(f"outputs[{i}]: kind {row.get('kind')!r} is not one of "
+                       f"{sorted(OUTPUT_KINDS)}")
+        if not SHA_RE.match(str(row.get("sha256", ""))):
+            out.append(f"outputs[{i}]: missing or malformed sha256")
+        if secretish.match(str(row["name"])):
+            out.append(f"outputs[{i}]: {row['name']!r} names a credential — a result "
+                       "outlives its session exactly like the packet; reference the "
+                       "store by name, never carry the value (FIX-PF-05.03)")
+    pd = env.get("packet_digest")
+    if pd is not None and not SHA_RE.match(str(pd)):
+        out.append("packet_digest: malformed — the tie to the dispatch packet must be "
+                   "a sha256 or absent, never a guess")
+    for i, row in enumerate(env.get("consumed") or []):
+        if not isinstance(row, dict) or not row.get("name")                 or not SHA_RE.match(str(row.get("sha256", ""))):
+            out.append(f"consumed[{i}]: needs name + sha256 — freshness is a comparison, "
+                       "and an unpinned consumption cannot be compared")
+
+    status = env.get("status")
+    if status not in RESULT_STATUSES:
+        out.append(f"status {status!r} is not one of {sorted(RESULT_STATUSES)}")
+    elif status == "completed" and failing:
+        out.append(f"status 'completed' beside {failing} failing check(s) — a completed "
+                   "attempt with red checks is a contradiction, not a nuance")
+
+    return out
+
+
+def consumed_stale(env, current_outputs):
+    """Which of this result's consumed inputs have moved (FIX-PF-05.03).
+
+    `current_outputs`: {name: sha256} — the predecessors' outputs as they are
+    NOW. A name whose digest differs is returned; a non-empty list means this
+    result is STALE and the node rebuilds at a new revision. A consumed name
+    the predecessors no longer produce is stale too — an input that vanished
+    is not fresher than one that changed.
+    """
+    stale = []
+    for row in env.get("consumed") or []:
+        name = row.get("name")
+        if current_outputs.get(name) != row.get("sha256"):
+            stale.append(name)
+    return stale
+
+
+def graph_problems(packets):
+    """Closure over a packet SET: unique ids, every edge resolves, no cycles.
+    A control edge participates in the cycle check like any other — ordering
+    that loops is still a loop."""
+    out = []
+    if not isinstance(packets, list) or not packets:
+        return ["the graph is not a non-empty list of packets"]
+    ids = [p.get("id") for p in packets if isinstance(p, dict)]
+    for dup in sorted({i for i in ids if ids.count(i) > 1}):
+        out.append(f"duplicate packet id {dup!r} — two packets, one name, no arbitration")
+    known = set(ids)
+    edges = {}
+    for p in packets:
+        if not isinstance(p, dict):
+            continue
+        edges[p.get("id")] = []
+        for dep in p.get("dependencies") or []:
+            tid = dep.get("task_id") if isinstance(dep, dict) else None
+            if tid is None:
+                continue
+            if tid not in known:
+                out.append(f"{p.get('id')}: depends on {tid!r}, which is not in the graph")
+                continue
+            edges[p.get("id")].append(tid)
+    state = {}
+    def visit(node, stack):
+        state[node] = "visiting"
+        for nxt in edges.get(node, []):
+            if state.get(nxt) == "visiting":
+                cycle = stack[stack.index(nxt):] + [nxt] if nxt in stack else [node, nxt]
+                out.append("cycle: " + " -> ".join(cycle))
+                continue
+            if nxt not in state:
+                visit(nxt, stack + [nxt])
+        state[node] = "done"
+    for node in edges:
+        if node not in state:
+            visit(node, [node])
+    return out
+
+
+def canon(packet):
+    """Canonical bytes: sorted keys, stable separators — same packet, same hash."""
+    return json.dumps(packet, sort_keys=True, ensure_ascii=False,
+                      separators=(",", ":")).encode("utf-8")
+
+
+def main(argv):
+    if len(argv) < 3 or argv[1] not in ("validate", "canon", "validate-result",
+                                        "validate-graph"):
+        print(__doc__.strip().splitlines()[0])
+        print("usage: packet.py validate <packet.json> | packet.py canon <packet.json> | "
+              "packet.py validate-result <envelope.json> [--current-revision N] "
+              "[--current-fence F]")
+        return 2
+    try:
+        with open(argv[2], encoding="utf-8") as fh:
+            packet = json.load(fh)
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"REJECTED: cannot read the packet — {exc}")
+        return 1
+    if argv[1] == "validate-graph":
+        found = graph_problems(packet)
+        for p_ in packet if isinstance(packet, list) else []:
+            for pr in problems(p_) if isinstance(p_, dict) else []:
+                found.append(f"{p_.get('id')}: {pr}")
+        if found:
+            for pr in found:
+                print(f"REJECTED: {pr}")
+            return 1
+        n_ctrl = sum(1 for p_ in packet for dep in (p_.get("dependencies") or [])
+                     if dep.get("kind") == "control")
+        print(f"ok: {len(packet)} packet(s), acyclic, every edge resolves; "
+              f"{n_ctrl} control edge(s) preserved")
+        return 0
+    if argv[1] == "validate-result":
+        opts = argv[3:]
+        current_revision = current_fence = None
+        while opts:
+            flag = opts.pop(0)
+            if flag == "--current-revision" and opts:
+                current_revision = int(opts.pop(0))
+            elif flag == "--current-fence" and opts:
+                current_fence = int(opts.pop(0))
+            else:
+                print(f"unknown option: {flag}")
+                return 2
+        found = result_problems(packet, current_revision, current_fence)
+        if found:
+            for pr in found:
+                print(f"REJECTED: {pr}")
+            return 1
+        checks = packet.get("checks") or []
+        not_run = sum(1 for c in checks if c.get("status") == "NOT_RUN")
+        green = sum(1 for c in checks if c.get("status") == "PASS")
+        print(f"ok: {packet['packet_id']} ({packet['status']}) — {green} PASS, "
+              f"{not_run} NOT_RUN of {len(checks)} check(s); "
+              f"revision {packet['built_against_revision']}, fence {packet['grant']['fence']}")
+        return 0
+    if argv[1] == "canon":
+        bytes_ = canon(packet)
+        if json.loads(bytes_.decode("utf-8")) != packet:
+            print("REJECTED: the packet does not round-trip canonically")
+            return 1
+        print(hashlib.sha256(bytes_).hexdigest())
+        return 0
+    found = problems(packet)
+    if found:
+        for p in found:
+            print(f"REJECTED: {p}")
+        return 1
+    print(f"ok: {packet['id']} ({packet['schema_version']}) — "
+          f"{len(packet['inputs'])} input(s), {len(packet['decision_refs'])} decision(s), "
+          f"{len(packet['source_scope']['edit_targets'])} edit target(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/plugins/task-pipeline/skills/task-pipeline/templates/README.md

@@ -25,6 +25,8 @@ from `super-ux`.
 | `hygiene.sh` | `scripts/check-hygiene.sh` | 0 seeds it · **5 runs it after every task** · 6 and 9 run it · 10 proves it |
 | `stage-coverage.sh` | `scripts/stage-coverage.sh` | 0 seeds it · **10 runs it before the coverage table** — every stage the flow declares must carry a verdict, or the flow stops declaring one it merges |
 | `hooks.example.json` | the project's `.claude/settings.json` | 0 — offered, never installed silently |
+| `browser-claims.json` | stage 6, beside the look — one row per browser claim | REQ/scenario id + state + kind (look/suite/library); validated by `test/browser_claims_test.py`, stdlib only |
+| `finding-evidence.json` | one record per audit finding, wherever the finding lives | the five-axes evidence schema: mechanism / reproduction / exposure / incidence / impact uncertainty, observations apart from assumptions |
 | `routing-rule.md` | the operator's `CLAUDE.md` — **offered by `setup`, never written silently** | 0 / `setup` |
 | `retro.md` | `docs/evidence/retro.md` — **one per project, not per run** | 10 writes (stamp → prune → entry), 0 reads it in full |
 | `retro-archive.md` | `docs/evidence/retro/YYYY-QN.md` | 10 rotates into it, 0 **queries** it |

package/plugins/task-pipeline/skills/task-pipeline/templates/browser-claims.json

@@ -0,0 +1,54 @@
+{
+ "schema_version": "browser-claims/1",
+ "note": "One row = one browser claim: which REQ/scenario it serves, which STATE it was captured in, and which KIND of check produced it — the look, the spec suite or the library script (the browser.md split). A functional PASS never yields a visual PASS; an artifact closes only the state it was captured in (the initial screenshot does not close an opened/error claim); no browser channel means status NOT_RUN with the reason, never a quiet green. python3 test/browser_claims_test.py validates a filled copy with stdlib only.",
+ "claims": [
+  {
+   "id": "BC-01",
+   "req": "REQ-3",
+   "scenario": "SCN-004",
+   "component": "nav-menu",
+   "state": "initial",
+   "kind": "look",
+   "artifact": "shots/nav-menu-initial.png",
+   "artifact_state": "initial",
+   "status": "NOT_RUN",
+   "reason": "template row — replace with a real capture"
+  },
+  {
+   "id": "BC-02",
+   "req": "REQ-3",
+   "scenario": "SCN-004",
+   "component": "nav-menu",
+   "state": "opened",
+   "kind": "look",
+   "artifact": "shots/nav-menu-opened.png",
+   "artifact_state": "opened",
+   "status": "NOT_RUN",
+   "reason": "template row — replace with a real capture"
+  },
+  {
+   "id": "BC-03",
+   "req": "REQ-3",
+   "scenario": "SCN-004",
+   "component": "nav-menu",
+   "state": "closed-again",
+   "kind": "look",
+   "artifact": "shots/nav-menu-closed-again.png",
+   "artifact_state": "closed-again",
+   "status": "NOT_RUN",
+   "reason": "the full toggle cycle: initial -> opened -> closed-again, each with its own artifact"
+  },
+  {
+   "id": "BC-04",
+   "req": "REQ-3",
+   "scenario": "SCN-004",
+   "component": "nav-menu",
+   "state": "any",
+   "kind": "suite",
+   "artifact": null,
+   "artifact_state": null,
+   "status": "NOT_RUN",
+   "reason": "the spec suite half — its PASS counts for functional claims only"
+  }
+ ]
+}

package/plugins/task-pipeline/skills/task-pipeline/templates/finding-evidence.json

@@ -0,0 +1,42 @@
+{
+ "schema": "finding-evidence/1",
+ "doc": "Minimal evidence record for one finding. The five axes are SEPARATE: a defect proven by reproduction stands with incidence unknown; UNKNOWN is not 0; absent telemetry lowers exposure claims, never mechanism truth; a documented exception never turns a failed invariant into PASS; unknown attacker control lowers exploitability confidence, not the observed behaviour. Keep observations and assumptions apart — a reader must be able to tell what was WATCHED from what was inferred.",
+ "fields": {
+  "mechanism_status": {
+   "one_of": ["confirmed", "suspected"],
+   "doc": "What the code/artefact was seen to do. Confirmed needs evidence (file:line, a command and its output, a reproduction)."
+  },
+  "reproduction": {
+   "one_of": ["reproduced", "not-attempted", "attempted-failed"],
+   "doc": "A local reproduction is proof BEFORE any incident — it licenses the finding on its own."
+  },
+  "exposure": {
+   "doc": "Who or what can reach the mechanism, or 'unknown'. This is the axis absent telemetry actually lowers."
+  },
+  "observed_incidence": {
+   "doc": "'unknown' | 'never-observed' | a count with its window. UNKNOWN is a word, never a zero.",
+   "default": "unknown"
+  },
+  "impact_uncertainty": {
+   "doc": "What is NOT known about the blast, stated — so a rare catastrophic path is not priced as a common trivial one."
+  },
+  "observed_scope": {
+   "doc": "What was actually looked at: 'local checkout', a deployment name, a log window."
+  },
+  "observed_at": {
+   "doc": "ISO-8601 UTC time of the observation."
+  },
+  "observations": {
+   "doc": "What was watched happening, each with its receipt."
+  },
+  "assumptions": {
+   "doc": "What was inferred, each named as such — never mixed into observations."
+  }
+ },
+ "rules": [
+  "a proven defect may have observed_incidence 'unknown' and remains a finding",
+  "observed_incidence 'unknown' never lowers mechanism_status",
+  "an operator interview is asked only when the unknown would change the action",
+  "a documented exception changes the decision axis, never the validity axis"
+ ]
+}

package/plugins/task-pipeline/skills/task-pipeline/templates/hooks.example.json

@@ -1,15 +1,15 @@
 {
   "_note": "EXAMPLE — copy this block into the project's .claude/settings.json. Doctrine: references/hooks.md. Hooks exist ONLY in Claude Code; on any other agent the same rule runs as a self-check and the run is recorded 'ungated'. Never describe a project as protected when its agents run elsewhere.",
   "_contract": "A PreToolUse hook blocks in one of two ways: exit 2 with the reason on stderr (stdout is ignored), or exit 0 with {\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"deny\",\"permissionDecisionReason\":\"...\"}} on stdout. ANY OTHER EXIT CODE IS NON-BLOCKING, so a crashing guard fails open and stops guarding without announcing it. That is why the command below ends in '|| exit 2' — the gate's own 'exit 1' would otherwise land in the non-blocking branch and the commit would proceed.",
+  "_filter_note": "Refuse a commit while the documentation gate is red. Matched narrowly: the matcher is free, the script is not. The `if` filter sits ON THE HANDLER, beside `type`/`command` — never beside `matcher`: a matcher group is only `matcher` + `hooks`, and a key Claude Code does not know there is ignored (and reported at session start from 2.1.270). Until v1.86.2 this template carried `if` at group level, so the gate ran on EVERY Bash call in every project that copied it, and a red docs gate refused every shell command rather than the commit.",
   "hooks": {
     "PreToolUse": [
       {
-        "_note": "Refuse a commit while the documentation gate is red. Matched narrowly: the matcher is free, the script is not.",
         "matcher": "Bash",
-        "if": "Bash(git commit *)",
         "hooks": [
           {
             "type": "command",
+            "if": "Bash(git commit *)",
             "shell": "bash",
             "timeout": 60,
             "command": "bash scripts/check-docs.sh >&2 || exit 2"

package/plugins/task-pipeline/skills/task-pipeline/templates/run.md

@@ -20,7 +20,7 @@ Run: `<topic>` · started `<YYYY-MM-DD>` · module map: `<path or "none">`
 
 ## `read:` — which doctrine this run actually opened
 
-The bundle is 38 reference files and nothing recorded which of them a run read, so **a
+The bundle is 39 reference files and nothing recorded which of them a run read, so **a
 skipped file and a read one were indistinguishable** — the class every guard in this
 pipeline exists to catch, left standing over the doctrine itself.
 
@@ -48,7 +48,7 @@ same claim one level down.
 |---|---|---|
 | `unmeasured — no run ledger` | there is no ledger | nothing to read from |
 | `unmeasured — the ledger carries no read: lines` | the hook is absent, **or** the run opened no doctrine | two opposite facts, and the ledger cannot separate them, so neither is claimed |
-| `N of 38 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
+| `N of 39 reference files read — unattested`, then each unread one | the hook is installed and fired | the count alone says there is a gap, not where — and `unattested` says the ledger cannot name who wrote the lines |
 
 **It is a disclosure: no floor, no direction, never a target.** A run that needs four files
 and reads four is not worse than one that reads thirty — and the moment the number becomes