@techierathore/techieflow 1.0.3 → 1.0.4

package/.tfcore/templates/v4custom/app-brief-tmpl.md

@@ -0,0 +1,65 @@
+<!-- tf-schema
+doc: brief
+file: docs/{App}-Brief.md
+header: App, Date
+section: What it is | required | max 150
+section: Who it is for | required | max 150
+section: Must do | required
+section: Out of scope | required | max 150
+section: Open questions | optional | max 150
+rule: brief-must-do
+rule: no-glossary
+target-lines: 60
+max-lines: 120
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     The brief is the input to day-1: `*day1-greenfield` and `*day1-brownfield` read it
+     and turn it into the Architecture, the BRD and the mockups. Its whole job is to be
+     ONE PAGE the owner can read and correct in two minutes, before anything expensive
+     is built on it.
+
+     It replaced a 221-line inherited template (2026-09-08) whose twelve sections —
+     executive summary, problem statement, proposed solution, goals and metrics, KPIs,
+     post-MVP vision, expansion opportunities — produced a document nobody read and
+     nothing checked. What the framework's own review says a brief is: "a one-page
+     brief: product, users, must-do, out of scope". That is what this template holds.
+
+     Each "Must do" line becomes one or more BRD items at day-1, so write them as
+     things the product does, one per line, numbered. Not features to build: outcomes
+     a user gets. If a line needs a paragraph to explain it, it is two lines.
+
+     "Open questions" is where a decision the owner has not taken goes, so day-1 asks
+     rather than assumes. An empty brief with three honest open questions is worth more
+     than a full one built on guesses. -->
+
+# {App} — Brief
+
+| | |
+|---|---|
+| App | {App} |
+| Date | {YYYY-MM-DD} |
+
+## What it is
+
+{Two or three sentences, at most 150 words. What the product does, in the words you
+would use to a person who has never heard of it. No technology.}
+
+## Who it is for
+
+{Who uses it and what they are trying to get done. Name each role. At most 150 words.}
+
+## Must do
+
+1. {One thing the product does, as an outcome a user gets.}
+2. {Another.}
+3. {Another.}
+
+## Out of scope
+
+{What this is deliberately not doing, so day-1 does not build it. At most 150 words.}
+
+## Open questions
+
+{A decision not yet taken, one per line, so day-1 asks instead of assuming. Delete the
+section when there are none.}

package/.tfcore/templates/v4custom/app-decision-request-tmpl.md

@@ -0,0 +1,85 @@
+<!-- tf-schema
+doc: decision-request
+file: docs/{App}-Decision-Request.md
+header: App, Written, Waiting on
+section: What happened | required | max 250
+section: What I need you to decide | required
+section: What I do when you answer | required | max 200
+section: Copy this back to me | required | max 250
+entries: What I need you to decide |
+per-entry: 150 300
+rule: entry-decision-options
+rule: entry-recommendation
+rule: paste-back-block
+rule: no-glossary
+target-lines: 120
+max-lines: 260
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     WHEN TO WRITE ONE. A command has hit a choice only the owner can make and the
+     answer changes what gets built. Write this file, render it to HTML, and say one
+     line in the terminal: which file to open, and that it holds N decisions. Never
+     argue the decision out in the terminal — that fills the context and buries the
+     question. Everything the owner needs is in the file.
+
+     WHO READS IT. The owner, and nobody else. No task ever loads a Decision Request
+     as input, and it is never named in core-config.yaml. The way the answer comes
+     back is the owner pasting the block from §"Copy this back to me" — that pasted
+     prompt is the input, and the file's job is done the moment it is answered.
+
+     HOW IT IS WRITTEN. Plain, simple English, the way you would explain it to
+     someone who has not read a line of the framework. No coined terms. No framework
+     shorthand. No requirement ids in the question itself — name the thing, not its
+     number. If a word needs defining, it is the wrong word: change it. A glossary
+     section is refused by `rule: no-glossary`, because a document that has to teach
+     its own vocabulary before it can ask its question was written for the wrong
+     reader.
+
+     WHAT IT IS NOT. Not a defect report — that is the feedback file. Not an
+     architecture decision record — that is DECISIONS.md, written after the fact.
+     This file asks a question and then stops existing: when it is answered, it moves
+     unchanged to docs/OldDocs/ and the live name is free for the next one.
+
+     ONE LIVE FILE. All open decisions go in this one file as separate entries. Never
+     a dated copy, never a -v2. -->
+
+# {App} — decisions I need from you
+
+| | |
+|---|---|
+| App | {App} |
+| Written | {YYYY-MM-DD} |
+| Waiting on | {N} decisions. Nothing has been changed yet. |
+
+## What happened
+
+{Two short paragraphs, at most 250 words. What was being done, what stopped it, and
+why the choice is yours rather than something to be worked out. Plain words.}
+
+## What I need you to decide
+
+### {1. The short name of the choice}
+
+{One paragraph: what the choice actually is, in plain words.}
+
+| Option | What happens | What it costs |
+|---|---|---|
+| **A — {name}** | {what the project looks like afterwards} | {work, and what is given up} |
+| **B — {name}** | {what the project looks like afterwards} | {work, and what is given up} |
+
+**My recommendation: {A}** — {one sentence saying why.}
+
+## What I do when you answer
+
+{The steps, in order, one line each. What gets edited, what gets re-checked, roughly
+how long. So the answer is given with the consequences in view.}
+
+## Copy this back to me
+
+{One fenced block per decision. Each block is a complete instruction that stands on
+its own — the owner pastes it and nothing else needs saying.}
+
+```
+{App}: decision 1 — go with option A. {The one thing that changes.}
+```

