qfai 2.1.0 → 2.1.2

package/assets/init/root/.agents/rules/documentation-clarity.md

@@ -1,25 +1,36 @@
 # Documentation Clarity
 
 The writing standard for every AI coding agent in this repository. It covers
-pull requests, issues, source-code comments and Markdown files.
+pull requests, issues, source-code comments, Markdown files, and the reports
+and replies an agent writes.
 
 Write for a reader who knows neither the background of the change nor the
-habits of this team. Keep only what that reader can follow.
+habits of this team. One test decides every clause below: if deleting a
+sentence leaves that reader no worse off, delete it.
+
+The clauses describe patterns of structure and meaning, not word lists. They
+hold in any language: the examples are English, and in another language the
+same pattern is rewritten in that language's own words.
 
 ## Scope
 
-| Surface                     | When it applies               |
-| --------------------------- | ----------------------------- |
-| Pull request title and body | On create and on update       |
-| Issue title and body        | On create and on update       |
-| Comments in source code     | Within the diff of the change |
-| Markdown files              | Within the diff of the change |
+Each surface takes the clauses shown. The clauses run in the order of writing.
+
+| Surface                     | When it applies               | Clauses   |
+| --------------------------- | ----------------------------- | --------- |
+| Pull request title and body | On create and on update       | 2 to 9    |
+| Issue title and body        | On create and on update       | 2 to 9    |
+| Comments in source code     | Within the diff of the change | 1 to 6, 9 |
+| Markdown files              | Within the diff of the change | 1 to 7, 9 |
+| Reports and replies         | When written                  | 3 to 9    |
 
 Leave everything outside the diff alone. Reformatting unrelated files is a
 separate change.
 
 ## 1. No local identifiers
 
+A reader outside this repository cannot open an internal reference.
+
 Never write these into source code or Markdown files:
 
 - issue and pull-request numbers (`#123`, `GH-123`)
@@ -29,55 +40,200 @@ Never write these into source code or Markdown files:
 When a reader needs the background, write the background itself in ordinary
 words instead of pointing at a number.
 
-Pull request and issue bodies are outside this clause. Numbers and links belong
-there, and in commit messages and the changelog.
+### Spec-tree IDs
+
+An ID the project's own spec tree defines (a business flow, story, acceptance
+criterion, example, business rule, contract or decision) names a document the
+reader can open in the repository. It is not a local identifier where that
+document is the audience or the target:
+
+- a document inside the spec tree;
+- a comment or test annotation in code or tests that points at the contract or
+  example the code carries out.
+
+It is one wherever the reader has no access to the tree: a setup guide, a
+README or any other document written for operators, and every file the project
+ships (`distributed-surface.md`). Describe the rule in words there.
+
+### Names the reader sees
+
+A name the reader meets in the product is not one that only this project
+understands. These may appear in a document written for that reader:
+
+- a screen label or button name, exactly as the product shows it;
+- an item name in a sheet or form the document tells the reader to fill in;
+- a product term the reader meets on screen.
+
+Where the reader cannot already know a term, define it once at its first use.
+Use one spelling throughout.
+
+Pull request and issue bodies are outside this clause (see Scope). Numbers and
+links belong there, and in commit messages and the changelog.
 
 ## 2. No account of how the work went
 
-What happened while the change was being designed or written stays out of the
-result:
+Ordinary specifications and change descriptions state the current behaviour
+and why. They omit design and implementation history, including:
 
 - "started as X, changed to Y"
 - "adjusted after review"
 - "temporary until Z lands"
 
-State the current behaviour and the reason it is that way. The history is
-already in the git log and the pull request; do not write it twice.
+The git log and pull request already hold this history.
+
+Only when the user expressly requests an incident, event or work record,
+include the necessary account of what happened. State the observed events,
+evidence, uncertainty, current impact and next action. Separate observations
+from interpretation.
 
