@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/core-config.yaml

@@ -18,6 +18,16 @@ architecture:
   architectureSharded: false
   architectureShardedLocation: docs/architecture
 customTechnicalDocuments: null
+# appSize / appKind: set by the day-1 tasks (reset Session 3, 2026-09-04). Size is Small (up to 10
+# screens, one role, 50 requirements), Medium (up to 20 screens, 100 requirements) or Large (split
+# into phases). Kind is app or library. tf-doc-check.sh reads them when a document header lacks them.
+appSize: null
+appKind: null
+# appPhase: the phase being worked on a Large project (reset Sitting 4b, 2026-09-05). 1 means the
+# plain file names (docs/{AppName}-BRD.md, -Checklist, -UIDesign, -DevGuide); 2 onward means
+# docs/{AppName}-P2-BRD.md and so on. Small and Medium projects leave it at 1. Set with
+# tf-day1-files.sh {AppName} --phase N; handoff moves it on when a phase is all Verified.
+appPhase: 1
 # devLoadAlwaysFiles: the day-1 tasks rewrite this list with the project's concrete paths
 # (docs/{AppName}-Coding-Standards.md + docs/{AppName}-Architecture.md). Empty until then —
 # the stock paths (docs/architecture/coding-standards.md etc.) never exist in this flow.

package/.tfcore/hooks/block-git.sh

@@ -7,7 +7,7 @@
 #
 #  1. GIT GUARD. Git is MANUAL in TechieFlow — agents never COMMIT, PUSH, STAGE,
 #     RESET, CHECKOUT or otherwise WRITE to git, ever (.tfcore/tasks/_smoke-test-policy.md
-#     §"Git is manual", _status-update-gate.md §"Never run git"). Outside YOLO,
+#     owner rule; this hook is the only place it is stated). Outside YOLO,
 #     agents never READ git either (status/log/diff/blame) — status evidence is the
 #     checklist table + working tree + a fresh build. In YOLO mode (below) READ-ONLY
 #     git/gh is allowed; WRITES stay blocked in every mode. settings.json's deny
