@techierathore/techieflow 1.0.4 → 1.1.1

package/.tfcore/utils/tf-ci-repro.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# tf-ci-repro.sh — reproduce a CI job here the way a fresh runner runs it (Lekhak TF-019, 2026-09-30).
+#
+#   bash .tfcore/utils/tf-ci-repro.sh [<workflow.yml>] [--job <id>] [--list] [--keep] [--run-setup]
+#
+# Run from the repository root. A developer machine hides CI failures in its package caches and its
+# build output: Lekhak's CI failed with NETSDK1112 because the win-x64 runtime pack was never
+# downloaded, while the same commands passed locally where the pack was already cached. A local run
+# with warm caches is therefore no proof that a CI failure is fixed. This script copies the repository
+# without anything .gitignore ignores, to a folder outside it, points every package cache it knows
+# (NuGet, npm, yarn, pnpm, pip, Go, Gradle, Maven) at an empty folder, and runs the job's `run:` steps
+# in the runner's shell, stopping at the first failure. A Windows job runs Windows-side from WSL.
+# `uses:` steps, steps that need a secret and steps that only install tools on the machine are
+# skipped, each with the reason. --list prints the plan and runs nothing; --keep keeps the copy.
+# Prints ONE verdict line last:
+#   PASS     job <id>: <n> run step(s) passed on a clean copy with empty caches (…) — logs <dir>   exit 0
+#   FAIL     job <id>: step <n> "<name>" failed (exit N) with empty caches — <first error> — log <file>   exit 1
+#   NOT-RUN  <why: no workflow, several jobs, a macOS job off a Mac …>                         exit 2
+# PyYAML is used when installed; without it (a stock Mac) a built-in reader takes the workflow.
+# Logs: tests/.artifacts/ci-repro/<UTC time>/step-NN.log. The first run downloads every package, so
+# it takes as long as a cold CI restore.
+set -uo pipefail
+case "${1:-}" in -h|--help) sed -n '2,21p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+exec python3 "$(dirname "${BASH_SOURCE[0]}")/tf-ci-repro.py" "$@"

package/.tfcore/utils/tf-day1-files.py

@@ -4,15 +4,17 @@
     bash .tfcore/utils/tf-day1-files.sh <App> [--size S|M|L] [--kind app|library] [--prefix obj|none] [--phase N]
     bash .tfcore/utils/tf-day1-files.sh --archive <file> [<file> ...]
 
-Default mode, for <App>:
-  - .tfcore/core-config.yaml: customTechnicalDocuments (brd, architecture, codingStandards),
-    devLoadAlwaysFiles, and appSize / appKind / appPhase when given.
+Default mode, for <App>. Each flag does its own part and nothing else:
+  - --size, --kind, --phase set appSize, appKind, appPhase in .tfcore/core-config.yaml; --phase is the
+    phase being worked (handoff moves it on).
   - --size L also writes docs/<App>-Phases.md from app-phases-tmpl.md when it does not exist
     (the Large layout: docs/TechieFlow-Document-Schemas.md §2, §3.11). The agent fills the table.
-  - --phase N sets appPhase, the phase being worked (handoff moves it on).
-  - .editorconfig from app-editorconfig-tmpl.editorconfig (overwritten; machine config).
-  - AGENTS.md and CLAUDE.md from their templates with {AppName} substituted and the
-    field-prefix line resolved (--prefix, default obj). An existing copy is archived first.
+  - --prefix obj|none (day-1 stage 2) writes .editorconfig (overwritten; machine config), AGENTS.md and
+    CLAUDE.md from their templates with {AppName} substituted and the field-prefix line resolved, an
+    existing copy archived first; and adds the brd, architecture and codingStandards paths to
+    customTechnicalDocuments and devLoadAlwaysFiles where missing, keeping every entry already there.
+Raising the size of a project with *amend-docs (--size L) once replaced Sevak's AGENTS.md and CLAUDE.md
+with blank templates and cut its document list to three entries (Sevak TF-001). tests/regression sv_001.
 --archive: move each file (and its sibling .html) to docs/OldDocs/, date-suffixed when a
 file of that name is already there. Never asks; never writes a -v2 variant.
 