-## 3. Cut
+## 3. Settle the message before writing
+
+Before the first sentence, answer three questions: who reads this, what they
+will do with it, and what the one thing is that they must take away. If the
+last cannot be said in one sentence, material is missing. Gather it before
+writing, and do not hide the gap in vague wording.
+
+- Conclusion first. The title or the opening says the result. No preamble.
+- One job per paragraph, stated in its opening sentence, and one new element at
+  a time. A second example says how it differs from the first.
+- A connective stays only where it names the relation between its two
+  neighbours.
+- Argue in one direction and conclude once. Do not end on a concession or a
+  recap.
+- A heading names the concrete subject or question. A bare label such as
+  "Overview" or "Details" says nothing and is cut, except a heading that a
+  schema or template fixes.
+- Depth follows importance: room where a decision depends on it, one line
+  elsewhere.
+- End with the decision or next action the text leads to, when there is one.
+  A short document needs no summary section.
+
+## 4. Cut
+
+Cut what the reader does not need.
 
 - Delete anything self-evident.
 - Merge repeated statements into one.
 - Shorten wordy phrasing.
-
-The test: if deleting a sentence leaves the reader no worse off, delete it.
-
-## 4. Plain language
+- Cut an identifier the reader will not meet again, such as a function name
+  mentioned once.
+- Cut a table, figure or code block the text never uses, and say what each one
+  that stays shows.
+
+### Patterns that add length and no information
+
+| Pattern                 | Shape                                                | Instead                                       |
+| ----------------------- | ---------------------------------------------------- | --------------------------------------------- |
+| Announcement            | "The key point is", "as follows", "three reasons"    | Say the point, or give the list               |
+| Recap                   | A closing paragraph that repeats the body            | Delete it, or say what follows                |
+| Empty intensifier       | "Very important", "crucial", "comprehensive"         | A number, a condition, or nothing             |
+| Padding connective      | "Furthermore" and "moreover" with no relation behind | Delete, or name the relation                  |
+| Self-answered question  | A question asked only so the next sentence answers   | State the answer                              |
+| Set filled to three     | Three items because three feels complete             | List what exists                              |
+| Repeated template       | Three sentences or paragraphs in a row of one shape  | Merge them, or give each its own shape        |
+| Contrast for rhythm     | "Not A but B" with no belief or mistake to correct   | State the claim                               |
+| Effect for its own sake | A one-line paragraph or dramatic closer for effect   | Keep only at a real turning point             |
+| Decoration              | Emoji, rule lines, ornamental dashes                 | Delete, except a line the repository requires |
+
+## 5. Plain language
+
+Use the word the reader already has, and say what happens and who does it.
 
 - Use ordinary vocabulary. Avoid coined terms and in-group phrasing.
 - State the point directly, not through a metaphor or a flourish. Write "a
   parameter worth varying", not "a dial worth turning". A metaphor carries
   associations the writer did not choose, and the reader has to translate it
   back.
-- One claim per sentence. Keep sentences short.
-- Break lines so no line is hard to scan.
-
-## 5. Make it readable at a glance
+- Read a figurative or inflated verb ("dive into", "tackle head-on",
+  "leverage", "dissolve") literally. If it is not literally true, replace it
+  with the act.
+- Name who acts. Software does not know, want or decide: say what the program
+  does, or who chose. Where the reader needs to know who performed an act, do
+  not leave that out.
+- Use concrete nouns. Name the file, the number, the date or the version
+  instead of "some", "many", "various", "the tool" or "the system".
+- One word per concept, defined before first use, with the function before the
+  name. Use the field's standard term, and do not stretch jargon into a
+  metaphor.
+- One claim per sentence. Keep sentences short. A sentence that nests more than
+  two conditions or negations, or buries three coordinate items, is split, and
+  the items become a list.
+
+## 6. Say how sure you are, and on what basis
+
+The reader acts on the certainty a sentence shows, so show the real one.
+
+- Mark a claim the reader would otherwise take as verified: say whether it is
+  a fact, an inference or an opinion. A fact names its source: a file, a
+  command and its output, a link.
+- Hedge only a real uncertainty, and say what is unconfirmed and how to confirm
+  it. A stack of hedges ("may possibly tend to") is deleted.
+- A causal claim carries a one-sentence mechanism. An event with several causes
+  is not reduced to one, and an example must support the whole claim, not part
+  of it.
+- Never turn "under investigation" into a result, a plan into finished work, or
+  program behaviour into somebody's decision.
+
+## 7. Make it readable at a glance
+
+Layout carries the structure the sentences would otherwise have to state.
 
 - Parallel items become a bullet list.
 - Three or more paired values become a table.
 - Ordered steps become a numbered list.
