qfai 2.1.1 → 2.1.2

package/assets/init/root/.agents/rules/api-budget.md

@@ -43,6 +43,154 @@ asking it once costs what asking about a single item costs.
 Three branches polled separately spend three times what the answer needs, and
 the multiplier grows with the work rather than staying put.
 
+### A first snapshot of two pull requests
+
+When git and a REST listing cannot answer the combined CI and review question,
+use aliases and a common fragment. Supply the repository owner, name and two
+pull-request numbers as variables. This query reads the first pages only.
+
+```graphql
+query PullRequestSnapshot($owner: String!, $name: String!, $firstPR: Int!, $secondPR: Int!) {
+  repository(owner: $owner, name: $name) {
+    first: pullRequest(number: $firstPR) {
+      ...PullRequestState
+    }
+    second: pullRequest(number: $secondPR) {
+      ...PullRequestState
+    }
+  }
+}
+
+fragment PullRequestState on PullRequest {
+  id
+  number
+  headRefOid
+  state
+  mergeable
+  commits(last: 1) {
+    nodes {
+      commit {
+        id
+        oid
+        statusCheckRollup {
+          id
+          state
+          contexts(first: 50, after: null) {
+            nodes {
+              __typename
+              ... on CheckRun {
+                id
+                name
+                status
+                conclusion
+                detailsUrl
+                completedAt
+              }
+              ... on StatusContext {
+                id
+                context
+                state
+                targetUrl
+              }
+            }
+            pageInfo {
+              hasNextPage
+              endCursor
+            }
+          }
+        }
+      }
+    }
+    pageInfo {
+      hasPreviousPage
+      startCursor
+    }
+  }
+  reviewThreads(first: 50, after: null) {
+    nodes {
+      id
+      isResolved
+      isOutdated
+      comments(first: 20, after: null) {
+        nodes {
+          id
+          body
+          author {
+            login
+          }
+          createdAt
+          updatedAt
+          url
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+  reviews(first: 50, after: null) {
+    nodes {
+      id
+      state
+      body
+      author {
+        login
+      }
+      submittedAt
+      commit {
+        oid
+      }
+      url
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+  comments(first: 50, after: null) {
+    nodes {
+      id
+      body
+      author {
+        login
+      }
+      createdAt
+      updatedAt
+      url
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
+    }
+  }
+}
+```
+
+- Keep a separate cursor for each PR's contexts, threads, reviews and comments,
+  and for each thread's comments. While `hasNextPage` is true, fetch that
+  connection with its own `endCursor` as `after`, retaining earlier pages.
+  Batch independent next-page requests with distinct aliases and variables;
+  never reuse one connection's cursor for another.
+- `commits(last: 1)` selects the head evidence, not the full commit history.
+  Its commit `oid` must equal that PR's `headRefOid`. Earlier commits indicated
+  by `hasPreviousPage` need not be fetched for this head check.
+- Require every page of the status and review connections before claiming
+  coverage. API errors, null PRs or required evidence, missing heads, or an OID
+  mismatch leave the snapshot incomplete. A null rollup does not prove CI passed.
+  If the head changes during pagination, discard that head's coverage and
+  collect a new snapshot. Apply the project's completion and merge rules only
+  to complete evidence for the current head.
+
+GitHub's [pull-request fields](https://docs.github.com/en/graphql/reference/pulls),
+[commit status fields](https://docs.github.com/en/graphql/reference/commits) and
+[pagination guide](https://docs.github.com/en/graphql/guides/using-pagination-in-the-graphql-api)
+define the query's fields and cursors.
+
 ## 3. Save a payload once and read it locally
 
 A log, a diff or a listing that will be searched more than once is written to
@@ -60,17 +208,48 @@ already said.
 Where the subject's duration is unknown, ask once, wait, and widen the gap as
 the wait grows.
 
+### One watcher for the task
+
+The root agent names one API watcher for recurring hosted-state checks. The
+root and all its descendants together have at most one such watcher. Other
+workers read its saved payloads and request fresh snapshots from it. Save the
+capture time, covered PRs and heads, pagination state and response headers with
+each payload so workers can judge whether it answers their question.
+
+Coordinate targets and timing with other known tasks using the same account;
+reuse their watcher where it can cover the combined set. This does not reserve
+the account or guarantee exclusive access against unknown sessions. It limits
+API polling, not workers doing local work or making necessary non-polling calls.
+
+These are operating instructions. The reminder does not elect a watcher or
+enforce the limit.
+
 ## 5. `rate_limit` is not the budget
 
-A dedicated rate-limit endpoint can report a stale or wrong figure. One has
-answered `0` calls used against a token that a real endpoint reported, minutes
-later, as most of the way through its allowance. An agent that trusts the
-endpoint reads reassurance and keeps spending.
+Read the budget from the response to a call that was going to be made anyway,
+never a dedicated `rate_limit` probe. Record that response's resource, remaining count
+and reset time. On GitHub these are `x-ratelimit-resource`,
+`x-ratelimit-remaining` and `x-ratelimit-reset`; also retain `Retry-After` when
+present. REST and GraphQL have separate primary allowances. Missing headers
+leave the budget unknown; a saved count is not a reservation for the next call.
+
+### Recover from an actual refusal
+
+When a real response refuses a request because of a rate limit, stop calls to
+the affected resource and tell the watcher and known account-sharing tasks.
+A successful HTTP status with a rate-limit error in the body is also a refusal.
+For a secondary limit, pause affected requests across REST and GraphQL for the
+same account. Changing tokens or API surfaces is not recovery.
+Wait for `Retry-After` and any applicable reset time. For a secondary limit
+with neither delay nor an exhausted primary allowance, wait at least one minute.
 
-The instrument is the response to a call that was going to be made anyway.
-Every response carries the remaining count, the reset time and the name of the
-allowance it was drawn from — and that last one is what says which allowance a
-refusal came from, where REST and GraphQL are counted separately.
+After the wait, make one real request already needed for the work. Resume that
+resource only when the request succeeds and its own headers show available
+budget. If it is refused again or the headers are missing, keep it stopped;
+do not run a retry loop or a `rate_limit` probe. Continue work that needs no
+call to that resource. GitHub's
+[rate-limit guidance](https://docs.github.com/en/graphql/overview/rate-limits-and-query-limits-for-the-graphql-api)
+describes the refusal signals and wait headers.
 
 ## The command, where there is one
 

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`)
@@ -56,55 +67,173 @@ understands. These may appear in a document written for that reader:
 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. Numbers and links belong
-there, and in commit messages and the changelog.
+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. 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
 
-## 3. 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
 

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.

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. Reply in the user's working language (.qfai/assistant/rule/communication.md), however much of what you have read this turn, such as tool output and agent reports, is in another. 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. 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."
-    }
+      "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."
   }
 }