@techierathore/techieflow 1.1.0 → 1.1.1

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

@@ -0,0 +1,264 @@
+#!/usr/bin/env bash
+# tf-develop.sh — *develop-end-to-end: a brief in, a greenfield app out, up to UAT, unattended (2026-10-08).
+#
+#   bash .tfcore/utils/tf-develop.sh <app-dir> --app <App> --brief <file> [--harness claude|opencode]
+#        [--model <id>] [--tier standard] [--no-push] [--dry-run] [--detach]
+#   bash .tfcore/utils/tf-develop.sh <app-dir> --report           # write the Build Report again from the saved state
+#   bash .tfcore/utils/tf-develop.sh <app-dir> --resume          # continue a stopped run where it stopped
+#
+# The flow-master's *develop-end-to-end starts this; the owner never types it. It runs four phases, each
+# one an unattended goal run (tf-goal.sh: no questions, survives usage limits by waiting for the reset
+# and resuming the same session):
+#   day1      *day1-greenfield <App>            BRD, Architecture, mockups — no owner review stop
+#   day1-2    *day1-greenfield <App> --stage2   checklist and the remaining documents
+#   build     *build-phase <App>                every row built, verified inline, FIX mode on failures
+#   handoff   *handoff-phase <App>              UsageGuide with its smoke checklist and test users: UAT-ready
+# While it runs, .tfcore/.session/develop.json exists and every task follows .tfcore/tasks/_develop-mode.md.
+#
+# GIT — the one exception to "agents never write to git", for this command only. The agent still
+# cannot commit: its git guard is unchanged. THIS script commits after each phase, and pushes, from
+# its own shell, never through an agent's tool. When it ends, nothing is left switched on.
+#
+# METRICS — after every phase it writes docs/metrics/develop-report.json and docs/<App>-Build-Report.md:
+# per phase the wall-clock time (limit waits included), the agent's working time and its tokens (summed
+# from that phase's run records in docs/metrics/runs.jsonl), and the totals: "built in …".
+#
+# Exit 0 UAT-ready · 3 the agent declared a phase BLOCKED (the owner must act; listed in the report)
+#      · 4 a phase ran out of cycles · 5 the provider refused the model · 2 usage error.
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+case "${1:-}" in
+  -h|--help) sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  "")        sed -n '2,27p' "$0" | sed 's/^# \{0,1\}//'; exit 2 ;;
+esac
+
+DIR="$(cd "$1" 2>/dev/null && pwd)" || { echo "tf-develop: no such dir: $1" >&2; exit 2; }; shift
+APP=""; BRIEF=""; HARNESS="claude"; MODEL=""; TIER="standard"; PUSH=1; DRY=0; RESUME=0; DETACH=0; REPORT_ONLY=0
+ARGS_IN=("$@")
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --app) APP="${2:-}"; shift 2 ;;
+    --brief) BRIEF="${2:-}"; shift 2 ;;
+    --harness) HARNESS="${2:-}"; shift 2 ;;
+    --model) MODEL="${2:-}"; shift 2 ;;
+    --tier) TIER="${2:-}"; shift 2 ;;
+    --no-push) PUSH=0; shift ;;
+    --dry-run) DRY=1; shift ;;
+    --resume) RESUME=1; shift ;;
+    --detach) DETACH=1; shift ;;
+    --report) REPORT_ONLY=1; shift ;;
+    *) echo "tf-develop: unknown argument $1" >&2; exit 2 ;;
+  esac
+done
+# --detach: start this same run in its own session and return at once, so it outlives the agent session
+# that started it (the flow-master's *develop-end-to-end), in a session of its own (tf_setsid, portable).
+if [[ $DETACH -eq 1 ]]; then
+  mkdir -p "$DIR/.tfcore/.session"
+  rest=(); for a in "${ARGS_IN[@]}"; do [[ "$a" != --detach ]] && rest+=("$a"); done
+  source "$HERE/tf-portable.sh"   # tf_setsid works on macOS too (a python3 or perl stand-in)
+  tf_setsid bash "$0" "$DIR" "${rest[@]}" > "$DIR/.tfcore/.session/develop.out" 2>&1 < /dev/null &
+  echo "tf-develop: started (pid $!) — follow .tfcore/.session/develop.log; the result is docs/<App>-Build-Report.md"
+  exit 0
+fi
+STATE="$DIR/.tfcore/.session/develop.json"
+GOAL_SH="${TF_DEVELOP_GOAL_SH:-$DIR/.tfcore/utils/tf-goal.sh}"   # tests point this at a fake
+mkdir -p "$DIR/.tfcore/.session" "$DIR/docs/metrics"
+ts() { date -u +%Y-%m-%dT%H:%M:%SZ; }
+# The app folder must be the TOP of its own repository. A folder inside another repository answers
+# rev-parse too, and `git add -A` there staged the whole outer repository (found by dev_001 on its first run).
+own_repo() { local top; top="$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null)" || return 1
+  [[ -n "$top" && "$(cd "$top" && pwd -P)" == "$(cd "$DIR" && pwd -P)" ]]; }
+log() { printf '[%s] tf-develop: %s\n' "$(ts)" "$*" | tee -a "$DIR/.tfcore/.session/develop.log" >&2; }
+
+st() { python3 - "$STATE" "$@" <<'PY'
+import json, sys
+p, op, *a = sys.argv[1:]
+try: d = json.load(open(p))
+except Exception: d = {}
+if op == "get": print(d.get(a[0], ""))
+elif op == "init":
+    d = {"app": a[0], "brief": a[1], "harness": a[2], "model": a[3], "tier": a[4], "push": a[5] == "1", "started": a[6], "phases": []}
+elif op == "done": print("yes" if any(x["name"] == a[0] and x["status"] == "done" for x in d.get("phases", [])) else "")
+elif op == "attempts": print(sum(1 for x in d.get("phases", []) if x["name"] == a[0]))
+elif op == "phase":   # name status started ended exit commit pushed attempt — one entry per attempt, keyed by its number:
+    # a blocked attempt and its resume can start in the same second on a fast machine, and keying by the
+    # start made the second overwrite the first (dev_001 on the CI runner, 2026-10-09)
+    ph = d.get("phases", [])
+    new = dict(zip(("name", "status", "started", "ended", "goal_exit", "commit", "pushed", "attempt"), a))
+    hit = [i for i, x in enumerate(ph) if x["name"] == a[0] and str(x.get("attempt", "")) == a[7]]
+    if hit: ph[hit[0]] = new
+    else: ph.append(new)
+    d["phases"] = ph
+if op in ("init", "phase"): json.dump(d, open(p, "w"), indent=1)
+PY
+}
+
+if [[ $REPORT_ONLY -eq 1 ]]; then :
+elif [[ $RESUME -eq 1 ]]; then
+  [[ -f "$STATE" ]] || { echo "tf-develop: --resume: no $STATE" >&2; exit 2; }
+  APP="$(st get app)"; BRIEF="$(st get brief)"; HARNESS="$(st get harness)"; MODEL="$(st get model)"; TIER="$(st get tier)"
+  [[ "$(st get push)" == "False" ]] && PUSH=0
+else
+  [[ -n "$APP" && -n "$BRIEF" ]] || { echo "tf-develop: --app <App> and --brief <file> are required" >&2; exit 2; }
+  [[ "$APP" =~ ^[A-Z][A-Za-z0-9]*$ ]] || { echo "tf-develop: --app must be PascalCase with no spaces" >&2; exit 2; }
+  [[ -f "$BRIEF" ]] || { echo "tf-develop: brief not found: $BRIEF" >&2; exit 2; }
+  own_repo || { echo "tf-develop: $DIR is not a git repository of its own (a folder inside another repository does not count) — set it up first" >&2; exit 2; }
+  if [[ $PUSH -eq 1 && -z "$(git -C "$DIR" remote 2>/dev/null)" ]]; then echo "tf-develop: $DIR has no git remote to push to — add one, or pass --no-push" >&2; exit 2; fi
+  if [[ $DRY -eq 0 ]]; then
+    [[ "$(cd "$(dirname "$BRIEF")" && pwd)/$(basename "$BRIEF")" == "$DIR/docs/$APP-Brief.md" ]] || cp "$BRIEF" "$DIR/docs/$APP-Brief.md"
+    st init "$APP" "docs/$APP-Brief.md" "$HARNESS" "$MODEL" "$TIER" "$PUSH" "$(ts)"
+  fi
+fi
+
+MODE="Act as the flow-master (.tfcore/agents/flow-master.md). The command is *develop-end-to-end for $APP, in develop mode: read .tfcore/tasks/_develop-mode.md first and follow it in every task — no question to the owner, no stop for an owner review; every decision the owner would make is yours, written where that rule says. The brief is docs/$APP-Brief.md."
+goal_of() {
+  case "$1" in
+    day1)    echo "$MODE Run *day1-greenfield $APP, stage 1 (.tfcore/tasks/day1-greenfield.md), with the brief as the concept, all of it. When stage 1 is complete and rendered, the goal is met: do not stop for review and do not start stage 2." ;;
+    day1-2)  echo "$MODE Run *day1-greenfield $APP --stage2. The goal is met when stage 2 is complete and its status gate has run." ;;
+    build)   echo "$MODE Run *build-phase $APP (.tfcore/tasks/build-phase.md) on the whole phase checklist: every row built, the verifier chained inline, FIX mode on every failing row, until every row is terminal. Create and migrate the database the Architecture names, locally, as that rule says." ;;
+    handoff) echo "$MODE Run *handoff-phase $APP (.tfcore/tasks/handoff-phase.md): the UsageGuide with its smoke checklist and test users, the guides, the HTMLs, the status gate. The goal is met when the app is ready for the owner's UAT." ;;
+  esac
+}
+
+commit_phase() {   # $1 phase → prints "<sha> <pushed yes|no|off>"
+  local sha="" pushed="off"
+  own_repo || { echo "none no"; return; }   # never commit into a repository the app folder merely sits inside
+  if [[ -n "$(git -C "$DIR" status --porcelain 2>/dev/null)" ]]; then
+    git -C "$DIR" add -A >/dev/null 2>&1
+    git -C "$DIR" commit -q -m "TechieFlow develop-end-to-end: $1 done — $APP" -m "Written by tf-develop.sh after the $1 phase; per-phase time and tokens in docs/metrics/develop-report.json." >/dev/null 2>&1
+  fi
+  sha="$(git -C "$DIR" rev-parse --short HEAD 2>/dev/null)"
+  if [[ $PUSH -eq 1 ]]; then
+    if git -C "$DIR" rev-parse --abbrev-ref --symbolic-full-name '@{u}' >/dev/null 2>&1; then
+      git -C "$DIR" push -q >/dev/null 2>&1 && pushed=yes || pushed=no
+    else
+      git -C "$DIR" push -q -u "$(git -C "$DIR" remote | head -1)" HEAD >/dev/null 2>&1 && pushed=yes || pushed=no
+    fi
+  fi
+  echo "${sha:-none} $pushed"
+}
+
+report() {   # writes docs/metrics/develop-report.json and docs/<App>-Build-Report.md from the state and runs.jsonl
+  python3 - "$STATE" "$DIR" <<'PY'
+import datetime, json, os, sys
+state, root = json.load(open(sys.argv[1])), sys.argv[2]
+app = state["app"]
+def t(s):
+    try: return datetime.datetime.strptime(s, "%Y-%m-%dT%H:%M:%SZ")
+    except Exception: return None
+runs = []
+try:
+    for line in open(os.path.join(root, "docs", "metrics", "runs.jsonl"), encoding="utf-8", errors="replace"):
+        try: r = json.loads(line)
+        except Exception: continue
+        if r.get("kind", "run") == "run" and r.get("app") in (None, app) and r.get("started"): runs.append(r)
+except OSError: pass
+voided = {(r.get("cmd"), r.get("started")) for r in runs if r.get("kind") == "run-void"}
+def hm(s):
+    s = int(s or 0); return f"{s // 3600} h {s % 3600 // 60:02d} min" if s >= 3600 else f"{s // 60} min {s % 60:02d} s"
+NAMES = {"day1": "Day 1, stage 1 (BRD, Architecture, mockups)", "day1-2": "Day 1, stage 2 (checklist, documents)",
+         "build": "Build and verify", "handoff": "Handoff (UsageGuide, UAT-ready)"}
+out, tot = [], {"wall_s": 0, "work_s": 0, "tokens_in": 0, "tokens_out": 0, "tokens_cache_read": 0, "tokens_cache_write": 0, "runs": 0}
+models = {}
+# One row per phase, summing every attempt of it (a phase stopped "blocked" and resumed is run again; its
+# first attempts' time and tokens are part of what the phase cost). A run record belongs to the attempt
+# whose window holds its start, the window's first second included and its last excluded: a record that
+# starts the second the previous phase ends belongs to the next one (the first proof run counted the
+# build's 301,201 tokens under Day 1 stage 2).
+order, attempts = [], {}
+for x in state.get("phases", []):
+    if x["name"] not in attempts: order.append(x["name"])
+    attempts.setdefault(x["name"], []).append(x)
+def inside(r, wins):
+    s = t(r.get("started"))
+    return s is not None and any(a <= s < b for a, b in wins)
+for name in order:
+    ats = attempts[name]; p = ats[-1]
+    wins = [(t(x.get("started")), t(x.get("ended")) or datetime.datetime.utcnow()) for x in ats if t(x.get("started"))]
+    rs = [r for r in runs if (r.get("cmd"), r.get("started")) not in voided and inside(r, wins)]
+    # A record's tokens are measured over its own window of the session, so a command chained inside
+    # another (devguide inside handoff-phase) is counted twice if both are summed: a record lying wholly
+    # inside another is dropped, and working time is the union of the windows, not their sum.
+    span = lambda r: (t(r.get("started")), t(r.get("ended")) or t(r.get("started")))
+    rs = [r for i, r in enumerate(rs) if not any(
+        j != i and span(o)[0] and span(r)[0] and span(o)[0] <= span(r)[0] and span(r)[1] <= span(o)[1]
+        and (span(o) != span(r) or j < i) for j, o in enumerate(rs))]
+    iv = sorted(span(r) for r in rs if span(r)[0]); union, cur = 0, None
+    for a_, b_ in iv:
+        if cur and a_ <= cur[1]: cur = (cur[0], max(cur[1], b_))
+        else:
+            if cur: union += (cur[1] - cur[0]).total_seconds()
+            cur = (a_, b_)
+    if cur: union += (cur[1] - cur[0]).total_seconds()
+    row = {"phase": name, "title": NAMES.get(name, name), "status": p.get("status"), "attempts": len(ats),
+           "started": ats[0].get("started"), "ended": p.get("ended"),
+           "wall_s": int(sum((b - a).total_seconds() for a, b in wins)), "work_s": int(union),
+           "tokens_in": sum(int(r.get("tokens_in") or 0) for r in rs), "tokens_out": sum(int(r.get("tokens_out") or 0) for r in rs),
+           "tokens_cache_read": sum(int(r.get("tokens_cache_read") or 0) for r in rs),
+           "tokens_cache_write": sum(int(r.get("tokens_cache_write") or 0) for r in rs),
+           "runs": len(rs), "commands": sorted({r.get("cmd") for r in rs if r.get("cmd")}), "commit": p.get("commit"), "pushed": p.get("pushed")}
+    for r in rs:
+        for m, n in (r.get("model_tokens_out") or {r.get("model") or "unknown": r.get("tokens_out") or 0}).items():
+            models[m] = models.get(m, 0) + int(n or 0)
+    for k in tot: tot[k] += row[k]
+    out.append(row)
+done = [p for p in out if p["status"] == "done"]
+ready = len(done) == 4
+starts = [t(p["started"]) for p in out if t(p["started"])]; ends = [t(p["ended"]) for p in out if t(p["ended"])]
+span = int((max(ends) - min(starts)).total_seconds()) if starts and ends else 0
+rep = {"app": app, "harness": state.get("harness"), "model": state.get("model") or None, "tier": state.get("tier"),
+       "started": state.get("started"), "status": "uat-ready" if ready else (out[-1]["status"] if out else "not-started"),
+       "elapsed_s": span, "totals": tot, "tokens_out_by_model": models, "phases": out,
+       "note": "elapsed_s is first phase start to last phase end, usage-limit waits included; work_s is the agent's own run time from its run records"}
+json.dump(rep, open(os.path.join(root, "docs", "metrics", "develop-report.json"), "w"), indent=1)
+L = [f"# {app} — Build Report", "", "| | |", "|---|---|",
+     f"| What | {app}, developed end to end from docs/{app}-Brief.md by *develop-end-to-end |",
+     f"| Result | {'Ready for UAT' if ready else 'Stopped at ' + (out[-1]['title'] if out else 'the start') + ' (' + rep['status'] + ')'} |",
+     f"| Built in | {hm(span)} from start to finish, of which the agent worked {hm(tot['work_s'])} |",
+     f"| Harness and model | {state.get('harness')}, {', '.join(sorted(models)) or state.get('model') or 'default'} |",
+     f"| Tokens | {tot['tokens_in']:,} in, {tot['tokens_out']:,} out, {tot['tokens_cache_read']:,} read from cache, {tot['tokens_cache_write']:,} written to cache |",
+     "", "## Phases", "", "| Phase | Result | Time | Agent working | Tokens out | Commit |", "|---|---|---|---|---|---|"]
+for p in out:
+    L.append(f"| {p['title']}{' (' + str(p['attempts']) + ' attempts)' if p['attempts'] > 1 else ''} | {p['status']} | {hm(p['wall_s'])} | {hm(p['work_s'])} | {p['tokens_out']:,} | {p['commit'] or '—'}{'' if p['pushed'] in ('yes', 'off') else ' (not pushed)'} |")
+L += ["", "Time is the clock from the phase's start to its end, summed over its attempts, waits for a usage limit to reset included. "
+      "Built in also counts the time between attempts, while a stopped run waited to be resumed. "
+      "Agent working is the sum of the phase's run records. The same figures, for a comparison harness, are in "
+      "`docs/metrics/develop-report.json`.", ""]
+open(os.path.join(root, "docs", f"{app}-Build-Report.md"), "w", encoding="utf-8").write("\n".join(L))
+print(f"report: {rep['status']}, {hm(span)} elapsed, {tot['tokens_out']:,} tokens out — docs/{app}-Build-Report.md")
+PY
+}
+
+# No --model: the tier's routed model (.tfcore/routing.yaml), never the machine's own default. The proof
+# run on OpenCode fell back to a local model server that was not running and failed every cycle.
+if [[ -z "$MODEL" && -f "$DIR/.tfcore/utils/tf-model-pick.sh" ]]; then
+  MODEL="$(cd "$DIR" && bash .tfcore/utils/tf-model-pick.sh pick "$TIER" "$HARNESS" 2>/dev/null)"
+  [[ "$MODEL" == inherit ]] && MODEL=""
+fi
+# --report: write the report again from the saved state (the run's, or the finished run's), nothing else
+if [[ $REPORT_ONLY -eq 1 ]]; then
+  [[ -f "$STATE" ]] || STATE="$DIR/.tfcore/.session/develop-done.json"
+  [[ -f "$STATE" ]] || { echo "tf-develop: --report: no develop run recorded here" >&2; exit 2; }
+  report; exit 0
+fi
+GOAL_ARGS=(--harness "$HARNESS" --tier "$TIER"); [[ -n "$MODEL" ]] && GOAL_ARGS+=(--model "$MODEL")
+for phase in day1 day1-2 build handoff; do
+  if [[ $DRY -eq 1 ]]; then echo "$phase: bash $GOAL_SH ${GOAL_ARGS[*]} $DIR \"$(goal_of "$phase" | cut -c1-90)…\"; then commit$([[ $PUSH -eq 1 ]] && echo ' and push')"; continue; fi
+  [[ -n "$(st done "$phase")" ]] && { log "$phase already done — skipped"; continue; }
+  start="$(ts)"; log "$phase started"; attempt=$(( $(st attempts "$phase") + 1 ))
+  st phase "$phase" running "$start" "" "" "" "" "$attempt"
+  bash "$GOAL_SH" "${GOAL_ARGS[@]}" "$DIR" "$(goal_of "$phase")"; rc=$?
+  status=done; [[ $rc -eq 3 ]] && status=blocked; [[ $rc -ne 0 && $rc -ne 3 ]] && status="failed (exit $rc)"
+  end="$(ts)"
+  st phase "$phase" "$status" "$start" "$end" "$rc" "" "" "$attempt"
+  report >/dev/null                                    # the phase's figures go into its own commit
+  read -r sha pushed <<<"$(commit_phase "$phase")"
+  st phase "$phase" "$status" "$start" "$end" "$rc" "$sha" "$pushed" "$attempt"
+  log "$phase $status — commit $sha, pushed $pushed"
+  if [[ $rc -ne 0 ]]; then report; commit_phase "report" >/dev/null; exit "$rc"; fi
+done
+[[ $DRY -eq 1 ]] && exit 0
+report; read -r sha pushed <<<"$(commit_phase "build report")"
+log "UAT-ready — final report commit $sha, pushed $pushed"
+mv -f "$STATE" "$DIR/.tfcore/.session/develop-done.json"   # develop mode ends with the run
+exit 0