@@ -55,7 +55,7 @@ block_git_msg() {
   cat >&2 <<'MSG'
 BLOCKED by TechieFlow policy: agents NEVER WRITE to git or gh — no commit / push / add / reset / checkout / stash / tag / merge / rebase / branch edits / gh pr|issue create|merge|close. Git is manual, owner-only, in EVERY mode including YOLO.
 Do NOT retry with another git/gh form. Instead:
-- Status updates / "what changed": read the checklist Requirements Status table + the working-tree files (ls -lt, find -newer, Read/Glob/Grep) + a fresh dotnet build — never commit history (.tfcore/tasks/_status-update-gate.md).
+- Status updates / "what changed": bash .tfcore/utils/tf-status-facts.sh <App> prints the facts from the checklist; the working-tree files (ls -lt, find -newer, Read) are the as-built code — never commit history.
 - Investigating code: read the files on disk at file:line — the working tree IS the as-built code.
 - Committing/tagging: never yours. Record REQ IDs in the checklist Remarks, not in commits. The owner commits manually.
 - If your command merely CONTAINS the word git (e.g. writing a doc, grepping for the string): use the Write/Edit/Grep tools instead of bash — that is the standing tool-preference rule anyway.
@@ -64,7 +64,7 @@ MSG
 block_read_msg() {
   if [[ "$STRICT_GIT" == "1" ]]; then
     cat >&2 <<'MSG'
-BLOCKED by TechieFlow Codex policy: agents do not run any git or gh command, including read-only status/log/diff/blame, in any mode.
+BLOCKED by TechieFlow policy: agents do not run any git or gh command, including read-only status/log/diff/blame, in any mode.
 Use the checklist Requirements Status table, working-tree files, filesystem metadata, and fresh build/test evidence instead. The owner performs version-control operations manually.
 MSG
     return
@@ -72,7 +72,7 @@ MSG
   cat >&2 <<'MSG'
 BLOCKED by TechieFlow policy: agents do not READ git outside YOLO mode (no status/log/diff/show/blame/grep) — git is manual, owner-only.
 Do NOT retry with another git/gh form. Instead:
-- Status updates / "what changed": read the checklist Requirements Status table + the working-tree files (ls -lt, find -newer, Read/Glob/Grep) + a fresh dotnet build — never commit history (.tfcore/tasks/_status-update-gate.md).
+- Status updates / "what changed": bash .tfcore/utils/tf-status-facts.sh <App> prints the facts from the checklist; the working-tree files (ls -lt, find -newer, Read) are the as-built code — never commit history.
 - Investigating code: read the files on disk at file:line — the working tree IS the as-built code.
 - Read-only git (status/log/diff/blame) becomes available only in YOLO / goal mode (`*yolo` → bash .tfcore/utils/tf-yolo.sh on). Git WRITES are never available.
 MSG

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

@@ -13,8 +13,8 @@
 # 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.
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Bash");
+# OpenCode via .opencode/plugin/techieflow.js.
 # Exit 2 + stderr = block the call and feed the message back to the agent.
 #
 # What it blocks:

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

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — in YOLO mode a build, test or app run stays in the FOREGROUND.
+#
+# Why a hook (owner, 2026-09-06; FR-46): twice in one build (MISS-TechieFlow-20260905-23 and
+# MISS-TechieFlow-20260906-05) the agent started the build as a background job and ended its
+# turn "waiting for the build". The turn ending kills the job; the supervisor only re-prompts;
+# three cycles were lost that way. A rule ignored twice becomes a hook, not a third paragraph.
+#
+# What it refuses, only while YOLO is on (TF_YOLO=1, the yolo.json flag, or a harness in
+# bypass / --auto mode):
+#   - a Bash call with run_in_background true whose command builds, tests, runs or publishes:
+#     tf-build.sh, dotnet build|test|run|publish|watch, msbuild, npm|pnpm|yarn build|test|start,
+#     also through winrun / cmd.exe / powershell.exe
+#   - the same commands backgrounded inside the command text: nohup, setsid, disown, or a
+#     trailing / inline `&` (not `&&`)
+# Everything else passes. Outside YOLO nothing changes (the owner may background what they like).
+#
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Bash"); OpenCode via
+# .opencode/plugin/techieflow.js. Exit 2 + stderr = block the call and tell the agent why.
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+ROOT="${CLAUDE_PROJECT_DIR:-${TF_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}}"
+
+yolo=0
+if [[ "${TF_YOLO:-0}" == "1" ]]; then yolo=1
+elif [[ -f "$ROOT/.tfcore/utils/tf-yolo.sh" ]] && CLAUDE_PROJECT_DIR="$ROOT" bash "$ROOT/.tfcore/utils/tf-yolo.sh" is-on >/dev/null 2>&1; then yolo=1
+fi
+
+TF_HOOK_INPUT="$INPUT" TF_YOLO_ON="$yolo" 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)
+
+yolo = os.environ.get("TF_YOLO_ON") == "1" or str(data.get("permission_mode", "")) in ("bypassPermissions", "auto")
+if not yolo:
+    sys.exit(0)
+
+BUILD = (r"\btf-build\.sh\b"
+         r"|\bdotnet\s+(build|test|run|publish|watch)\b"
+         r"|\bmsbuild\b"
+         r"|\b(npm|pnpm|yarn)\s+(run\s+)?(build|test|start|dev)\b"
+         # the verify tooling (Sitting 4c, MISS-TechieFlow-20260906-22): a backgrounded browser
+         # test run ended a verify turn "waiting for the tests" on 2026-09-06
+         r"|\b(npx\s+)?playwright\s+test\b"
+         r"|\btf-verify-(tests|screens|boot|env)\.sh\b"
+         r"|\btf-(assets|mockup-parity|perf)\.sh\b"
+         r"|\bpytest\b")
+low = cmd.lower()
+if not re.search(BUILD, low):
+    sys.exit(0)
+
+bg_flag = bool(ti.get("run_in_background"))
+# `&` that is not `&&` and not inside `2>&1` / `>&2`
+inline_bg = bool(re.search(r"(?<![&>\d])&(?![&\d])", low)) or bool(re.search(r"\b(nohup|setsid|disown)\b", low))
+if not (bg_flag or inline_bg):
+    sys.exit(0)
+
+how = "run_in_background" if bg_flag else "nohup / setsid / a trailing &"
+print("BLOCKED by TechieFlow policy: in YOLO mode a build, test or app run is NEVER started in "
+      f"the background ({how} here). Ending the turn to wait for it kills the job, and nobody "
+      "wakes you; three build cycles were lost that way on 2026-09-06. Run it in the "
+      "foreground and wait: bash .tfcore/utils/tf-build.sh [build|test], npx playwright test, or the "
+      "tf-verify-*.sh scripts (a timeout of ten minutes is fine), then act on the result line. Owner rule 2026-09-06 (FR-46).",
+      file=sys.stderr)
+sys.exit(2)
+PY
+exit $?

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

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — database writes happen only from build-phase or fix-issues,
+# and only through the migration path the Stack decisions name (owner, 2026-09-05;
+# MISS-TechieFlow-20260905-09: a day-1 run created a user and patched two stored
+# procedures in the development database).
+#
+# What it refuses, in every command:
+#   - a direct SQL write through a client: psql, pgcli, sqlite3, mysql, mariadb, sqlcmd,
+#     mongosh with INSERT / UPDATE / DELETE / CREATE / ALTER / DROP / TRUNCATE / GRANT /
+#     REPLACE / MERGE in the command text, a -f / -i script, or stdin redirected from a file
+#   - dropping or resetting a database
+# What it allows only while .tfcore/.session/phase.json says build-phase or fix-issues
+# (written by bash .tfcore/utils/tf-phase.sh start <command>, step 0 of every task):
+#   - a migration runner: dotnet ef database update, dotnet run --project <…Db|…Migration(s)…>,
+#     dbup, flyway migrate, liquibase update, alembic upgrade, prisma migrate, knex migrate,
+#     rails db:migrate, sequelize db:migrate
+# Reads (SELECT, \d, .tables, dumps to stdout) pass. YOLO does not relax this.
+#
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Bash"); OpenCode via
+# .opencode/plugin/techieflow.js. Exit 2 + stderr = block the call and tell the agent why.
+# Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
+
+INPUT="$(cat)"
+command -v python3 >/dev/null 2>&1 || exit 0
+ROOT="${CLAUDE_PROJECT_DIR:-$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)}"
+
+TF_HOOK_INPUT="$INPUT" TF_ROOT="$ROOT" python3 - <<'PY'
+import json, os, re, sys, time
+
+try:
+    data = json.loads(os.environ.get("TF_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+cmd = (data.get("tool_input") or {}).get("command")
+if not isinstance(cmd, str) or not cmd.strip():
+    sys.exit(0)
+
+WRITE_VERBS = r"\b(insert|update|delete|create|alter|drop|truncate|grant|revoke|replace|merge|upsert)\b"
+CLIENTS = r"\b(psql|pgcli|sqlite3|mysql|mariadb|sqlcmd|mongosh|mongo)\b"
+MIGRATORS = (r"\bdotnet\s+ef\s+database\s+(update|drop)\b"
+             r"|\bdotnet\s+run\b[^|;&]*--project\s+\S*(db|migration|migrations)\b"
+             r"|\bdbup\b|\bflyway\s+(migrate|clean|undo)\b|\bliquibase\s+(update|rollback|drop-all)\b"
+             r"|\balembic\s+(upgrade|downgrade)\b|\bprisma\s+(migrate|db\s+push)\b|\bknex\s+migrate\b"
+             r"|\brails\s+db:(migrate|reset|drop|schema:load)\b|\bsequelize\s+db:migrate\b|\bgoose\s+(up|down|reset)\b")
+DROP_DB = r"\b(dropdb|drop\s+database|mongo(sh)?\b[^|;&]*dropDatabase)\b"
+
+def phase():
+    p = os.path.join(os.environ.get("TF_ROOT", "."), ".tfcore", ".session", "phase.json")
+    try:
+        if time.time() - os.path.getmtime(p) > 24 * 3600:
+            return None
+        with open(p, encoding="utf-8") as fh:
+            return (json.load(fh) or {}).get("cmd")
+    except Exception:
+        return None
+
+# Words inside an echo/printf string or a comment line are not commands: an echo naming the
+# migration tool refused a verify run's read on 2026-09-06 (MISS-TechieFlow-20260906-20).
+# Strip them before matching, so only a command that runs a migrator or writes through a
+# client is refused.
+low = cmd.lower()
+low = re.sub(r"(?m)^\s*#.*$", "", low)
+low = re.sub(r"\b(echo|printf)\s+(\"[^\"]*\"|'[^']*'|[^\n;|&]*)", r"\1", low)
+direct_write = (re.search(CLIENTS, low)
+                and (re.search(WRITE_VERBS, low)
+                     or re.search(r"\s-(f|i)\s+\S+\.sql\b", low)
+                     or re.search(r"<\s*\S+\.sql\b", low)))
+if direct_write or re.search(DROP_DB, low):
+    print("BLOCKED by TechieFlow policy: a direct database write (SQL through a client, or dropping "
+          "a database) is not allowed from any command. Schema and data changes go through the "
+          "migration path named in the Architecture's Stack decisions (for the .NET answer set, the "
+          "<App>Db DbUp project), run from *build-phase or *fix-issues. A read (SELECT, \\d, .tables) "
+          "is fine. Owner rule 2026-09-05.", file=sys.stderr)
+    sys.exit(2)
+
+if re.search(MIGRATORS, low):
+    ph = phase()
+    if ph in ("build-phase", "fix-issues"):
+        sys.exit(0)
+    who = f"the marker says {ph}" if ph else "no command marker is set"
+    print("BLOCKED by TechieFlow policy: a database migration runs only from *build-phase or "
+          f"*fix-issues, and {who}. Day-1, mockups, split-brd, amend-docs, devguide, verify, "
+          "triage and status commands write documents and records, never the database. If you are "
+          "inside build-phase or fix-issues, step 0 was skipped: run "
+          "bash .tfcore/utils/tf-phase.sh start <command> <App> and retry. Owner rule 2026-09-05.",
+          file=sys.stderr)
+    sys.exit(2)
+sys.exit(0)
+PY
+exit $?

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

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# TechieFlow PreToolUse hook — the telemetry streams are written ONLY by tf-emit.sh.
+#
+# docs/metrics/*.jsonl are append-only histories (SCHEMA.md §10, _metrics-emit-gate.md).
+# This hook refuses every other way of writing them:
+#   - Write / Edit / MultiEdit whose file_path is a docs/metrics/*.jsonl file
+#   - a shell command that writes one: redirection (> >>), tee, cp/mv/install onto
+#     it, sed -i / perl -i, a python/node one-liner naming it, truncate/dd
+# Reading them is fine. `bash .tfcore/utils/tf-emit.sh <stream>` never names the
+# file on the command line, so it passes; so do tf-metrics.sh --report/--rollup.
+#
+# Wired in .claude/settings.json -> hooks.PreToolUse (matcher "Write|Edit|MultiEdit"
+# AND matcher "Bash"); OpenCode via .opencode/plugin/techieflow.js.
+# 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
+
+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 {}
+STREAM = r"docs/metrics/[\w.-]+\.jsonl"
+# What makes a python/node command a WRITE rather than a read: an explicit write mode,
+# something that emits, or a move onto the path. A read names none of these.
+WRITEY = (r"(?:['\"][wax]b?\+?['\"]|\.write\b|\.writelines\b|json\.dump\b|"
+          r"\btruncate\b|\bos\.rename\b|\bos\.replace\b|\bshutil\.(?:copy|move)\b|"
+          r"createWriteStream|writeFileSync|appendFileSync)")
+
+MSG = ("BLOCKED by TechieFlow policy: docs/metrics/*.jsonl are append-only telemetry "
+       "streams written only through bash .tfcore/utils/tf-emit.sh <stream> (stdin JSON). "
+       "Never Write, Edit, redirect or copy onto them. A wrong record is corrected by a "
+       "new record (miss-fix, miss-amend, a later gate), never by an edit.")
+
+fp = ti.get("file_path") or ti.get("filePath")
+if isinstance(fp, str) and re.search(STREAM + r"$", fp.replace("\\", "/"), re.I):
+    print(MSG, file=sys.stderr)
+    sys.exit(2)
+
+cmd = ti.get("command")
+if isinstance(cmd, str) and re.search(STREAM, cmd, re.I):
+    if re.search(
+        r"(>>?\s*[\"']?[^\s|;&]*" + STREAM + r")"
+        r"|(\btee\b[^|;&]*" + STREAM + r")"
+        r"|(\b(cp|mv|install)\b[^|;&]*" + STREAM + r")"
+        r"|(\b(sed|perl)\b[^|;&]*\s-[a-zA-Z]*i[a-zA-Z]*\b[^|;&]*" + STREAM + r")"
+        # A python/node command NAMING a stream used to be blocked outright, which also
+        # refused every READ -- and this file's own header says reading is fine. Checking
+        # a stream with a one-liner is a normal, frequent thing to do, and a guard that
+        # blocks it teaches people to route around the guard. So the clause now needs a
+        # write in the command as well as the path. MISS-TechieFlow-20260909-03.
+        r"|(\b(python3?|node)\b[^|;&]*" + STREAM + r"[^|;&]*" + WRITEY + r")"
+        r"|(\b(python3?|node)\b[^|;&]*" + WRITEY + r"[^|;&]*" + STREAM + r")"
+        r"|(\b(truncate|dd)\b[^|;&]*" + STREAM + r")",
+        cmd, re.I,
+    ):
+        print(MSG, file=sys.stderr)
+        sys.exit(2)
+
+sys.exit(0)
+PY
+exit $?

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

@@ -1,102 +1,147 @@
 #!/usr/bin/env bash
-# TechieFlow Stop hook — refuses to end a turn while PROJECT-STATUS.html is stale.
+# TechieFlow Stop hook — refuses to end a turn while the status gate is incomplete.
 #
-# _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 gate (_status-update-gate.md) is six steps an agent can forget. This hook
+# checks the RESULT of each step, so a forgotten step cannot end the turn. It
+# prints one line per outstanding item, each naming the one command to run.
 #
-# 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.
+#   1. PROJECT-STATUS.html missing or older than PROJECT-STATUS.md
+#        -> bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md
+#   Only when PROJECT-STATUS.md was written in this session (newer than the
+#   session pointer .tfcore/.session/<harness>.json):
+#   2. tf-doc-check.sh FAILs on PROJECT-STATUS.md      -> fix the file, re-run the check
+#   3. docs/<App>-BRD.md older than docs/<App>-Checklist.md
+#        -> bash .tfcore/utils/tf-brd-status.sh <App>
+#   4. no runs.jsonl record after the status write     -> the run record (_metrics-emit-gate.md)
 #
-# 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).
+# Wired in .claude/settings.json -> hooks.Stop; OpenCode via
+# .opencode/plugin/techieflow.js session.idle (a nudge: OpenCode has no blocking
+# Stop hook). Exit 2 + stderr = block the stop and feed the message to the agent.
+# Honours stop_hook_active so a wedged turn can still end (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
+import datetime
+import glob
+import json
+import os
+import subprocess
+import 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)
 
+problems = []
 md_mtime = os.path.getmtime(md)
 
+# 1. HTML present and current
 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"
+    problems.append("PROJECT-STATUS.html does not exist. Run: bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md")
+elif md_mtime > os.path.getmtime(html):
+    problems.append("PROJECT-STATUS.html is older than PROJECT-STATUS.md. Run: bash .tfcore/utils/tf-render-html.sh PROJECT-STATUS.md")
+
+
+def session_start():
+    """mtime of the harness's session pointer; None when there is none (checks 2-4 skipped)."""
+    d = os.path.join(root, ".tfcore", ".session")
+    if any(k.startswith("OPENCODE") for k in os.environ):
+        cands = [os.path.join(d, "opencode.json")]
+    elif os.environ.get("CLAUDECODE") or any(k.startswith("CLAUDE_CODE") for k in os.environ):
+        cands = [os.path.join(d, "claude-code.json")]
     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)
+        cands = [os.path.join(d, "claude-code.json"), os.path.join(d, "opencode.json")]
+    times = [os.path.getmtime(p) for p in cands if os.path.isfile(p)]
+    return max(times) if times else None
+
+
+start = session_start()
+written_this_session = start is not None and md_mtime >= start
+
+if written_this_session:
+    # 2. the checker passes on the status file
+    try:
+        chk = os.path.join(root, ".tfcore", "utils", "tf-doc-check.sh")
+        if os.path.isfile(chk):
+            out = subprocess.run(["bash", chk, "--quiet", "PROJECT-STATUS.md"], cwd=root,
+                                 capture_output=True, text=True, timeout=60).stdout
+            fails = [l for l in out.splitlines() if l.startswith("FAIL")]
+            if fails:
+                problems.append(f"PROJECT-STATUS.md fails the document check ({len(fails)} line(s)). Fix it, then run: bash .tfcore/utils/tf-doc-check.sh PROJECT-STATUS.md")
+                problems.extend("  " + l for l in fails[:5])
+    except Exception:
+        pass
+
+    # 2b. the checker passes on every checklist written this session. Until 2026-09-06 only
+    # PROJECT-STATUS was checked here, so a build closed its gate with three Remarks cells over
+    # 60 words in the checklist and nothing refused the stop (MISS-TechieFlow-20260906-06).
+    try:
+        chk = os.path.join(root, ".tfcore", "utils", "tf-doc-check.sh")
+        if os.path.isfile(chk):
+            for cl in sorted(glob.glob(os.path.join(root, "docs", "*-Checklist.md"))):
+                if os.path.getmtime(cl) < start:
+                    continue
+                rel = os.path.relpath(cl, root)
+                out = subprocess.run(["bash", chk, "--quiet", rel], cwd=root,
+                                     capture_output=True, text=True, timeout=120).stdout
+                fails = [l for l in out.splitlines() if l.startswith("FAIL")]
+                if fails:
+                    problems.append(f"{rel} fails the document check ({len(fails)} line(s)). Fix the rows, then run: bash .tfcore/utils/tf-doc-check.sh {rel}")
+                    problems.extend("  " + l for l in fails[:5])
+    except Exception:
+        pass
+
+    # 3. the BRD's Development status table is not older than the checklist
+    try:
+        for cl in glob.glob(os.path.join(root, "docs", "*-Checklist.md")):
+            app = os.path.basename(cl)[: -len("-Checklist.md")]
+            brd = os.path.join(root, "docs", f"{app}-BRD.md")
+            if os.path.isfile(brd) and os.path.getmtime(cl) > os.path.getmtime(brd):
+                problems.append(f"docs/{app}-BRD.md is older than docs/{app}-Checklist.md. Run: bash .tfcore/utils/tf-brd-status.sh {app}")
+    except Exception:
+        pass
+
+    # 4. a run record follows the status write (5 minutes of tolerance for emit-before-write)
+    try:
+        runs = os.path.join(root, "docs", "metrics", "runs.jsonl")
+        last = None
+        if os.path.isfile(runs):
+            with open(runs, encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    try:
+                        ts = json.loads(line).get("ts")
+                    except Exception:
+                        continue
+                    if ts:
+                        last = ts
+        last_epoch = None
+        if last:
+            last_epoch = datetime.datetime.strptime(last[:19], "%Y-%m-%dT%H:%M:%S").replace(
+                tzinfo=datetime.timezone.utc).timestamp()
+        if last_epoch is None or last_epoch < md_mtime - 300:
+            problems.append("PROJECT-STATUS.md was written but no run record follows it in docs/metrics/runs.jsonl. Append the run record: .tfcore/tasks/_metrics-emit-gate.md")
+    except Exception:
+        pass
+
+if not problems:
+    sys.exit(0)
+
+print("BLOCKED by TechieFlow policy: the status gate is not complete (_status-update-gate.md).", file=sys.stderr)
+for p in problems:
+    print(" - " + p, file=sys.stderr)
+sys.exit(2)
 PY
 exit $?

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

@@ -1,14 +1,14 @@
 #!/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.
+# PROJECT-STATUS is a one-page snapshot agents overwrite in place, never an
+# append-log. The shape is the template .tfcore/templates/v4custom/app-project-status-tmpl.md;
+# the steps are .tfcore/tasks/_status-update-gate.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").
+# Wired in .claude/settings.json → hooks.PreToolUse (matcher "Write|Edit|MultiEdit"
+# AND matcher "Bash"); OpenCode via .opencode/plugin/techieflow.js.
 # Exit 2 + stderr = block the call and feed the message back to the agent.
 #
 # What it blocks (only for files named PROJECT-STATUS.md):
@@ -17,6 +17,11 @@
 #   - 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).
+#   - (Bash) any shell command that WRITES the file — redirection, tee, cp, mv,
+#     sed -i, a Python/Node one-liner — because a shell write is invisible to the
+#     Write/Edit checks above (reset Session 3, 2026-09-04). Reading it is fine.
+# Content rules (section word limits, the two command blocks, the five-row log)
+# are checked by .tfcore/utils/tf-doc-check.sh at the status gate.
 # Fails OPEN (exit 0) if python3 or parseable JSON is unavailable.
 
 INPUT="$(cat)"
@@ -32,6 +37,31 @@ except Exception:
     sys.exit(0)
 
 ti = data.get("tool_input") or {}
+
+# --- Bash branch: refuse shell writes to PROJECT-STATUS.md -------------------
+cmd = ti.get("command")
+if isinstance(cmd, str):
+    if re.search(r"PROJECT-STATUS\.md", cmd, re.I) and re.search(
+        r"(>>?\s*[\"']?[^\s|;&]*PROJECT-STATUS\.md)"      # > / >> redirection
+        r"|(\btee\b[^|;&]*PROJECT-STATUS\.md)"            # tee
+        r"|(\b(cp|mv|install)\b[^|;&]*PROJECT-STATUS\.md)"  # copy / move onto it
+        r"|(\b(sed|perl)\b[^|;&]*\s-[a-zA-Z]*i[a-zA-Z]*\b[^|;&]*PROJECT-STATUS\.md)"  # in-place edit
+        r"|(\b(python3?|node)\b[^|;&]*PROJECT-STATUS\.md)"  # a one-liner that opens it
+        r"|(\b(truncate|dd)\b[^|;&]*PROJECT-STATUS\.md)",
+        cmd, re.I,
+    ):
+        print(
+            "BLOCKED by TechieFlow policy: PROJECT-STATUS.md is written ONLY through "
+            "the harness Write/Edit tool, never through the shell (redirection, tee, "
+            "cp, mv, sed -i, a script). The shell path bypasses the shape guard, which "
+            "is how status files got spoiled. Write the file with the Write tool in the "
+            "template shape (.tfcore/templates/v4custom/app-project-status-tmpl.md), "
+            "then run: bash .tfcore/utils/tf-doc-check.sh PROJECT-STATUS.md",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    sys.exit(0)
+
 path = (ti.get("file_path") or "").replace("\\", "/")
 if path.rsplit("/", 1)[-1].lower() != "project-status.md":
     sys.exit(0)
@@ -97,24 +127,21 @@ if is_full_write:
         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."
+            "history lives in the checklist Remarks and the telemetry streams, 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).",
+        "BLOCKED by TechieFlow policy: PROJECT-STATUS is a one-page snapshot you "
+        "overwrite in place, never append to (.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.",
+        "Fix and retry: run bash .tfcore/utils/tf-status-facts.sh <App> and write only "
+        "the eight template sections (.tfcore/templates/v4custom/app-project-status-tmpl.md), "
+        "each overwritten in place. The detail goes in the checklist Remarks, not here.",
         file=sys.stderr,
     )
     sys.exit(2)