@techierathore/techieflow 1.0.3 → 1.0.4

package/.tfcore/utils/tf-verify-screens.sh

@@ -4,18 +4,27 @@
 #   bash .tfcore/utils/tf-verify-screens.sh --list tests/.artifacts/verify/list.json --base http://localhost:5099 \
 #        [--login-path /login --user ravi --password '…'] [--cookie 'k=v'] [--storage-state file]
 #   bash .tfcore/utils/tf-verify-screens.sh --screen home=/ --screen posts=/posts --base URL   # a smoke: changed screens only
-#   bash .tfcore/utils/tf-verify-screens.sh --list … --cdp http://172.18.144.1:9223               # a Blazor Hybrid Windows head
+#   bash .tfcore/utils/tf-verify-screens.sh --list … --cdp http://172.18.144.1:9223               # an embedded-browser desktop head
+#   … --error-selector '.my-crash-banner'   # the banner THIS stack shows when its client side falls over
+#                                           # (repeatable; defaults cover one framework's id and [data-error-ui])
 #
 # For every screen, at 1280 and 390 px: every control the mockup anchors is present and shows
 # something, no header-only table, no blank page, no Blazor or console error (render); nothing
 # overlaps, nothing has zero size or sits off-screen, no sideways scroll, a stylesheet is loaded
-# (visual). Saves a screenshot per screen and width under tests/.artifacts/verify/screens/ and
+# (visual). Overlap and off-screen are measured on the rectangle an element paints in, clipped by
+# every scrolling ancestor, and the page is read only after its first render (--render-wait,
+# default 5000 ms). Saves a screenshot per screen and width under tests/.artifacts/verify/screens/ and
 # writes tests/.artifacts/verify/screens.json; that JSON is the evidence a smoke names before a
 # row is written Implemented, and what the verdict script reads. It decides no row's status.
 # Exit 0 every screen OK · 5 a screen failed · 2 the app was unreachable · 4 Playwright missing.
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-case "${1:-}" in -h|--help|"") sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:+0}${1:-3}" ;; esac
+# `--help` is a request and exits 0; no argument at all is a mistake and exits 3. (The one-line
+# form this replaces computed "0--help" as its exit code and printed a bash error under the help.)
+case "${1:-}" in
+  -h|--help) sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  "")        sed -n '2,19p' "$0" | sed 's/^# \{0,1\}//'; exit 3 ;;
+esac
 command -v node >/dev/null 2>&1 || { echo "tf-verify-screens: node is required (bash .tfcore/utils/tf-verify-env.sh)" >&2; exit 4; }
 node -e "import('playwright').then(()=>process.exit(0)).catch(()=>process.exit(1))" 2>/dev/null || {
   echo "tf-verify-screens: the 'playwright' package is not resolvable from this folder; run bash .tfcore/utils/tf-verify-env.sh" >&2; exit 4; }

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

@@ -6,9 +6,11 @@
 #
 # Browser tests: `npx playwright test` over tests/verify/ (the JSON reporter). Unit tests:
 # `tf-build.sh test` with normal console verbosity. A test belongs to a row when its name contains
-# the row's id (REQ-UI-004 …). A row is PASS when every test carrying its id passed, FAIL when one
-# failed (the reason and the screenshot, when the reporter kept one, are recorded), and absent
-# when no test carries its id. Writes tests/.artifacts/verify/tests.json for the verdict script.
+# the row's id (REQ-UI-004 …). A row is PASS when a test carrying its id passed and none failed,
+# FAIL when one failed (the reason and the screenshot, when the reporter kept one, are recorded),
+# NOT-TESTED when every test carrying its id was SKIPPED, and absent when no test carries its id.
+# A skipped clause is a third outcome, never a failure: `test.skip(!SEEDED, …)` says the state does
+# not exist in the data, which is not a defect (TF-022). Writes tests/.artifacts/verify/tests.json.
 # Exit 0 ran (whatever the results) · 2 nothing could run.
 set -uo pipefail
 HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -54,17 +56,38 @@ fi
 TF_PWJSON="$PWJSON" TF_UNITLOG="$UNITLOG" TF_UNITLINE="$UNITLINE" TF_OUT="$OUT" python3 - <<'PY'
 import json, os, re
 ID = re.compile(r"(REQ-(?:UI|FN|NFR|RAG)-\d{3})", re.I)