package/.tfcore/utils/tf-devguide-list.py

@@ -3,7 +3,7 @@
 
     bash .tfcore/utils/tf-devguide-list.sh <App> [--phase N] [--update]
 
-Reads appKind and appPhase from .tfcore/core-config.yaml and prints:
+Reads appKind (or metrics.project_type) and appPhase from .tfcore/core-config.yaml and prints:
   app             every routed page found in the code (route, file), matched to the phase's
                   UIDesign screens and to the roles in the UsageGuide's Test users table;
                   UIDesign screens with no code (a defect), routes with no UIDesign screen
@@ -151,7 +151,11 @@ def main(argv):
     app = argv[1]
     update = "--update" in argv
     phase = int(argv[argv.index("--phase") + 1]) if "--phase" in argv and argv.index("--phase") + 1 < len(argv) else int(cfg("appPhase", "1"))
-    kind = cfg("appKind", "app").lower()
+    kind = cfg("appKind", "").lower()
+    if not kind:   # metrics.project_type: library says it when appKind is not set (TrBlazeUI TF-005)
+        pt = re.search(r"(?m)^\s+project_type:\s*(\S+)", read(os.path.join(".tfcore", "core-config.yaml"))) \
+            if os.path.isfile(os.path.join(".tfcore", "core-config.yaml")) else None
+        kind = pt.group(1).strip("'\"").lower() if pt else "app"
     if "--kind" in argv and argv.index("--kind") + 1 < len(argv):
         kind = argv[argv.index("--kind") + 1].lower()   # override for a project whose config lacks it
     sub = "app"

