@techierathore/techieflow 1.0.2 → 1.0.4

package/.tfcore/utils/tf-log-miss.py

@@ -0,0 +1,197 @@
+#!/usr/bin/env python3
+"""tf-log-miss.py — one miss record from one sentence (see tf-log-miss.sh).
+
+    bash .tfcore/utils/tf-log-miss.sh <App> --what "<the owner's sentence>" --sort spec|unsaid|weak-check|ignored
+         [--req REQ-UI-014 | --new "<title>" --acceptance "<When … on <screen>, then …>" [--prefix FN] [--section "<screen>"]]
+         [--class <miss_class>] [--why <why_missed>] [--artifact <artifact>] [--severity blocker|major|minor]
+         [--found-by owner|production] [--evidence <path>] [--fixed [--fix-run <ISO>]] [--started <ISO>]
+
+First the sort (FR-32): --sort answers the four questions, in order, and is required.
+    spec        the app's spec did not say it            -> fix the checklist line; the framework is untouched
+    unsaid      the framework never said it              -> one requirement line plus a check; no prose in a task
+    weak-check  a check existed and did not catch it     -> fix the check (a review becomes a script)
+    ignored     it was written and not followed          -> a hook or script, or delete the rule
+Then, in order: the duplicate check (an open miss of the same class on the row is reported, not
+re-logged; a null why_missed or sort on it is completed with --amend); the origin lookup
+(tf-emit.sh --origin-of); the miss record with the sentence as `what` and the sort; the checklist line
+(the row demoted to Needs re-verify with "⚠ miss <date>: <sentence>", or a new Not Started row with
+BRD-pending when nothing owns it; nothing when the repo has no checklist); with --fixed, a miss-fix
+record instead of a demotion; then the run record (cmd log-miss). The emitter rewrites the readable
+docs/<App>-Misses.md. Prints the report block. Exit 0 · 2 could not run.
+"""
+import datetime
+import importlib.util
+import json
+import os
+import re
+import subprocess
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+EMIT = os.path.join(HERE, "tf-emit.sh")
+CLASSES = {"missed-requirement", "partial-implementation", "unspecified-gap", "regression", "wrong-behaviour", "standards-violation", "spec-contradiction", "other"}
+DEFAULT_ARTIFACT = {"unspecified-gap": "brd", "spec-contradiction": "brd", "standards-violation": "src"}
+SORTS = ("spec", "unsaid", "weak-check", "ignored")
+SORT_QUESTIONS = """tf-log-miss: --sort is missing. Answer the four questions in order and pass the first that fits:
+  1. Did the app's spec say it clearly?            no  -> --sort spec        (fix the checklist line)
+  2. Did the framework say it anywhere?            no  -> --sort unsaid      (one requirement line plus a check)
+  3. Was there a check, and did it fail to catch it? yes -> --sort weak-check (fix the check)
+  4. Was it written and ignored anyway?            yes -> --sort ignored     (a hook, or delete the rule)"""
+
+
+def die(m):
+    print(f"tf-log-miss: {m}", file=sys.stderr)
+    sys.exit(2)
+
+
+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
+
+
+def q(*args):
+    return subprocess.run(["bash", EMIT, *args], capture_output=True, text=True).stdout.strip()
+
+
+def emit(stream, rec):
+    """Append one record. Returns (ok, reason) — the reason is what the emitter refused it for,
+    so the caller can say the miss was NOT recorded instead of claiming it was (miss 06 of
+    2026-09-07: a refused artifact value printed 'Miss logged' and an id that existed nowhere)."""
+    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()
+    reason = ""
+    if not ok:
+        reason = msg.splitlines()[0][:200] if msg else "no reason printed"
+        print(f"  {stream}: not written — {reason}")
+    return ok, reason
+
+
+def main(argv):
+    if len(argv) < 2 or argv[1] in ("-h", "--help") or "--what" not in argv:
+        print(__doc__)
+        return 0 if "-h" in argv or "--help" in argv else 2
+    app = argv[1]
+    what = opt(argv, "--what", "").strip()
+    if not what:
+        die("--what needs the sentence")
+    sort = opt(argv, "--sort")
+    if not sort:
+        print(SORT_QUESTIONS, file=sys.stderr)
+        return 2
+    if sort not in SORTS:
+        die(f"--sort must be one of {', '.join(SORTS)}")
+    req = (opt(argv, "--req") or "").upper() or None
+    new_title = opt(argv, "--new")
+    cls = opt(argv, "--class") or ("unspecified-gap" if new_title else "wrong-behaviour")
+    if cls not in CLASSES:
+        die(f"--class must be one of {', '.join(sorted(CLASSES))}")
+    why = opt(argv, "--why")
+    artifact = opt(argv, "--artifact") or DEFAULT_ARTIFACT.get(cls, "src")
+    severity = opt(argv, "--severity", "major")
+    found_by = opt(argv, "--found-by", "owner")
+    fixed = "--fixed" in argv
+    started = opt(argv, "--started") or ""
+    if not started:
+        mk = subprocess.run(["bash", os.path.join(HERE, "tf-phase.sh"), "show"], capture_output=True, text=True).stdout
+        m = re.search(r'"started":"([^"]*)"', mk)
+        started = m.group(1) if m else datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    now = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    spec = importlib.util.spec_from_file_location("tf_checklist_edit", os.path.join(HERE, "tf-checklist-edit.py"))
+    ce = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(ce)
+    phase = 1
+    cfg = os.path.join(".tfcore", "core-config.yaml")
+    if os.path.isfile(cfg):
+        m = re.search(r"(?m)^appPhase:\s*(\d+)", open(cfg, encoding="utf-8").read())
+        phase = int(m.group(1)) if m else 1
+    cl = os.path.join("docs", f"{app}-Checklist.md" if phase <= 1 else f"{app}-P{phase}-Checklist.md")
+    has_cl = os.path.isfile(cl)
+
+    # 1. duplicate check
+    if req:
+        opened = q("--open-miss", req)
+        if opened and opened.split()[-1] == cls:
+            mid = opened.split()[0]
+            line = f"already logged as {mid}, still open."
+            for fld, val in (("why_missed", why), ("sort", sort)):
+                if val:
+                    r = q("--amend", mid, fld, val)
+                    line += f" {fld} completed with {val}." if "refus" not in r.lower() else f" ({fld} not amended: {r.split('—')[-1].strip()[:90]})"
+            print(f"# Miss not re-logged — {app}\n{line}")
+            return 0
+
+    # 2. the checklist line
+    doc_line = "no checklist in this repo — record only"
+    if has_cl:
+        if req:
+            if fixed:
+                doc_line = f"{req} left as it is (--fixed)"
+            else:
+                prior = ce.demote(cl, req, what, evidence=opt(argv, "--evidence"), source=found_by,
+                                  prefix="⚠ prod bug" if found_by == "production" else "⚠ miss")
+                doc_line = f"{req} demoted to Needs re-verify (was {prior['status']})" if prior else f"{req} is not a row of {cl}; record only"
+        elif new_title:
+            acc = opt(argv, "--acceptance") or die("--new needs --acceptance")
+            req = ce.add_row(cl, opt(argv, "--prefix", "FN").upper(), new_title, acc, section=opt(argv, "--section"),
+                             mockup=opt(argv, "--mockup"), remark=f"logged via *log-miss {ce.TODAY}")
+            doc_line = f"new Not Started row {req} (BRD-pending; *amend-docs gives it its BRD item)"
+        else:
+            doc_line = "no owning row and no --new: record only"
+
+    # 3. the miss
+    mid = q("--next-miss-id")
+    rec = {"kind": "miss", "miss_id": mid, "req_id": req, "req_class": req.split("-")[1] if req else None, "miss_class": cls,
+           "artifact": artifact, "severity": severity, "why_missed": why, "origin_phase": "day1-greenfield" if cls in ("unspecified-gap", "spec-contradiction") else "build-phase",
+           "origin_agent": "analyst" if cls in ("unspecified-gap", "spec-contradiction") else "flow-master",
+           "found_by": found_by, "found_phase": "log-miss", "found_gate": None, "found_run_id": started, "failure_class": "other", "what": what[:300],
+           "sort": sort}
+    attributed = "inferred, no run record found"
+    if req and cls not in ("unspecified-gap", "spec-contradiction"):
+        o = q("--origin-of", req).split()
+        if len(o) >= 3:
+            rec["origin_run_id"], rec["origin_phase"], rec["origin_agent"] = o[0], o[1], o[2]
+            attributed = f"linked to run {o[0]}"
+    ok, refusal = emit("misses", rec)
+
+    # 4. --fixed
+    fix_line = ""
+    if fixed and ok:
+        fa = q("--next-fix-attempt", mid) or "1"
+        fr = {"kind": "miss-fix", "miss_id": mid, "req_id": req, "fix_cmd": "log-miss", "fix_attempt": int(fa) if fa.isdigit() else 1,
+              "verdict_after": "Verified", "reopened": False}
+        if opt(argv, "--fix-run"):
+            fr["fix_run_id"] = opt(argv, "--fix-run")
+        fix_ok, _ = emit("misses", fr)
+        fix_line = ("closed in the same run" + (f" against run {fr['fix_run_id']}" if "fix_run_id" in fr else " (fix run unknown: costed none)")) if fix_ok else "miss-fix not written"
+
+    # 5. the run record
+    run = {"kind": "run", "app": app, "cmd": "log-miss", "mode": None, "started": started, "ended": now,
+           "reqs_touched": [req] if req else [], "reqs_count": 1 if req else 0, "subagents": [], "files_written": 1 if has_cl else 0, "build_result": "not-run"}
+    emit("runs", run)
+
+    if not ok:
+        print(f"# Miss NOT recorded — {app}")
+        print(f"Refused    : {refusal}")
+        print(f"Nothing carries the id {mid}: the stream has no record and docs/{app}-Misses.md is unchanged.")
+        print(f"Docs       : {doc_line}")
+        print("Next       : fix the value the emitter named and run the same command again.")
+        return 2
+
+    print(f"# Miss logged — {app}")
+    print(f"{mid}  {cls} / {artifact} / {severity}")
+    print(f"Why missed : {why or 'not assessed'}")
+    print(f"Whose gap  : {sort} — " + {"spec": "the app's spec did not say it; fix the checklist line", "unsaid": "the framework never said it; one requirement line plus a check",
+                                        "weak-check": "the check was too weak; fix the check", "ignored": "said and ignored; a hook, or delete the rule"}[sort])
+    print(f"Owning REQ : {req or 'none'}")
+    print(f"Attributed : {rec['origin_phase']} ({rec['origin_agent']}) — {attributed}")
+    print(f"Found by   : {found_by}")
+    print(f"Docs       : {doc_line}; docs/{app}-Misses.md rewritten")
+    if fix_line:
+        print(f"Fix        : {fix_line}")
+    print(f"Next       : *fix-issues {app}" + (f" {req}" if req and not fixed else ""))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/.tfcore/utils/tf-log-miss.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# tf-log-miss.sh — one miss record from one sentence (Sitting 4c, 2026-09-06).
+#
+#   bash .tfcore/utils/tf-log-miss.sh <App> --what "<the owner's sentence>" [--req REQ-UI-014 | --new "<title>" --acceptance "<When … on <screen>, then …>"]
+#        [--class <miss_class>] [--why <why_missed>] [--artifact <artifact>] [--severity blocker|major|minor]
+#        [--found-by owner|production] [--evidence <path>] [--fixed [--fix-run <ISO>]] [--started <ISO>]
+#
+# Duplicate check, origin lookup, the miss record carrying the sentence, the checklist line (a demotion,
+# or a new Not Started row with BRD-pending), a miss-fix instead of a demotion with --fixed, then the run
+# record. Never boots, never fixes, never argues. Details: tf-log-miss.py.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-log-miss: python3 is required" >&2; exit 2; }
+exec python3 "$HERE/tf-log-miss.py" "$@"