+- A chain of cause and effect stays in prose. A list drops the "because"
+  between items.
+- Bold marks the one thing a skimmer must not miss, once or twice per section.
+  Bold on many phrases makes none stand out.
+- Break lines so no line is hard to scan.
 
-## 6. Re-read what you wrote
-
-Read every line you changed and check two things:
-
-1. Is any phrasing still hard to follow?
-2. Does any sentence read as a literal translation?
-
-An agent that reasons in one language and writes in another leaves translation
-artefacts behind. This happens in every language pair. Rewrite the sentence
-the way someone writing natively in that language would put it.
+## 8. Reports and replies
+
+A report to the user is a document: a status update, a review result or a
+final summary. § 3 applies, so the opening is the outcome (done, partly
+done, blocked or failed) and the ending is what the reader must decide or do,
+when something is owed. A report also needs these:
+
+- Separate what was verified, with the command and its result, from what was
+  not run or not checked. Never write "verified" for something unrun.
+- List what changed by its effect, not every step taken. Name work that was not
+  requested, and work that remains, as such.
+- State a failure with its evidence. Do not soften it with a hedge or bury it
+  below good news.
+
+## 9. Re-read what you wrote
+
+Read every line you changed once for each question that applies to its
+surface (see Scope).
+
+| Question                                                                             | Clause |
+| ------------------------------------------------------------------------------------ | ------ |
+| Is there a number, ticket or private name the reader cannot open?                    | 1      |
+| Does any design or implementation history fall outside clause 2's exception?         | 2      |
+| Does the opening carry the result, and does each paragraph do one job?               | 3      |
+| Is anything left that clause 4 cuts?                                                 | 4      |
+| Is any word figurative, vague or missing its actor?                                  | 5      |
+| Does each claim show the certainty it has, with its basis?                           | 6      |
+| Does the layout show the structure?                                                  | 7      |
+| Does a report open with its outcome and separate what was checked from what was not? | 8      |
+
+When the user expressly requested an incident, event or work record, apply
+clause 2's exception before cutting the account of what happened.
+
+Last, check for a sentence that reads as a literal translation. An agent that
+reasons in one language and writes in another leaves translation artefacts
+behind, in every language pair. Rewrite the sentence the way someone writing
+natively in that language would put it.
+
+A pattern is a candidate, not a verdict. Keep a phrase that is literally true
+and that the reader needs, and rewrite one that only matches the shape.
+
+After a rewrite, compare it with the text it replaced. Nothing is added or
+lost: no condition, cause, actor or number is added, no constraint, warning or
+mandatory step is dropped or weakened, the certainty is unchanged, and every
+reference still points at the same thing. Read again until a pass finds
+nothing new. A finding that keeps coming back means the paragraph is wrong in
+its structure: rewrite the paragraph.
 
 ## Automatic reminder
 
@@ -92,8 +248,9 @@ standard at the two moments it is easiest to forget:
 Each hook prints one message from `.agents/rules/reminders.json`, with no
 network, and a missing file prints nothing. Claude Code runs `node` directly,
 with no shell. Codex runs it as one command line, the same under every shell,
-once the project's hooks are trusted, and reminds after a patch that adds or changes a Markdown file. Delete
-the entries from both files to turn the reminder off; the rule still applies.
+once the project's hooks are trusted, and reminds after a patch that adds or changes a
+Markdown file. Delete the entries from both files to turn the reminder off; the
+rule still applies.
 
 The `gh` command line is out of scope. A shell-argument condition also matches
 compound commands that have nothing to do with GitHub, which would put the

package/assets/init/root/.agents/rules/grilling.md