package/.tfcore/utils/tf-doc-check.py

@@ -70,7 +70,9 @@ DOC_NAME = re.compile(
     r"^(.+?)(?:-P(\d+))?-(BRD|Deployment-Checklist(?:-[\w]+)?|Checklist|UIDesign|DevGuide|Architecture|Coding-Standards|UsageGuide|Usage-Guide|ProductGuide|Phases)\.md$",
     re.I)
 PHASE_FORM = re.compile(r"^(\d+)\s+of\s+(\d+)$", re.I)
-PHASE_STATUS = {"planned", "building", "done"}
+# kept-whole: a phase finished before the size cap that the owner chose to keep as one document;
+# its cap and word maximum are reported as WARN, not FAIL (Lekhak TF-029)
+PHASE_STATUS = {"planned", "building", "done", "kept-whole"}
 BRD_RANGE = re.compile(r"(?:BRD-)?(\d+)\s*(?:to|-|–|—)\s*(?:BRD-)?(\d+)", re.I)
 
 SIZE_NAMES = {"s": "S", "small": "S", "m": "M", "medium": "M", "l": "L", "large": "L"}
@@ -96,9 +98,10 @@ NAMES_SCREEN = re.compile(r"\b(on|opens?|from|in)\b", re.I)
 
 
 def acceptance_words(line: str) -> int:
-    """Words in an acceptance line, without the "Acceptance:" label and without a perf-budget tail."""
+    """Words in an acceptance line, without the "Acceptance:" label and without a perf-budget or
+    zoom-check tail (the markers the verifier reads)."""
     t = re.sub(r"^\s*[-*]\s*\*?Acceptance:?\*?:?\s*", "", line)
-    t = re.split(r"perf-budget:", t, flags=re.I)[0]
+    t = re.split(r"perf-budget:|zoom-check:", t, flags=re.I)[0]
     return len(re.findall(r"\S+", t))
 
 
@@ -331,7 +334,7 @@ def read_core_config(root: str) -> dict:
     if os.path.exists(p):
         with open(p, encoding="utf-8") as fh:
             for line in fh:
-                m = re.match(r"^(appSize|appKind|appPhase):\s*(\S+)", line)
+                m = re.match(r"^(appSize|appKind|appPhase):\s*(\S+)", line) or re.match(r"^\s+(project_type):\s*(\S+)", line)
                 if m and m.group(2) not in ("null", "~", "''", '""'):
                     out[m.group(1)] = m.group(2).strip("'\"")
     return out
@@ -356,6 +359,24 @@ def foreign_prefix(path: str):
     return app if app and apps and app.lower() not in apps else None
 
 