package/.tfcore/templates/v4custom/app-library-feedback-tmpl.md

@@ -1,31 +1,86 @@
-<!-- ============================================================
-     ONE FEEDBACK FILE PER LIBRARY — never a combined file.
-     TrBlazeUI and TechieRag are separate codebases with separate
-     teams; each team receives (or pulls) only its own file:
-       docs/{AppName}-TrBlazeUI-Feedback.md  (issue IDs TR-NNN)
-       docs/{AppName}-TechieRag-Feedback.md  (issue IDs TR-RAG-NNN)
-     A future library {LibName} gets docs/{AppName}-{LibName}-Feedback.md
-     with its own ID prefix (WORKFLOW.html §9.1).
-     Create a library's file on the FIRST issue for that library;
-     substitute {Library} and the ID prefix below.
-     ============================================================ -->
-
-# {Library} Feedback — surfaced during {AppName}
-
-## Summary (filled by /flow-master on consolidation)
-- 0 blockers, 0 major, 0 minor, 0 nice-to-have
-- Last consolidated: {YYYY-MM-DD}
-
-## Issues
-
-<!-- Append entries as gaps are found. IDs are append-only, never renumbered.
-     TrBlazeUI → TR-NNN · TechieRag → TR-RAG-NNN -->
-
-### TR-001 — <short title>
-- **Severity:** blocker | major | minor | nice-to-have
-- **Repro:** <minimal code snippet>
-- **Expected:** …
-- **Actual:** …
-- **Encountered in:** REQ-UI-013
-- **Workaround:** <what you did in app code>
-- **Suggested fix:** <hypothesis for the library team>
+<!-- tf-schema
+doc: feedback
+file: docs/{App}-{Upstream}-Feedback.md
+header: App, Upstream, Updated
+section: Summary | required | max 200
+section: Entries | required
+section: Replies from* | optional
+section: Resolution status* | optional
+entries: Entries |
+per-entry: 120 250
+rule: entry-feedback-fields
+rule: entry-blocks-line
+rule: feedback-blocking-count
+rule: no-glossary
+-->
+<!-- Authoring notes (agent only; never visible text).
+
+     ONE FEEDBACK FILE PER UPSTREAM — never a combined file. Each upstream owns a
+     separate codebase and receives only its own file:
+
+       docs/{App}-TrBlazeUI-Feedback.md    ids TR-NNN        (the UI library)
+       docs/{App}-TechieRag-Feedback.md    ids TR-RAG-NNN    (the RAG library)
+       docs/{App}-TechieFlow-Feedback.md   ids TF-NNN        (the framework itself)
+
+     A future library {LibName} gets docs/{App}-{LibName}-Feedback.md with its own
+     prefix. Create the file on the FIRST entry for that upstream.
+
+     REPORTING IS NEVER REFUSED. If something upstream is wrong, file it — whatever
+     the severity, whatever the day. What this schema constrains is the SHAPE, not
+     the right to report:
+
+     1. Every entry says whether it BLOCKS the work, in one word. That is the field
+        the owner reads first, and it decides whether the run stops.
+     2. A non-blocking entry is filed and the work CONTINUES. Never stop, never ask,
+        never write a page of analysis about it mid-run. One entry, then carry on.
+     3. 250 words for the REPORT, hard: the eight fields, and nothing else. An entry is
+        a bug report, not an essay. Evidence goes in a code block, not in prose.
+        Working-out that is genuinely worth keeping goes under a `#### Detail` heading
+        inside the entry, and is not counted — so a thorough analysis costs nothing and
+        an unreadable entry is still refused.
+     4. Plain English. No coined terms, no framework shorthand, no word the reader
+        would have to look up. If you find yourself writing a glossary, the words
+        are wrong — change the words. `rule: no-glossary` refuses the section.
+     5. A decision for the owner does NOT go in this file. It goes in a Decision
+        Request (`app-decision-request-tmpl.md`), which is written for the owner and
+        carries the prompt to paste back.
+
+     "Replies from {Upstream}" holds the upstream team's answers, newest block first.
+     Ids are append-only and never renumbered. A fixed entry keeps its body and gains
+     a resolution line; the record of what was wrong is the point. -->
+
+# {Upstream} feedback — found while building {App}
+
+| | |
+|---|---|
+| App | {App} |
+| Upstream | {Upstream} |
+| Updated | {YYYY-MM-DD} |
+
+## Summary
+
+{N} entries: {n} blocking now, {n} filed and not blocking, {n} fixed upstream.
+
+{One sentence naming what is blocked right now, or the sentence "Nothing is blocked."}
+
+## Entries
+
+### {TF-001} — {one line saying what is wrong}
+
+- **Severity:** blocker | major | minor
+- **Blocks:** yes — {the row or command that cannot proceed} | no — {what was done instead, and the work carried on}
+- **Repro:** {the shortest command or snippet that shows it}
+- **Expected:** {what should have happened}
+- **Actual:** {what happened}
+- **Encountered in:** {REQ-UI-013, or the command that was running}
+- **Workaround:** {what was done in this project, or "none"}
+- **Suggested fix:** {one concrete change for the upstream team}
+
+#### Detail
+
+{Optional, and not counted against the 250 words: the root cause, the reasoning, the
+longer version of the fix. Everything above must stand on its own without it.}
+
+## Replies from {Upstream}
+
+<!-- The upstream team's answers, newest block first. Left in full: this is the record. -->