@@ -225,7 +225,7 @@ fact, say what depends on it, and leave the answer to them.
 **A value with no candidates goes through the tool's free-text path.**
 `user-questions.md` § 2 names that path for exactly this shape. Where the round
 falls back to plain text the value is put as a plain request instead — for one
-of the three reasons above, never because the answer is a value. Reaching past a
+of the three reasons above, never because the answer is a value. Not using a
 free-text path the tool has drops the structure for nothing. Where the
 candidates are listable the question is a choice, which the classifier above
 already settles.
@@ -354,8 +354,8 @@ lookup could have reached.
 
 Where a document requires the field to hold something, write the defaulted value
 and label it an assumption beside the open question. What is forbidden is the
-assumption on its own: unread, it is a decision nobody took, wearing the face of
-one somebody did.
+assumption on its own: unread, it is a decision nobody took, recorded as if
+somebody had.
 
 **A fact declared undefaultable stops the run.** There is no value to write
 down: the agent does not hold it, a guessed one is the corruption the tree warns
@@ -378,7 +378,7 @@ decision. An agent that builds one, judges it, and carries on has settled a
 question of taste on the user's behalf, which is the thing this rule spends
 every round avoiding.
 
-Talking through such a question is where a session balloons: you keep
+Talking through such a question is where a session grows without bound: you keep
 rephrasing, the user keeps guessing, and the scope grows to fill the
 uncertainty.
 

package/assets/init/root/.agents/rules/interface-clarity.md

@@ -30,9 +30,9 @@ takes its label from the user's word for the thing, never from the parameter it
 fills.
 
 Out: internal identifiers, model and table names, request shapes, retry counts,
-flags, and every knob a library underneath exposes because it exposes it.
+flags, and every setting a library underneath exposes because it exposes it.
 
-A setting earns a control when someone needs to change it, not when it exists.
+A setting gets a control when someone needs to change it, not when it exists.
 
 ## 2. Do not explain the interface
 
@@ -73,8 +73,8 @@ the user is worse off. If not, it goes.
 - The pattern the platform already has, in the place users look for it.
 - One word per concept — the user's word — everywhere it appears.
 
-A novel interaction has to beat the familiar one by enough to pay for being
-learned. Most do not.
+A novel interaction has to beat the familiar one by more than the cost of
+learning it. Most do not.
 
 ## 5. Show the structure
 
@@ -97,7 +97,7 @@ Cutting stops here. None of these is excess at any size.
 
 - **The label.** WCAG 3.3.2 requires a label for every form input, and a
   placeholder standing in for one is a documented failure. The label names the
-  control; an explanation apologises for it. This rule deletes the second and
+  control; an explanation makes up for a control that does not say so. This rule deletes the second and
   protects the first.
 - Accessible names, roles and states, and a focus order that follows the reading
   order.

package/assets/init/root/.agents/rules/minimal-implementation.md

@@ -62,9 +62,9 @@ is still a Change Request.
 The ladder trims code, not obligations. These stay whatever rung you stop at.
 
 - Required traceability annotations.
-  The execution ledger and Article V links also stay: BF → US → AC → EX →
-  Tests → Code → Verification evidence. A BR lives in its enforcing contract
-  and cites the relevant EX.
+  The Article V links also stay: BF → US → AC → EX → Tests → Code →
+  Verification evidence. A BR lives in its enforcing contract and cites the
+  relevant EX.
 - Repository quality gates and their verification evidence.
 - Validation of input crossing a trust boundary.
 - Error handling that prevents data loss.
@@ -156,6 +156,14 @@ a case that cannot happen.
 An addition someone does want is its own change, or an expansion declared under
 Article VII of `.qfai/assistant/rule/constitution.md`.
 
+- **A fix nobody asked for**, such as a pre-existing bug or a performance
+  concern, is reported as a follow-up. A fix the requested behaviour cannot work
+  without stays in. The change's report names it, and it needs no expansion
+  declared under Article VII.
+- **An ambiguous request**, where the work goes ahead on an assumption, is built
+  only for the reading the wording and the surrounding code most directly support.
+  State the assumption. Whether to ask instead is `grilling.md`'s to decide.
+
 ## 5. What this rule is not
 
 - Not a licence to skip a requirement. The spec is the authority.