@@ -86,22 +88,45 @@ def set_key(text, key, value_lines):
     return "\n".join(out) + "\n"
 
 
-def update_config(app, size, kind, phase):
+def block_of(text, key):
+    """The indented lines under a top-level YAML key, [] when the key is absent or empty."""
+    lines, out, inside = text.splitlines(), [], False
+    for line in lines:
+        if re.match(rf"^{re.escape(key)}:", line):
+            inside = True
+            continue
+        if inside:
+            if line.startswith((" ", "\t")):
+                out.append(line)
+            elif line.strip():
+                break
+    return out
+
+
+def add_documents(s, app):
+    """The day-1 document paths, added where missing; every entry already listed is kept."""
+    docs = block_of(s, "customTechnicalDocuments")
+    have = {m.group(1) for m in (re.match(r"^\s+([\w-]+):", l) for l in docs) if m}
+    for k, v in (("brd", f"docs/{app}-BRD.md"), ("architecture", f"docs/{app}-Architecture.md"),
+                 ("codingStandards", f"docs/{app}-Coding-Standards.md")):
+        if k not in have:
+            docs.append(f"  {k}: {v}")
+    s = set_key(s, "customTechnicalDocuments", ["customTechnicalDocuments:"] + docs)
+    files = block_of(s, "devLoadAlwaysFiles")
+    listed = {l.strip().lstrip("-").strip() for l in files}
+    for f in (f"docs/{app}-Coding-Standards.md", f"docs/{app}-Architecture.md"):
+        if f not in listed:
+            files.append(f"  - {f}")
+    return set_key(s, "devLoadAlwaysFiles", ["devLoadAlwaysFiles:"] + files)
+
+
+def update_config(app, size, kind, phase, documents):
     p = os.path.join(".tfcore", "core-config.yaml")
     if not os.path.isfile(p):
         die(f"{p} does not exist at its literal path; is the framework installed here?")
     s = read(p)
-    s = set_key(s, "customTechnicalDocuments", [
-        "customTechnicalDocuments:",
-        f"  brd: docs/{app}-BRD.md",
-        f"  architecture: docs/{app}-Architecture.md",
-        f"  codingStandards: docs/{app}-Coding-Standards.md",
-    ])
-    s = set_key(s, "devLoadAlwaysFiles", [
-        "devLoadAlwaysFiles:",
-        f"  - docs/{app}-Coding-Standards.md",
-        f"  - docs/{app}-Architecture.md",
-    ])
+    if documents:
+        s = add_documents(s, app)
     if size:
         s = set_key(s, "appSize", [f"appSize: {size}"])
     if kind:
@@ -109,9 +134,9 @@ def update_config(app, size, kind, phase):
     if phase:
         s = set_key(s, "appPhase", [f"appPhase: {phase}"])
     write(p, s)
-    print(f"tf-day1-files: .tfcore/core-config.yaml updated (documents for {app}"
-          + (f", appSize {size}" if size else "") + (f", appKind {kind}" if kind else "")
-          + (f", appPhase {phase}" if phase else "") + ")")
+    done = ([f"documents for {app}"] if documents else []) + ([f"appSize {size}"] if size else []) \
+        + ([f"appKind {kind}"] if kind else []) + ([f"appPhase {phase}"] if phase else [])
+    print(f"tf-day1-files: .tfcore/core-config.yaml updated ({', '.join(done)})")
 
 
 def write_phases_doc(app):
@@ -161,8 +186,7 @@ def main(argv):
     app = argv[1]
     if not re.fullmatch(r"[A-Z][A-Za-z0-9]*", app):
         die(f"app name {app!r} must be PascalCase with no spaces")
-    size = kind = phase = None
-    prefix = "obj"
+    size = kind = phase = prefix = None
     args = argv[2:]
     i = 0
     while i < len(args):
@@ -190,12 +214,15 @@ def main(argv):
             i += 2
         else:
             die(f"unknown argument {a!r}")