package/.tfcore/templates/v4custom/html-render-shell.md

@@ -23,7 +23,7 @@ Each rendered HTML file is:
 - A **single self-contained `.html` file**, no external CSS, no external JS except the two `<script>` tags below (mermaid + svg-pan-zoom from jsdelivr CDN).
 - Sibling to the source MD (same filename, `.html` extension).
 - **Light + dark theme with a persisted toggle** (§2 + §3 + §7). Default is chosen by **time of day** on first open — light between 07:00 and 19:00 local, softened dark otherwise — then the user's explicit toggle choice (saved in `localStorage` as `tf-theme`) wins on every later visit. Light is a **warm off-white** (never harsh bright white); dark is a softened near-black. Monospace for code/pre, sans for body.
-- **Only human-readable docs are ever rendered to HTML** (BRD, Architecture, UsageGuide, DevGuide, PROJECT-STATUS). The **checklists are AI-agent working documents — never render them to HTML** (they are read by agents in markdown; an HTML mirror just wastes tokens and drifts). If you are about to emit a `*-Checklist.html`, STOP — that is banned.
+- **Only human-readable docs are ever rendered to HTML** (BRD, Architecture, UsageGuide, DevGuide, ProductGuide, PROJECT-STATUS, a Decision Request, a feedback file). **An agent working document is never rendered to HTML** — it is read in markdown, and an HTML mirror wastes tokens and drifts from the source. Two are banned by name, and `tf-render-html.py` refuses both with exit 2: the **requirements checklist** `{App}-Checklist.md`, and the **miss log** `{App}-Misses.md`. If you are about to emit a `*-Checklist.html` or a `*-Misses.html`, STOP — that is banned. The test for anything else: if the only reader is an agent, it stays markdown.
 - Working anchor links from any auto-generated or hand-written TOC to its target heading.
 - Copy buttons on every **code** `<pre>` — but NOT on `pre.mermaid` (a button injected there corrupts the diagram source mermaid reads → "Syntax error"; mermaid blocks get copy/export from their own diagram toolbar).
 - Mermaid toolbar on every rendered diagram.

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