-reqs, browser, unit = {}, {"ran": False, "passed": 0, "failed": 0, "tests": 0}, {"ran": False, "line": os.environ.get("TF_UNITLINE", "")}
+reqs = {}
+browser = {"ran": False, "passed": 0, "failed": 0, "skipped": 0, "tests": 0}
+unit = {"ran": False, "line": os.environ.get("TF_UNITLINE", "")}
 
-def add(rid, ok, name, source, reason="", shot=""):
-    r = reqs.setdefault(rid.upper(), {"result": "PASS", "source": source, "tests": [], "reason": "", "screenshot": ""})
-    r["tests"].append(name)
-    if not ok:
-        r["result"] = "FAIL"
+def add(rid, outcome, name, source, reason="", shot=""):
+    """Record one test against a row. `outcome` is "pass", "fail" or "skip".
+
+    A SKIPPED clause is the third outcome and neither of the other two. A conditional
+    `test.skip(!SEEDED, "needs the seeded dataset")` says the state does not exist in the
+    data yet: that is not a pass, and it is not a defect either. Counting it as a failure
+    put FAIL on rows no code could clear and sent build-phase back into FIX mode against
+    them (TF-022, TfLens 2026-09-09). A row whose clauses were ALL skipped ends
+    NOT-TESTED, which the verdict script reads as not measured — never Verified, never a
+    defect. tests/regression/run.sh tf_022."""
+    r = reqs.setdefault(rid.upper(), {"result": "NOT-TESTED", "source": source, "tests": [],
+                                      "skipped": [], "passed": 0, "failed": 0,
+                                      "reason": "", "screenshot": ""})
+    if outcome == "skip":
+        r["skipped"].append(name)
         if not r["reason"]:
+            r["reason"] = (reason or "the test was skipped")[:200]
+        return
+    r["tests"].append(name)
+    if outcome == "pass":
+        r["passed"] += 1
+    else:
+        if r["result"] != "FAIL":          # the first real failure owns the reason
             r["reason"] = reason[:200]
+        r["failed"] += 1
         if shot and not r["screenshot"]:
             r["screenshot"] = shot
+    r["result"] = "FAIL" if r["failed"] else "PASS"
 
 pw = os.environ.get("TF_PWJSON", "")
 if pw and os.path.isfile(pw):
@@ -78,11 +101,21 @@ if pw and os.path.isfile(pw):
                     res = t.get("results", [])
                     last = res[-1] if res else {}
                     status = last.get("status", t.get("status", "unexpected"))
-                    ok = status in ("passed", "expected") or t.get("status") == "expected"
+                    # skipped is read FIRST: it is neither a pass nor a failure (TF-022)
+                    if status == "skipped" or t.get("status") == "skipped":
+                        outcome = "skip"
+                    elif status in ("passed", "expected") or t.get("status") == "expected":
+                        outcome = "pass"
+                    else:
+                        outcome = "fail"
                     browser["tests"] += 1
-                    browser["passed" if ok else "failed"] += 1
+                    browser[{"pass": "passed", "fail": "failed", "skip": "skipped"}[outcome]] += 1
                     err = ""
-                    if last.get("error"):
+                    if outcome == "skip":
+                        why = [a.get("description") for a in (t.get("annotations") or [])
+                               if a.get("type") == "skip" and a.get("description")]
+                        err = "skipped" + (": " + str(why[0]) if why else "")
+                    elif last.get("error"):
                         err = re.sub(r"\x1b\[[0-9;]*m", "", str(last["error"].get("message", "")).split("\n")[0])
                     shot = ""
                     for a in last.get("attachments", []):
@@ -91,7 +124,7 @@ if pw and os.path.isfile(pw):
                             shot = shot[shot.find("tests/"):] if "tests/" in shot else shot
                             break
                     for rid in set(ID.findall(title)):
-                        add(rid, ok, title.strip(), "browser", err, shot)
+                        add(rid, outcome, title.strip(), "browser", err, shot)
             for s in suite.get("suites", []):
                 walk(s, path + [s.get("title", "")] if s.get("title") and not s["title"].endswith(".ts") and not s["title"].endswith(".js") and not s["title"].endswith(".mjs") else path)
         for s in data.get("suites", []):
@@ -104,20 +137,30 @@ if ul and os.path.isfile(ul):
     unit["ran"] = True
     for line in open(ul, encoding="utf-8", errors="replace"):
         m = re.match(r"\s*(Passed|Failed|Skipped)\s+(\S.*?)\s*(\[[^\]]*\])?\s*$", line)