+def phase_status(path: str, app: str, phase: int):
+    """The Status cell of this phase's row in docs/{App}-Phases.md beside it, lower-cased; None when
+    there is no Phases document or no row for the phase."""
+    p = os.path.join(os.path.dirname(path), f"{app}-Phases.md")
+    if not app or not os.path.isfile(p):
+        return None
+    with open(p, encoding="utf-8") as fh:
+        txt = strip_noise(fh.read())
+    for header, rows in tables_in(txt):
+        low = [h.lower() for h in header]
+        if "phase" in low and "status" in low:
+            ip, ist = low.index("phase"), low.index("status")
+            for r in rows:
+                if len(r) > max(ip, ist) and r[ip].strip("`* ") == str(phase):
+                    return r[ist].strip("`* ").lower()
+    return None
+
+
 def phase_file(app: str, phase: int, suffix: str) -> str:
     return f"{app}-{suffix}.md" if phase <= 1 else f"{app}-P{phase}-{suffix}.md"
 
@@ -450,6 +471,10 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
             rep.fail(rel, f'a phase-{phase} file needs the header row "Phase | {phase} of <m>"')
         elif os.path.exists(phases_doc):
             rep.fail(rel, f'the project has phases ({os.path.relpath(phases_doc, root)}); this file needs the header row "Phase | 1 of <m>"')
