@techierathore/techieflow 1.0.3 → 1.1.0

package/.opencode/plugin/techieflow.js

@@ -18,10 +18,10 @@
 // auto-approves the permission map's rm/rmdir/sudo asks and TF_YOLO=1 is
 // exported to tool shells so block-git.sh allows read-only git. Writes to
 // git never reach this hook — they are `deny` in the map.
-//   bash  {command}                        -> Bash  {command}            -> block-git.sh + guard-artifacts.sh
+//   bash  {command}                        -> Bash  {command}            -> block-git.sh + guard-artifacts.sh + guard-verify-deps.sh
 //   edit  {filePath,oldString,newString}   -> Edit  {file_path,old_string,new_string}
 //   write {filePath,content}               -> Write {file_path,content}  -> guard-status.sh + guard-verify.sh
-//   session.idle (root session)            -> Stop  {stop_hook_active}   -> guard-status-html.sh
+//   session.idle (root session)            -> Stop  {stop_hook_active, last_assistant_message, turn_started} -> guard-status-html.sh
 //   session.created (first root session)   -> SessionStart              -> sweep-artifacts.sh
 // OpenCode has no blocking Stop hook, so the stale-PROJECT-STATUS.html guard
 // (_status-update-gate.md step 4) is bridged as a ONE-SHOT nudge: when the root
@@ -42,14 +42,25 @@
 // idles once). Records share session_id; consumers take the record with the
 // highest output_tokens (or latest ts) per session_id. SCHEMA.md §4 notes this.
 
+//
+// Two OpenCode plugin APIs, one file (2026-09-27). OpenCode 1.x (the design's 1.18.18; 1.18.32 is
+// the last 1.x) reads the default export's `server`; OpenCode 2 (checked on 2.0.18, 2026-09-28)
+// accepts only a default export with `id` and `setup`, and refused this file with "Plugin must export
+// a default definition with an id and an effect or setup function". The default export carries all
+// three; `setup` translates 2.x's hook and event API into the 1.x hooks below, so the guards, the
+// shell env and telemetry are the same code in both. What 2.x does not offer: `permission.ask` (YOLO
+// auto-approval; OpenCode 2's own `--auto` flag is the switch there) and the session's messages, so
+// the Stop nudge's owner-text check (guard-status-html.sh check 5) is skipped there; checks 1-4 run.
+
 import fs from "node:fs"
 import path from "node:path"
 import os from "node:os"
 import { spawnSync } from "node:child_process"
+import { fileURLToPath } from "node:url"
 
 const GUARD_TIMEOUT_MS = 10000
 
