@techierathore/techieflow 1.0.1 → 1.0.3

package/.tfcore/utils/tf-perf-grade.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""tf-perf-grade.py — grade a tf-perf.sh measurement against a row's budget (see tf-perf-grade.sh).
+
+    bash .tfcore/utils/tf-perf-grade.sh --budget "p95 ttfb <= 500ms @ concurrency 50" \
+         --json tests/.artifacts/verify/perf/REQ-NFR-001.json [--json-out <file>]
+
+Prints one line: PERF-OK | PERF-MARGINAL (over the budget by up to a quarter: a warning, never a
+demotion) | PERF-FAIL (slower than budget × 1.25, or the app shed a tenth or more of the requests
+at that concurrency) | PERF-UNMEASURED with the reason (unreachable, auth wall, non-200 answers,
+errors during the run, a Debug build, fewer than 20 samples). It reads the budget, never invents
+one. Exit 0 OK or MARGINAL · 1 FAIL · 2 UNMEASURED · 3 usage.
+"""
+import json
+import os
+import re
+import sys
+
+BUDGET = re.compile(r"(p50|p95|max)\s+(ttfb|load)\s*<=\s*(\d+)\s*ms(?:\s*@\s*concurrency\s+(\d+))?", re.I)
+
+
+def grade(budget, data):
+    """-> dict(verdict, reason, metric, percentile, measured, budget, concurrency, failure_class)"""
+    m = BUDGET.search(budget or "")
+    if not m:
+        return {"verdict": "PERF-UNMEASURED", "reason": f"budget line not in the fixed form: {budget!r}"}
+    pct, metric, limit, conc = m.group(1).lower(), m.group(2).lower(), int(m.group(3)), int(m.group(4) or 1)
+    out = {"metric": metric, "percentile": pct, "budget": limit, "concurrency": conc, "measured": None, "failure_class": None}
+    st = data.get("status")
+    if st == "unreachable":
+        return dict(out, verdict="PERF-UNMEASURED", reason="the app was unreachable (a build check problem, not a speed result)")
+    if st == "redirected":
+        return dict(out, verdict="PERF-UNMEASURED", reason="auth wall: every request was redirected; present a session with --cookie or --header")
+    levels = data.get("levels") or []
+    if not levels:
+        return dict(out, verdict="PERF-UNMEASURED", reason="no measurement level in the file")
+    lvl = next((l for l in levels if l.get("concurrency") == conc), None)
+    note = ""
+    if lvl is None:
+        lvl = levels[0]
+        note = f" (measured at concurrency {lvl.get('concurrency')}, the budget names {conc})"
+    err_rate = lvl.get("error_rate") or 0
+    if err_rate >= 0.10:
+        surv = (lvl.get(f"{metric}_ms") or {}).get(pct)
+        return dict(out, verdict="PERF-FAIL", failure_class="timeout", measured=surv,
+                    reason=f"{lvl.get('errors')} of {lvl.get('samples', 0) + lvl.get('errors', 0)} requests failed at concurrency {lvl.get('concurrency')}: the budget is not servable; survivors' {pct} {metric} {surv} ms")
+    if lvl.get("non_200"):
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"non-200 answers ({', '.join(lvl['non_200'][:3])}); a wrong path or a correctness failure, not a speed result")
+    if (lvl.get("redirect_rate") or 0) > 0:
+        return dict(out, verdict="PERF-UNMEASURED", reason="some requests were redirected (auth wall); present a session and re-measure")
+    if err_rate > 0:
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"errors during the run (rate {err_rate}); re-run when quiet")
+    if str(data.get("build_config", "unknown")) != "Release":
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"build is {data.get('build_config', 'unknown')}, not Release; a Debug number is not evidence")
+    val = (lvl.get(f"{metric}_ms") or {}).get(pct)
+    if val is None:
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"no {pct} {metric} figure in the file")
+    out["measured"] = val
+    if lvl.get("weak"):
+        return dict(out, verdict="PERF-UNMEASURED", reason=f"weak sample ({lvl.get('samples')} requests behind the {pct}); raise --requests and re-run")
+    if val <= limit:
+        return dict(out, verdict="PERF-OK", reason=f"{pct} {metric} {val} ms within {limit} ms @ concurrency {lvl.get('concurrency')}{note}")
+    if val <= limit * 1.25:
+        return dict(out, verdict="PERF-MARGINAL", reason=f"{pct} {metric} {val} ms vs budget {limit} ms @ concurrency {lvl.get('concurrency')} (marginal){note}")
+    return dict(out, verdict="PERF-FAIL", failure_class="slow-ttfb" if metric == "ttfb" else "slow-load",
+                reason=f"{pct} {metric} {val} ms vs budget {limit} ms @ concurrency {lvl.get('concurrency')}{note}")
+
+
+def main(argv):
+    budget = jpath = out = None
+    i = 1
+    while i < len(argv):
+        if argv[i] == "--budget" and i + 1 < len(argv):
+            budget = argv[i + 1]; i += 2
+        elif argv[i] == "--json" and i + 1 < len(argv):
+            jpath = argv[i + 1]; i += 2
+        elif argv[i] == "--json-out" and i + 1 < len(argv):
+            out = argv[i + 1]; i += 2
+        else:
+            print(__doc__); return 3
+    if not budget or not jpath:
+        print(__doc__); return 3
+    if not os.path.isfile(jpath):
+        print(f"PERF-UNMEASURED reason=measurement file {jpath} does not exist"); return 2
+    try:
+        data = json.load(open(jpath, encoding="utf-8"))
+    except Exception as e:
+        print(f"PERF-UNMEASURED reason=measurement file unreadable: {e}"); return 2
+    g = grade(budget, data)
+    if out:
+        os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+        json.dump(g, open(out, "w"), indent=1)
+    print(f"{g['verdict']} reason={g['reason']}")
+    return {"PERF-OK": 0, "PERF-MARGINAL": 0, "PERF-FAIL": 1}.get(g["verdict"], 2)
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/.tfcore/utils/tf-perf-grade.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# tf-perf-grade.sh — grade a tf-perf.sh measurement against a row's declared budget (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-perf-grade.sh --budget "p95 ttfb <= 500ms @ concurrency 50" \
+#        --json tests/.artifacts/verify/perf/REQ-NFR-001.json [--json-out <file>]
+#
+# Prints PERF-OK, PERF-MARGINAL, PERF-FAIL or PERF-UNMEASURED with the reason. Never invents a budget.
+# Exit 0 OK or MARGINAL · 1 FAIL · 2 UNMEASURED · 3 usage. Details: tf-perf-grade.py.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "PERF-UNMEASURED reason=python3 is required"; exit 2; }
+exec python3 "$HERE/tf-perf-grade.py" "$@"

package/.tfcore/utils/tf-phase.sh

@@ -0,0 +1,74 @@
+#!/usr/bin/env bash
+# tf-phase.sh — mark which TechieFlow command is running (Sitting 4b, 2026-09-05).
+#
+#   bash .tfcore/utils/tf-phase.sh start <command> [App]   # step 0 of every task: prints the start
+#                                                          # time and writes the marker
+#   bash .tfcore/utils/tf-phase.sh show                    # prints the marker, or "none"
+#   bash .tfcore/utils/tf-phase.sh end                     # removes the marker
+#   bash .tfcore/utils/tf-phase.sh goal [App]              # tf-goal.sh only: an unclaimed marker the first
+#                                                          # command's `start` claims, keeping its started
+#
+# The marker is .tfcore/.session/phase.json:
+#   {"cmd":"build-phase","app":"MyApp","started":"2026-09-05T16:19:38Z"}
+# Who reads it:
+#   - .tfcore/hooks/guard-db.sh: a migration runner is allowed only while the marker says
+#     build-phase or fix-issues (MISS-TechieFlow-20260905-09: day-1 patched a database).
+#   - tf-emit.sh: a run record that leaves `started` out gets it from here, so the start
+#     time is a measurement, never reconstructed.
+# A marker older than 24 h is ignored by the readers (a killed session must not keep a
+# grant alive). The next `start` overwrites; `end` is optional tidiness.
+# Never committed: .tfcore/.session/ is git-ignored. Exit 0 always except a usage error (2).
+set -u
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+DIR="$ROOT/.tfcore/.session"
+FILE="$DIR/phase.json"
+case "${1:-}" in
+  start)
+    CMD="${2:-}"
+    [[ -z "$CMD" ]] && { echo "tf-phase: usage: tf-phase.sh start <command> [App]" >&2; exit 2; }
+    CMD="${CMD#\*}"
+    APP="${3:-}"
+    NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    mkdir -p "$DIR"
+    # A supervisor (tf-goal.sh) writes an unclaimed marker {"cmd":"goal",…} when its first cycle
+    # starts. The first command of that run claims it and KEEPS its started: the run began when
+    # the harness began reading, not when the agent got round to step 0 (MISS-TechieFlow-20260905-20:
+    # a 38-minute stage 2 recorded a 27-second run because step 0 ran last).
+    if [[ -f "$FILE" ]] && grep -q '"cmd":"goal"' "$FILE" && [[ -z "$(find "$FILE" -mmin +1440 2>/dev/null)" ]]; then
+      NOW="$(sed -n 's/.*"started":"\([^"]*\)".*/\1/p' "$FILE")"
+      echo "tf-phase: started taken from the supervisor's marker ($NOW)" >&2
+    fi
+    printf '{"cmd":"%s","app":"%s","started":"%s"}\n' "$CMD" "$APP" "$NOW" > "$FILE"
+    echo "$NOW"
+    echo "tf-phase: $CMD${APP:+ $APP} started $NOW (marker .tfcore/.session/phase.json)" >&2
+    # The document-check baseline (Sitting 4c, 2026-09-06): the findings the checklists and the
+    # status file already carry when the command starts are recorded, so the gate and the Stop
+    # hook block only on findings this command introduces (Schemas §7.1 decision 8: old projects
+    # are repaired through *amend-docs, never by whichever command happens to run next).
+    if [[ -x "$ROOT/.tfcore/utils/tf-doc-check.sh" || -f "$ROOT/.tfcore/utils/tf-doc-check.sh" ]]; then
+      docs=(); for f in "$ROOT"/docs/*-Checklist.md "$ROOT"/PROJECT-STATUS.md; do [[ -f "$f" ]] && docs+=("$f"); done
+      if [[ ${#docs[@]} -gt 0 ]]; then
+        ( cd "$ROOT" && bash .tfcore/utils/tf-doc-check.sh --root "$ROOT" --baseline-write "${docs[@]}" 2>/dev/null | tail -1 >&2 ) || true
+      fi
+    fi
+    ;;
+  goal)
+    # written by tf-goal.sh at the start of a run's first cycle; claimed by the first `start`
+    NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    mkdir -p "$DIR"
+    printf '{"cmd":"goal","app":"%s","started":"%s"}\n' "${2:-}" "$NOW" > "$FILE"
+    echo "$NOW"
+    ;;
+  show)
+    if [[ -f "$FILE" ]]; then cat "$FILE"; else echo "none"; fi
+    ;;
+  end)
+    rm -f "$FILE"
+    echo "tf-phase: marker removed"
+    ;;
+  *)
+    sed -n '2,20p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    exit 2
+    ;;
+esac
+exit 0

package/.tfcore/utils/tf-routing-bind.sh

@@ -16,9 +16,6 @@
 #                                         model-only agent entries merge, command
 #                                         entries must be complete → they carry
 #                                         template+description+model)
-#   Codex:
-#     .codex/agents/*.toml + .agents/skills/techieflow-*/SKILL.md, generated
-#     by tf-codex-bind.py. Subagent model/effort is pinned when routing is on;
 #     skills remain thin loaders and do not claim to switch the main thread.
 #
 # When `enabled: false` (the default) every generated artifact is REMOVED, using
@@ -109,9 +106,18 @@ def write(relpath, content):
 
 MARK = "<!-- generated by tf-routing-bind.sh from .tfcore/routing.yaml — do not edit; edit routing.yaml and re-run -->"
 
+# A phase whose task file no longer ships gets no binding, with a printed warning: the seven
+# never-used commands were removed in Sitting 4c (2026-09-06) and routing.yaml is preserved per
+# project, so a stale line there must never write a file reference OpenCode refuses to load
+# (MISS-TechieFlow-20260906-27: OpenCode would not start on TechieBlog-oc).
+for _ph in sorted(cfg["phases"]):
+    if not os.path.isfile(os.path.join(root, ".tfcore", "tasks", _ph + ".md")):
+        print("tf-routing-bind: phase %s has no task file .tfcore/tasks/%s.md; no binding written (remove the line from routing.yaml)" % (_ph, _ph))
+        del cfg["phases"][_ph]
+
 # --- Claude Code: routed wrapper commands ---------------------------------
 OWNER = {"day1-greenfield": "analyst", "day1-brownfield": "analyst",
-         "author-brd": "analyst", "amend-docs": "analyst", "mockups": "analyst",
+         "amend-docs": "analyst", "mockups": "analyst",
          "split-brd": "analyst", "verify-phase": "verifier"}
 for phase, t in sorted(cfg["phases"].items()):
     m = model_for(t, "claude")
@@ -212,5 +218,4 @@ with open(manifest_path, "w", encoding="utf-8", newline="\n") as fh:
 print("tf-routing-bind: routing enabled — %d artifact(s) generated (%d stale removed)"
       % (len(generated), removed))
 PY
-python3 "$SELF_DIR/tf-codex-bind.py" "$ROOT" || echo "tf-routing-bind: warning: Codex bindings were not refreshed" >&2
 exit 0

package/.tfcore/utils/tf-routing.sh

@@ -8,7 +8,7 @@
 #   bash .tfcore/utils/tf-routing.sh set-model <tier> <harness> <model>
 #                                                               e.g. set-model economy opencode opencode-go/deepseek-v4-flash
 #                                                               e.g. set-model frontier claude opus
-#                                                               e.g. set-model standard codex gpt-5.6-terra
+#                                                               e.g. set-model standard opencode openai/gpt-5.6-terra
 #   bash .tfcore/utils/tf-routing.sh bind                       re-generate bindings after editing routing.yaml by hand
 #   bash .tfcore/utils/tf-routing.sh set-escalation <phase> <attempts> <tier>
 #                                                               e.g. set-escalation fix-issues 2 frontier
@@ -90,12 +90,12 @@ PY
   set-model)
     TIER="${2:-}"; HARNESS="${3:-}"; MODEL="${4:-}"
     case "$TIER" in frontier|standard|economy) ;; *)
-      echo "usage: tf-routing.sh set-model <frontier|standard|economy> <claude|opencode|codex> <model-id>" >&2; exit 2 ;;
+      echo "usage: tf-routing.sh set-model <frontier|standard|economy> <claude|opencode> <model-id>" >&2; exit 2 ;;
     esac
-    case "$HARNESS" in claude|opencode|codex) ;; *)
-      echo "harness must be claude, opencode, or codex" >&2; exit 2 ;;
+    case "$HARNESS" in claude|opencode) ;; *)
+      echo "harness must be claude or opencode" >&2; exit 2 ;;
     esac
-    [[ -n "$MODEL" ]] || { echo "usage: tf-routing.sh set-model <tier> <claude|opencode|codex> <model-id>" >&2; exit 2; }
+    [[ -n "$MODEL" ]] || { echo "usage: tf-routing.sh set-model <tier> <claude|opencode> <model-id>" >&2; exit 2; }
     python3 - "$RY" "$TIER" "$HARNESS" "$MODEL" <<'PY'
 import sys
 p, tier, harness, model = sys.argv[1:5]
@@ -199,7 +199,7 @@ print()
 print("Tier models:")
 for t in ("frontier", "standard", "economy"):
     m = cfg["tiers"].get(t, {})
-    print("  %-9s claude: %-10s opencode: %-36s codex: %s" % (t, m.get("claude", "-"), m.get("opencode", "-"), m.get("codex", "-")))
+    print("  %-9s claude: %-10s opencode: %s" % (t, m.get("claude", "-"), m.get("opencode", "-")))
 print()
 print("Phases by tier:")
 for t in ("frontier", "standard", "economy", "inherit"):
@@ -226,7 +226,6 @@ if cfg["enabled"]:
     print("Invoke routed phases as:")
     print("  OpenCode:    /techieflow:tasks:<phase>        (same commands as always — model now pinned)")
     print("  Claude Code: /tf:<phase>                      (new wrappers; old commands still work, unrouted)")
-    print("  Codex:        $techieflow-<phase>              (main-thread model inherited; delegated roles are pinned)")
     print()
     print("WHERE YOU SEE IT — opening the TUI looks UNCHANGED on purpose: your normal chat")
     print("(the default 'build' agent) stays on YOUR selected model. Routing becomes visible when:")

package/.tfcore/utils/tf-split-brd.py

@@ -0,0 +1,304 @@
+#!/usr/bin/env python3
+"""tf-split-brd.py — draft docs/<App>-Checklist.md from the BRD ledger (see tf-split-brd.sh).
+
+    bash .tfcore/utils/tf-split-brd.sh <App>                # write the checklist (refuses if one exists)
+    bash .tfcore/utils/tf-split-brd.sh <App> --force        # overwrite an existing checklist
+    bash .tfcore/utils/tf-split-brd.sh <App> --add-missing  # append rows only for BRD items with no row yet
+    bash .tfcore/utils/tf-split-brd.sh <App> --phase 2      # a later phase of a Large project
+    bash .tfcore/utils/tf-split-brd.sh <App> --all-phases   # every phase in docs/<App>-Phases.md
+
+Large projects (docs/TechieFlow-Document-Schemas.md §2): phase 1 is docs/<App>-BRD.md and
+docs/<App>-Checklist.md; phase n is docs/<App>-Pn-BRD.md and docs/<App>-Pn-Checklist.md. Without
+--phase the phase comes from appPhase in .tfcore/core-config.yaml (1 when absent). REQ numbers run
+on across phases: a new checklist starts each prefix after the highest number in every other
+phase's checklist, so an id is never reused.
+
+Reads docs/<App>-BRD.md: the header (App, Size), the Screens and flow table (screen, route),
+every `**BRD-N**` ledger item with its title, screen, mockup link and acceptance line, and
+the Non-functional table. Writes the checklist in the template shape: header, Goal, the one
+Requirements Status table, then one section per screen holding the detail entries, plus
+"RAG / AI requirements" and "Non-functional". Acceptance and perf-budget lines are copied
+verbatim; an item without one gets a TODO line the checker will refuse, never an invented one.
+
+Class is guessed, and the agent corrects it: Non-functional table -> REQ-NFR; text about
+embeddings, vectors, prompts, chat or a model -> REQ-RAG; text about what a screen shows
+(page, screen, list, form, dialog, button, menu, layout, theme, displays, shows) -> REQ-UI;
+everything else -> REQ-FN. Exit 0 written, 1 refused, 2 could not run.
+"""
+import os
+import re
+import sys
+
+RAG_WORDS = re.compile(r"\b(embedding|embeddings|vector|rag\b|prompt template|llm|language model|retriev|semantic search|chatbot|chat completion)", re.I)
+UI_WORDS = re.compile(r"\b(page|screen|list|lists|form|dialog|button|menu|layout|theme|display|displays|shows|shown|grid|table|card|panel|tab|tabs|badge|icon|responsive|mobile)\b", re.I)
+STATUS_LINE = ("**Status values:** `Not Started` · `In Progress` · `Implemented` · `Verified` · `Done (pre-existing)` · "
+               "`Needs re-verify` · `PARTIAL` · `FAIL` · `Blocked` · `Owner-UAT` · `N/A`.")
+
+
+def die(msg, code=2):
+    print(f"tf-split-brd: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def read(p):
+    with open(p, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def header_field(text, name):
+    m = re.search(rf"(?im)^\|\s*{re.escape(name)}\s*\|\s*([^|]+?)\s*\|", text)
+    return m.group(1).strip() if m else ""
+
+
+def section(text, name):
+    m = re.search(rf"(?ms)^##\s+(?:\d+[.)]\s*)?{name}[^\n]*\n(.*?)(?=^## |\Z)", text)
+    return m.group(1) if m else ""
+
+
+def screens(text):
+    """[(name, route)] from the Screens and flow table; dialog rows are skipped."""
+    out = []
+    for line in section(text, "Screens and flow").splitlines():
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 2 or cells[0].lower() in ("screen", "") or set(cells[0]) <= set("-: "):
+            continue
+        route = cells[1].strip("` ")
+        if route.lower().startswith("on "):
+            continue
+        out.append((cells[0].strip("`* "), route))
+    return out
+
+
+def ledger(text):
+    """Every **BRD-N** item: id, title, screen, mockup, acceptance, perf, section name."""
+    items = []
+    nfr_ids = set()
+    for line in section(text, "Non-functional requirements").splitlines():
+        m = re.match(r"^\s*\|\s*`?\**(BRD-\d+)", line)
+        if m:
+            nfr_ids.add(m.group(1))
+            cells = [c.strip() for c in line.strip().strip("|").split("|")]
+            title = cells[2] if len(cells) > 2 else cells[-1]
+            measure = cells[3] if len(cells) > 3 else ""
+            items.append({"id": m.group(1), "title": title.strip("`* "), "screen": "", "mockup": "",
+                          "acceptance": "", "perf": measure if "perf-budget" in measure.lower() else "", "nfr": True})
+    lines = text.splitlines()
+    i = 0
+    while i < len(lines):
+        m = re.match(r"^\s*[-*]\s*\*\*(BRD-\d+)\*\*\s*[—:-]+\s*(.*)$", lines[i])
+        if m and m.group(1) not in nfr_ids:
+            rid, rest = m.group(1), m.group(2)
+            title = re.split(r"\s*(?:\.\s+\*|\s\*Screen|\s·\s\*|\s\*Mockup)", rest, 1)[0].strip().rstrip(".")
+            sm = re.search(r"\*Screen:\*\s*([^·*\n]+)", rest)
+            mm = re.search(r"\(((?:\./|docs/)?mockups/[^)\s]+)\)", rest) or re.search(r"((?:docs/)?mockups/[\w./-]+\.html)", rest)
+            acc = perf = ""
+            j = i + 1
+            while j < len(lines) and (lines[j].startswith("  ") or lines[j].strip() == ""):
+                if re.search(r"\*Acceptance:?\*|^\s*[-*]\s*Acceptance:", lines[j], re.I):
+                    acc = re.sub(r"^\s*[-*]\s*\*?Acceptance:?\*?:?\s*", "", lines[j]).strip()
+                pm = re.search(r"perf-budget:[^\n|]+", lines[j], re.I)
+                if pm:
+                    perf = pm.group(0).strip()
+                if lines[j].strip() == "" and j + 1 < len(lines) and not lines[j + 1].startswith("  "):
+                    break
+                j += 1
+            items.append({"id": rid, "title": title, "screen": sm.group(1).strip() if sm else "",
+                          "mockup": mm.group(1) if mm else "", "acceptance": acc, "perf": perf, "nfr": False})
+        i += 1
+    return [it for it in items if not it["nfr"]] + [it for it in items if it["nfr"]]
+
+
+def classify(it):
+    if it["nfr"]:
+        return "NFR"
+    blob = it["title"] + " " + it["acceptance"]
+    if RAG_WORDS.search(blob):
+        return "RAG"
+    if UI_WORDS.search(blob):
+        return "UI"
+    return "FN"
+
+
+def slug(s):
+    return re.sub(r"[^a-z0-9]+", "-", s.lower()).strip("-")
+
+
+def entry(req, it):
+    mock = f" · *Mockup:* {it['mockup'].replace('docs/', '')}" if it["mockup"] else ""
+    acc = it["acceptance"] or "TODO — write: When <actor> <does what> on <screen>, then <a result a browser robot can observe>"
+    if it["perf"] and it["perf"].lower() not in acc.lower():
+        acc = acc.rstrip(".") + "; " + it["perf"]
+    return (f'<a id="d-{req.lower()}"></a>\n- **{req}** — {it["title"]}. *BRD:* {it["id"]}{mock}\n'
+            f"  - *Acceptance:* {acc}\n")
+
+
+def config_phase():
+    """appPhase from .tfcore/core-config.yaml; 1 when absent or null."""
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(p):
+        m = re.search(r"(?m)^appPhase:\s*(\d+)", read(p))
+        if m:
+            return int(m.group(1))
+    return 1
+
+
+def phase_names(app, phase):
+    """(BRD path, checklist path) for a phase: plain names for phase 1, App-Pn- otherwise."""
+    pfx = f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+    return os.path.join("docs", f"{pfx}BRD.md"), os.path.join("docs", f"{pfx}Checklist.md")
+
+
+def phases_listed(app):
+    """Phase numbers from the Phases table of docs/<App>-Phases.md, in order."""
+    p = os.path.join("docs", f"{app}-Phases.md")
+    if not os.path.isfile(p):
+        die(f"{p} does not exist; --all-phases needs the Phases document")
+    nums = []
+    for line in section(read(p), "Phases").splitlines():
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if cells and cells[0].strip("`* ").isdigit():
+            nums.append(int(cells[0].strip("`* ")))
+    if not nums:
+        die(f"{p} has no numbered rows in its Phases table")
+    return nums
+
+
+def other_phase_counters(app, own_cl, below=None):
+    """Highest REQ number per prefix across the other phases' checklists, so ids run on.
+    below=n counts only phases under n (an --all-phases run, which rewrites them in order);
+    otherwise every other phase counts, so a single-phase run can never reuse an id."""
+    counters = {"UI": 0, "FN": 0, "RAG": 0, "NFR": 0}
+    if not os.path.isdir("docs"):
+        return counters
+    for f in os.listdir("docs"):
+        m = re.fullmatch(rf"{re.escape(app)}(?:-P(\d+))?-Checklist\.md", f)
+        if not m or os.path.join("docs", f) == own_cl:
+            continue
+        if below is not None and int(m.group(1) or 1) >= below:
+            continue
+        for r in re.finditer(r"REQ-(UI|FN|RAG|NFR)-(\d{3})", read(os.path.join("docs", f))):
+            counters[r.group(1)] = max(counters[r.group(1)], int(r.group(2)))
+    return counters
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    app = argv[1]
+    force = "--force" in argv
+    add_missing = "--add-missing" in argv
+    phase = None
+    if "--phase" in argv:
+        i = argv.index("--phase")
+        if i + 1 >= len(argv) or not argv[i + 1].isdigit() or int(argv[i + 1]) < 1:
+            die("--phase needs a number from 1 upwards")
+        phase = int(argv[i + 1])
+    if "--all-phases" in argv:
+        rc = 0
+        for n in phases_listed(app):
+            rc = max(rc, run(app, n, force, add_missing, in_order=True))
+        return rc
+    return run(app, phase if phase else config_phase(), force, add_missing)
+
+
+def run(app, phase, force, add_missing, in_order=False):
+    brd_p, cl_p = phase_names(app, phase)
+    if not os.path.isfile(brd_p):
+        die(f"{brd_p} does not exist" + (f" (phase {phase}; phase 1 is docs/{app}-BRD.md)" if phase > 1 else ""))
+    brd = read(brd_p)
+    items = ledger(brd)
+    if not items:
+        die(f"{brd_p} has no **BRD-N** items in its Requirements section")
+    scr = screens(brd)
+    routes = {s.lower(): r for s, r in scr}
+    size = header_field(brd, "Size") or "Small"
+    phase_label = header_field(brd, "Phase")
+
+    existing = read(cl_p) if os.path.isfile(cl_p) else ""
+    if existing and not force and not add_missing:
+        die(f"{cl_p} already exists; use --add-missing to append rows for new BRD items, or --force to rewrite", 1)
+    mapped = set(re.findall(r"\*BRD:\*\s*(BRD-\d+)", existing)) | set(re.findall(r"\((BRD-\d+)\)", existing))
+    counters = other_phase_counters(app, cl_p, below=phase if in_order else None)
+    if add_missing:
+        for m in re.finditer(r"REQ-(UI|FN|RAG|NFR)-(\d{3})", existing):
+            counters[m.group(1)] = max(counters[m.group(1)], int(m.group(2)))
+    new_counts = {"UI": 0, "FN": 0, "RAG": 0, "NFR": 0}
+
+    rows, entries = [], {}
+    for it in items:
+        if add_missing and it["id"] in mapped:
+            continue
+        cls = classify(it)
+        counters[cls] += 1
+        new_counts[cls] += 1
+        req = f"REQ-{cls}-{counters[cls]:03d}"
+        rows.append(f"| {req} | {it['title']} | Not Started | 0% | — | [view](#d-{req.lower()}) |")
+        key = ("Non-functional" if cls == "NFR" else "RAG / AI requirements" if cls == "RAG"
+               else (it["screen"] or "Other"))
+        entries.setdefault(key, []).append(entry(req, it))
+
+    if add_missing and existing:
+        if not rows:
+            print(f"tf-split-brd: every BRD item already has a row in {cl_p}; nothing to add")
+            return 0
+        text = existing
+        m = re.search(r"(?ms)^## Requirements Status\s*\n.*?(?=^## |\Z)", text)
+        if not m:
+            die(f"{cl_p} has no Requirements Status section")
+        tbl_end = m.end()
+        # insert rows after the last table row of the status table
+        seg = text[m.start():tbl_end]
+        last_row = list(re.finditer(r"(?m)^\|\s*REQ-[^\n]*$", seg))
+        if last_row:
+            pos = m.start() + last_row[-1].end()
+            text = text[:pos] + "\n" + "\n".join(rows) + text[pos:]
+        for key, ents in entries.items():
+            hm = re.search(rf"(?ms)^##\s+(?:Page:\s*)?{re.escape(key)}\b[^\n]*\n.*?(?=^## |\Z)", text)
+            block = "\n".join(ents)
+            if hm:
+                text = text[:hm.end()].rstrip("\n") + "\n\n" + block + "\n" + text[hm.end():]
+            else:
+                heading = key if key in ("Non-functional", "RAG / AI requirements") else f"Page: {key}" + (f" (`{routes[key.lower()]}`)" if key.lower() in routes else "")
+                text = text.rstrip("\n") + f"\n\n## {heading}\n\n{block}\n"
+        with open(cl_p, "w", encoding="utf-8", newline="\n") as f:
+            f.write(text)
+        print(f"tf-split-brd: appended {len(rows)} row(s) to {cl_p}: " + ", ".join(r.split("|")[1].strip() for r in rows))
+        return 0
+
+    goal = re.sub(r"\s+", " ", section(brd, "Summary").strip().split("\n\n")[0]).strip() or f"Build {app} as the BRD describes."
+    title = f"# {app} — Checklist" + (f" (phase {phase})" if phase_label else "")
+    out = [title, "", "| | |", "|---|---|", f"| App | {app} |", f"| Size | {size} |"]
+    if phase_label:
+        out.append(f"| Phase | {phase_label} |")
+    out += ["", "## Goal", "", goal + (" This checklist is the whole work list of this phase." if phase_label else " This single checklist is the whole work list."), "",
+           "## Requirements Status", "",
+           "| ID | Requirement | Status | % | Remarks | Details |", "|----|-------------|--------|---|---------|---------|"]
+    out += rows
+    out += ["", STATUS_LINE, ""]
+    ordered = [s for s, _ in scr if s in entries] + [k for k in entries if k not in dict(scr) and k not in ("RAG / AI requirements", "Non-functional")]
+    for key in ordered:
+        route = routes.get(key.lower(), "")
+        out.append(f"## Page: {key}" + (f" (`{route}`)" if route else ""))
+        out.append("")
+        out.append("\n".join(entries[key]))
+    for key in ("RAG / AI requirements", "Non-functional"):
+        if key in entries:
+            out += [f"## {key}", "", "\n".join(entries[key])]
+    with open(cl_p, "w", encoding="utf-8", newline="\n") as f:
+        f.write("\n".join(out).rstrip("\n") + "\n")
+    n = {k: v for k, v in new_counts.items() if v}
+    todo = sum(1 for it in items if not it["acceptance"] and not it["nfr"])
+    print(f"tf-split-brd: wrote {cl_p}: {len(rows)} rows (" + ", ".join(f"{k} {v}" for k, v in n.items()) + f"), {len(ordered)} screen section(s)"
+          + (f"; {todo} item(s) had no acceptance line and carry a TODO the checker will refuse" if todo else ""))
+    print("tf-split-brd: correct any class the guess got wrong, then run: bash .tfcore/utils/tf-doc-check.sh --app " + app)
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except Exception as e:
+        die(str(e))

package/.tfcore/utils/tf-split-brd.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# tf-split-brd.sh — draft docs/<App>-Checklist.md from the BRD ledger.
+#
+#   bash .tfcore/utils/tf-split-brd.sh MyApp                # write it (refuses if one exists)
+#   bash .tfcore/utils/tf-split-brd.sh MyApp --force        # rewrite
+#   bash .tfcore/utils/tf-split-brd.sh MyApp --add-missing  # append rows for BRD items with no row (amend-docs)
+#   bash .tfcore/utils/tf-split-brd.sh MyApp --phase 2      # a later phase of a Large project (docs/MyApp-P2-BRD.md)
+#   bash .tfcore/utils/tf-split-brd.sh MyApp --all-phases   # every phase listed in docs/MyApp-Phases.md
+#
+# Without --phase the phase is appPhase in core-config.yaml (1 when absent).
+# REQ numbers run on across phases; an id is never reused.
+#
+# One row per BRD item in the template shape, acceptance lines copied verbatim,
+# class guessed (UI / FN / RAG / NFR) for the agent to correct. Then run
+# tf-doc-check.sh --app MyApp. Thin wrapper over tf-split-brd.py; Python 3 stdlib only.
+set -uo pipefail
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-split-brd: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-split-brd.py" "$@"