package/.tfcore/utils/tf-misses-md.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""tf-misses-md.py — the readable miss list, docs/<App>-Misses.md (Session 5, 2026-09-07; FR-31).
+
+    python3 .tfcore/utils/tf-misses-md.py [--root <repo>] [--app <App>] [--quiet]
+
+Rebuilds docs/<App>-Misses.md from docs/metrics/misses.jsonl: one row per `miss` record, newest first,
+in three tables (open, fixed, will not fix), each row holding the miss id, the owning row, when and
+by whom it was found, whose gap it was (the `sort` field, folded from any miss-amend) and the `what`
+sentence. Markdown only — there is no HTML sibling: the miss log is read by agents and by the owner
+in markdown, and tf-render-html.py refuses it (owner, 2026-09-08; an HTML copy nobody opened was
+being re-rendered on every miss in every project). tf-emit.sh calls this after every write to the
+misses stream, so the file is never older than the record; run it by hand once on a project whose
+stream predates it. The file is derived: never edit it, edit nothing, log a miss.
+Exit 0 always (telemetry has no veto); the reason for a skipped write is printed unless --quiet.
+"""
+import datetime
+import glob
+import json
+import os
+import re
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+SORT_WORDS = {
+    "spec": "the app's spec",
+    "unsaid": "the framework never said it",
+    "weak-check": "the check was too weak",
+    "ignored": "said and ignored",
+}
+SORT_LEGEND = ("**Whose gap** answers the four questions of the miss protocol: "
+               "**the app's spec** did not say it, so the checklist line is fixed; "
+               "**the framework never said it**, so one requirement line and a check are added; "
+               "**the check was too weak** (a review, or a script that did not fire), so the check is fixed; "
+               "**said and ignored**, so the rule becomes a hook or is deleted. "
+               "**not sorted** means the record predates the sort or nobody has answered yet; "
+               "`bash .tfcore/utils/tf-emit.sh --amend <miss> sort <spec|unsaid|weak-check|ignored>` completes it.")
+
+
+def find_root(explicit):
+    if explicit and os.path.isdir(explicit):
+        return os.path.abspath(explicit)
+    for k in ("TF_METRICS_ROOT", "CLAUDE_PROJECT_DIR"):
+        v = os.environ.get(k)
+        if v and os.path.isdir(v):
+            return os.path.abspath(v)
+    d = os.getcwd()
+    while d and d != os.path.dirname(d):
+        if os.path.isdir(os.path.join(d, ".tfcore")) or os.path.isdir(os.path.join(d, "docs")):
+            return d
+        d = os.path.dirname(d)
+    return os.getcwd()
+
+
+def app_name(root, explicit):
+    if explicit:
+        return explicit
+    hits = [h for h in glob.glob(os.path.join(root, "docs", "*-Checklist.md"))
+            if not re.search(r"-(Deployment|P\d+)-Checklist\.md$", h)]
+    if len(hits) == 1:
+        return os.path.basename(hits[0])[: -len("-Checklist.md")]
+    return os.path.basename(os.path.abspath(root))
+
+
+def load(path):
+    out = []
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    out.append(json.loads(line))
+                except Exception:
+                    pass
+    except FileNotFoundError:
+        pass
+    return out
+
+
+def cell(text):
+    text = (text or "").replace("\r", " ").replace("\n", " ").replace("|", "\\|").strip()
+    return text or "—"
+
+
+def day(ts):
+    return (ts or "")[:10] or "—"
+
+
+def build(root, app):
+    recs = load(os.path.join(root, "docs", "metrics", "misses.jsonl"))
+    misses = [r for r in recs if r.get("kind") == "miss"]
+    by_id = {}
+    for i, m in enumerate(misses):
+        if not m.get("miss_id"):            # a record from before the emitter required an id: still a miss, still a row
+            m["miss_id"] = f"(no id, record {i + 1})"
+        by_id.setdefault(m["miss_id"], m)
+    for a in sorted((r for r in recs if r.get("kind") == "miss-amend"), key=lambda r: r.get("ts") or ""):
+        p = by_id.get(a.get("miss_id"))
+        if p is not None and a.get("field") and p.get(a["field"]) is None:
+            p[a["field"]] = a.get("value")
+    latest = {}
+    for f in recs:
+        if f.get("kind") != "miss-fix" or not f.get("miss_id"):
+            continue
+        prev = latest.get(f["miss_id"])
+        if prev is None or (f.get("ts") or "") >= (prev.get("ts") or ""):
+            latest[f["miss_id"]] = f
+
+    def state(m):
+        v = (latest.get(m["miss_id"]) or {}).get("verdict_after")
+        return "fixed" if v == "Verified" else "wont-fix" if v == "wont-fix" else "open"
+
+    groups = {"open": [], "fixed": [], "wont-fix": []}
+    for m in sorted(by_id.values(), key=lambda r: (r.get("miss_id") or "", r.get("ts") or ""), reverse=True):
+        groups[state(m)].append(m)
+
+    def what(m):
+        w = (m.get("what") or "").strip()
+        if w:
+            return cell(w)
+        bits = [m.get("miss_class") or "?", m.get("artifact") or "?"]
+        if m.get("why_missed"):
+            bits.append("why: " + m["why_missed"])
+        return "no sentence recorded (" + ", ".join(bits) + ")"
+
+    def found(m):
+        who = m.get("found_by") or "?"
+        return f"{day(m.get('ts'))} by {who}"
+
+    def gap(m):
+        return SORT_WORDS.get(m.get("sort") or "", "not sorted")
+
+    def ident(m):
+        return m["miss_id"] + (f" ({m['req_id']})" if m.get("req_id") else "")
+
+    today = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d")
+    n = len(by_id)
+    lines = [f"# {app} — Misses", "", "| | |", "|---|---|", f"| App | {app} |",
+             f"| Count | {n} logged: {len(groups['open'])} open, {len(groups['fixed'])} fixed, {len(groups['wont-fix'])} will not fix |",
+             "| Source | `docs/metrics/misses.jsonl`, one row per miss record. Rewritten by `tf-misses-md.sh` on every new record. Never edit it: a wrong row is corrected by a new record. |",
+             f"| Updated | {today} |", "", SORT_LEGEND, ""]
+    if not n:
+        lines += ["No miss has been logged yet.", ""]
+    for key, title in (("open", "Open"), ("fixed", "Fixed"), ("wont-fix", "Will not fix")):
+        rows = groups[key]
+        if not rows:
+            continue
+        lines += [f"## {title} ({len(rows)})", ""]
+        if key == "open":
+            lines += ["| Miss | Found | Whose gap | What went wrong |", "|---|---|---|---|"]
+            for m in rows:
+                lines.append(f"| {ident(m)} | {found(m)} | {gap(m)} | {what(m)} |")
+        else:
+            lines += ["| Miss | Found | Closed | Whose gap | What went wrong |", "|---|---|---|---|---|"]
+            for m in rows:
+                f = latest.get(m["miss_id"]) or {}
+                closed = day(f.get("ts")) + (f" by {f['fix_cmd']}" if f.get("fix_cmd") else "")
+                lines.append(f"| {ident(m)} | {found(m)} | {closed} | {gap(m)} | {what(m)} |")
+        lines.append("")
+    return "\n".join(lines), n
+
+
+def main(argv):
+    if "-h" in argv or "--help" in argv:
+        print(__doc__)
+        return 0
+    quiet = "--quiet" in argv
+
+    def opt(name):
+        return argv[argv.index(name) + 1] if name in argv and argv.index(name) + 1 < len(argv) else None
+
+    try:
+        root = find_root(opt("--root"))
+        app = app_name(root, opt("--app"))
+        text, n = build(root, app)
+        rel = os.path.join("docs", f"{app}-Misses.md")
+        out = os.path.join(root, rel)
+        os.makedirs(os.path.dirname(out), exist_ok=True)
+        old = None
+        try:
+            with open(out, encoding="utf-8") as fh:
+                old = fh.read()
+        except FileNotFoundError:
+            pass
+        stale = out[:-3] + ".html"                 # left by a pre-2026-09-08 run, before the miss
+        gone = ""                                  # log was ruled an agent document (owner)
+        if os.path.isfile(stale):
+            os.remove(stale)
+            gone = "; removed the stale HTML copy"
+        same = lambda s: re.sub(r"\| Updated \| [0-9-]+ \|", "", s)   # everything but the date must match
+        if old is not None and same(old) == same(text):
+            if not quiet:
+                print(f"tf-misses-md: {rel} unchanged ({n} misses){gone}")
+            return 0
+        with open(out, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(text)
+        if not quiet:
+            print(f"tf-misses-md: wrote {rel} ({n} misses){gone}")
+    except Exception as e:
+        if not quiet:
+            print(f"tf-misses-md: nothing written ({e})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/.tfcore/utils/tf-misses-md.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# tf-misses-md.sh — rebuild the readable miss list docs/<App>-Misses.md from the misses
+# stream (Session 5, 2026-09-07; FR-31). Markdown only: the miss log is never rendered to
+# HTML. tf-emit.sh runs it after every write to that stream; run it by hand once on a
+# project whose stream is older than this script.
+#
+#   bash .tfcore/utils/tf-misses-md.sh [--root <repo>] [--app <App>] [--quiet]
+#
+# Exit 0 always. Details: tf-misses-md.py.
+set -u
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+command -v python3 >/dev/null 2>&1 || { echo "tf-misses-md: python3 is required" >&2; exit 0; }
+python3 "$HERE/tf-misses-md.py" "$@"
+exit 0

package/.tfcore/utils/tf-mockups-locate.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""tf-mockups-locate.py — bring every mockup into docs/mockups/ (see tf-mockups-locate.sh).
+
+    bash .tfcore/utils/tf-mockups-locate.sh [--dry-run]
+
+The framework keeps one mockup folder, docs/mockups/. A brownfield repository may hold
+mockups elsewhere (a root mockups/ folder, a designs/ folder, an html file beside the
+docs). Two folders confused a real project, so this script finds every folder whose
+name says mockup (mockup, mockups, wireframes, designs, screens) outside docs/mockups/,
+docs/OldDocs/, the framework folders, node_modules, bin and obj, and moves each .html,
+.png, .jpg or .svg it holds into docs/mockups/. A name already taken there gets the
+source folder name as a suffix. Prints one line per file moved, then the final list of
+docs/mockups/ files. Exit 0 always; 2 if docs/ cannot be created.
+"""
+import os
+import shutil
+import sys
+
+NAMES = {"mockup", "mockups", "wireframe", "wireframes", "designs", "screens", "ui-mockups", "mock-ups"}
+SKIP_DIRS = {".tfcore", ".claude", ".opencode", ".git", "node_modules", "bin", "obj",
+             "OldDocs", "tests", "wwwroot"}
+EXT = (".html", ".htm", ".png", ".jpg", ".jpeg", ".svg")
+
+
+def main(argv):
+    dry = "--dry-run" in argv
+    if "-h" in argv or "--help" in argv:
+        print(__doc__)
+        return 0
+    root = os.getcwd()
+    target = os.path.join(root, "docs", "mockups")
+    try:
+        os.makedirs(target, exist_ok=True)
+    except Exception as e:
+        print(f"tf-mockups-locate: cannot create docs/mockups ({e})", file=sys.stderr)
+        return 2
+    moved = 0
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS]
+        rel = os.path.relpath(dirpath, root).replace(os.sep, "/")
+        if rel in (".", "docs/mockups") or rel.startswith("docs/mockups/"):
+            continue
+        if os.path.basename(dirpath).lower() not in NAMES:
+            continue
+        for fn in sorted(filenames):
+            if not fn.lower().endswith(EXT):
+                continue
+            src = os.path.join(dirpath, fn)
+            dest = os.path.join(target, fn)
+            if os.path.exists(dest):
+                stem, ext = os.path.splitext(fn)
+                dest = os.path.join(target, f"{stem}-{os.path.basename(dirpath)}{ext}")
+            print(f"tf-mockups-locate: {'would move' if dry else 'moved'} {rel}/{fn} -> docs/mockups/{os.path.basename(dest)}")
+            if not dry:
+                shutil.move(src, dest)
+            moved += 1
+        if not dry and not os.listdir(dirpath):
+            os.rmdir(dirpath)
+            print(f"tf-mockups-locate: removed the empty folder {rel}/")
+    files = sorted(f for f in os.listdir(target) if f.lower().endswith(EXT))
+    print(f"tf-mockups-locate: {moved} file(s) {'to move' if dry else 'moved'}; docs/mockups/ now holds {len(files)}: " + (", ".join(files) if files else "(none)"))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/.tfcore/utils/tf-mockups-locate.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# tf-mockups-locate.sh — bring every mockup in the repository into docs/mockups/.
+#
+#   bash .tfcore/utils/tf-mockups-locate.sh            # move, then list docs/mockups/
+#   bash .tfcore/utils/tf-mockups-locate.sh --dry-run  # only report
+#
+# Finds folders named mockup(s), wireframe(s), designs or screens outside
+# docs/mockups/ and moves their .html/.png/.jpg/.svg files there, so the
+# framework's one mockup folder is the only one. Run at brownfield day-1 and by
+# the mockups task before it links or draws anything.
+# Thin wrapper over tf-mockups-locate.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-mockups-locate: python3 is required (standard library only)." >&2
+  exit 2
+fi
+exec python3 "$SELF_DIR/tf-mockups-locate.py" "$@"