@techierathore/techieflow 1.0.0

package/.tfcore/hooks/codex-adapter.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python3
+"""Translate Codex hooks to TechieFlow's existing guard and telemetry contracts.
+
+Modes (see .codex/hooks.json):
+  pre-tool       Bash  -> block-git.sh + guard-artifacts.sh
+                 Edit/Write/apply_patch -> guard-status.sh + guard-verify.sh
+  stop           guard-status-html.sh (PROJECT-STATUS.html must not be stale)
+  session-start  session pointer + sweep-artifacts.sh (expired run material)
+  session-start  write the .tfcore/.session/codex.json pointer
+  session-end    pointer + session telemetry
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import re
+import subprocess
+import sys
+from datetime import datetime, timezone
+
+
+def read_event() -> dict:
+    try:
+        value = json.load(sys.stdin)
+        return value if isinstance(value, dict) else {}
+    except Exception:
+        return {}
+
+
+def project_root(event: dict) -> pathlib.Path:
+    start = pathlib.Path(str(event.get("cwd") or os.getcwd())).resolve()
+    for candidate in (start, *start.parents):
+        if (candidate / ".tfcore").is_dir():
+            return candidate
+    return start
+
+
+def environment(root: pathlib.Path, event: dict) -> dict[str, str]:
+    env = os.environ.copy()
+    env.update(
+        TF_HARNESS="codex",
+        TF_PROJECT_DIR=str(root),
+        CLAUDE_PROJECT_DIR=str(root),
+        TF_SESSION_ID=str(event.get("session_id") or ""),
+    )
+    if (root / ".tfcore" / ".session" / "yolo.json").exists():
+        env["TF_YOLO"] = "1"
+    return env
+
+
+def deny(reason: str) -> None:
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }))
+
+
+def run_guard(root: pathlib.Path, event: dict, script: str, payload: dict) -> str | None:
+    path = root / ".tfcore" / "hooks" / script
+    if not path.exists():
+        return None
+    try:
+        env = environment(root, event)
+        if script == "block-git.sh":
+            # Codex also has an all-git exec-policy rule. Keep the hook's
+            # compound-command fallback equally strict in YOLO mode.
+            env["TF_STRICT_GIT"] = "1"
+        result = subprocess.run(
+            ["bash", str(path)], input=json.dumps(payload), text=True,
+            capture_output=True, timeout=10, env=env, check=False,
+        )
+    except Exception as exc:
+        # Policy checks fail closed. Telemetry is handled separately and fails open.
+        return f"TechieFlow could not execute {script}: {exc}"
+    if result.returncode == 2:
+        return result.stderr.strip() or f"Blocked by TechieFlow guard {script}"
+    if result.returncode not in (0,):
+        return f"TechieFlow guard {script} failed unexpectedly (exit {result.returncode})."
+    return None
+
+
+def pre_tool(event: dict) -> None:
+    root = project_root(event)
+    tool = str(event.get("tool_name") or "")
+    raw = event.get("tool_input")
+    args = raw if isinstance(raw, dict) else {}
+    scripts: list[str] = []
+    if tool == "Bash":
+        payload = {"tool_name": "Bash", "tool_input": {"command": str(args.get("command") or "")}}
+        scripts = ["block-git.sh", "guard-artifacts.sh"]
+    elif tool == "apply_patch":
+        patch = str(args.get("command") or args.get("patch") or "")
+        # Run the existing guards once per file using actual paths and separated
+        # added/removed lines. This avoids treating context or removed Verified
+        # cells as newly introduced content.
+        headers = list(re.finditer(r"(?m)^\*\*\* (Update|Add|Delete) File: (.+)$", patch))
+        for index, header in enumerate(headers):
+            end = headers[index + 1].start() if index + 1 < len(headers) else len(patch)
+            section = patch[header.end():end]
+            file_path = header.group(2).strip()
+            base_name = pathlib.PurePosixPath(file_path.replace("\\", "/")).name.lower()
+            if header.group(1) == "Delete" and (
+                base_name == "project-status.md" or base_name.endswith("-checklist.md")
+            ):
+                deny(
+                    "TechieFlow protected documents cannot be deleted: "
+                    f"{file_path}. Update their canonical fixed shape instead."
+                )
+                return
+            added = []
+            removed = []
+            for line in section.splitlines():
+                if line.startswith("+") and not line.startswith("+++"):
+                    added.append(line[1:])
+                elif line.startswith("-") and not line.startswith("---"):
+                    removed.append(line[1:])
+            payload = {
+                "hook_event_name": "PreToolUse", "cwd": str(root),
+                "session_id": event.get("session_id"), "tool_name": "Edit",
+                "tool_input": {"file_path": file_path,
+                               "old_string": "\n".join(removed),
+                               "new_string": "\n".join(added)},
+            }
+            for script in ("guard-status.sh", "guard-verify.sh"):
+                reason = run_guard(root, event, script, payload)
+                if reason:
+                    deny(reason)
+                    return
+        return
+    elif tool in ("Edit", "Write"):
+        payload = {"tool_name": tool, "tool_input": args}
+        scripts = ["guard-status.sh", "guard-verify.sh"]
+    else:
+        return
+    payload.update(hook_event_name="PreToolUse", cwd=str(root), session_id=event.get("session_id"))
+    for script in scripts:
+        reason = run_guard(root, event, script, payload)
+        if reason:
+            deny(reason)
+            return
+
+
+def stop(event: dict) -> None:
+    """Stop hook: refuse to end the turn while PROJECT-STATUS.html is stale.
+
+    Same contract as the Claude Code Stop hook (_status-update-gate.md §8):
+    guard-status-html.sh exits 2 when the .html is older than the .md or
+    missing; `stop_hook_active` is passed through so a turn that genuinely
+    cannot render still terminates instead of looping.
+    """
+    root = project_root(event)
+    payload = {
+        "hook_event_name": "Stop", "cwd": str(root),
+        "session_id": event.get("session_id"),
+        "stop_hook_active": bool(event.get("stop_hook_active")),
+    }
+    reason = run_guard(root, event, "guard-status-html.sh", payload)
+    if reason:
+        print(json.dumps({"decision": "block", "reason": reason}))
+
+
+def write_pointer(root: pathlib.Path, event: dict) -> None:
+    session_id = str(event.get("session_id") or "")
+    if not session_id:
+        return
+    target = root / ".tfcore" / ".session" / "codex.json"
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(json.dumps({
+            "session_id": session_id,
+            "transcript_path": event.get("transcript_path"),
+            "model": event.get("model"),
+            "ts": datetime.now(timezone.utc).isoformat(),
+        }) + "\n", encoding="utf-8")
+    except Exception:
+        pass
+
+
+def sweep_artifacts(root: pathlib.Path, event: dict) -> None:
+    """SessionStart analogue of the Claude Code sweep-artifacts.sh hook: delete
+    run material under tests/.artifacts/ and .verify/ older than the retention
+    window and any banned repo-root legacy dir. No veto — never raises."""
+    script = root / ".tfcore" / "hooks" / "sweep-artifacts.sh"
+    if not script.exists():
+        return
+    try:
+        res = subprocess.run(["bash", str(script)], input=json.dumps(event), text=True,
+                             capture_output=True, timeout=30, env=environment(root, event), check=False)
+        summary = (res.stdout or "").strip()
+        if summary:
+            print(summary)  # SessionStart stdout is surfaced into the session
+    except Exception:
+        pass
+
+
+def session_end(root: pathlib.Path, event: dict) -> None:
+    # Transcript format is explicitly not a stable Codex hook interface. Record
+    # honest session metadata; codex exec --json telemetry is enriched separately.
+    emit = root / ".tfcore" / "utils" / "tf-emit.sh"
+    if not emit.exists() or not event.get("session_id"):
+        return
+    record = {
+        "kind": "session",
+        "session_id": event.get("session_id"),
+        "model": event.get("model"),
+        "duration_s": None,
+        "input_tokens": None,
+        "output_tokens": None,
+        "cache_read_tokens": None,
+        "cache_creation_tokens": None,
+        "cost_usd": None,
+        "children_sessions": None,
+        "harness": "codex",
+    }
+    try:
+        subprocess.run(["bash", str(emit), "sessions"], input=json.dumps(record), text=True,
+                       capture_output=True, timeout=2, env=environment(root, event), check=False)
+    except Exception:
+        pass
+
+
+def main() -> int:
+    event = read_event()
+    root = project_root(event)
+    mode = sys.argv[1] if len(sys.argv) > 1 else ""
+    if mode == "pre-tool":
+        pre_tool(event)
+    elif mode == "stop":
+        stop(event)
+    elif mode == "session-start":
+        write_pointer(root, event)
+        # .codex/hooks.json runs session-start for UserPromptSubmit too; sweep
+        # only on the real session start so every prompt does not walk the tree.
+        if str(event.get("hook_event_name") or "").lower() != "userpromptsubmit":
+            sweep_artifacts(root, event)
+    elif mode == "session-end":
+        write_pointer(root, event)
+        session_end(root, event)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/.tfcore/hooks/guard-artifacts.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — blocks repo-root run-artifact directories.
+#
+# verify-phase.md §1 ARTIFACT-LOCATION RULE: everything a run generates that is
+# not a deliverable lands under tests/.artifacts/. Repo-root siblings —
+# test-results-<slug>/, scripts-<slug>/ — are BANNED: a suffixed name escapes the
+# ignore pattern written for the unsuffixed one, and nothing ever cleans them up.
+#
+# The prose rule has now failed THREE times: fourteen test-results-* dirs in one
+# app, then four scripts-cluster-* dirs in the next fan-out after those were
+# banned, then ten test-results-* dirs in TechieBlog (2026-08-23..25, swept
+# 2026-08-25). Every one came from an agent passing `--output test-results-<slug>`
+# and overriding the config's pinned outputDir. This hook makes the rule
+# MECHANICAL, the same way block-git.sh made the git ban mechanical.
+#
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Bash"); Codex via
+# .tfcore/hooks/codex-adapter.py pre-tool; OpenCode via .opencode/plugin/techieflow.js.
+# Exit 2 + stderr = block the call and feed the message back to the agent.
+#
+# What it blocks:
+#   - --output / --output-dir pointed at a root-level test-results* or scripts-*
+#     (bare -o is deliberately NOT matched — see the comment in the Python body)
+#   - mkdir of a root-level test-results* or scripts-* directory
+# What it deliberately ALLOWS:
+#   - --output tests/.artifacts/<slug>        (the sanctioned isolation form)
+#   - anything under tests/, and the project's own tracked scripts/ (no hyphen)
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+TF_HOOK_INPUT="$INPUT" python3 - <<'PY'
+import json, os, re, sys
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+ti = data.get("tool_input") or {}
+cmd = ti.get("command")
+if not isinstance(cmd, str) or not cmd.strip():
+    sys.exit(0)
+
+errors = []
+
+# A root-relative artifact path: optional ./ then test-results… or scripts-…
+# `tests/…` never matches (the 's' in "tests" is followed by '/'), and the
+# project's own `scripts/` never matches (requires the hyphen).
+ROOT_ARTIFACT = r"(?:\./)?(test-results[\w.-]*|scripts-[\w.-]+)/?"
+
+# Long form ONLY. A bare `-o` is deliberately NOT matched: Playwright has no -o
+# shorthand for --output, while `grep -o 'test-results-…'` and `curl -o` are
+# legitimate and would false-positive. Cheap specificity beats a clever pattern.
+for m in re.finditer(
+    r"--output(?:-dir)?[=\s]+(['\"]?)" + ROOT_ARTIFACT,
+    cmd,
+):
+    errors.append(
+        f'--output points at repo-root "{m.group(2)}". The single artifact '
+        "destination is playwright.config.ts's pinned outputDir "
+        "(tests/.artifacts/test-results), which Playwright namespaces per test "
+        "AND wipes at the start of every run — that is what keeps the tree from "
+        "growing. If a parallel fan-out genuinely needs isolation, the ONLY "
+        "permitted override is a subfolder: --output tests/.artifacts/<slug>."
+    )
+
+for m in re.finditer(
+    r"(?<!\w)mkdir(?:\s+-[\w-]+)*\s+(['\"]?)" + ROOT_ARTIFACT,
+    cmd,
+):
+    errors.append(
+        f'mkdir would create repo-root "{m.group(2)}". Run material — tool output '
+        "AND the throwaway scripts you write to drive it — lives under "
+        "tests/.artifacts/ (harness scripts: tests/.artifacts/harness/<name>.mjs). "
+        "Never a root-level <name>-<slug>/ per run or per cluster."
+    )
+
+if errors:
+    print(
+        "BLOCKED by TechieFlow policy: no repo-root run-artifact directory "
+        "(verify-phase.md §1 ARTIFACT-LOCATION RULE).",
+        file=sys.stderr,
+    )
+    for e in dict.fromkeys(errors):
+        print(" - " + e, file=sys.stderr)
+    print(
+        "Do NOT reason by the letter of this list: any NEW root-level "
+        "<name>-<slug>/ you are about to create for a fan-out is the same defect, "
+        "whatever the noun. Re-run writing under tests/.artifacts/ instead. "
+        "Note: a script that imports the Playwright LIBRARY does not load "
+        "playwright.config.ts at all — it must place its own captures under "
+        "tests/.artifacts/ explicitly, resolved relative to the repo root, never "
+        "an absolute path.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+sys.exit(0)
+PY
+exit $?

package/.tfcore/hooks/guard-status-html.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# TechieFlow Stop hook — refuses to end a turn while PROJECT-STATUS.html is stale.
+#
+# _status-update-gate.md §8: "If you edited PROJECT-STATUS.md you re-render
+# PROJECT-STATUS.html in the same turn, full stop." The owner reads the .html; a
+# markdown-only update leaves the page the human actually looks at stale, which
+# defeats the entire purpose of the gate.
+#
+# The prose rule kept failing silently: on 2026-08-25 the owner was reading a
+# PROJECT-STATUS.html rendered 4.5 hours earlier that still listed REQ-FN-062 as
+# blocked and repeated three "owner actions" he had already completed. guard-status.sh
+# already enforces the SHAPE of the markdown; nothing checked that the sibling HTML
+# was current. This closes that gap.
+#
+# Stop (not PostToolUse) is the right trigger because the rule is about the TURN,
+# not the edit — an agent legitimately writes the .md and then renders the .html
+# a few tool calls later. This only complains when the turn is actually ending
+# with the two files out of sync.
+#
+# Wired in .claude/settings.json → hooks.Stop; Codex via .codex/hooks.json Stop →
+# codex-adapter.py stop; OpenCode via .opencode/plugin/techieflow.js session.idle
+# (one-shot nudge — OpenCode has no blocking Stop hook).
+# Exit 2 + stderr = block the stop and feed the message back to the agent.
+# Honours stop_hook_active so a wedged turn can still terminate (no loop).
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+TF_HOOK_INPUT="$INPUT" TF_PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$PWD}" python3 - <<'PY'
+import json, os, sys
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+# Already re-invoked once for this stop — let the turn end rather than loop.
+if data.get("stop_hook_active"):
+    sys.exit(0)
+
+root = os.environ.get("TF_PROJECT_DIR") or os.getcwd()
+md = os.path.join(root, "PROJECT-STATUS.md")
+html = os.path.join(root, "PROJECT-STATUS.html")
+
+if not os.path.isfile(md):
+    sys.exit(0)
+
+md_mtime = os.path.getmtime(md)
+
+if not os.path.isfile(html):
+    print(
+        "BLOCKED by TechieFlow policy: PROJECT-STATUS.md exists but "
+        "PROJECT-STATUS.html does not. The owner reads the HTML "
+        "(_status-update-gate.md §8) — render it before ending the turn, using "
+        ".tfcore/templates/v4custom/html-render-shell.md. Never hand-roll a "
+        "different scaffold.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+html_mtime = os.path.getmtime(html)
+
+if md_mtime > html_mtime:
+    drift = int(md_mtime - html_mtime)
+    if drift >= 3600:
+        ago = f"{drift // 3600}h {(drift % 3600) // 60}m"
+    elif drift >= 60:
+        ago = f"{drift // 60}m"
+    else:
+        ago = f"{drift}s"
+    print(
+        "BLOCKED by TechieFlow policy: PROJECT-STATUS.html is STALE — "
+        f"PROJECT-STATUS.md is {ago} newer (_status-update-gate.md §8).",
+        file=sys.stderr,
+    )
+    print(
+        " - The owner reads the .html. A markdown-only update is an INCOMPLETE "
+        "update: it leaves the page the human actually looks at showing the "
+        "previous run's reality (closed REQs still open, retracted owner-actions "
+        "still listed, the wrong next command).",
+        file=sys.stderr,
+    )
+    print(
+        " - Re-render PROJECT-STATUS.html from the markdown NOW, in this turn, "
+        "using the shared scaffold in "
+        ".tfcore/templates/v4custom/html-render-shell.md (§1 slug rule, §2 CSS, "
+        "§3 skeleton, §4 anchors, §7 JS). Keep the existing shell — update the "
+        "body sections, the subtitle's current_phase/last-updated line, and add "
+        "the new Verification-log row. Sidebar TOC iff >6 H2s.",
+        file=sys.stderr,
+    )
+    print(
+        " - Then confirm parity: same H2 set and same slugs in both files, and no "
+        "string surviving in the HTML that the markdown no longer says.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+sys.exit(0)
+PY
+exit $?

package/.tfcore/hooks/guard-status.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — blocks convoluted PROJECT-STATUS.md writes.
+#
+# PROJECT-STATUS is a CRISP, FIXED-SHAPE snapshot agents OVERWRITE — never an
+# append-log. See .tfcore/tasks/_status-update-gate.md §"CRISP, FIXED-SHAPE
+# snapshot" and .tfcore/templates/v4custom/app-project-status-tmpl.md. The prose
+# rule alone kept failing (AstroLyfe's 286-line mess, repeat offenses after);
+# this hook makes the shape MECHANICAL, the same way block-git.sh made the git
+# ban mechanical.
+#
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Write|Edit|MultiEdit").
+# Exit 2 + stderr = block the call and feed the message back to the agent.
+#
+# What it blocks (only for files named PROJECT-STATUS.md):
+#   - Any H2 heading outside the template's fixed section set (per-run dated
+#     H2s like "## *verify all — coverage matrix (DATE)" are the disease).
+#   - Headings that name a command run (*verify / *build-phase / *fix-issues).
+#   - A paragraph stuffed into `current_phase:` (must be ONE short line).
+#   - A full-file Write longer than 120 lines (template shape is ~60).
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# stdin feeds python the SCRIPT (heredoc), so the payload travels via env var.
+TF_HOOK_INPUT="$INPUT" python3 - <<'PY'
+import json, os, re, sys
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+ti = data.get("tool_input") or {}
+path = (ti.get("file_path") or "").replace("\\", "/")
+if path.rsplit("/", 1)[-1].lower() != "project-status.md":
+    sys.exit(0)
+
+# Write carries the whole file in `content`; Edit/MultiEdit carry fragments.
+pieces = []
+is_full_write = False
+if isinstance(ti.get("content"), str):
+    pieces.append(ti["content"])
+    is_full_write = True
+if isinstance(ti.get("new_string"), str):
+    pieces.append(ti["new_string"])
+for e in ti.get("edits") or []:
+    if isinstance(e, dict) and isinstance(e.get("new_string"), str):
+        pieces.append(e["new_string"])
+new = "\n".join(pieces)
+if not new:
+    sys.exit(0)
+
+ALLOWED = {
+    "where i am",
+    "next command to run",
+    "open requirements",
+    "known blockers",
+    "verification log",
+    "library feedback summary",
+    "standards compliance",
+    "deferred / future",
+    "recovery note",  # written by *refresh-status, may carry a date
+}
+
+errors = []
+
+for m in re.finditer(r"(?m)^##\s+(.+)$", new):
+    heading = m.group(1).strip()
+    h = heading.rstrip(":").lower()
+    base = re.sub(r"\s*[—\-(].*$", "", h).strip()  # drop trailing dates/qualifiers
+    if h in ALLOWED or base in ALLOWED:
+        continue
+    errors.append(
+        f'H2 "## {heading}" is not a template section. PROJECT-STATUS has EXACTLY '
+        "the fixed sections of app-project-status-tmpl.md — a run NEVER adds a new "
+        "H2; it overwrites the existing sections + adds ONE Verification-log row."
+    )
+
+if re.search(r"(?m)^#{2,}\s.*\*(verify|build-phase|fix-issues|refresh-status)", new):
+    errors.append(
+        "A heading naming a command run (*verify / *build-phase / *fix-issues) is "
+        "per-run narrative. Record the run as ONE Verification-log table row; "
+        "per-REQ detail goes in the checklist Remarks cells."
+    )
+
+m = re.search(r"(?m)^current_phase:\s*(.+)$", new)
+if m and len(m.group(1).strip()) > 120:
+    errors.append(
+        "current_phase must be ONE short line (phase name + at most a half-line "
+        "qualifier), never a paragraph of run detail."
+    )
+
+if is_full_write:
+    n_lines = new.count("\n") + 1
+    if n_lines > 120:
+        errors.append(
+            f"This write is {n_lines} lines. PROJECT-STATUS is a one-page snapshot "
+            "(~60 lines, hard cap 120). TRIM to the template shape — blow-by-blow "
+            "history lives in the checklist Remarks and .verify/ artifacts, never here."
+        )
+
+if errors:
+    print(
+        "BLOCKED by TechieFlow policy: PROJECT-STATUS is a CRISP, FIXED-SHAPE "
+        "snapshot you OVERWRITE in place — never append to, never restructure "
+        "(.tfcore/tasks/_status-update-gate.md).",
+        file=sys.stderr,
+    )
+    for e in errors:
+        print(" - " + e, file=sys.stderr)
+    print(
+        "Fix and retry: keep ONLY the template sections (Where I am / Next command "
+        "to run / Open requirements / Known blockers / Verification log / Library "
+        "feedback summary / Standards compliance / Deferred / future), overwrite "
+        "their content in place, add ONE Verification-log row for this run, and put "
+        "the detail in docs/<APP>-Checklist.md Remarks. Do NOT pad, do NOT narrate.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+
+sys.exit(0)
+PY
+exit $?

package/.tfcore/hooks/guard-verify.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — blocks self-attested `Verified` verdicts.
+#
+# `Verified` is the verifier's verdict, written ONLY by an EXECUTED verify-phase
+# run (chained inline by build-phase §6b, or a standalone `*verify`). On
+# 2026-07-09 a build orchestrator did its own smoke and wrote `Verified`
+# verdicts itself — the prose rule ("chain the verifier") was skipped silently.
+# This hook makes the gate MECHANICAL, the same way block-git.sh made the git
+# ban mechanical and guard-status.sh made the status shape mechanical.
+#
+# How it works: verify-phase §6 writes a run ledger `docs/.last-verify.json`
+# ({"date","app","scope","booted","gates","evidence"}) immediately before it
+# records verdicts — after actually booting the app and running the gates.
+# Any Write/Edit/MultiEdit to a `*-Checklist.md` that INTRODUCES a `Verified`
+# status cell is blocked unless a same-day ledger sits next to the checklist.
+#
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Write|Edit|MultiEdit").
+# Exit 2 + stderr = block the call and feed the message back to the agent.
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# stdin feeds python the SCRIPT (heredoc), so the payload travels via env var.
+TF_HOOK_INPUT="$INPUT" python3 - <<'PY'
+import datetime, json, os, re, sys
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+ti = data.get("tool_input") or {}
+path = (ti.get("file_path") or "").replace("\\", "/")
+if not path.rsplit("/", 1)[-1].lower().endswith("-checklist.md"):
+    sys.exit(0)
+
+# A `Verified` STATUS CELL: a table cell holding exactly Verified (optional
+# bold / trailing date qualifier). Remarks prose like "VERIFIED 2026-07-07"
+# or "Needs re-verify" does not match.
+CELL = re.compile(r"\|\s*\**Verified\**\s*(?:\([^)|]*\))?\s*\|")
+
+new_pieces, old_pieces = [], []
+if isinstance(ti.get("content"), str):
+    new_pieces.append(ti["content"])
+if isinstance(ti.get("new_string"), str):
+    new_pieces.append(ti["new_string"])
+if isinstance(ti.get("old_string"), str):
+    old_pieces.append(ti["old_string"])
+for e in ti.get("edits") or []:
+    if isinstance(e, dict):
+        if isinstance(e.get("new_string"), str):
+            new_pieces.append(e["new_string"])
+        if isinstance(e.get("old_string"), str):
+            old_pieces.append(e["old_string"])
+
+n_new = sum(len(CELL.findall(p)) for p in new_pieces)
+n_old = sum(len(CELL.findall(p)) for p in old_pieces)
+if n_new <= n_old:
+    sys.exit(0)  # no NEW Verified cell introduced (demotions, moves, other edits)
+
+# Introducing `Verified` — require a same-day run ledger next to the checklist.
+ledger_path = os.path.join(os.path.dirname(path), ".last-verify.json")
+try:
+    with open(ledger_path, "r", encoding="utf-8") as f:
+        ledger = json.load(f)
+    if str(ledger.get("date", "")).strip() == datetime.date.today().isoformat():
+        sys.exit(0)  # fresh ledger — an executed verify-phase (or documented reconcile) unlocked it
+    stale = f"exists but is dated {ledger.get('date')!r}, not today"
+except FileNotFoundError:
+    stale = "does not exist"
+except Exception:
+    stale = "exists but is not valid JSON"
+
+print(
+    "BLOCKED by TechieFlow policy: this write INTRODUCES a `Verified` status, "
+    f"but the verify run ledger {ledger_path} {stale}.",
+    file=sys.stderr,
+)
+print(
+    " - `Verified` is the VERIFIER'S verdict. It is written only downstream of an "
+    "EXECUTED .tfcore/tasks/verify-phase.md run — boot the app, run the scoped "
+    "tests, apply the §4a data-render + §4b visual-truth gates, write the run "
+    "ledger (verify-phase §6), THEN record verdicts.",
+    file=sys.stderr,
+)
+print(
+    " - If you are the build orchestrator after your self-smoke: your ceiling is "
+    "`Implemented` (build-phase §6a / _smoke-test-policy). Chain the verifier by "
+    "EXECUTING verify-phase inline (build-phase §6b) — summarizing your smoke as "
+    "a verdict is self-attestation, the exact failure this hook exists to stop.",
+    file=sys.stderr,
+)
+print(
+    " - If you are *refresh-status* reconciling a status column to PRE-EXISTING "
+    "dated VERIFIED evidence already in that row's Remarks: write the ledger with "
+    '{"date":"<today>","mode":"reconcile","evidence":"<the pre-existing remark '
+    'date>"} first (refresh-status §4).',
+    file=sys.stderr,
+)
+print(
+    " - Writing the ledger WITHOUT having run verify-phase's steps is falsifying "
+    "the audit record.",
+    file=sys.stderr,
+)
+sys.exit(2)
+PY
+exit $?