+    # a phase the owner kept whole past the cap: its size findings are WARN, never a gate failure (Lekhak TF-029)
+    kept = doc in PHASED_DOCS and bool(app) and phase_status(path, app, phase) == "kept-whole"
+    size_finding = rep.warn if kept else rep.fail
+    kept_why = f"; phase {phase} is kept-whole in {app}-Phases.md, so this is reported, not blocking" if kept else ""
 
     # 2. sections: strangers, order, presence
     present = [(norm_heading(h), h, txt) for h, txt in split_sections(clean, 2) if h is not None]
@@ -502,7 +527,7 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
             target, mx = target + extra * schema.per_entry[0], mx + extra * schema.per_entry[1]
             why = f", with {extra} entries past the cap of {SCREEN_CAP[size]}" if extra else ""
         if total > mx:
-            rep.fail(rel, f"{total:,} words; the {SIZE_LONG[size]} maximum is {mx:,} (target {target:,}{why}). Shorten prose; never drop a screen, field or requirement to fit")
+            size_finding(rel, f"{total:,} words; the {SIZE_LONG[size]} maximum is {mx:,} (target {target:,}{why}). Shorten prose; never drop a screen, field or requirement to fit{kept_why}")
         elif total > target:
             rep.warn(rel, f"{total:,} words; the {SIZE_LONG[size]} target is {target:,} (maximum {mx:,}{why})")
     for key, h, txt in present:
@@ -564,7 +589,7 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     # 5. document rules
     ctx = dict(doc=doc, body=body, clean=clean, nocomment=nocomment, present=present, header=header,
                size=size, kind=kind, root=root, path=path, rel=rel, entry_names=entry_names,
-               app=app, phase=phase)
+               app=app, phase=phase, size_finding=size_finding, kept_why=kept_why)
     for rule in schema.rules:
         if not rule.startswith("entry-"):
             check_doc_rule(rule, ctx, rep)
@@ -653,7 +678,7 @@ def check_doc_rule(rule, c, rep):
         if dupes:
             rep.fail(rel, "duplicate requirement ids: " + ", ".join(f"BRD-{d}" for d in sorted(dupes, key=int)))
         if len(seen) > REQ_CAP[size]:
-            rep.fail(rel, f"{len(seen)} requirements; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases (each phase its own BRD) instead of growing this one")
+            c["size_finding"](rel, f"{len(seen)} requirements; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases (each phase its own BRD) instead of growing this one{c['kept_why']}")
         c["brd_ids"] = seen
         req = section_text(present, "Requirements") or ""
         cur = None
@@ -986,7 +1011,7 @@ def check_doc_rule(rule, c, rep):
                             rep.fail(rel, f"phase {n} BRD range runs backwards ({x} to {y})")
                 st = r[ist].strip("`* ").lower()
                 if st not in PHASE_STATUS:
-                    rep.fail(rel, f'phase {n} status "{r[ist]}" must be planned, building or done')
+                    rep.fail(rel, f'phase {n} status "{r[ist]}" must be planned, building, done or kept-whole')
                 rows_out.append(dict(n=n, name=r[iname].strip("`* "), screens=screens, lo=lo, hi=hi, ranges=ranges, status=st))
         nums = [p["n"] for p in rows_out]
         if nums != list(range(1, len(nums) + 1)):
@@ -1033,10 +1058,12 @@ def check_checklist(c, rep):
         row_status[rid] = status.strip("`* ").lower()
         if not re.fullmatch(r"REQ-(UI|FN|RAG|NFR)-\d{3}", rid):
             rep.fail(rel, f'id "{rid}" is not REQ-UI/FN/RAG/NFR- plus three digits')
+        removed = " A removed row reads N/A with % 0, and the date goes in Remarks"
         if status.strip("`* ").lower() not in STATUS_VALUES:
-            rep.fail(rel, f'{rid} status "{status}" is not one of the fixed values')
+            rep.fail(rel, f'{rid} status "{status}" is not one of the fixed values.'
+                          + (removed if status.strip("`* ").lower().startswith("n/a") else ""))
         if pct.strip("`* ").rstrip("%").strip() not in ("0", "25", "50", "75", "100"):
-            rep.fail(rel, f'{rid} % "{pct}" must be 0, 25, 50, 75 or 100')
+            rep.fail(rel, f'{rid} % "{pct}" must be 0, 25, 50, 75 or 100.' + removed)
         n = len(re.findall(r"\S+", remarks))
         if n > 60:
             rep.fail(rel, f"{rid} Remarks is {n} words; at most 60, current state only (history lives in the telemetry streams)")
@@ -1046,6 +1073,10 @@ def check_checklist(c, rep):
         said = re.sub(r"`[^`]*(?:`|$)", " ", remarks)
         if NOT_PRESENT.search(said) and not NAMES_PATH.search(remarks):
             rep.fail(rel, f"{rid} Remarks says something is not present without naming the path that was tried; search tools skip .tfcore/, so read the literal path first")
+        if row_status[rid] == "n/a":
+            # a removed or reserved row is kept for traceability; it has no screen, mockup or BRD item to
+            # point at, so the detail-entry rules do not apply to it (Lekhak TF-028)
+            continue
         m = re.search(r"\(#([^)]+)\)", details)
         if not m:
             rep.fail(rel, f"{rid} Details cell has no link to its detail entry")