package/assets/init/root/.agents/rules/reminders.json

@@ -2,14 +2,16 @@
   "structured-question": {
     "hookSpecificOutput": {
       "hookEventName": "UserPromptSubmit",
-      "additionalContext": "QFAI user questions (.agents/rules/user-questions.md). Every question you put to the user this turn goes through the host's structured question tool where it is callable, and through that rule's fallback where it is not — carrying the same parts either way. No question is light enough to skip it: a yes-or-no, a confirmation and a \"just checking\" are each a question. A turn that leaves the next step to the user ends with such a question, listing the next actions with the recommended one first, never with a status report or an offer in prose. Read the rule rather than working from this line."
-    }
+      "additionalContext": "QFAI user questions (.agents/rules/user-questions.md). Put every question through the host's structured question tool where callable, and through that rule's fallback where it is not, with the same parts. No question is light enough to skip it. Ask only when the next step needs the user's answer. Background waiting and completion-only reports need no question. State the current state, awaited evidence or result and the resume condition; promise no unsupported automatic restart. Dismissal or silence is no answer or permission. Existing delegation can cover a routine choice; it cannot supply a hard-required fact or uncovered approval, override cancellation or bypass an explicit tool block. Requested free-text values resume the waiting step; independent instructions need a new plan; split mixed replies and infer no option approval. Reply in the user's working language (.qfai/assistant/rule/communication.md). Read the rule."
+    },
+    "briefContext": "QFAI user questions: read .agents/rules/user-questions.md; ask in the answer's shape only when an answer is needed; waiting and completion reports need none; reply in the user's working language."
   },
   "free-text-entry": {
     "hookSpecificOutput": {
       "hookEventName": "UserPromptSubmit",
-      "additionalContext": "QFAI free-text entry (the `qfai-run` skill). When the user's message asks for a change, a fix, an investigation of the codebase or a question about the project and names no skill, invoke the `qfai-run` skill for it before any other work. A message that names a skill goes to that skill. A question that one command or one file read answers needs no run: answer it directly. If `qfai-run` cannot start, stop and say so; do not answer without the workflow. `qfai-run` itself tells a reply to a run in progress from a new request. Read the skill rather than working from this line."
-    }
+      "additionalContext": "QFAI free-text entry (the `qfai-run` skill). When the user's message asks for a change, a fix, an investigation of the codebase or a question about the project and names no skill, invoke the `qfai-run` skill for it before any other work. A message that names a skill goes to that skill. A question that one command or one file read answers needs no run: answer it directly. If `qfai-run` cannot start, stop and say so; do not answer without the workflow. Plan new requests; a pending answer or requested operation result resumes the current step without a new invocation. An answer after request-info has closed follows its declared branch. An ambiguous reply implies no success, fact or approval. Read the skill rather than working from this line. In a git worktree, read `.claude/skills/qfai-run/SKILL.md` under the current directory, since the host may have loaded another checkout's copy of it."
+    },
+    "briefContext": "For new requests, use qfai-run to plan; pending answers or requested operation results resume the current step."
   },
   "qfai-not-installed": {
     "hookSpecificOutput": {
@@ -20,49 +22,60 @@
   "documentation-clarity-before-post": {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
-      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). Before this title or body ships: no issue or PR numbers, ticket IDs or team-local jargon in source and docs; no account of how the work went, only the current behaviour and why; cut self-evident, repeated and wordy text; ordinary words, one claim per sentence, short lines; bullet lists and tables for parallel items; then re-read every line and rewrite anything that reads as a literal translation."
+      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). PR and issue bodies may contain numbers and links. No issue or PR numbers, ticket IDs or team-local jargon in source or ordinary Markdown; keep the rule's existing exceptions. Ordinary specifications and change descriptions omit design and implementation history. Only when the user expressly requests an incident, event or work record, include necessary observed events, evidence, uncertainty, current impact and next action. Put the conclusion first. Cut self-evident, repeated or wordy text, announcements, recaps and empty intensifiers. Use ordinary words, name who acts, one claim per sentence, short lines, and lists or tables for parallel items. Also mark what is unverified. Re-read every changed line and rewrite literal translations or anything that matches a pattern in the rule."
     }
   },
   "grilling-design-artifact": {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
       "additionalContext": "QFAI grilling (.agents/rules/grilling.md). Before this: is a decision about to be fixed that the request needs and the repository cannot settle? Outside the discussion stage, settle it between agents and take the griller's recommendation; ask the user only a critical decision — one that contradicts a spec, a contract or a recorded decision, one whose effect cannot be taken back, or product intent nothing written states. Do not ask about, or add, what the request did not need. Read the rule rather than working from this line."
-    }
+    },
+    "briefContext": "QFAI grilling: read .agents/rules/grilling.md before fixing a required decision; consult agents and bring only critical decisions to the user."
   },
   "grilling-delegation": {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
       "additionalContext": "QFAI grilling (.agents/rules/grilling.md). Before this: is a decision about to be fixed that the request needs and the repository cannot settle? Outside the discussion stage, settle it between agents and take the griller's recommendation; ask the user only a critical decision — one that contradicts a spec, a contract or a recorded decision, one whose effect cannot be taken back, or product intent nothing written states. Do not ask about, or add, what the request did not need. Read the rule rather than working from this line."
-    }
+    },
+    "briefContext": "QFAI grilling: read .agents/rules/grilling.md before fixing a required decision; consult agents and bring only critical decisions to the user."
   },
   "grilling-plan": {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
       "additionalContext": "QFAI grilling (.agents/rules/grilling.md). Before this: is a decision about to be fixed that the request needs and the repository cannot settle? Outside the discussion stage, settle it between agents and take the griller's recommendation; ask the user only a critical decision — one that contradicts a spec, a contract or a recorded decision, one whose effect cannot be taken back, or product intent nothing written states. Do not ask about, or add, what the request did not need. Read the rule rather than working from this line."
-    }
+    },
+    "briefContext": "QFAI grilling: read .agents/rules/grilling.md before fixing a required decision; consult agents and bring only critical decisions to the user."
   },
   "documentation-clarity-after-write": {
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
-      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). For the Markdown just written, inside this change only: no issue or PR numbers, ticket IDs or team-local jargon; no account of how the work went, only the current behaviour and why; cut self-evident, repeated and wordy text; ordinary words, one claim per sentence, short lines; bullet lists and tables for parallel items; then re-read every line and rewrite anything that reads as a literal translation."
-    }
+      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). For the changed source and ordinary Markdown: no issue or PR numbers, ticket IDs or team-local jargon; keep the rule's existing exceptions. Ordinary specifications and change descriptions omit design and implementation history. Only when the user expressly requests an incident, event or work record, include necessary observed events, evidence, uncertainty, current impact and next action. Put the conclusion first. Cut self-evident, repeated or wordy text, announcements, recaps and empty intensifiers. Use ordinary words, name who acts, one claim per sentence, short lines, and lists or tables for parallel items. Also mark what is unverified. Re-read every changed line and rewrite literal translations or anything that matches a pattern in the rule."
+    },
+    "briefContext": "QFAI documentation clarity: read .agents/rules/documentation-clarity.md for every changed line, keeping its exceptions and marking what is unverified."
   },
   "documentation-clarity-after-edit": {
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
-      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). For the Markdown just edited, inside this change only: no issue or PR numbers, ticket IDs or team-local jargon; no account of how the work went, only the current behaviour and why; cut self-evident, repeated and wordy text; ordinary words, one claim per sentence, short lines; bullet lists and tables for parallel items; then re-read every line and rewrite anything that reads as a literal translation."
-    }
+      "additionalContext": "QFAI documentation clarity (.agents/rules/documentation-clarity.md). For the changed source and ordinary Markdown: no issue or PR numbers, ticket IDs or team-local jargon; keep the rule's existing exceptions. Ordinary specifications and change descriptions omit design and implementation history. Only when the user expressly requests an incident, event or work record, include necessary observed events, evidence, uncertainty, current impact and next action. Put the conclusion first. Cut self-evident, repeated or wordy text, announcements, recaps and empty intensifiers. Use ordinary words, name who acts, one claim per sentence, short lines, and lists or tables for parallel items. Also mark what is unverified. Re-read every changed line and rewrite literal translations or anything that matches a pattern in the rule."
+    },
+    "briefContext": "QFAI documentation clarity: read .agents/rules/documentation-clarity.md for every changed line, keeping its exceptions and marking what is unverified."
   },
   "minimal-implementation": {
     "hookSpecificOutput": {
       "hookEventName": "PostToolUse",
       "additionalContext": "QFAI minimal implementation (.agents/rules/minimal-implementation.md). A source file just changed, which is this reminder's trigger and not the rule's scope: could it not exist at all, is it already in this codebase, or does the standard library, the platform or an already-installed dependency do it? The same rungs run at a design stage that decides where a capability or a body of data comes from. Otherwise the least code that works. Mark a deliberate shortcut with both its ceiling and the condition that lifts it. The ladder never removes what § 2 of that rule lists. For a change to a screen or to terminal output, .agents/rules/interface-clarity.md governs what may appear."
-    }
+    },
+    "briefContext": "QFAI minimal implementation: read .agents/rules/minimal-implementation.md, including its mandatory floor in § 2, and .agents/rules/interface-clarity.md before deciding what to implement."
   },
   "api-budget": {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
       "additionalContext": "QFAI API budget (.agents/rules/api-budget.md). Before this call: can git answer it instead? Then REST, then GraphQL — the forge's own pull-request and issue subcommands take the GraphQL path, a separate allowance counted in points. One call for the whole set, not one per branch. Save a payload once and search the file; a second grep is not a second download. Poll no faster than the thing being polled changes. A rate-limit endpoint misreports the budget: read the remaining count off this response's own headers. The allowance belongs to the account, and every session and sub-agent draws on it at once. Read the rule rather than working from this line."
-    }
+    },
+    "briefContext": "QFAI API budget: read .agents/rules/api-budget.md; use git before REST before GraphQL and reuse saved results."
+  },
+  "session-feedback": {
+    "decision": "block",
+    "reason": "QFAI session feedback (.agents/rules/session-feedback.md). A turn is ending. Decide first, from the whole session: is every task the user gave you complete, and is nothing waiting on the user: no question, approval or choice? If not, or if you already ran this review after the user's latest instruction, reply with one short line and stop. Otherwise read the rule and follow it: review the session for problems in QFAI itself (its rules, skills, steps, commands, hooks and documents, and what using them cost), and draft one issue for each, with none of the project's names, source, secrets or personal data. If nothing is worth reporting, say so in one line. If something is, ask the user through the structured question tool whether to file, showing each draft, and file to the QFAI repository only the drafts they approve. Under a no-question mode ask nothing and file nothing: put the drafts in your final report."
   }
 }