-        if not m or m.group(1) == "Skipped":
+        if not m:
             continue
+        # a skipped unit test is recorded as skipped, not dropped: the row then reads
+        # NOT-TESTED with the evidence, rather than looking as if no test exists (TF-022)
+        outcome = {"Passed": "pass", "Failed": "fail", "Skipped": "skip"}[m.group(1)]
         name = m.group(2).strip()
         for rid in set(ID.findall(name)):
-            add(rid, m.group(1) == "Passed", name, "unit", "unit test failed: " + name[:120])
+            add(rid, outcome, name, "unit",
+                ("unit test failed: " if outcome == "fail" else "unit test skipped: ") + name[:120])
 unit["passed"] = sum(1 for r in reqs.values() if r["source"] == "unit" and r["result"] == "PASS")
 unit["failed"] = sum(1 for r in reqs.values() if r["source"] == "unit" and r["result"] == "FAIL")
+unit["not_tested"] = sum(1 for r in reqs.values() if r["source"] == "unit" and r["result"] == "NOT-TESTED")
 
 json.dump({"reqs": reqs, "browser": browser, "unit": unit}, open(os.environ["TF_OUT"], "w"), indent=1)
-p = sum(1 for r in reqs.values() if r["result"] == "PASS"); f = len(reqs) - p
-print(f"rows with a test: {len(reqs)} — {p} PASS, {f} FAIL" + (f" (browser {browser['passed']}/{browser['tests']} tests passed)" if browser["ran"] else ""))
+p = sum(1 for r in reqs.values() if r["result"] == "PASS")
+f = sum(1 for r in reqs.values() if r["result"] == "FAIL")
+ns = sum(1 for r in reqs.values() if r["result"] == "NOT-TESTED")
+print(f"rows with a test: {len(reqs)} — {p} PASS, {f} FAIL, {ns} NOT-TESTED (every clause skipped)"
+      + (f" (browser {browser['passed']}/{browser['tests']} tests passed, {browser['skipped']} skipped)" if browser["ran"] else ""))
 for rid, r in sorted(reqs.items()):
     if r["result"] == "FAIL":
         print(f"  FAIL {rid} — {r['reason']}" + (f" — {r['screenshot']}" if r["screenshot"] else ""))
+    elif r["result"] == "NOT-TESTED":
+        print(f"  NOT-TESTED {rid} — {len(r['skipped'])} test(s) skipped, none ran — {r['reason']}")
 print(f"JSON: {os.environ['TF_OUT']}")
 PY
 [[ $ran_any -eq 1 ]] && exit 0 || exit 2

package/.tfcore/utils/tf-verify-verdict.py

@@ -19,7 +19,8 @@ For each row, the seven checks in order, and the first that fails is the verdict
   (standards has no script yet and is never listed as run)
 
 Verdicts: PASS · FAIL (acceptance) · BUILD-FAIL · RENDER-FAIL · ASSET-FAIL · VISUAL-FAIL · MOCKUP-FAIL ·
-PERF-FAIL · NOT-TESTED (no test carried the id; the screen checks passed or did not run) ·
+PERF-FAIL · NOT-TESTED (no test carried the id, or every test carrying it was skipped; the screen
+checks passed or did not run) ·
 NOT-OBSERVABLE (an NFR row with no budget and no unit test) · NOT-DRIVEN (its screen was never driven:
 the head could not be booted, or has no driver). A row is Verified only on PASS. NOT-* rows keep their
 status and get a Remark saying so; nothing is ever written as a static-only pass.
@@ -114,6 +115,13 @@ def main(argv):
         scr = scr_by_name.get(r.get("screen") or "")
         driven = bool(scr) and scr.get("render") != "UNREACHABLE"
         t = tests.get(rid)
+        # A row whose every clause was SKIPPED is NOT-TESTED: the acceptance gate did not run on
+        # it. It is neither a pass nor a defect, so it grades exactly like a row with no test at
+        # all — never Verified, no gate record (TF-022). `t` is kept for the note.
+        skipped_only = bool(t) and t.get("result") == "NOT-TESTED"
+        if skipped_only:
+            notes.append(f"acceptance not measured ({len(t.get('skipped') or [])} test(s) skipped, none ran)")
+            t = None
         # every check on its own: (name, ran, failed, verdict, class, detail, evidence); the first failure wins
         checks = []
 