@@ -1054,7 +1085,7 @@ def check_checklist(c, rep):
     if not ids:
         rep.fail(rel, "the Requirements Status table has no REQ- rows")
     if len(ids) > REQ_CAP[size]:
-        rep.fail(rel, f"{len(ids)} rows; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases instead of growing this checklist")
+        c["size_finding"](rel, f"{len(ids)} rows; the {SIZE_LONG[size]} cap is {REQ_CAP[size]}. Split into phases instead of growing this checklist{c['kept_why']}")
     dupes = sorted({i for i in ids if ids.count(i) > 1})
     if dupes:
         rep.fail(rel, "duplicate rows: " + ", ".join(dupes))
@@ -1076,6 +1107,9 @@ def check_checklist(c, rep):
             start = pos + own.end()
         nxt = re.search(r"\n\s*(?:[-*]\s*)?<a id=|\n## |\n### ", body[start:])   # an entry is a list item: the dash precedes the anchor (miss 21)
         entry = body[pos: start + nxt.start()] if nxt else body[pos:]
+        if row_status.get(rid) == "n/a":
+            brd_refs.update(re.findall(r"BRD-(\d+)", entry))   # a retired BRD item still has its row
+            continue
         acc = [l for l in entry.splitlines() if ACCEPT_LINE.search(l)]
         if len(acc) != 1:
             rep.fail(rel, f"{rid} must have exactly one acceptance line; found {len(acc)}")
@@ -1100,7 +1134,10 @@ def check_checklist(c, rep):
         brd_refs.update(refs)
         if rid.startswith("REQ-UI"):
             links = links_to(entry, "mockups")
-            if not links:
+            # a library or docs project (metrics.project_type, or kind: library) has no screens and no
+            # docs/mockups/: its UI rows map to components, so a missing link is not a finding there; a
+            # link it does carry must still resolve (TrBlazeUI TF-003)
+            if not links and c.get("kind") == "app" and read_core_config(root).get("project_type", "app").lower() not in ("library", "docs"):
                 rep.fail(rel, f"{rid} is a UI row without a mockup link")
             for l in sorted(links):
                 if not resolve(root, path, l):