@@ -4,8 +4,10 @@
     bash .tfcore/utils/tf-build-list.sh <App> [--phase N] [--prompts]
 
 Reads the phase's checklist (appPhase in core-config.yaml, or --phase) and prints:
-  - the mode: FIX (rows FAIL / PARTIAL / In Progress / Needs re-verify exist), FRESH
-    (every open row), or NOTHING (every row terminal or Blocked)
+  - the mode: FIX (rows FAIL / PARTIAL / In Progress / Needs re-verify exist, and they
+    come FIRST in the list), FRESH (nothing failing), or NOTHING (every row terminal or
+    Blocked). The working list is every open row in both FIX and FRESH: the mode says
+    what to build first, never what to leave out.
   - the working list, grouped into clusters by the checklist's page section, each
     naming its builder from the row prefix: REQ-UI -> trblazeui, REQ-RAG -> techierag,
     REQ-FN / REQ-NFR -> builder
@@ -113,8 +115,17 @@ def main(argv):
 
     fix_rows = [r for r in rows if r["status"] in FIX]
     open_rows = [r for r in rows if r["status"] not in TERMINAL | BLOCKED]
+    # Repair before new work, but never INSTEAD of it. A row can sit at `Needs re-verify`
+    # permanently -- TfLens REQ-FN-067 and -070 need a repository that emits events.ndjson
+    # and none exists, so every honest verify run re-confirms that gate rather than clearing
+    # it. FIX used to win outright, which pinned the mode forever: the twelve rows a later
+    # *amend-docs added were never once printed, and a pass that trusted the working list
+    # would have met build-phase's ending condition with twelve requirements at 0%.
+    # So the working list is every open row, and FIX only says which ones come first.
+    # tests/regression/run.sh tf_019.
     if fix_rows:
-        mode, work = "FIX", fix_rows
+        rest = [r for r in open_rows if r not in fix_rows]
+        mode, work = "FIX", fix_rows + rest
     elif open_rows:
         mode, work = "FRESH", open_rows
     else:
@@ -124,6 +135,15 @@ def main(argv):
     print(f"# tf-build-list — {app} — {cl} — phase {phase}")
     print(f"Mode: {mode} — {len(work)} row(s) to build; {terminal} terminal, {len(blocked)} Blocked, {len(rows)} total"
           + (f" — {', '.join(r['id'] for r in work[:8])}{' …' if len(work) > 8 else ''}" if work else ""))
+    # Every row is in exactly one of the four counts, and the arithmetic is printed so a
+    # reader can check it rather than trust it. A row missing from all of them is the
+    # failure this line exists to make impossible.
+    if len(work) + terminal + len(blocked) != len(rows):
+        print(f"⚠ {len(rows) - len(work) - terminal - len(blocked)} row(s) are in no category — "
+              "the checklist carries a status this script does not know; fix the row or the script")
+    if fix_rows and len(work) > len(fix_rows):
+        print(f"Order: {len(fix_rows)} failing row(s) first ({', '.join(r['id'] for r in fix_rows)}), "
+              f"then {len(work) - len(fix_rows)} not yet started")
     if blocked:
         print("Blocked (library gaps, pass through unless the feedback entry is resolved): " + ", ".join(r["id"] for r in blocked))
     if not work:

package/.tfcore/utils/tf-build-list.sh

@@ -6,8 +6,9 @@
 #   bash .tfcore/utils/tf-build-list.sh MyApp --phase 2     # a later phase of a Large project
 #
 # Reads the phase's checklist (appPhase in core-config.yaml unless --phase). Rows FAIL /