@@ -188,7 +196,8 @@ def main(argv):
                           else f"screen {r['screen']} was not driven in this run")
             elif not t:
                 verdict = "NOT-TESTED"
-                detail = f"no test named {rid} ran" + (f"; screen {r['screen']} renders and looks right" if driven else "")
+                detail = (f"every test named {rid} was skipped" if skipped_only else f"no test named {rid} ran") \
+                    + (f"; screen {r['screen']} renders and looks right" if driven else "")
             elif r.get("screen") and not driven and not booted:
                 verdict = "NOT-DRIVEN"
                 detail = f"test passed but {boot.get('head', 'the app')} was not driven: {boot.get('reason')}"

package/README.md

@@ -126,10 +126,11 @@ Replace `{App}` with your application name. Claude Code takes the long persona p
 
 ## 5. What it produces
 
-Every per-project document is named after the application: `docs/<App>-BRD.md`, `-Architecture.md`, `-Checklist.md`, `-UIDesign.md`, `-Coding-Standards.md`, `-UsageGuide.md`, `-DevGuide.md`, `-ProductGuide.md`, `-Deployment-Checklist.md`, plus `PROJECT-STATUS.md` and `CLAUDE.md` at the root, mockups under `docs/mockups/`, and screenshots under `docs/screenshots/<App>/`.
+Every per-project document is named after the application: `docs/<App>-Brief.md`, `-BRD.md`, `-Architecture.md`, `-Checklist.md`, `-UIDesign.md`, `-Coding-Standards.md`, `-UsageGuide.md`, `-DevGuide.md`, `-ProductGuide.md`, `-Deployment-Checklist.md`, `-Misses.md`, `-Decision-Request.md`, `-<Upstream>-Feedback.md`, plus `PROJECT-STATUS.md` and `CLAUDE.md` at the root, mockups under `docs/mockups/`, and screenshots under `docs/screenshots/<App>/`.
 
 | Document | Who reads it |
 |---|---|
+| Brief | You, before anything is built. One page: what it is, who for, must do, out of scope. Day-1 reads it. |
 | BRD, Architecture, UIDesign and the mockups | You, at the day-1 review. This is the cheap moment to redirect. |
 | Checklist | Agents only. One table, one row per requirement, the single source of truth. Never rendered to HTML. |
 | Coding Standards | Every implementing agent, and the verifier's standards check. |
@@ -138,9 +139,11 @@ Every per-project document is named after the application: `docs/<App>-BRD.md`,
 | DevGuide | A developer tracing a bug: every screen to its code, with the line to break on. |
 | ProductGuide | The end user. |
 | Deployment Checklist | Whoever puts it on the host, after UAT. |
-| Library feedback, one file per library | That library's team. |
+| Misses | You and the agents. Rebuilt from the record whenever something is logged as missed. |
+| Decision Request | You. Every choice an agent cannot make: options, what each costs, a recommendation, and a block to paste back. It is never read back by an agent. |
+| Feedback, one file per upstream | That team — each library, and the framework itself. Every entry says in its first word whether it blocks your work. Reporting is never refused; a non-blocking entry never stops a run. |
 
-Each document has a required shape and a size budget for the application's size (Small, Medium or Large), enforced by `bash .tfcore/utils/tf-doc-check.sh --app {App}`. Add `--warn` to get a report instead of a refusal, which is what you want on a project that predates the schemas. Human documents render to HTML by script; the checklist never does.
+Each document has a required shape and a size budget for the application's size (Small, Medium or Large), enforced by `bash .tfcore/utils/tf-doc-check.sh --app {App}`. Add `--warn` to get a report instead of a refusal, which is what you want on a project that predates the schemas. Human documents render to HTML by script; an agent document never does — the checklist and the miss list are refused by name.
 
 ---
 
@@ -152,7 +155,7 @@ The shipped configuration allows every file operation and all of Bash with no pr
 
 Five append-only streams per project under `docs/metrics/`, read with `*metrics {App}`: command runs, verification verdicts, misses, chat sessions, and your own commits. They answer five questions — the first-pass rate, which check caught the failure, the escape rate, what misses cost to fix, and the effort per phase. Definitions, real figures and the sentence to say about each are in [`docs/TechieFlow-Telemetry-Explained.md`](docs/TechieFlow-Telemetry-Explained.md); the field contract is `.tfcore/telemetry/SCHEMA.md`.
 
