@techierathore/techieflow 1.0.2 → 1.0.3

package/.tfcore/utils/tf-status-evidence.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# tf-status-evidence.sh — the evidence *refresh-status rebuilds PROJECT-STATUS from, after a
+# session died before its status gate (Sitting 4b, 2026-09-06). Reads only; never git.
+#
+#   bash .tfcore/utils/tf-status-evidence.sh <App> [--no-build] [--phase N]
+#
+# Prints, in this order:
+#   1. what the stale PROJECT-STATUS.md claims (last_updated, current_phase, the next command)
+#   2. files under src/ and tests/ changed after that file was last written (work the gate never saw)
+#   3. checklist rows left at Implemented / In Progress / Needs re-verify / PARTIAL / FAIL
+#      (the fingerprint of a smoke that ran and a verify that did not)
+#   4. the build verdict from tf-build.sh (skipped with --no-build)
+# Then the agent decides the interruption signature and runs tf-status-facts.sh for the gate.
+set -uo pipefail
+APP="${1:-}"; [[ -z "$APP" ]] && { sed -n '2,12p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 2; }
+shift
+BUILD=1; PHASE=""
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --no-build) BUILD=0; shift ;;
+    --phase) PHASE="$2"; shift 2 ;;
+    *) shift ;;
+  esac
+done
+[[ -z "$PHASE" ]] && PHASE="$(grep -oE '^appPhase:\s*[0-9]+' .tfcore/core-config.yaml 2>/dev/null | grep -oE '[0-9]+' || echo 1)"
+[[ "$PHASE" -le 1 ]] && CL="docs/${APP}-Checklist.md" || CL="docs/${APP}-P${PHASE}-Checklist.md"
+ST="PROJECT-STATUS.md"
+
+echo "# tf-status-evidence — $APP — $(date -u +%Y-%m-%dT%H:%M:%SZ) — phase $PHASE"
+echo
+echo "## 1. What the stale status file claims (a hypothesis, not a fact)"
+if [[ -f "$ST" ]]; then
+  grep -E '^(last_updated|current_phase|last_verified_build|last_verified_date):' "$ST" | sed 's/^/- /'
+  awk '/^## Next command to run/{p=1;next} /^## /{p=0} p' "$ST" | grep -E '^\s*/' | sed 's/^\s*/- next: /' | head -2
+  echo "- written: $(date -u -r "$ST" +%Y-%m-%dT%H:%M:%SZ)"
+else
+  echo "- no PROJECT-STATUS.md; treat as never written"
+fi
+echo
+echo "## 2. Files changed after the status file was written (src/ and tests/, newest first)"
+if [[ -f "$ST" ]]; then
+  mapfile -t NEWER < <(find src tests -type f -newer "$ST" \
+      -not -path '*/bin/*' -not -path '*/obj/*' -not -path '*/node_modules/*' -not -path '*/.artifacts/*' 2>/dev/null \
+      | xargs -r ls -t 2>/dev/null)
+  echo "- ${#NEWER[@]} file(s)"
+  printf -- '- %s\n' "${NEWER[@]:0:30}"
+  [[ ${#NEWER[@]} -gt 30 ]] && echo "- (${#NEWER[@]} in total; the rest with: find src tests -type f -newer PROJECT-STATUS.md)"
+else
+  echo "- no status file to compare against"
+fi
+echo
+echo "## 3. Checklist rows that look interrupted ($CL)"
+if [[ -f "$CL" ]]; then
+  grep -E '^\s*\|\s*`?REQ-' "$CL" | awk -F'|' '{id=$2; st=$4; gsub(/^[ `*]+|[ `*]+$/,"",id); gsub(/^[ ]+|[ ]+$/,"",st); print id" — "st}' \
+    | grep -iE ' — (Implemented|In Progress|Needs re-verify|PARTIAL|FAIL)' | sed 's/^/- /' | head -40
+  n=$(grep -E '^\s*\|\s*`?REQ-' "$CL" | awk -F'|' '{print $4}' | grep -ciE 'Implemented|In Progress|Needs re-verify|PARTIAL|FAIL' || true)
+  [[ "$n" == "0" ]] && echo "- none: every row is terminal, Blocked or not started"
+else
+  echo "- $CL does not exist"
+fi
+echo
+echo "## 4. Build"
+if [[ $BUILD -eq 1 ]]; then
+  bash "$(dirname "${BASH_SOURCE[0]}")/tf-build.sh" build 2>&1 | tail -3 | sed 's/^/- /'
+else
+  echo "- skipped (--no-build)"
+fi
+exit 0

package/.tfcore/utils/tf-status-facts.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+"""tf-status-facts.py — print the facts PROJECT-STATUS.md is written from.
+
+    bash .tfcore/utils/tf-status-facts.sh <App> ["<command label>"] [--phase N]
+
+Reads docs/<App>-Checklist.md, docs/.last-verify.json, docs/metrics/gates.jsonl,
+docs/<App>-*-Feedback.md and the current PROJECT-STATUS.md. On a Large project the
+checklist is the one of the phase being worked: --phase N, else appPhase in
+.tfcore/core-config.yaml (phase 1 is docs/<App>-Checklist.md, phase n is
+docs/<App>-Pn-Checklist.md), and the phase line names it from docs/<App>-Phases.md. Prints, ready to copy
+into the template (.tfcore/templates/v4custom/app-project-status-tmpl.md):
+
+  - the frontmatter values (last_updated, current_phase, last_verified_*)
+  - the Open requirements section (counts by status, at most ten named rows)
+  - the Verification log table with its new row (last five kept)
+  - the Library feedback summary lines
+  - the Next command to run, in both harness forms, and why
+
+Writes nothing. The agent writes PROJECT-STATUS.md with the harness Write tool.
+Python 3 standard library only. Exit 0 printed, 2 could not run.
+"""
+import datetime
+import glob
+import json
+import os
+import re
+import sys
+
+TERMINAL = {"verified", "done (pre-existing)", "n/a"}
+PASS_THROUGH = {"blocked"}           # a library gap; counts as closed for the ladder
+BUILT = {"implemented", "needs re-verify"}
+OWNER = {"owner-uat"}                # only the owner can close it, from the UsageGuide test plan
+# anything else (Not Started, In Progress, PARTIAL, FAIL, unknown) is not built yet
+
+LADDER = ["Not Started", "In Progress", "PARTIAL", "FAIL", "Implemented", "Needs re-verify",
+          "Blocked", "Owner-UAT", "Verified", "Done (pre-existing)", "N/A"]
+COUNT_ROWS = ["Not Started", "In Progress", "Implemented", "Needs re-verify", "Blocked"]
+
+CC = "/TechieFlow:agents:"
+OC = "/"
+AGENT_OC = {"flow-master": "flow-master", "verifier": "flow-verifier", "analyst": "flow-analyst"}
+
+
+def die(msg):
+    print(f"tf-status-facts: {msg}", file=sys.stderr)
+    sys.exit(2)
+
+
+def norm_status(raw):
+    s = raw.strip().strip("`* ").strip()
+    low = s.lower()
+    for v in LADDER:
+        if low == v.lower() or low.startswith(v.lower() + " ("):
+            return v
+    return s or "?"
+
+
+def read(path):
+    with open(path, encoding="utf-8", errors="replace") as f:
+        return f.read()
+
+
+def checklist_rows(text):
+    rows = []
+    for line in text.splitlines():
+        if not re.match(r"^\s*\|\s*`?REQ-", line):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) < 3:
+            continue
+        rid = cells[0].strip("`* ")
+        rows.append({"id": rid, "name": cells[1].strip("`* "), "status": norm_status(cells[2])})
+    return rows
+
+
+def ladder_rank(status):
+    return LADDER.index(status) if status in LADDER else 0
+
+
+def last_verify(root, app):
+    """(date, build_result) from docs/.last-verify.json and gates.jsonl; ('', 'not-run') if none."""
+    ledger = os.path.join(root, "docs", ".last-verify.json")
+    if not os.path.isfile(ledger):
+        return "", "not-run"
+    try:
+        data = json.loads(read(ledger).strip().splitlines()[-1])
+    except Exception:
+        return "", "not-run"
+    date = str(data.get("date", ""))[:10]
+    result = "PASS"
+    gates = os.path.join(root, "docs", "metrics", "gates.jsonl")
+    if date and os.path.isfile(gates):
+        for line in read(gates).splitlines():
+            try:
+                rec = json.loads(line)
+            except Exception:
+                continue
+            if rec.get("app") == app and str(rec.get("ts", ""))[:10] == date and rec.get("gate") == "build":
+                result = "FAIL"
+                break
+    return date, result
+
+
+def existing_log_rows(status_text):
+    m = re.search(r"(?ms)^## Verification log\s*\n(.*?)(?=^## |\Z)", status_text)
+    if not m:
+        return []
+    rows = []
+    for line in m.group(1).splitlines():
+        if re.match(r"^\s*\|", line) and not re.match(r"^\s*\|\s*-", line) and "Date" not in line.split("|")[1]:
+            rows.append(line.strip())
+    return rows
+
+
+def handoff_ran(log_rows):
+    return any("handoff" in r.lower() for r in log_rows)
+
+
+def feedback_lines(root, app):
+    out = []
+    for path in sorted(glob.glob(os.path.join(root, "docs", f"{app}-*-Feedback.md"))):
+        lib = re.sub(rf"^{re.escape(app)}-(.+)-Feedback\.md$", r"\1", os.path.basename(path))
+        text = read(path)
+        entries = re.split(r"(?m)^###\s+", text)[1:]
+        open_n = 0
+        for e in entries:
+            closed = re.search(r"(?im)^\s*[-*]\s*\*\*(status|resolved|fixed)[^:]*:\*\*\s*(fixed|resolved|closed|done)", e)
+            if not closed:
+                open_n += 1
+        rel = os.path.relpath(path, root).replace(os.sep, "/")
+        out.append(f"- {lib}: {open_n} open of {len(entries)} — {rel}")
+    return out or ["- None"]
+
+
+def config_phase(root):
+    p = os.path.join(root, ".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_prefix(app, phase):
+    return f"{app}-" if phase <= 1 else f"{app}-P{phase}-"
+
+
+def phase_row(root, app, phase):
+    """(name, total phases) from docs/<App>-Phases.md; ('', 0) when the project has no phases."""
+    p = os.path.join(root, "docs", f"{app}-Phases.md")
+    if not os.path.isfile(p):
+        return "", 0
+    m = re.search(r"(?ms)^##\s+(?:\d+[.)]\s*)?Phases[^\n]*\n(.*?)(?=^## |\Z)", read(p))
+    name, total = "", 0
+    for line in (m.group(1) if m else "").splitlines():
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) >= 2 and cells[0].strip("`* ").isdigit():
+            total += 1
+            if int(cells[0].strip("`* ")) == phase:
+                name = cells[1].strip("`* ")
+    return name, total
+
+
+def next_command(app, rows, log_rows, phase=1):
+    """Returns (phase, qualifier, cc_line, oc_line, reason)."""
+    def ids(lst):
+        return ", ".join(r["id"] for r in lst[:6]) + (" …" if len(lst) > 6 else "")
+
+    if not rows:
+        if os.path.isfile(os.path.join(os.getcwd(), "docs", f"{phase_prefix(app, phase)}BRD.md")):
+            return ("Day-1", "stage 1 done, awaiting owner review",
+                    f"{CC}analyst *day1-greenfield {app} --stage2", f"{OC}flow-analyst *day1-greenfield {app} --stage2",
+                    "the BRD exists and no checklist; stage 2 runs on the owner's go-ahead")
+        return ("Day-1", "no documents yet",
+                f"{CC}analyst *day1-greenfield {app}", f"{OC}flow-analyst *day1-greenfield {app}",
+                "no BRD and no checklist exist; day-1 stage 1 has not run")
+
+    unbuilt = [r for r in rows if r["status"].lower() not in TERMINAL | PASS_THROUGH | BUILT | OWNER]
+    built = [r for r in rows if r["status"].lower() in BUILT]
+    owner = [r for r in rows if r["status"].lower() in OWNER]
+    total = len(rows)
+    closed = sum(1 for r in rows if r["status"].lower() in TERMINAL)
+    q = f"{closed} of {total} verified"
+
+    if unbuilt:
+        return ("Build", f"{len(unbuilt)} not built, {q}",
+                f"{CC}flow-master *build-phase {app}", f"{OC}flow-master *build-phase {app}",
+                f"{len(unbuilt)} rows are not built yet: {ids(unbuilt)}")
+    if built:
+        ui = [r for r in built if r["id"].startswith("REQ-UI")]
+        scope = "ui" if len(ui) == len(built) else ("functional" if not ui else "all")
+        return ("Verify", f"{len(built)} to verify, {q}",
+                f"{CC}verifier *verify {scope} {app}", f"{OC}flow-verifier *verify {scope} {app}",
+                f"{len(built)} rows are built and not verified: {ids(built)}")
+    if owner:
+        if handoff_ran(log_rows):
+            line = f"(owner-run) docs/{app}-UsageGuide.md — {ids(owner)}"
+            return ("UAT", f"{len(owner)} owner-run, {q}", line, line,
+                    f"{len(owner)} rows are Owner-UAT and handoff has run; the owner closes them")
+        return ("Handoff", f"{len(owner)} owner-run, {q}",
+                f"{CC}flow-master *handoff-phase {app}", f"{OC}flow-master *handoff-phase {app}",
+                f"{len(owner)} rows are Owner-UAT and handoff has not run yet")
+    if handoff_ran(log_rows):
+        line = "(owner) set current_phase to Released after UAT — no agent command"
+        return ("UAT", f"handoff done, {q}", line, line,
+                "every row is terminal and handoff has run; waiting on the owner")
+    return ("Handoff", q,
+            f"{CC}flow-master *handoff-phase {app}", f"{OC}flow-master *handoff-phase {app}",
+            "every row is terminal and handoff has not run yet")
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0
+    app = argv[1]
+    args = argv[2:]
+    root = os.getcwd()
+    phase_n = None
+    if "--phase" in args:
+        i = args.index("--phase")
+        if i + 1 >= len(args) or not args[i + 1].isdigit() or int(args[i + 1]) < 1:
+            die("--phase needs a number from 1 upwards")
+        phase_n = int(args[i + 1])
+        del args[i:i + 2]
+    phase_n = phase_n or config_phase(root)
+    label = args[0] if args else "status"
+    today = datetime.date.today().isoformat()
+
+    cl_rel = f"docs/{phase_prefix(app, phase_n)}Checklist.md"
+    cl_path = os.path.join(root, cl_rel)
+    rows = checklist_rows(read(cl_path)) if os.path.isfile(cl_path) else []
+    st_path = os.path.join(root, "PROJECT-STATUS.md")
+    st_text = read(st_path) if os.path.isfile(st_path) else ""
+    log_rows = existing_log_rows(st_text)
+    vdate, vresult = last_verify(root, app)
+    phase, qual, cc, oc, reason = next_command(app, rows, log_rows, phase_n)
+    pname, ptotal = phase_row(root, app, phase_n)
+    if ptotal or phase_n > 1:
+        tag = f"Phase {phase_n} of {ptotal or '?'}" + (f" ({pname})" if pname else "")
+        phase = f"{tag} · {phase}"
+        reason = f"{reason}; working {cl_rel}"
+
+    total = len(rows)
+    closed = sum(1 for r in rows if r["status"].lower() in TERMINAL)
+    counts = {}
+    for r in rows:
+        counts[r["status"]] = counts.get(r["status"], 0) + 1
+    open_rows = sorted((r for r in rows if r["status"].lower() not in TERMINAL),
+                       key=lambda r: (ladder_rank(r["status"]), r["id"]))
+
+    print(f"# tf-status-facts — {app} — {today} — copy into PROJECT-STATUS.md (Write tool)")
+    print()
+    print("## Frontmatter values")
+    print(f"last_updated: {today}")
+    print(f"current_phase: {phase} — {qual}")
+    print(f"last_verified_build: {vresult}")
+    print(f"last_verified_date: {vdate or 'never'}")
+    print()
+    print("## Next command to run")
+    print(f"Claude Code:\n```\n{cc}\n```\nOpenCode:\n```\n{oc}\n```")
+    print(f"Why: {reason}.")
+    print()
+    print("## Open requirements")
+    print("| Status | Count |\n|---|---|")
+    shown = set()
+    for s in COUNT_ROWS:
+        print(f"| {s} | {counts.get(s, 0)} |")
+        shown.add(s)
+    for s, n in sorted(counts.items(), key=lambda kv: ladder_rank(kv[0])):
+        if s not in shown and s.lower() not in TERMINAL:
+            print(f"| {s} | {n} |")
+    print()
+    if open_rows:
+        for r in open_rows[:10]:
+            print(f"- [ ] {r['id']} — {r['name']} ({r['status']})")
+        if len(open_rows) > 10:
+            print(f"- ({len(open_rows) - 10} more open rows in {cl_rel})")
+    else:
+        print("- None")
+    print()
+    print("## Verification log")
+    print("Last five passes; older passes live in `docs/metrics/gates.jsonl`.")
+    print()
+    print("| Date | Phase | Result | Status table |\n|---|---|---|---|")
+    new_row = f"| {today} | {label} | {closed}/{total} Verified | {cl_rel}#requirements-status |"
+    for r in (log_rows[-4:] if len(log_rows) > 4 else log_rows):
+        print(r)
+    print(new_row)
+    print()
+    print("## Library feedback summary")
+    for line in feedback_lines(root, app):
+        print(line)
+    print()
+    print("## You write these yourself")
+    print("- Where I am: at most 80 words, state not story." + (f" Name the phase: {phase.split(' · ')[0]}." if ptotal or phase_n > 1 else ""))
+    print("- Known blockers: one line each, or `- None`.")
+    print("- Standards compliance: `- Last check {date}: {n} findings, see the checklist Remarks.`")
+    print("- Deferred / future: parked ideas, one line each.")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main(sys.argv))
+    except SystemExit:
+        raise
+    except Exception as e:  # never a stack trace for the agent to wade through
+        die(str(e))

package/.tfcore/utils/tf-status-facts.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# tf-status-facts.sh — print the facts PROJECT-STATUS.md is written from.
+#
+#   bash .tfcore/utils/tf-status-facts.sh MyApp "build-phase"
+#
+# Prints the frontmatter values, the next command in both harness forms, the
+# Open requirements section, the Verification log with its new row, and the
+# library feedback lines, all copy-ready for the template
+# .tfcore/templates/v4custom/app-project-status-tmpl.md. Writes nothing:
+# PROJECT-STATUS.md is written with the harness Write tool (guard-status.sh
+# refuses a shell write). Step 1 of _status-update-gate.md.
+#
+# Thin wrapper over tf-status-facts.py. Python 3 standard library only.
+set -uo pipefail
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "tf-status-facts: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-status-facts.py" "$@"

package/.tfcore/utils/tf-triage.py

@@ -0,0 +1,243 @@
+#!/usr/bin/env python3
+"""tf-triage.py — log reported bugs in the checklist and the telemetry (see tf-triage.sh).
+
+    bash .tfcore/utils/tf-triage.sh <App> demote <REQ> "<symptom>" [--kind layout|render-empty|data-logic|rag]
+                                     [--evidence <path>] [--source owner|production] [--why <why_missed>] [--sort <sort>]
+    bash .tfcore/utils/tf-triage.sh <App> new "<title>" "<When … on <screen>, then …>" [--prefix UI|FN|NFR|RAG]
+                                     [--section "<screen>"] [--evidence <path>] [--source owner|production] [--mockup <file>] [--sort <sort>]
+    bash .tfcore/utils/tf-triage.sh <App> note <REQ> "<could not reproduce: what was tried>"
+    bash .tfcore/utils/tf-triage.sh <App> close [--started <ISO>] [--verify-ran] [--cmd triage-issues|fix-issues]
+
+demote  the row goes to Needs re-verify (% capped at 75) with a dated Remark holding the symptom in the
+        reporter's words, the evidence path and the kind.
+new     a defect no row covers: the next free id in the prefix, a Not Started row, a detail entry with the
+        acceptance line and the marker BRD-pending (*amend-docs gives it its BRD item).
+note    a dated remark on the nearest row, no status change (could not reproduce).
+close   what triage owes the telemetry, from the actions above (tests/.artifacts/verify/triage.json):
+        one gate record per demoted or new row with gate "escaped" (no check caught it), one miss per row
+        with found_by owner or production, the symptom as `what` and the sort (FR-32; --sort on demote or
+        new, else weak-check for a demoted row, whose line existed and whose check let it through, and
+        spec for a new row, which the spec never had) (duplicates collapsed through
+        tf-emit.sh --open-miss; the origin run looked up with --origin-of), then the run record. It also
+        lists every file under src/, source/ or tests/ changed since the start: a triage that edited code
+        is reported and logged as an instruction-ignored miss (FR-28).
+Exit 0 · 2 could not run.
+"""
+import datetime
+import importlib.util
+import json
+import os
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+LOGP = os.path.join("tests", ".artifacts", "verify", "triage.json")
+KIND_CLASS = {"layout": "overlap", "render-empty": "blank-data", "data-logic": "assert-fail", "rag": "other", None: "other"}
+EMIT = os.path.join(HERE, "tf-emit.sh")
+
+
+def die(m):
+    print(f"tf-triage: {m}", file=sys.stderr)
+    sys.exit(2)
+
+
+def mod():
+    spec = importlib.util.spec_from_file_location("tf_checklist_edit", os.path.join(HERE, "tf-checklist-edit.py"))
+    m = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(m)
+    return m
+
+
+def cfg_phase():
+    p = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(p):
+        import re
+        m = re.search(r"(?m)^appPhase:\s*(\d+)", open(p, encoding="utf-8").read())
+        if m:
+            return int(m.group(1))
+    return 1
+
+
+def checklist(app):
+    ph = cfg_phase()
+    p = os.path.join("docs", f"{app}-Checklist.md" if ph <= 1 else f"{app}-P{ph}-Checklist.md")
+    if not os.path.isfile(p):
+        die(f"{p} does not exist")
+    return p
+
+
+def log_load():
+    try:
+        return json.load(open(LOGP, encoding="utf-8"))
+    except Exception:
+        return {"actions": []}
+
+
+def log_save(d):
+    os.makedirs(os.path.dirname(LOGP), exist_ok=True)
+    json.dump(d, open(LOGP, "w", encoding="utf-8"), indent=1)
+
+
+def opt(argv, name, default=None):
+    return argv[argv.index(name) + 1] if name in argv and argv.index(name) + 1 < len(argv) else default
+
+
+SORTS = ("spec", "unsaid", "weak-check", "ignored")
+
+
+def sort_opt(argv, default):
+    s = opt(argv, "--sort", default)
+    if s not in SORTS:
+        die(f"--sort must be one of {', '.join(SORTS)}")
+    return s
+
+
+def q(*args):
+    p = subprocess.run(["bash", EMIT, *args], capture_output=True, text=True)
+    return p.stdout.strip()
+
+
+def emit(stream, rec):
+    p = subprocess.run(["bash", EMIT, stream], input=json.dumps(rec), capture_output=True, text=True)
+    msg = (p.stdout + p.stderr).strip()
+    ok = p.returncode == 0 and "refus" not in msg.lower() and "error" not in msg.lower()
+    if not ok:
+        print(f"  {stream}: not written — {msg.splitlines()[0][:160] if msg else 'no reason printed'}")
+    return ok
+
+
+def main(argv):
+    if len(argv) < 3 or argv[1] in ("-h", "--help"):
+        print(__doc__)
+        return 0 if len(argv) > 1 else 2
+    app, verb = argv[1], argv[2]
+    ce = mod()
+    cl = checklist(app)
+    log = log_load()
+    log.setdefault("app", app)
+    now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    if verb == "demote":
+        if len(argv) < 5:
+            die("demote needs <REQ> \"<symptom>\"")
+        rid, symptom = argv[3].upper(), argv[4]
+        kind = opt(argv, "--kind"); ev = opt(argv, "--evidence"); src = opt(argv, "--source", "owner")
+        prior = ce.demote(cl, rid, symptom, kind=kind, evidence=ev, source=src, prefix="⚠ prod bug" if src == "production" else "⚠ UAT bug")
+        if prior is None:
+            die(f"{rid} is not a row of {cl}")
+        log["actions"].append({"verb": "demote", "req_id": rid, "symptom": symptom, "kind": kind, "evidence": ev, "source": src,
+                               "why": opt(argv, "--why", "insufficient-verify-method"), "sort": sort_opt(argv, "weak-check"),
+                               "prior": prior["status"], "ts": now})
+        log_save(log)
+        print(f"{rid}: {prior['status']} → Needs re-verify — {symptom}")
+        return 0
+
+    if verb == "new":
+        if len(argv) < 5:
+            die("new needs \"<title>\" \"<acceptance>\"")
+        title, acc = argv[3], argv[4]
+        prefix = opt(argv, "--prefix", "FN").upper(); section = opt(argv, "--section"); ev = opt(argv, "--evidence")
+        src = opt(argv, "--source", "owner"); mockup = opt(argv, "--mockup")
+        if prefix == "UI" and not mockup:
+            print("note: a UI row needs a mockup link; pass --mockup docs/mockups/<screen>.html or the checker will flag it")
+        rid = ce.add_row(cl, prefix, title, acc, section=section, mockup=mockup,
+                         remark=f"logged from {'production' if src == 'production' else 'UAT'} {ce.TODAY}" + (f" (evidence: {ev})" if ev else ""))
+        log["actions"].append({"verb": "new", "req_id": rid, "symptom": title, "kind": None, "evidence": ev, "source": src,
+                               "why": opt(argv, "--why", "missing-checklist-item"), "sort": sort_opt(argv, "spec"), "prior": None, "ts": now})
+        log_save(log)
+        print(f"{rid}: new Not Started row — {title}")
+        return 0
+
+    if verb == "note":
+        if len(argv) < 5:
+            die("note needs <REQ> \"<text>\"")
+        rid = argv[3].upper()
+        if ce.note(cl, rid, argv[4]) is None:
+            die(f"{rid} is not a row of {cl}")
+        log["actions"].append({"verb": "note", "req_id": rid, "symptom": argv[4], "ts": now})
+        log_save(log)
+        print(f"{rid}: noted — {argv[4]}")
+        return 0
+
+    if verb == "close":
+        started = opt(argv, "--started") or subprocess.run(["bash", os.path.join(HERE, "tf-phase.sh"), "show"], capture_output=True, text=True).stdout
+        if started.startswith("{"):
+            import re
+            m = re.search(r'"started":"([^"]*)"', started)
+            started = m.group(1) if m else ""
+        started = started.strip() if started and not started.startswith("none") else ""
+        cmd = opt(argv, "--cmd", "triage-issues")
+        # code untouched?
+        changed = []
+        if started:
+            t0 = datetime.datetime.strptime(started, "%Y-%m-%dT%H:%M:%SZ").replace(tzinfo=datetime.timezone.utc).timestamp()
+            for top in ("src", "source", "tests"):
+                for d, dirs, files in os.walk(top):
+                    dirs[:] = [x for x in dirs if x not in ("bin", "obj", "node_modules", ".artifacts", "TestResults")]
+                    for f in files:
+                        p = os.path.join(d, f)
+                        try:
+                            if os.path.getmtime(p) > t0:
+                                changed.append(p.replace("\\", "/"))
+                        except OSError:
+                            pass
+        acts = [a for a in log.get("actions", []) if a["verb"] in ("demote", "new")]
+        gates = misses = 0
+        for a in acts:
+            rid = a["req_id"]; cls_req = rid.split("-")[1]
+            att = q("--next-attempt", rid) or "1"
+            fc = KIND_CLASS.get(a.get("kind"), "other")
+            rec = {"kind": "gate", "app": app, "run_id": started, "req_id": rid, "req_class": cls_req,
+                   "attempt": int(att) if att.isdigit() else 1, "verdict": "Needs re-verify" if a["verb"] == "demote" else "FAIL",
+                   "gate": "escaped", "gates_run": [], "failure_class": fc, "prior_verdict": a.get("prior")}
+            if emit("gates", rec):
+                gates += 1
+            mc = ("unspecified-gap" if a["verb"] == "new" else "regression" if (a.get("prior") or "").lower().startswith("verified") else "wrong-behaviour")
+            opened = q("--open-miss", rid)
+            if opened and opened.split()[-1] == mc:
+                print(f"  {rid}: already open as {opened.split()[0]} ({mc}); no second miss")
+                continue
+            mid = q("--next-miss-id")
+            m = {"kind": "miss", "miss_id": mid, "req_id": rid, "req_class": cls_req, "miss_class": mc,
+                 "artifact": "brd" if a["verb"] == "new" else "src", "severity": "major", "why_missed": a.get("why"),
+                 "origin_phase": "day1-greenfield" if a["verb"] == "new" else "build-phase", "origin_agent": "analyst" if a["verb"] == "new" else "flow-master",
+                 "found_by": a.get("source", "owner"), "found_phase": cmd, "found_gate": None, "found_run_id": started,
+                 "failure_class": fc, "what": a["symptom"][:300], "sort": a.get("sort") or ("spec" if a["verb"] == "new" else "weak-check")}
+            if a["verb"] != "new":
+                o = q("--origin-of", rid).split()
+                if len(o) >= 3:
+                    m["origin_run_id"], m["origin_phase"], m["origin_agent"] = o[0], o[1], o[2]
+            if emit("misses", m):
+                misses += 1
+                a["miss_id"] = mid
+        if changed and cmd == "triage-issues" and not log.get("code_miss_id"):
+            mid = q("--next-miss-id")
+            log["code_miss_id"] = mid
+            emit("misses", {"kind": "miss", "miss_id": mid, "req_id": None, "req_class": None, "miss_class": "other", "artifact": "src",
+                            "severity": "major", "why_missed": "instruction-ignored", "origin_phase": "triage-issues", "origin_agent": "flow-master",
+                            "found_by": "gate", "found_phase": "triage-issues", "found_gate": None, "found_run_id": started, "failure_class": "other",
+                            "what": f"triage edited {len(changed)} file(s) under src, source or tests, which a triage never does: " + ", ".join(changed[:5]),
+                            "sort": "ignored"})
+            print(f"WARNING: {len(changed)} file(s) changed under src/, source/ or tests/ during this triage (logged as {mid}): " + ", ".join(changed[:5]))
+        if cmd == "triage-issues":
+            rec = {"kind": "run", "app": app, "cmd": "triage-issues", "mode": None, "ended": now, "reqs_touched": [a["req_id"] for a in acts],
+                   "reqs_count": len(acts), "subagents": [], "files_written": 1, "build_result": "not-run"}
+            if started:
+                rec["started"] = started
+            already = False   # one run record per start: a close called twice must not count the triage twice
+            runs_path = os.path.join(q("--where") or "docs/metrics", "runs.jsonl")
+            if started and os.path.isfile(runs_path):
+                already = any('"cmd":"triage-issues"' in l and f'"started":"{started}"' in l for l in open(runs_path, encoding="utf-8", errors="replace"))
+            ok = True if already else emit("runs", rec)
+        else:
+            ok = None
+        log["closed"] = now
+        log_save(log)
+        print(f"triage: {len(acts)} row(s) logged — {gates} gate record(s) (escaped), {misses} miss(es)"
+              + (f", run record {'written' if ok else 'not written'}" if ok is not None else "") + f"; code untouched: {'yes' if not changed else 'NO'}")
+        return 0
+    die(f"unknown verb {verb}")
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

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

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# tf-triage.sh — log reported bugs in the checklist and the telemetry (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-triage.sh <App> demote <REQ> "<symptom>" [--kind layout|render-empty|data-logic|rag] [--evidence <path>] [--source owner|production] [--why <why_missed>]
+#   bash .tfcore/utils/tf-triage.sh <App> new "<title>" "<When … on <screen>, then …>" [--prefix UI|FN|NFR|RAG] [--section "<screen>"] [--evidence <path>] [--mockup <file>]
+#   bash .tfcore/utils/tf-triage.sh <App> note <REQ> "<could not reproduce: what was tried>"
+#   bash .tfcore/utils/tf-triage.sh <App> close [--started <ISO>] [--cmd triage-issues|fix-issues]
+#
+# demote: Needs re-verify with a dated Remark in the reporter's words. new: a Not Started row with its
+# acceptance line and BRD-pending. note: a remark, no status change. close: the escaped gate records,
+# one miss per row (found by the owner, the symptom as `what`, duplicates collapsed), the run record,
+# and a warning plus a miss when code changed during the triage. Details: tf-triage.py.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-triage: python3 is required" >&2; exit 2; }
+exec python3 "$HERE/tf-triage.py" "$@"