-# PARTIAL / In Progress / Needs re-verify make it FIX mode over exactly those rows; else every
-# open row is FRESH; Blocked rows pass through. Clusters follow the checklist's page sections,
+# PARTIAL / In Progress / Needs re-verify make it FIX mode, which puts those rows FIRST and
+# then lists every other open row; FRESH is the same list when nothing is failing; Blocked rows
+# pass through. Clusters follow the checklist's page sections,
 # each with its builder from the prefix (UI -> trblazeui, RAG -> techierag, FN/NFR -> builder).
 # Prompts are filled from .tfcore/templates/v4custom/build-subagent-prompt.md.
 # Writes nothing. Thin wrapper over tf-build-list.py; Python 3 stdlib only.

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

@@ -52,12 +52,20 @@ DOC_KINDS = [
     ("-devguide.md", "devguide", "app-devguide-tmpl.md"),
     ("-productguide.md", "productguide", "app-productguide-tmpl.md"),
     ("-phases.md", "phases", "app-phases-tmpl.md"),
+    ("-brief.md", "brief", "app-brief-tmpl.md"),
+    ("-decision-request.md", "decision-request", "app-decision-request-tmpl.md"),
+    ("-feedback.md", "feedback", "app-library-feedback-tmpl.md"),
 ]
 SIZED_DOCS = {"brd", "architecture", "uidesign", "checklist", "usageguide", "devguide", "productguide"}
 # Large projects: these four split by phase. Phase 1 keeps the plain name (App-BRD.md);
 # phase 2 onward are App-P2-BRD.md and so on. docs/TechieFlow-Document-Schemas.md §2.
 PHASED_DOCS = {"brd", "checklist", "uidesign", "devguide"}
 PHASED_SUFFIX = {"brd": "BRD", "checklist": "Checklist", "uidesign": "UIDesign", "devguide": "DevGuide"}
+# A feedback entry's heading opens with its id: TF-016, TR-010, TR-RAG-002.
+ENTRY_ID = re.compile(r"^[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+\b")
+# A closed entry carries its resolution banner near the top of its body. The banner is not
+# always first: an entry may open with a renumbering or scope note, so the window is generous.
+FEEDBACK_CLOSED = re.compile(r"(?i)(✅|\bfixed upstream\b|\bwill not fix\b|\bwont-fix\b|is \*\*closed\*\*)")
 DOC_NAME = re.compile(
     r"^(.+?)(?:-P(\d+))?-(BRD|Deployment-Checklist(?:-[\w]+)?|Checklist|UIDesign|DevGuide|Architecture|Coding-Standards|UsageGuide|Usage-Guide|ProductGuide|Phases)\.md$",
     re.I)
@@ -429,6 +437,9 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
             continue
         if doc == "checklist" and re.search(r"<a id=['\"]d-req-", txt, re.I):
             continue  # a page group holding detail entries
+        if doc == "feedback" and ENTRY_ID.match(h.strip()):
+            continue  # an entry written at ## level: the layout every feedback file shipped
+                      # with before this schema existed. Read as an entry, not a stranger.
         extra = "; bugs and feedback go to the misses stream, not the checklist" if doc == "checklist" else ""
         rep.fail(rel, f'section "{h}" is not in the template{extra}')
 
@@ -438,6 +449,9 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
         d = schema.declared(key)
         if not d:
             continue
+        if doc == "feedback" and d[1] != "required":
+            continue    # correspondence blocks are appended over time and sit either side
+                        # of the entries; where they land carries no meaning
         idx = order_of[norm_heading(d[0])]
         if idx < last_idx:
             rep.fail(rel, f'section "{h}" comes after "{last_name}"; the template order is the other way round')
@@ -464,7 +478,9 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     for key, h, txt in present:
         d = schema.declared(key)
         if d and d[2]:
-            n = word_count(txt)
+            # A `####` block inside a section is detail the reader chooses to open, and is not
+            # counted — the same rule as a feedback entry's `#### Detail` (owner, 2026-09-08).
+            n = word_count(re.split(r"(?m)^####\s", txt)[0])
             if n > d[2]:
                 rep.fail(rel, f'section "{h}" is {n} words; at most {d[2]}')
     if schema.max_lines:
@@ -479,8 +495,14 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
     if schema.entries:
         sec_txt = section_text(present, schema.entries[0])
         prefix = schema.entries[1]