-Standing rules: provenance never merges, only identifiers and counts are recorded, telemetry has no veto, and an agent never writes what it cannot know. Dollar figures exist only for OpenCode runs; Claude Code reports tokens and no rate card is ever applied.
+Standing rules: provenance never merges, only identifiers and counts are recorded, telemetry has no veto, and an agent never writes what it cannot know. **Tokens are what is recorded; money is worked out when the report runs.** A record stores what the provider itself charged — only a metered provider charges per token — and never a computed price. The report separately prints a **list price**, the published rate applied to the tokens actually measured, which is the one figure that compares a Claude phase with an OpenCode one. A price is never called a bill, and a monthly plan's allowance is counted apart from both.
 
 ## 8. Running phases on cheaper models
 
@@ -164,7 +167,14 @@ bash .tfcore/utils/tf-routing.sh on
 bash .tfcore/utils/tf-routing.sh set-tier verify-phase economy
 ```
 
-Drift is observed, never enforced: a run on the wrong model is recorded as such and nothing blocks. Full guide: [`docs/TechieFlow-Routing-Guide.md`](docs/TechieFlow-Routing-Guide.md).
+Each tier also names the models to try **instead**, while its own is out of quota. When a usage limit is hit, the supervisor parks that model until its stated reset, moves to the next model in the tier's chain, re-binds so the sub-agents move with it, and carries on; only when every model in the chain is limited does it wait. `--no-fallback` restores the old wait-for-reset behaviour.
+
+```bash
+bash .tfcore/utils/tf-model-pick.sh status               # what each tier would run right now
+bash .tfcore/utils/tf-model-pick.sh chain standard opencode   # the order it falls back in
+```
+
+Drift is observed, never enforced: a run on the wrong model is recorded as such and nothing blocks. The step-by-step setup, and what a cost figure means on each kind of plan, are in the full guide: [`docs/TechieFlow-Routing-Guide.md`](docs/TechieFlow-Routing-Guide.md).
 
 ---
 

package/opencode.jsonc

@@ -897,6 +897,30 @@
       "template": "{file:./.tfcore/tasks/create-doc.md}",
       "description": "Create a document from a YAML-driven TechieFlow template (interactive, section by section)."
     },
+    "techieflow:tasks:verify": {
+      "template": "{file:./.tfcore/tasks/verify-phase.md}",
+      "description": "The verifier's *verify. Boot the app, run the seven checks on every row in scope, write the verdicts."
+    },
+    "techieflow:tasks:metrics": {
+      "template": "{file:./.tfcore/tasks/metrics-report.md}",
+      "description": "The flow-master's *metrics. Read the telemetry streams and write the metrics report."
+    },
+    "techieflow:tasks:brainstorm": {
+      "template": "{file:./.tfcore/tasks/facilitate-brainstorming-session.md}",
+      "description": "The analyst's *brainstorm. Run a structured brainstorming session."
+    },
+    "techieflow:tasks:research-prompt": {
+      "template": "{file:./.tfcore/tasks/create-deep-research-prompt.md}",
+      "description": "The analyst's *research-prompt. Generate a well-structured research prompt."
+    },
+    "techieflow:tasks:research": {
+      "template": "{file:./.tfcore/tasks/create-deep-research-prompt.md}",
+      "description": "The architect's *research. Generate a well-structured research prompt."
+    },
+    "techieflow:tasks:create-project-brief": {
+      "template": "{file:./.tfcore/tasks/create-project-brief.md}",
+      "description": "Write the one-page project brief that day-1 takes as input: product, users, must-do, out of scope. The analyst's *create-project-brief."
+    },
     "techieflow:tasks:create-deep-research-prompt": {
       "template": "{file:./.tfcore/tasks/create-deep-research-prompt.md}",
       "description": "Generate well-structured research prompts."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techierathore/techieflow",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "TechieFlow: a spec-driven development framework for AI coding agents, for Claude Code and OpenCode. One command installs it into any project.",
   "license": "Apache-2.0",
   "repository": {

package/scripts/install.mjs

@@ -369,6 +369,10 @@ const canonicalSettings = String.raw`{
           {
             "type": "command",
             "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-build.sh\""
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.tfcore/hooks/guard-verify-deps.sh\""
           }
         ]
       },