-    update_config(app, size, kind, phase)
+    if not (size or kind or phase or prefix):
+        die("nothing to do: give --size, --kind, --phase or --prefix")
+    update_config(app, size, kind, phase, documents=bool(prefix))
     if size == "L":
         write_phases_doc(app)
-    write_from_template(app, "app-editorconfig-tmpl.editorconfig", ".editorconfig", None)
-    write_from_template(app, "app-agents-md-tmpl.md", "AGENTS.md", prefix)
-    write_from_template(app, "app-claude-md-tmpl.md", "CLAUDE.md", prefix)
+    if prefix:     # day-1 stage 2 only: a size, kind or phase change never rewrites these (Sevak TF-001)
+        write_from_template(app, "app-editorconfig-tmpl.editorconfig", ".editorconfig", None)
+        write_from_template(app, "app-agents-md-tmpl.md", "AGENTS.md", prefix)
+        write_from_template(app, "app-claude-md-tmpl.md", "CLAUDE.md", prefix)
     return 0
 
 

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
@@ -50,9 +50,16 @@ def cfg(key, default):
 PRUNE = {"bin", "obj", "node_modules", ".git", ".artifacts", "OldDocs", "dist", ".tfcore", ".claude", ".opencode", "packages", "TestResults"}
 
 
+# The folders a project keeps its code in, in the order tf-verify-boot.sh looks (Lekhak TF-014: Lekhak's
+# is source/, and --update counted only src/).
+CODE_ROOTS = ("src", "source")
+
+
 def walk(root, exts, skip_samples=False):
     for d, dirs, files in os.walk(root):
-        dirs[:] = [x for x in dirs if x not in PRUNE]   # prune in place: never descend into build output
+        # prune in place: never descend into build output, nor into any hidden folder (.tfbuild, .vs,
+        # .playwright …), which holds tool output, never a page (Lekhak TF-014)
+        dirs[:] = [x for x in dirs if x not in PRUNE and not x.startswith(".")]
         dd = d.replace("\\", "/") + "/"
         if any(s in dd for s in SKIP):
             continue
@@ -60,20 +67,28 @@ def walk(root, exts, skip_samples=False):
             continue
         for f in files:
             if f.lower().endswith(exts):
-                yield os.path.join(d, f).replace("\\", "/").lstrip("./")
+                p = os.path.join(d, f).replace("\\", "/")
+                # only a leading "./" goes: lstrip("./") also ate the dot of a hidden folder, and
+                # .tfbuild/… became tfbuild/…, which does not exist (Lekhak TF-014)
+                yield p[2:] if p.startswith("./") else p
+
+
+def code_files(exts, skip_samples=True):
+    """Every file with these extensions under the project's code folders (src/, source/)."""
+    for r in CODE_ROOTS:
+        if os.path.isdir(r):
+            yield from walk(r, exts, skip_samples=skip_samples)
 
 
 def roles_from_usageguide(app):
-    p = os.path.join("docs", f"{app}-UsageGuide.md")
-    roles = []
-    if os.path.isfile(p):
-        m = re.search(r"(?ms)^##\s+(?:\d+[.)]\s*)?Test users[^\n]*\n(.*?)(?=^## |\Z)", read(p))
-        if m:
-            for line in m.group(1).splitlines():
-                c = [x.strip() for x in line.strip().strip("|").split("|")]
-                if len(c) >= 4 and c[0].strip("`* ").isdigit():
-                    roles.append((c[1].strip("`* "), c[3].strip("`* ")))
-    return roles
+    # the guide may be {App}-UsageGuide.md or {App}-Usage-Guide.md, its heading ## or ###, and its
+    # table the template's numbered shape or one read by its header names (AppManager TF-009):
+    # the same reader tf-verify-list.py uses
+    import importlib.util
+    spec = importlib.util.spec_from_file_location("tf_verify_list", os.path.join(os.path.dirname(os.path.abspath(__file__)), "tf-verify-list.py"))
+    vl = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(vl)
+    return [(u["user"], u["role"]) for u in vl.test_users(vl.usage_guide(app))]
 
 
 def screens_from_uidesign(app, phase):