+        pairs = list(split_sections(sec_txt, 3)) if sec_txt is not None else []
+        if doc == "feedback":
+            # Entries may sit under "Entries" as ###, or stand at ## level as every
+            # feedback file wrote them before this schema. Both are read the same way.
+            pairs += [(h, t) for _k, h, t in present if ENTRY_ID.match(h.strip())]
+            sec_txt = sec_txt if sec_txt is not None else ""
         if sec_txt is not None:
-            for h3, etxt in split_sections(sec_txt, 3):
+            for h3, etxt in pairs:
                 if h3 is None:
                     continue
                 if prefix and not h3.lower().startswith(prefix.lower()):
@@ -489,8 +511,16 @@ def check_document(path: str, rep: Report, cli_size=None, root=None):
                 ename = h3[len(prefix):].strip() if prefix else h3
                 ename = re.sub(r"\s*\(.*$", "", ename).strip("` ").strip()
                 entry_names.append(ename)
+                if doc == "feedback" and FEEDBACK_CLOSED.search(etxt[:2500]):
+                    continue    # a closed entry is the record of what was wrong and why.
+                                # History may be as long as it needs to be; the shape and the
+                                # word cap bind the LIVE ones, which are what the owner reads.
                 if schema.per_entry:
-                    n = word_count(etxt)
+                    # The cap binds the REPORT, not the working-out. Anything under a `####`
+                    # heading inside the entry is detail a reader chooses to open, and is not
+                    # counted: a thorough analysis is worth having, an entry the owner cannot
+                    # read at a glance is not (owner, 2026-09-08).
+                    n = word_count(re.split(r"(?m)^####\s", etxt)[0])
                     if n > schema.per_entry[1]:
                         rep.fail(rel, f'entry "{ename}" is {n} words; maximum {schema.per_entry[1]} (target {schema.per_entry[0]})')
                     elif n > schema.per_entry[0]:
@@ -549,6 +579,29 @@ def check_entry_rule(rule, ename, etxt, rel, root, path, rep):
     elif rule == "entry-expected":
         if not re.search(r"(?im)^\s*[-*]?\s*\**expected", etxt):
             rep.fail(rel, f'entry "{ename}" has no "Expected:" line')
+    elif rule == "entry-feedback-fields":
+        # A feedback entry is a bug report, not an essay. Same eight fields every time,
+        # so the upstream team reads them in one shape and the owner reads "Blocks" first.
+        for field in ("Severity", "Blocks", "Repro", "Expected", "Actual",
+                      "Encountered in", "Workaround", "Suggested fix"):
+            if not re.search(r"(?im)^\s*[-*]?\s*\**%s\**\s*:" % re.escape(field), etxt):
+                rep.fail(rel, f'entry "{ename}" has no "{field}:" line')
+    elif rule == "entry-blocks-line":
+        # The one word that decides whether the run stops. "no" also has to say what was
+        # done instead, because a non-blocking entry is filed and the work carries on.
+        m = re.search(r"(?im)^\s*[-*]?\s*\**Blocks\**\s*:\s*(.+)$", etxt)
+        if m:
+            val = m.group(1).strip().strip("*` ").lower()
+            if not re.match(r"^(yes|no)\b", val):
+                rep.fail(rel, f'entry "{ename}" says "Blocks: {m.group(1).strip()[:40]}"; it must start "yes" or "no"')
+            elif val.startswith("no") and len(val) < 8:
+                rep.fail(rel, f'entry "{ename}" says "Blocks: no" and stops; say what was done instead and that the work carried on')
+    elif rule == "entry-decision-options":
+        if not has_table_with(etxt, "option", "what happens"):
+            rep.fail(rel, f'decision "{ename}" has no options table (Option, What happens, What it costs)')
+    elif rule == "entry-recommendation":
+        if not re.search(r"(?im)^\s*\**My recommendation", etxt):
+            rep.fail(rel, f'decision "{ename}" has no "My recommendation:" line — the owner is owed one, with the reason in a sentence')
 
 
 def check_doc_rule(rule, c, rep):
@@ -782,6 +835,50 @@ def check_doc_rule(rule, c, rep):
         if re.search(r"\b(and|or)\b|,|/", tgt):
             rep.fail(rel, f'Hosting target "{tgt}" names more than one target; one document per hosting target')
 