@@ -1275,14 +1312,18 @@ NAV_ITEM = re.compile(r"""<(div|li|span|button)\b[^>]*\bclass\s*=\s*["'][^"']*(?
 
 
 def _mock_target(mock_dir: str, t: str):
-    """Resolve a link the way a browser opening docs/mockups/<file> would. Returns the file
-    name when it lands on an existing file inside the mockup folder, else None."""
+    """Resolve a link the way a browser opening docs/mockups/<file> would. Returns the path
+    relative to the mockup folder when it lands on an existing file inside it, at any depth
+    (Lekhak TF-008: index.html linking to admin/connection-settings.html opens, and was
+    failed), else None. A leading slash, or a path that leaves docs/mockups/, is still None."""
     if re.match(r"^(https?:|mailto:|tel:|javascript:|data:)", t, re.I) or t.startswith("/"):
         return None
+    t = re.split(r"[?#]", t, maxsplit=1)[0]
+    base = os.path.normpath(mock_dir)
     p = os.path.normpath(os.path.join(mock_dir, t))
-    if os.path.dirname(p) != os.path.normpath(mock_dir) or not os.path.isfile(p):
+    if not (p == base or p.startswith(base + os.sep)) or not os.path.isfile(p):
         return None
-    return os.path.basename(p)
+    return os.path.relpath(p, base).replace(os.sep, "/")
 
 
 def check_mockups(root: str, rep: Report):
@@ -1315,7 +1356,8 @@ def check_mockups(root: str, rep: Report):
                 continue
             name = _mock_target(mock_dir, t)
             if name is None:
-                hint = "write the file name alone, not a folder or a leading slash" if ("/" in t) else "the file does not exist"
+                hint = ("a leading slash opens from the disk's root; write the path from docs/mockups/" if t.startswith("/")
+                        else "the file does not exist inside docs/mockups/")
                 rep.fail(rel, f'links to "{t}", which does not open from docs/mockups/ ({hint})')
             else:
                 targets.append(name)
@@ -1420,6 +1462,7 @@ def main(argv=None):
     if a.app:
         root = root or os.getcwd()
         files += app_files(root, a.app)
+        files = list(dict.fromkeys(os.path.abspath(f) for f in files))   # a file given and listed by --app once
         if not files:
             print(f"tf-doc-check: no documents for app {a.app} under {root}", file=sys.stderr)
             return 2
@@ -1452,9 +1495,16 @@ def main(argv=None):
                 base = json.load(fh) or {}
         except Exception:
             base = {}
-        for f in files:
-            r = os.path.relpath(f, root)
-            base[r] = sorted({l.split(": ", 1)[1] for l in rep.lines if l.startswith("FAIL ") and l.split(": ", 1)[0].endswith(" " + r)})
+        # every finding, under whatever it names: the mockup-folder and cross-document checks name
+        # docs/mockups/index.html or another document, not one of the files given, and were never
+        # recorded, so ~60 old findings read as new on every *amend-docs (Lekhak TF-023)
+        new = {os.path.relpath(f, root): set() for f in files}
+        for l in rep.lines:
+            if l.startswith("FAIL ") and ": " in l:
+                head, msg = l.split(": ", 1)
+                new.setdefault(head[len("FAIL "):], set()).add(msg)
+        for r, msgs in new.items():
+            base[r] = sorted(msgs)
         os.makedirs(os.path.dirname(base_path), exist_ok=True)
         with open(base_path, "w", encoding="utf-8") as fh:
             json.dump(base, fh, indent=1)
@@ -1468,11 +1518,23 @@ def main(argv=None):
                 with open(base_path, encoding="utf-8") as fh:
                     base = json.load(fh) or {}
                 relined = []
+                # A size finding carries its count ("20,677 words; the Small maximum is 8,000"), so any
+                # edit to an over-limit document, a cut included, changed the text and read as new
+                # (Lekhak TF-023). The same finding with a count no larger than the old one is old;
+                # a document that grew past its maximum still FAILs.
+                def _shape(m):
+                    return re.sub(r"\d[\d,]*", "#", m)
+                def _first(m):
+                    n = re.search(r"\d[\d,]*", m)
+                    return int(n.group(0).replace(",", "")) if n else None
                 for l in rep.lines:
                     if l.startswith("FAIL "):
                         head, msg = l.split(": ", 1)
                         r = head[len("FAIL "):]
-                        if msg in set(base.get(r, [])):
+                        was = base.get(r, [])
+                        same = msg in set(was) or (re.match(r"^\d[\d,]* (words|lines|rows|requirements|KB|screens)", msg) and any(
+                            _shape(o) == _shape(msg) and _first(o) is not None and _first(msg) <= _first(o) for o in was))
+                        if same:
                             relined.append("OLD  " + l[5:])
                             rep.fails -= 1
                             old += 1

package/.tfcore/utils/tf-doc-tests.sh

@@ -7,7 +7,8 @@
 # docs/Lekhak-UsageGuide.md and fails when the REQ-NFR-042 paragraph is gone. *amend-docs removed that
 # paragraph, ran no test, closed green, and only CI noticed. This script looks for test source files
 # (a path containing "test") that name one of the documents, by file name or by name without ".md".
-# When one does, it runs the unit tests through tf-build.sh test. Prints ONE line:
+# When one does, it runs the test projects holding those files, each on its own through tf-build.sh
+# test (TechieRag TF-004), or the solution's tests one project at a time. Prints ONE line:
 #   NONE     no test reads <docs>; nothing to run                             exit 0
 #   PASS     <n> test file(s) read <docs> (<files>); the unit tests pass — <build line>   exit 0
 #   FAIL     <n> test file(s) read <docs> (<files>); the unit tests fail — <build line>   exit 1
@@ -20,7 +21,7 @@ DOCS=(); TARGET=""
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --target) TARGET="${2:-}"; shift 2 ;;
-    -h|--help) sed -n '2,15p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    -h|--help) sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) DOCS+=("$1"); shift ;;
   esac
 done
@@ -71,7 +72,43 @@ if [[ -z "$TARGET" && -z "$ROOTSLN" ]]; then
   fi
   exit 2
 fi
-LINE="$(bash "$HERE/tf-build.sh" test ${TARGET:+"$TARGET"} 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+# Only the test projects that hold a reader, each on its own (TechieRag TF-004): the whole solution at
+# once let the local-model tests take the memory, and TechieRag.Tests failed with "Cannot allocate
+# memory" on a test that passes alone. A reader in no .NET test project (a browser spec) falls back to
+# the solution run, which tf-build.sh also splits into one test project at a time.
+OWNERS="$(TF_READERS="$READERS" python3 - <<'PY'
+import glob, os, sys
+out = []
+for r in os.environ.get("TF_READERS", "").split("\n"):
+    if not r.strip():
+        continue
+    d = os.path.dirname(r)
+    while d and d not in (".", "/"):
+        projs = glob.glob(os.path.join(d, "*.csproj"))
+        if projs:
+            p = projs[0]
+            if p not in out:
+                out.append(p)
+            break
+        d = os.path.dirname(d)
+print("\n".join(out))
+PY
+)"
+if [[ -n "$OWNERS" && -z "$TARGET" ]]; then
+  fails=(); notrun=(); passed=0; vl=()
+  while IFS= read -r p; do
+    [[ -z "$p" ]] && continue
+    v="$(bash "$HERE/tf-build.sh" test "$p" 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+    vl+=("$(basename "$p" .csproj): ${v:-no verdict}")
+    case "$v" in PASS*) passed=$((passed+1)) ;; FAIL*) fails+=("$(basename "$p" .csproj)") ;; *) notrun+=("$(basename "$p" .csproj)") ;; esac
+  done <<<"$OWNERS"
+  k="$(grep -c . <<<"$OWNERS")"
+  if [[ ${#fails[@]} -gt 0 ]]; then LINE="FAIL  ${fails[*]} failed ($k test project(s) holding a reader, each run on its own) — ${vl[*]}"
+  elif [[ ${#notrun[@]} -gt 0 ]]; then LINE="NOT-RUN ${notrun[*]} could not run — ${vl[*]}"
+  else LINE="PASS  $k test project(s) holding a reader, each run on its own — ${vl[*]}"; fi
+else
+  LINE="$(bash "$HERE/tf-build.sh" test ${TARGET:+"$TARGET"} 2>&1 | grep -m1 -E '^(PASS|FAIL|NOT-RUN)' || true)"
+fi
 case "$LINE" in
   PASS*)    echo "PASS     $N test file(s) read ${DOCS[*]} ($LIST); the unit tests pass — $LINE"; exit 0 ;;
   FAIL*)    echo "FAIL     $N test file(s) read ${DOCS[*]} ($LIST); the unit tests fail — $LINE"; exit 1 ;;