package/assets/init/root/.agents/rules/session-feedback.md

@@ -0,0 +1,136 @@
+# Session Feedback
+
+What an agent does once, when every task the user gave it is complete: review
+the whole session for problems in QFAI itself, and ask the user whether to
+report them.
+
+An agent in a session notices what a maintainer cannot see from outside: a rule
+that contradicted another, a gate that stopped correct work, a step that cost an
+hour for a small result. The notice ends with the session unless something
+carries it out. This rule carries it to the QFAI repository, at the moment the
+agent holds the most evidence, and only with the user's agreement.
+
+## Scope
+
+| Target                                                                    | Applies                                    |
+| ------------------------------------------------------------------------- | ------------------------------------------ |
+| The end of the turn after which no task the user gave is left             | Reviewed                                   |
+| A pause: a question, an approval, a phase boundary, a halt, a next action | Not reviewed                               |
+| A problem in the adopter's own project                                    | Outside this rule                          |
+| A problem in QFAI's rules, skills, steps, commands, hooks or documents    | Reported once the user agrees              |
+| A run under a no-question mode                                            | Drafted into the final report, never filed |
+
+## 1. When the review runs
+
+Only when both hold, judged from the whole session:
+
+1. Every task the user gave is complete, in every stage the plan chose.
+2. Nothing waits on the user: no question, approval or choice is open.
+
+A turn that ends with a question, a plan awaiting approval or a list of next
+actions is a pause. So is the end of one stage of several. If the user's next
+answer would start more work, the work is not complete.
+
+The `Stop` hook puts the question at the end of a turn, because no hook can see
+whether the user's work is done. The agent answers it from the session. When the
+work is not complete, or the review already ran after the user's latest
+instruction, the agent replies with one short line and stops. In doubt, the work
+is not complete.
+
+> SIMPLIFIED: the hook fires at every end of turn that does not end in a
+> question mark, a statement-style pause included, and the agent declines it
+> when the work is not complete, which costs one short extra turn and the
+> message each time.
+> Lift when: the host reports whether the user's work is complete.
+
+## 2. What to review
+
+The whole session, for these, where QFAI caused or contributed to them:
+
+- **Blockers.** A gate, check or rule that stopped correct work.
+- **Structural problems and contradictions.** Two rules, specs or skills asking
+  for incompatible things, or text that points at nothing.
+- **Lost efficiency.** Repeated steps, waiting, and rework that a rule or
+  command caused.
+- **Tokens against output.** Large reads, repeated loads and long ceremony for a
+  small result.
+- **Poor value.** A mechanism whose cost for this work exceeded what it gave.
+- **Over-work.** Work beyond the request because a rule or step required it.
+- **Quality that missed the user's wish.** Output the user had to correct or
+  reject, and the QFAI guidance that led there.
+
+A finding names its evidence: the command, finding code, message or shipped file.
+A feeling without evidence is not a finding. A figure is given only when the
+session measured it, and an estimate says so.
+
+## 3. What a draft holds
+
+One draft for each problem, never a log of the session. Each holds:
+
+- a title that states the problem in one line;
+- what happened, with the QFAI command, finding code or shipped file named;
+- the cost, in time, tokens or rework;
+- what would have helped, as a suggestion.
+
+Write it for a maintainer who has not seen the session, in English, whatever
+language the session used. `documentation-clarity.md` sets the writing standard.
+
+A draft carries none of these: the name of the project or its organisation, a
+repository address, source code, a path of the project's own, a secret, personal
+data, or the user's words beyond what the problem needs. A path under what QFAI
+ships is fine. Generalise the rest.
+
+A message quoted from the session has the project's paths, IDs and names
+replaced by placeholders. Nothing else is quoted from the project's files or
+tool output.
+
+## 4. Ask before filing
+
+Put one question to the user through the host's structured question tool, in the
+form `user-questions.md` sets out:
+
+- one option for each draft, labelled by its title and described by what it
+  reports and the cost it names, with the full text of every draft shown beside
+  the question;
+- more than one may be chosen, and choosing none files nothing;
+- the recommendation first, with its reason.
+
+A requested change to a draft is made, and the question is put again. Filing is
+visible to others, so the answer covers the drafts shown and nothing wider
+(`action-reversibility.md`).
+
+When the review finds nothing worth reporting, say so in one line and ask
+nothing.
+
+## 5. Filing
+
+For each approved draft, write the body to a scratch file
+(`temporary-files.md`) and file it once:
+
+```sh
+gh issue create --repo aganesy/QFAI --title '<title>' --body-file <file>
+```
+
+The title is plain words: no backtick, `$`, or quote in it, so the shell
+expands nothing. Report each issue's address. Where `gh` is missing or not signed
+in, give the user the title and body to post at
+`https://github.com/aganesy/QFAI/issues/new`. Never ask for, read or enter a
+credential.
+
+## 6. Under a no-question mode
+
+Nothing is asked and nothing is filed. The drafts go in the final report, and
+the report says they were not filed.
+
+## Related
+
+- The form of the question: `user-questions.md`
+- Why filing needs an answer: `action-reversibility.md`
+- The writing standard for a draft: `documentation-clarity.md`
+- Where the scratch file goes: `temporary-files.md`
+
+## Scope of this file
+
+This is the master copy for every AI coding agent in this repository.
+Tool-specific instruction files point here instead of restating it. Edit this
+file when the rule changes.