-export const TechieFlowPlugin = async ({ directory, client }) => {
+const TechieFlowPlugin = async ({ directory, client }) => {
   const root = directory
   const hooksDir = path.join(root, ".tfcore", "hooks")
   const tfEmit = path.join(root, ".tfcore", "utils", "tf-emit.sh")
@@ -110,8 +121,29 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
   const htmlNudged = Object.create(null) // rootID -> true once the stale-HTML nudge was sent
   let pointerWritten = false
 
+  // What Claude Code hands its Stop hook and OpenCode does not: the closing message, and when
+  // the turn began (the last prompt the owner typed). The guard checks the message the owner
+  // reads at the end of a command (tf-owner-text.sh). Empty on any failure: the check then skips.
+  async function closingTurn(rootID) {
+    try {
+      if (typeof client.session.messages !== "function") return {}
+      const res = await client.session.messages({ path: { id: rootID } })
+      const list = Array.isArray(res) ? res : (res && res.data) || []
+      const text = (m) => (m.parts || []).filter((x) => x.type === "text" && !x.synthetic).map((x) => x.text).join("\n")
+      let message = "", turn = null
+      for (const m of list) {
+        const info = m.info || {}
+        if (info.role === "user" && text(m).trim()) turn = (info.time || {}).created || turn
+        if (info.role === "assistant" && text(m).trim()) message = text(m)
+      }
+      return turn ? { last_assistant_message: message, turn_started: turn } : {}
+    } catch {
+      return {}
+    }
+  }
+
   // Stop-hook analogue for guard-status-html.sh (see header). Never throws.
-  function nudgeStaleStatusHtml(rootID) {
+  async function nudgeStaleStatusHtml(rootID) {
     try {
       if (!client || !client.session || typeof client.session.prompt !== "function") return
       const msg = guardBlocks("guard-status-html.sh", {
@@ -119,6 +151,7 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
         cwd: root,
         session_id: rootID,
         stop_hook_active: htmlNudged[rootID] === true,
+        ...(htmlNudged[rootID] === true ? {} : await closingTurn(rootID)),
       })
       if (!msg) return
       htmlNudged[rootID] = true
@@ -232,14 +265,16 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
       const args = output.args || {}
       let payload = null
       let scripts = []
-      if (input.tool === "bash") {
+      if (input.tool === "bash" || input.tool === "shell") {
+        // 1.x calls it bash; 2.x calls it shell (same `command` argument)
         payload = { tool_name: "Bash", tool_input: { command: String(args.command || ""), run_in_background: !!(args.background || args.run_in_background) } }
-        scripts = ["block-git.sh", "guard-artifacts.sh", "guard-status.sh", "guard-metrics.sh", "guard-db.sh", "guard-build.sh"]
+        scripts = ["block-git.sh", "guard-artifacts.sh", "guard-status.sh", "guard-metrics.sh", "guard-db.sh", "guard-build.sh", "guard-verify-deps.sh"]
       } else if (input.tool === "edit") {
+        // 1.x names the file filePath, 2.x names it path
         payload = {
           tool_name: "Edit",
           tool_input: {
-            file_path: String(args.filePath || ""),
+            file_path: String(args.filePath || args.path || ""),
             old_string: String(args.oldString || ""),
             new_string: String(args.newString || ""),
           },
@@ -248,7 +283,7 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
       } else if (input.tool === "write") {
         payload = {
           tool_name: "Write",
-          tool_input: { file_path: String(args.filePath || ""), content: String(args.content || "") },
+          tool_input: { file_path: String(args.filePath || args.path || ""), content: String(args.content || "") },
         }
         scripts = ["guard-status.sh", "guard-verify.sh", "guard-metrics.sh"]
       } else if (input.tool === "apply_patch") {
@@ -367,7 +402,7 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
           if (!sid) return
           if (rootOf(sid) === sid) {
             emitSession(sid)
-            nudgeStaleStatusHtml(sid)
+            await nudgeStaleStatusHtml(sid)
           }
           return
         }
@@ -375,3 +410,140 @@ export const TechieFlowPlugin = async ({ directory, client }) => {
     },
   }
 }
+
+// ---- OpenCode 2.x: translate its API into the 1.x hooks above ----
+// The 2.x context names no project directory, and its background service does not run in the
+// project, so the root is where this file sits: <root>/.opencode/plugin/techieflow.js.
+function projectRoot() {
+  try {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..")
+  } catch {
+    return process.cwd()
+  }
+}
+
+function eventTime(value) {
+  const n = typeof value === "number" ? value : Date.parse(String(value || ""))
+  return Number.isFinite(n) ? n : Date.now()
+}
+
+async function setupV2(context) {
+  const root = projectRoot()
+  // What the Stop nudge needs from a client: prompt a session. 2.x has no message listing, so
+  // closingTurn() finds no messages and the owner-text check is skipped (see the header).
+  const client = {
+    session: {
+      prompt: ({ path: p, body }) =>
+        context.session.prompt({
+          sessionID: p.id,
+          text: ((body && body.parts) || []).map((x) => x.text || "").join("\n"),
+        }),
+    },
+  }
+  const hooks = await TechieFlowPlugin({ directory: root, client })
+  const registrations = []
+
+  // Guards. A throw here stops the call, as in 1.x.
+  registrations.push(
+    await context.tool.hook("execute.before", async (event) => {
+      await hooks["tool.execute.before"]({ tool: event.tool, sessionID: event.sessionID, callID: event.id }, { args: event.input || {} })
+    }),
+  )
+
+  // TF_HARNESS, TF_PROJECT_DIR, TF_YOLO for the agent's shell commands.
+  registrations.push(
+    await context.shell.hook("create.before", async (event) => {
+      if (!event || !event.env) return
+      await hooks["shell.env"]({}, { env: event.env })
+    }),
+  )
+
+  // Telemetry and the Stop nudge: 2.x events rewritten as the 1.x events the handler reads.
+  // A step carries its own tokens and cost; each step is recorded once, under its own key.
+  // The session is created before this subscription starts, so no session.created arrives for
+  // it: a session is learned the first time an event of this project names it, and its parent
+  // is read with session.get (a root session has no parentID). A turn ends with
+  // session.execution.*, which carries no location, so only sessions learned here count.
+  const models = Object.create(null) // assistantMessageID -> {model, t0}
+  const known = Object.create(null) // sessionID -> true once learned
+  let stream = null
+  let stopped = false
+  const learn = async (sessionID) => {
+    if (!sessionID || known[sessionID]) return
+    known[sessionID] = true
+    let parentID = null
+    try {
+      const info = await context.session.get({ sessionID })
+      parentID = (info && info.parentID) || null
+    } catch {}
+    await hooks.event({ event: { type: "session.created", properties: { info: { id: sessionID, parentID } } } })
+  }
+  const translate = (ev) => {
+    const d = ev.data || {}
+    if (ev.type === "session.step.started") {
+      models[d.assistantMessageID] = { model: d.model || {}, t0: eventTime(ev.created) }
+      return null
+    }
+    if (ev.type === "session.step.ended") {
+      const started = models[d.assistantMessageID] || { model: {}, t0: eventTime(ev.created) }
+      const t = d.tokens || {}
+      return {
+        type: "message.updated",
+        properties: {
+          info: {
+            role: "assistant",
+            id: String(d.assistantMessageID) + ":" + String(ev.id),
+            sessionID: d.sessionID,
+            providerID: started.model.providerID,
+            modelID: started.model.id,
+            cost: d.cost,
+            tokens: { input: t.input, output: t.output, cache: t.cache || {} },
+            time: { created: started.t0, completed: eventTime(ev.created) },
+          },
+        },
+      }
+    }
+    const idle =
+      /^session\.execution\.(succeeded|failed|interrupted)$/.test(ev.type) ||
+      (ev.type === "session.status" && d.status && d.status.type === "idle") ||
+      ev.type === "session.idle"
+    if (idle && known[d.sessionID]) return { type: "session.idle", properties: { sessionID: d.sessionID } }
+    return null
+  }
+  ;(async () => {
+    try {
+      stream = context.event.subscribe()
+      for await (const ev of stream) {
+        if (stopped) break
+        try {
+          if (!ev) continue
+          if (ev.location && ev.location.directory) {
+            if (path.resolve(ev.location.directory) !== root) continue
+            if (ev.data && ev.data.sessionID) await learn(ev.data.sessionID)
+          }
+          const event = translate(ev)
+          if (event) await hooks.event({ event })
+        } catch {} // telemetry never blocks anything
+      }
+    } catch {}
+  })()
+
+  return async () => {
+    stopped = true
+    try {
+      if (stream && typeof stream.return === "function") await stream.return()
+    } catch {}
+    for (const r of registrations) {
+      try {
+        await r.dispose()
+      } catch {}
+    }
+  }
+}
+
+// OpenCode 1.x reads `server`; OpenCode 2.x reads `setup`. Each ignores the other.
+export default {
+  id: "techieflow",
+  server: TechieFlowPlugin,
+  setup: setupV2,
+}

package/.tfcore/agents/analyst.md

@@ -41,6 +41,7 @@ persona:
   identity: Strategic analyst specializing in brainstorming, market research, competitive analysis, and project briefing
   focus: Research planning, ideation facilitation, strategic analysis, actionable insights
   core_principles:
+    - OWNER LANGUAGE - Everything the owner reads is plain, simple English: no coined terms, no framework shorthand, no word they would have to look up. A choice only the owner can make goes in `docs/{App}-Decision-Request.md` with a recommendation and a block to paste back, and ONE line in the terminal — never argued out in the conversation. Reporting an upstream defect is never refused; it goes in the feedback file, answers "Blocks: yes|no" first, and a non-blocking entry never stops the run. `.tfcore/tasks/_owner-language.md`.
     - Curiosity-Driven Inquiry - Ask probing "why" questions to uncover underlying truths
     - Objective & Evidence-Based Analysis - Ground findings in verifiable data and credible sources
     - Strategic Contextualization - Frame all work within broader strategic context
@@ -52,7 +53,7 @@ persona:
     - Maintaining a Broad Perspective - Stay aware of market trends and dynamics
     - Integrity of Information - Ensure accurate sourcing and representation
     - Numbered Options Protocol - Always use numbered lists for selections
-    - RUN IT YOURSELF - When a task you run boots or smokes an app (devguide OBSERVE at brownfield day-1, render sweeps), the Playwright/MAUI/Appium harness is already set up - run it yourself; never hand the boot to the owner (_smoke-test-policy.md banned excuses).
+    - RUN IT YOURSELF - When a task you run boots or smokes an app (devguide OBSERVE at brownfield day-1, render sweeps), the project's own test harness is already set up - run it yourself; never hand the boot to the owner (_smoke-test-policy.md banned excuses).
     - BRD Numbering Protocol - When authoring or extending a BRD, every business/functional requirement MUST receive a stable unique ID in the form 'BRD-{N}' (BRD-1, BRD-2, ...). IDs are APPEND-ONLY across revisions - never renumber existing IDs; new requirements take the next unused integer. Group requirements by phase under '## Phase {N}' headings so the verifier and UI agent can scope by phase.
     - Interactive BRD Elicitation - BRD authoring runs with elicit=true. NEVER assume a requirement. For each section/area, surface candidate requirements as a numbered list and have the user confirm / reject / refine each one before assigning it a BRD-N. Do not batch-write multiple requirements without per-item confirmation.
 # All commands require * prefix when used (e.g., *help)
@@ -60,14 +61,12 @@ commands:
   - help: Show numbered list of the following commands to allow selection
   - day1-brownfield {AppName}: Day-1 master task for an EXISTING project. Produces Architecture, BRD, Coding-Standards, .editorconfig, PROJECT-STATUS, CLAUDE.md + the screen-by-screen DevGuide (with per-screen screenshots) in one session; if an existing dev/phase plan is found, also migrates it into the one Checklist (inline split, statuses preserved). Runs task day1-brownfield.md.
   - day1-greenfield {AppName}: Day-1 master task for a NEW project. Produces brief + BRD + target Architecture + UI mockups + Coding-Standards + .editorconfig + PROJECT-STATUS + CLAUDE.md + UsageGuide. Runs task day1-greenfield.md.
-  - mockups {AppName} [--update]: Produce the greenfield UI design — docs/{AppName}-UIDesign.md (per-screen component map) + rendered docs/mockups/*.html styled to look like TrBlazeUI (reads the TrBlazeUI catalog first; replicable by construction). The visual contract the build matches + the verifier diffs against. Runs task mockups.md.
+  - mockups {AppName} [--update]: Produce the greenfield UI design — docs/{AppName}-UIDesign.md (per-screen component map) + rendered docs/mockups/*.html styled to look like the UI library the Architecture names (read that library's component catalog first when it ships one; replicable by construction). The visual contract the build matches + the verifier diffs against. Runs task mockups.md.
   - split-brd {AppName}: Split docs/{AppName}-BRD.md into the one docs/{AppName}-Checklist.md (REQ-UI/FN/RAG/NFR-* in a single Requirements Status table); seeds phase tags + Done(pre-existing) statuses from any existing dev/phase plan. Runs task split-brd.md.
   - brainstorm {topic}: Facilitate structured brainstorming session (run task facilitate-brainstorming-session.md with template brainstorming-output-tmpl.yaml)
   - amend-docs {AppName} {change}: Fold an evolving concept / changed requirements into the EXISTING day-1 docs IN PLACE — surgically amends BRD + Architecture (append-only BRD IDs, unchanged sections preserved), ripples to PROJECT-STATUS / BRD §4 / the checklist (and points UI changes at *mockups --update), re-renders HTML. The incremental alternative to re-running *day1-* (which archives + regenerates). Runs task amend-docs.md.
-  - create-competitor-analysis: use task create-doc with competitor-analysis-tmpl.yaml
-  - create-project-brief: use task create-doc with project-brief-tmpl.yaml
+  - create-project-brief {AppName}: Write docs/{AppName}-Brief.md, the one page day-1 reads — what it is, who for, must do, out of scope, open questions. Runs task create-project-brief.md.
   - doc-out: Output full document in progress to current destination file
-  - perform-market-research: use task create-doc with market-research-tmpl.yaml
   - research-prompt {topic}: execute task create-deep-research-prompt.md
   - yolo: Toggle YOLO / goal mode — run `bash .tfcore/utils/tf-yolo.sh on|off`, then operate per .tfcore/tasks/_yolo-mode.md: no confirmations or elicitation pauses (take the sensible default, record it), deletes + read-only git allowed (git writes never), run the command to completion. Also implied by the word YOLO in any command, an active /goal, or a tf-goal.sh run.
   - exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
@@ -79,6 +78,7 @@ dependencies:
     - amend-docs.md
     - create-deep-research-prompt.md
     - create-doc.md
+    - create-project-brief.md
     - day1-brownfield.md
     - day1-greenfield.md
     - facilitate-brainstorming-session.md
@@ -86,7 +86,4 @@ dependencies:
     - split-brd.md
   templates:
     - brainstorming-output-tmpl.yaml
-    - competitor-analysis-tmpl.yaml
-    - market-research-tmpl.yaml
-    - project-brief-tmpl.yaml
 ```

package/.tfcore/agents/architect.md

@@ -41,6 +41,7 @@ persona:
   identity: Master of holistic application design who bridges frontend, backend, infrastructure, and everything in between
   focus: Complete systems architecture, cross-stack optimization, pragmatic technology selection
   core_principles:
+    - OWNER LANGUAGE - Everything the owner reads is plain, simple English: no coined terms, no framework shorthand, no word they would have to look up. A choice only the owner can make goes in `docs/{App}-Decision-Request.md` with a recommendation and a block to paste back, and ONE line in the terminal — never argued out in the conversation. Reporting an upstream defect is never refused; it goes in the feedback file, answers "Blocks: yes|no" first, and a non-blocking entry never stops the run. `.tfcore/tasks/_owner-language.md`.
     - Holistic System Thinking - View every component as part of a larger system
     - User Experience Drives Architecture - Start with user journeys and work backward
     - Pragmatic Technology Selection - Choose boring technology where possible, exciting where necessary
@@ -54,10 +55,6 @@ persona:
 # All commands require * prefix when used (e.g., *help)
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - create-backend-architecture: use create-doc with architecture-tmpl.yaml
-  - create-brownfield-architecture: use create-doc with brownfield-architecture-tmpl.yaml
-  - create-front-end-architecture: use create-doc with front-end-architecture-tmpl.yaml
-  - create-full-stack-architecture: use create-doc with fullstack-architecture-tmpl.yaml
   - doc-out: Output full document to current destination file
   - research {topic}: execute task create-deep-research-prompt
   - yolo: Toggle YOLO / goal mode — run `bash .tfcore/utils/tf-yolo.sh on|off`, then operate per .tfcore/tasks/_yolo-mode.md: no confirmations or elicitation pauses (take the sensible default, record it), deletes + read-only git allowed (git writes never), run the command to completion. Also implied by the word YOLO in any command, an active /goal, or a tf-goal.sh run.
@@ -69,10 +66,4 @@ dependencies:
     - technical-preferences.md
   tasks:
     - create-deep-research-prompt.md
-    - create-doc.md
-  templates:
-    - architecture-tmpl.yaml
-    - brownfield-architecture-tmpl.yaml
-    - front-end-architecture-tmpl.yaml
-    - fullstack-architecture-tmpl.yaml
 ```

package/.tfcore/agents/flow-master.md

@@ -13,6 +13,7 @@ Madhav, the TechieFlow master (icon 🪈): the one persona for building, fixing,
 
 Each rule lives in one place; these lines only point at it.
 
+- Everything the owner reads is plain, simple English, a question for the owner goes in `docs/{App}-Decision-Request.md` rather than into the conversation, and an upstream defect is always filed — answering "Blocks: yes|no" first, and never stopping the run when the answer is no: `.tfcore/tasks/_owner-language.md`.
 - Run to completion in YOLO or goal mode: `.tfcore/tasks/_yolo-mode.md`. `*build-phase` is in it by default.
 - Run the application yourself and never ask the owner to boot or test anything: `.tfcore/tasks/_smoke-test-policy.md`, with `bash .tfcore/utils/tf-build.sh` for building on any host.
 - A smoke is not a verify. `Verified` is written only by an executed `*verify`; the hook refuses it otherwise. Your ceiling as a builder is `Implemented`.

package/.tfcore/agents/verifier.md

@@ -13,6 +13,7 @@ Vidur, the TechieFlow verifier (icon 🔍): the one persona that proves whether
 
 Each rule lives in one place; these lines only point at it.
 
+- Everything the owner reads is plain, simple English, a question for the owner goes in `docs/{App}-Decision-Request.md` rather than into the conversation, and an upstream defect is always filed — answering "Blocks: yes|no" first, and never stopping the run when the answer is no: `.tfcore/tasks/_owner-language.md`.
 - Run to completion: `.tfcore/tasks/_yolo-mode.md`. `*verify` is in YOLO by default.
 - Boot the application yourself, on this machine, and never ask the owner to start or test anything: `.tfcore/tasks/_smoke-test-policy.md` and `bash .tfcore/utils/tf-verify-boot.sh`.
 - Evidence over assertion. A row is `Verified` only when every check that ran passed, and the verdict script writes it from the evidence files; a `Verified` written by hand is refused by the hook. A check that could not run is written as not measured, never as a pass.

package/.tfcore/hooks/block-git.sh

@@ -85,7 +85,9 @@ if ! command -v python3 >/dev/null 2>&1; then
 fi
 
 # Verdicts: ALLOW | ASK_RM | BLOCK_WRITE | BLOCK_READ
-VERDICT="$(TF_HOOK_INPUT="$INPUT" TF_YOLO_ON="$YOLO" python3 - <<'PY' 2>/dev/null
+# The program is read into a variable first: bash 3.2 (a stock Mac) cannot parse this program as a
+# here-document inside $( ), because it scans the text for quotes and brackets.
+IFS= read -r -d '' GIT_GUARD_PY <<'PY' || true
 import json, os, re, shlex, sys
 
 raw = os.environ.get("TF_HOOK_INPUT", "")
@@ -283,7 +285,7 @@ elif (found_rm[0] or found_sudo[0]) and not yolo:
 else:
     print("ALLOW")
 PY
-)"
+VERDICT="$(TF_HOOK_INPUT="$INPUT" TF_YOLO_ON="$YOLO" python3 -c "$GIT_GUARD_PY" 2>/dev/null </dev/null)"
 
 case "$VERDICT" in
   BLOCK_WRITE) block_git_msg; exit 2 ;;

package/.tfcore/hooks/guard-build.sh

@@ -59,8 +59,12 @@ if not re.search(BUILD, low):
     sys.exit(0)
 
 bg_flag = bool(ti.get("run_in_background"))
+# A quoted argument is data, not shell: `--screen "Scorecard & Portfolio=/x"` backgrounds nothing
+# (AppManager TF-025). A quoted string that itself names a build stays, so
+# `powershell.exe -Command "dotnet run &"` is still read.
+bare = re.sub(r"\"[^\"]*\"|'[^']*'", lambda m: m.group(0) if re.search(BUILD, m.group(0)) else '""', low)
 # `&` that is not `&&` and not inside `2>&1` / `>&2`
-inline_bg = bool(re.search(r"(?<![&>\d])&(?![&\d])", low)) or bool(re.search(r"\b(nohup|setsid|disown)\b", low))
+inline_bg = bool(re.search(r"(?<![&>\d])&(?![&\d])", bare)) or bool(re.search(r"\b(nohup|setsid|disown)\b", bare))
 if not (bg_flag or inline_bg):
     sys.exit(0)
 

package/.tfcore/hooks/guard-db.sh

@@ -9,7 +9,8 @@
 #     mongosh with INSERT / UPDATE / DELETE / CREATE / ALTER / DROP / TRUNCATE / GRANT /
 #     REPLACE / MERGE in the command text, a -f / -i script, or stdin redirected from a file
 #   - dropping or resetting a database
-# What it allows only while .tfcore/.session/phase.json says build-phase or fix-issues
+# What it allows only while .tfcore/.session/phase.json says build-phase, fix-issues or
+# triage-and-fix (whose step 3 runs the fix-issues steps)
 # (written by bash .tfcore/utils/tf-phase.sh start <command>, step 0 of every task):
 #   - a migration runner: dotnet ef database update, dotnet run --project <…Db|…Migration(s)…>,
 #     dbup, flyway migrate, liquibase update, alembic upgrade, prisma migrate, knex migrate,
@@ -75,11 +76,12 @@ if direct_write or re.search(DROP_DB, low):
 
 if re.search(MIGRATORS, low):
     ph = phase()
-    if ph in ("build-phase", "fix-issues"):
+    # triage-and-fix step 3 is fix-issues steps 2 to 5 under its own marker (AppManager TF-027)
+    if ph in ("build-phase", "fix-issues", "triage-and-fix"):
         sys.exit(0)
     who = f"the marker says {ph}" if ph else "no command marker is set"
-    print("BLOCKED by TechieFlow policy: a database migration runs only from *build-phase or "
-          f"*fix-issues, and {who}. Day-1, mockups, split-brd, amend-docs, devguide, verify, "
+    print("BLOCKED by TechieFlow policy: a database migration runs only from *build-phase, "
+          f"*fix-issues or *triage-and-fix, and {who}. Day-1, mockups, split-brd, amend-docs, devguide, verify, "
           "triage and status commands write documents and records, never the database. If you are "
           "inside build-phase or fix-issues, step 0 was skipped: run "
           "bash .tfcore/utils/tf-phase.sh start <command> <App> and retry. Owner rule 2026-09-05.",

package/.tfcore/hooks/guard-metrics.sh

@@ -27,6 +27,12 @@ except Exception:
 
 ti = data.get("tool_input") or {}
 STREAM = r"docs/metrics/[\w.-]+\.jsonl"
+# What makes a python/node command a WRITE rather than a read: an explicit write mode,
+# something that emits, or a move onto the path. A read names none of these.
+WRITEY = (r"(?:['\"][wax]b?\+?['\"]|\.write\b|\.writelines\b|json\.dump\b|"
+          r"\btruncate\b|\bos\.rename\b|\bos\.replace\b|\bshutil\.(?:copy|move)\b|"
+          r"createWriteStream|writeFileSync|appendFileSync)")
+
 MSG = ("BLOCKED by TechieFlow policy: docs/metrics/*.jsonl are append-only telemetry "
        "streams written only through bash .tfcore/utils/tf-emit.sh <stream> (stdin JSON). "
        "Never Write, Edit, redirect or copy onto them. A wrong record is corrected by a "
@@ -44,7 +50,13 @@ if isinstance(cmd, str) and re.search(STREAM, cmd, re.I):
         r"|(\btee\b[^|;&]*" + STREAM + r")"
         r"|(\b(cp|mv|install)\b[^|;&]*" + STREAM + r")"
         r"|(\b(sed|perl)\b[^|;&]*\s-[a-zA-Z]*i[a-zA-Z]*\b[^|;&]*" + STREAM + r")"
-        r"|(\b(python3?|node)\b[^|;&]*" + STREAM + r")"
+        # A python/node command NAMING a stream used to be blocked outright, which also
+        # refused every READ -- and this file's own header says reading is fine. Checking
+        # a stream with a one-liner is a normal, frequent thing to do, and a guard that
+        # blocks it teaches people to route around the guard. So the clause now needs a
+        # write in the command as well as the path. MISS-TechieFlow-20260909-03.
+        r"|(\b(python3?|node)\b[^|;&]*" + STREAM + r"[^|;&]*" + WRITEY + r")"
+        r"|(\b(python3?|node)\b[^|;&]*" + WRITEY + r"[^|;&]*" + STREAM + r")"
         r"|(\b(truncate|dd)\b[^|;&]*" + STREAM + r")",
         cmd, re.I,
     ):

package/.tfcore/hooks/guard-status-html.sh

@@ -10,9 +10,14 @@
 #   Only when PROJECT-STATUS.md was written in this session (newer than the
 #   session pointer .tfcore/.session/<harness>.json):
 #   2. tf-doc-check.sh FAILs on PROJECT-STATUS.md      -> fix the file, re-run the check
+#   2c. a BRD or UI design written this session leaves a screen with no row, UI design
+#       entry or mockup                               -> add it, re-run the check (TF-030)
 #   3. docs/<App>-BRD.md older than docs/<App>-Checklist.md
 #        -> bash .tfcore/utils/tf-brd-status.sh <App>
 #   4. no runs.jsonl record after the status write     -> the run record (_metrics-emit-gate.md)
+#   Only on the turn that wrote PROJECT-STATUS.md (a command's closing turn):
+#   5. tf-owner-text.sh FAILs on the closing message or a free-form document it
+#      hands the owner                                  -> rewrite it for the owner
 #
 # Wired in .claude/settings.json -> hooks.Stop; OpenCode via
 # .opencode/plugin/techieflow.js session.idle (a nudge: OpenCode has no blocking
@@ -28,6 +33,7 @@ import datetime
 import glob
 import json
 import os
+import re
 import subprocess
 import sys
 
@@ -58,10 +64,18 @@ elif md_mtime > os.path.getmtime(html):
 def session_start():
     """mtime of the harness's session pointer; None when there is none (checks 2-4 skipped)."""
     d = os.path.join(root, ".tfcore", ".session")
-    if any(k.startswith("OPENCODE") for k in os.environ):
+    # The harness in the order tf-harness.sh and tf-emit.sh take it: TF_HARNESS (the OpenCode
+    # plugin sets it on every guard it spawns), then Claude Code's own variables, then OPENCODE*.
+    # OpenCode first let any OPENCODE_* in the owner's shell (an API key, a config path) send a
+    # Claude Code turn to opencode.json; with no such file, checks 2-5 never ran (2026-09-27).
+    tf = os.environ.get("TF_HARNESS")
+    if tf == "opencode":
         cands = [os.path.join(d, "opencode.json")]
-    elif os.environ.get("CLAUDECODE") or any(k.startswith("CLAUDE_CODE") for k in os.environ):
+    elif tf == "claude-code" or any(os.environ.get(k) for k in (
+            "CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CLAUDE_CODE_SESSION_ID", "CLAUDE_PROJECT_DIR")):
         cands = [os.path.join(d, "claude-code.json")]
+    elif any(k.startswith("OPENCODE") for k in os.environ):
+        cands = [os.path.join(d, "opencode.json")]
     else:
         cands = [os.path.join(d, "claude-code.json"), os.path.join(d, "opencode.json")]
     times = [os.path.getmtime(p) for p in cands if os.path.isfile(p)]
@@ -104,6 +118,31 @@ if written_this_session:
     except Exception:
         pass
 
+    # 2c. a screen is not finished until it has its row, its UI design entry and its mockup. An
+    # amendment added a Price providers screen inside a requirement with none of the three, the
+    # checker's one finding was on the checklist and passed as old, and the page was built with no
+    # design (TfLens TF-030, 2026-09-11). On a turn that wrote a BRD or a UI design, those findings
+    # block; a BRD's other findings stay with *amend-docs, as before.
+    try:
+        chk = os.path.join(root, ".tfcore", "utils", "tf-doc-check.sh")
+        chain = re.compile(r'names the screen "|has no "### Screen:" entry|is in the UIDesign but not in the BRD'
+                           r'|has no mockup link \(docs/mockups')
+        apps = set()
+        for f in glob.glob(os.path.join(root, "docs", "*.md")):
+            m = re.match(r"^(.+?)-(?:P\d+-)?(?:BRD|UIDesign)\.md$", os.path.basename(f))
+            if m and os.path.getmtime(f) >= start:
+                apps.add(m.group(1))
+        for app in sorted(apps) if os.path.isfile(chk) else ():
+            out = subprocess.run(["bash", chk, "--quiet", "--app", app], cwd=root,
+                                 capture_output=True, text=True, timeout=180).stdout
+            fails = [l for l in out.splitlines() if l.startswith("FAIL") and chain.search(l)]
+            if fails:
+                problems.append(f"a screen in {app}'s documents has no row, UI design entry or mockup ({len(fails)} line(s)). "
+                                f"Add what is missing, then run: bash .tfcore/utils/tf-doc-check.sh --app {app}")
+                problems.extend("  " + l for l in fails[:5])
+    except Exception:
+        pass
+
     # 3. the BRD's Development status table is not older than the checklist
     try:
         for cl in glob.glob(os.path.join(root, "docs", "*-Checklist.md")):
@@ -136,6 +175,51 @@ if written_this_session:
     except Exception:
         pass
 
+    # 5. what the owner reads when a command ends: the closing message, and every free-form
+    # document it hands over that this turn wrote, through tf-owner-text.sh. TfLens's hand-off of
+    # 2026-09-11 reached the owner in jargon, named upstream problems with no word on what they
+    # touch, called two fixed ones open, and gave no prompt (MISS-TechieFlow-20260911-03). Only on
+    # the turn that closed a command -- PROJECT-STATUS written after this turn's prompt -- so an
+    # ordinary conversation is never held to a hand-off's shape. Claude Code hands the hook the
+    # message; the OpenCode plugin passes the same two fields.
+    try:
+        message = data.get("last_assistant_message") or ""
+        turn = data.get("turn_started")
+        if turn is None and data.get("transcript_path") and os.path.isfile(data["transcript_path"]):
+            with open(data["transcript_path"], encoding="utf-8", errors="replace") as f:
+                for line in f:
+                    try:
+                        r = json.loads(line)
+                    except Exception:
+                        continue
+                    c = (r.get("message") or {}).get("content")
+                    prompt = r.get("type") == "user" and not r.get("isMeta") and (
+                        isinstance(c, str) or (isinstance(c, list) and any(isinstance(x, dict) and x.get("type") == "text" for x in c)))
+                    if prompt and r.get("timestamp"):
+                        turn = r["timestamp"]
+        if isinstance(turn, str):
+            turn = datetime.datetime.strptime(turn[:19], "%Y-%m-%dT%H:%M:%S").replace(
+                tzinfo=datetime.timezone.utc).timestamp()
+        elif isinstance(turn, (int, float)) and turn > 1e12:
+            turn = turn / 1000.0
+        chk = os.path.join(root, ".tfcore", "utils", "tf-owner-text.sh")
+        if message.strip() and turn and md_mtime >= turn - 2 and os.path.isfile(chk):
+            handed = []
+            for m in set(re.findall(r"(?<![\w/.-])((?:docs/)?[\w.-]+\.md)\b", message)):
+                p = os.path.join(root, m if m.startswith("docs/") else os.path.join("docs", m))
+                if os.path.isfile(p) and os.path.getmtime(p) >= turn - 2:
+                    handed.append(os.path.relpath(p, root))
+            res = subprocess.run(["bash", chk, "--root", root, "--final", "--stdin"] + sorted(handed), cwd=root,
+                                 input=message, capture_output=True, text=True, timeout=60)
+            fails = [l for l in res.stdout.splitlines() if l.startswith("FAIL")]
+            if fails:
+                problems.append(f"what you are handing the owner is not written for the owner ({len(fails)} line(s)). "
+                                "Fix each, then write the closing message again — plain words, every upstream problem "
+                                "with what it affects and its prompt, and the next prompt in a code block:")
+                problems.extend("  " + l for l in fails[:8])
+    except Exception:
+        pass
+
 if not problems:
     sys.exit(0)