@@ -88,9 +103,9 @@ def screens_from_uidesign(app, phase):
 
 def routes_in_code():
     found = []
-    for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".jsx", ".vue")):
-        if "/" not in f:
-            continue   # a top-level file is never a page
+    for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".jsx", ".vue"), skip_samples=True):
+        if "/" not in f or re.search(r"\.(spec|test)\.\w+$", f):
+            continue   # a top-level file is never a page; a test's `path:` is a screenshot, not a route (TfLens TF-050)
         txt = read(f)
         for ext_re, pat, what in ROUTE_PATTERNS:
             if re.search(ext_re, f, re.I):
@@ -136,12 +151,16 @@ 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"
     if kind.startswith("lib"):
-        razors = [f for f in walk("src", (".razor",), skip_samples=True)] if os.path.isdir("src") else []
+        razors = list(code_files((".razor",)))
         sub = "ui-library" if razors else "service-library"
     print(f"# tf-devguide-list — {app} — kind {sub} — phase {phase}")
     print()
@@ -184,9 +203,9 @@ def main(argv):
             for k in sorted(endpoints):
                 print(f"- {k} — {', '.join(sorted(set(endpoints[k]))[:2])}")
     elif sub == "ui-library":
-        comps = [f for f in walk("src", (".razor",), skip_samples=True)]
+        comps = list(code_files((".razor",)))
         if not comps:
-            print("NOTHING: no component under src/. Build first.")
+            print("NOTHING: no component under src/ or source/. Build first.")
             return 0
         samples = sample_files((".razor", ".cshtml", ".html"))
         stxt = {f: read(f) for f in samples}
@@ -196,9 +215,9 @@ def main(argv):
             shown = [s for s, t in stxt.items() if re.search(rf"<{re.escape(name)}\b", t)]
             print(f"- {os.path.dirname(f).split('/')[-1]} / {name} — {f} — " + (f"shown in {shown[0]}" + (f" (+{len(shown)-1})" if len(shown) > 1 else "") if shown else "NO SAMPLE shows it: a sample gap to log"))
     else:
-        files = [f for f in walk("src", (".cs", ".ts", ".py", ".go", ".java"), skip_samples=True)]
+        files = list(code_files((".cs", ".ts", ".py", ".go", ".java")))
         if not files:
-            print("NOTHING: no source under src/. Build first.")
+            print("NOTHING: no source under src/ or source/. Build first.")
             return 0
         items = []
         for f in files:
@@ -222,6 +241,16 @@ def main(argv):
         print()
         if ver is None:
             print(f"## --update: no existing guide at {gp} (or no \"Verified on\"); everything is new")
+            # a guide kept under another name or folder (Lekhak TF-014: docs/devguides/, one file per
+            # role) is named, so it is read and carried over, never silently rewritten from scratch
+            import glob
+            base = os.path.basename(gp)[:-len(".md")]
+            others = sorted(f for f in glob.glob(os.path.join("docs", "**", base + "*.md"), recursive=True)
+                            if os.path.normpath(f) != os.path.normpath(gp))
+            if others:
+                print(f"- {len(others)} guide file(s) under another name: " + ", ".join(f.replace(os.sep, "/") for f in others[:8])
+                      + (" …" if len(others) > 8 else ""))
+                print(f"  read them and carry every entry that still matches the code into {gp}; do not start from nothing")
         else:
             print(f"## --update: existing guide {gp}, Verified on {ver}, {len(entries)} entries")
             try:
@@ -230,8 +259,8 @@ def main(argv):
             except Exception:
                 cutoff = None
             if cutoff:
-                changed = [f for f in walk(".", (".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".py"), skip_samples=False)
-                           if f.startswith(("src/",)) and os.path.getmtime(f) > cutoff]
+                changed = [f for f in code_files((".razor", ".cshtml", ".cs", ".ts", ".tsx", ".js", ".py"), skip_samples=False)
+                           if os.path.getmtime(f) > cutoff]
                 print(f"- {len(changed)} source file(s) changed since then; remap the entries they serve, keep the rest verbatim")
                 for f in changed[:30]:
                     print(f"  - {f}")