+    elif rule == "brief-must-do":
+        txt = section_text(present, "Must do")
+        if txt is None:
+            return
+        n = len(re.findall(r"(?m)^\s*\d+[.)]\s+\S", txt))
+        if n == 0:
+            rep.fail(rel, 'the "Must do" section is not a numbered list; day-1 turns each line into requirements, so one line is one thing the product does')
+        elif n > 25:
+            rep.fail(rel, f'the "Must do" section has {n} lines; a brief that long is a BRD. Keep the page, and let day-1 expand it')
+
+    elif rule == "no-glossary":
+        # A document written for the owner explains itself in plain words or it is
+        # written wrong. A section that defines the document's own vocabulary before it
+        # can ask its question is the tell: the fix is to change the words, never to
+        # teach them (owner, 2026-09-08).
+        for _key, h, _txt in present:
+            if re.search(r"(?i)\b(glossary|terminology|words this document uses|"
+                         r"terms? (used|you)|what these words mean|definitions)\b", h):
+                rep.fail(rel, f'section "{h}" defines this document\'s own vocabulary; '
+                              f'write it in plain English instead — if a word needs a glossary, use a different word')
+
+    elif rule == "feedback-blocking-count":
+        txt = section_text(present, "Summary")
+        if txt is None:
+            return
+        if not re.search(r"(?i)\bblocking\b|\bnothing is blocked\b", txt):
+            rep.fail(rel, 'the Summary must say how many entries are blocking right now, '
+                          'or "Nothing is blocked" — it is the first thing the owner reads')
+
+    elif rule == "paste-back-block":
+        # `present` is built from the prose-only copy, which drops fenced blocks — and a
+        # fenced block is exactly what this rule looks for. Re-split the uncommented source.
+        raw_present = [(norm_heading(h), h, t) for h, t in split_sections(nocomment, 2) if h is not None]
+        txt = section_text(raw_present, "Copy this back to me")
+        if txt is None:
+            return
+        blocks = re.findall(r"^```", txt, re.M)
+        if len(blocks) < 2:
+            rep.fail(rel, 'the "Copy this back to me" section has no fenced block; '
+                          'the owner answers by pasting it, so it must be there to paste')
+        n_dec = len(c.get("entry_names") or [])
+        if n_dec and len(blocks) // 2 < n_dec:
+            rep.fail(rel, f'{n_dec} decisions but {len(blocks) // 2} paste-back block(s); one per decision')
+
     elif rule == "phases-table":
         txt = section_text(present, "Phases")
         if txt is None:
@@ -1148,7 +1245,7 @@ def check_mockups(root: str, rep: Report):
 # ----------------------------------------------------------------------------
 def app_files(root: str, app: str):
     docs = os.path.join(root, "docs")
-    names = [f"{app}-Phases.md", f"{app}-BRD.md", f"{app}-Architecture.md", f"{app}-UIDesign.md", f"{app}-Checklist.md",
+    names = [f"{app}-Brief.md", f"{app}-Phases.md", f"{app}-BRD.md", f"{app}-Architecture.md", f"{app}-UIDesign.md", f"{app}-Checklist.md",
              f"{app}-Coding-Standards.md", f"{app}-UsageGuide.md", f"{app}-DevGuide.md", f"{app}-ProductGuide.md"]
     # later phases of a Large project: App-P2-BRD.md, App-P2-Checklist.md, … in phase order
     extra = []
@@ -1160,6 +1257,11 @@ def app_files(root: str, app: str):
     names += [f for _p, _o, f in sorted(extra)]
     if os.path.isdir(docs):
         names += sorted(f for f in os.listdir(docs) if re.match(rf"^{re.escape(app)}-Deployment-Checklist(-[\w]+)?\.md$", f))
+        # the two documents written for a reader outside this project: the owner's open
+        # decisions, and whatever this project has reported upstream (one file per upstream)
+        names += sorted(f for f in os.listdir(docs)
+                        if re.match(rf"^{re.escape(app)}-Decision-Request\.md$", f)
+                        or re.match(rf"^{re.escape(app)}-[\w.]+-Feedback\.md$", f))
     out = [os.path.join(docs, n) for n in names if os.path.exists(os.path.join(docs, n))]
     ps = os.path.join(root, "PROJECT-STATUS.md")
     if os.path.exists(ps):