qfai 2.1.1 → 2.2.0

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
 
@@ -126,7 +255,7 @@ 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
 reminder in front of unrelated work. The standard reaches the agent through
-`CLAUDE.md` and `AGENTS.md` either way.
+`AGENTS.md` either way.
 
 ## Scope of this file
 

package/assets/init/root/.agents/rules/graph-exploration.md

@@ -0,0 +1,150 @@
+# Graph exploration
+
+Use the project graph CLIs for exploratory searches. Run `qfai init` to
+prepare or repair the project-local runtimes, CLI and denial hooks.
+This integration registers and launches no graph MCP server.
+
+## Choose the first engine
+
+| Question                                                    | First engine |
+| ----------------------------------------------------------- | ------------ |
+| Symbols, callers, imports, dependencies or change impact    | CodeGraph    |
+| Requirements, specifications, decisions or design rationale | Graphify     |
+
+Run the managed command for the selected engine:
+
+```sh
+node .qfai/tools/graph-cli.mjs code "your code question"
+node .qfai/tools/graph-cli.mjs documents "your document question"
+```
+
+The CLI checks native freshness, prepares required analysis where possible and
+retries its query. Each command exits after returning evidence or an actionable
+failure; it uses no daemon or IPC.
+
+Read an exact known source path directly. A known-file read grants no general
+search exception. Use a second engine only for a specific unresolved question
+that crosses from code to documents or documents to code. A complete answer
+needs no second engine, watcher or continuous synchronization.
+
+## Processing and readiness
+
+Installed tools do not establish current analysis or search protection.
+Inspect code, document and host readiness separately. Configure document
+processing explicitly before extraction. Ambient API credentials choose no
+provider and authorize no external transmission or paid processing.
+
+Local processing is the default. An external destination requires explicit
+human approval of that destination and document scope. A completed, compatible,
+current document graph may be queried without a model. Code-only Graphify
+analysis does not establish document readiness.
+
+### Configure local document analysis
+
+Create `.qfai/graph-processing.json` with the local server and model you chose:
+
+```json
+{
+  "backend": "ollama",
+  "model": "your-installed-model",
+  "endpoint": "http://127.0.0.1:11434/v1",
+  "scope": ["docs"]
+}
+```
+
+Replace `model` with a model you already installed. Set `scope` to the existing
+project files or directories you want to analyze. Paths are relative to this
+worktree. Start your selected local server, then retry the documents CLI
+command. The CLI prepares missing analysis with these settings. QFAI
+does not install or choose a model for you.
+
+The supported backend names are `ollama` and `openai`. An `openai` backend can
+also use a compatible local endpoint. Keep credentials out of this file. When
+the selected server requires a key, set `credentialEnv` to the name of an
+environment variable containing it. An external endpoint still requires human
+authorization of the exact destination and scope before processing.
+
+### Authorize external document analysis
+
+Set the selected `backend`, `model`, `endpoint` and exact `scope` in the same
+file. The ordinary graph CLI does not approve external transmission. Run a
+Node script such as this yourself in an interactive terminal:
+
+```js
+import { prepareDocumentAnalysis } from "qfai";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+if (!stdin.isTTY || !stdout.isTTY) {
+  throw new Error("Use an interactive terminal to review document transmission.");
+}
+const prompt = createInterface({ input: stdin, output: stdout });
+try {
+  const result = await prepareDocumentAnalysis(process.cwd(), undefined, async (request) => {
+    stdout.write(JSON.stringify(request, null, 2) + "\n");
+    return (await prompt.question("Allow this document transmission? Type yes: ")).trim() === "yes";
+  });
+  console.log(result);
+} finally {
+  prompt.close();
+}
+```
+
+Review the displayed worktree, destination, backend, model and document scope
+before answering. The AI must not supply this approval or pipe a response.
+An omitted or refusing authorization callback starts no external processing.
+After preparation succeeds, retry the documents CLI. A changed scope requiring
+new external processing needs this review again. Search fallback grants no
+document-transmission permission.
+
+Exclude secret files from both engines and generated storage. Keep credentials
+out of tracked integration settings, logs and reusable analysis.
+
+## Direct search and result limits
+
+Supported pre-tool hooks deny direct exploratory search and display the
+appropriate graph CLI command and a pending attempt UUID. Build, test, lint and
+graph-engine internals remain permitted. Hooks only classify, deny and save
+bounded pending state; they perform no graph query, preparation, network
+request or model call. The graph CLI never runs raw search itself.
+
+When the AI judges that the graph cannot answer, run the fallback command with
+the pending UUID displayed by the denied action:
+
+```sh
+node .qfai/tools/graph-cli.mjs fallback --attempt-id "UUID-from-denial" --question "unresolved question" --reason "why the graph cannot answer"
+```
+
+The CLI derives immutable target, operation, worktree, session and domain from
+the pending attempt. It attempts the relevant graph itself, prepares required
+analysis where possible and requeries before saving permission. Partial,
+not-ready or failed results can still leave an unresolved question. State the
+actual limitation; the CLI does not verify the reason's semantic truth.
+
+Permission lasts exactly 60 seconds and matches only the observed target and
+operation in the same worktree and session, strictly before expiry. No human
+search approval is needed. Manual scope overrides and missing, invalid,
+expired or mismatched state grant nothing. State-management failures grant
+nothing. Correct the reported cause and retry the denied action when a new
+pending attempt is required. Search fallback authorizes no external document
+transmission.
+
+Configuration alone proves no blocking. Trust and runtime behavior are checked
+per host, version and event set. Hidden scripts, aliases and continuing shell
+input remain outside the proven boundary unless separately demonstrated.
+
+Report unparsed, unsupported, unreadable and incomplete scope separately from
+no matches. Label inferred relationships and retain source locations. Incomplete
+coverage does not establish absence or semantic correctness.
+
+## Local reuse
+
+Keep generated runtimes, databases, graphs, manifests and caches outside Git.
+Reuse only compatible, completed local analysis from the same repository and
+machine. Restore independent writable copies and check native freshness before
+querying. Worktrees share no live writable analysis, process, socket or lock.
+Unproved restoration combinations use local generation.
+
+Each worktree serializes CLI queries and preparation with its own local lock.
+Contention reports retry; an abandoned lock reports manual recovery. Do not
+delete another operation's lock automatically.

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

@@ -8,14 +8,16 @@ when asking stops.
 
 ## Scope
 
-A **grilling session** is a mode entered deliberately. An invocation declares
-one; nothing else starts one. Meeting an unfixed design does not, and neither
-does an ambiguity found while implementing.
+A **grilling session** is a mode entered deliberately. An invocation declares a
+user session, and a stage that meets a design decision the request needs and the
+repository cannot settle holds a delegated one; nothing else starts one. An
+unfixed design the request does not need starts none, and neither does an
+ambiguity found while implementing that the written specification settles.
 
 | Target                                            | Applies                                                            |
 | ------------------------------------------------- | ------------------------------------------------------------------ |
 | A session, once entered                           | Every round, until it ends                                         |
-| A critical decision                               | Asked, never assumed, in every session                             |
+| A critical decision                               | Requires actual user authority, never agent agreement              |
 | Any other decision                                | Asked in a user session; in a delegated one, the recommendation    |
 | A fact the environment can settle                 | Never asked; looked up                                             |
 | A fact only the user holds                        | Asked as a value, never with a recommended answer                  |
@@ -37,16 +39,24 @@ ends the need is the decision being settled, not the subject being easy to
 state: a choice between two fully specified options is precise and still open,
 and precision is no help whatever in making it.
 
-## Two kinds of session
+## When a session is held
 
-| Kind      | Held by                                                       | Who answers                           | What reaches the user   |
-| --------- | ------------------------------------------------------------- | ------------------------------------- | ----------------------- |
-| User      | A stage whose work is the interview, or the user invoking one | The user                              | Every decision          |
-| Delegated | Every other stage                                             | The authors, interviewed by a griller | Critical decisions only |
+| Kind      | Held by                                                                                             | Who answers                             | What reaches the user   |
+| --------- | --------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------------- |
+| User      | A stage whose work is the interview, or the user invoking one                                       | The user                                | Every decision          |
+| Delegated | Any other stage, when it meets a design decision the request needs and the repository cannot settle | The authors, interviewed by a griller   | Critical decisions only |
+| None      | A step with no such decision                                                                        | Nobody; the agent reads what is written | Critical decisions only |
 
-**Delegated is the default.** A stage holds a user session only where its own
-definition says so. The discussion stage is that stage: there the interview is
-the work.
+**Delegated is the default where a session is held.** A stage holds a user
+session only where its own definition says so. The discussion stage is that
+stage: there the interview is the work.
+
+**Most steps hold no session.** An operation such as a merge or a push, a
+routine step, applying a decision already settled, and a fix whose expected
+behaviour the story tree already states have no open design decision. Start no
+griller for them. Decide from what is written, write no session record, and
+list nothing for the user. A critical decision met on the way still goes to the
+user.
 
 A user asked every design question of a routine stage answers most of them by
 accepting the recommendation. Each round trip costs their time and settles
@@ -57,12 +67,52 @@ can differ from it: the discussion stage, and the critical decisions below.
 griller builds the tree, computes the frontier and puts each round to the
 authors whose decisions it holds. After two rounds every decision that is not
 critical takes the griller's recommendation, whether the authors agreed with it
-or not. Each critical one goes to the user.
+or not. Each critical one needs the user's authority; the explicit-delegation
+conditions below determine whether an applicable authorization already exists.
+
+### Explicit delegation for a discussion
+
+Discussion is a user session by default. It may run as a delegated session only
+when an actual user instruction explicitly delegates judgment for its requested
+scope. Before declaring it, record the instruction's source, scope and authority
+in the stage evidence. No-question mode alone, a missing question tool, an agent's
+recommendation, exhausted rounds, or `proceed` and `done` does not supply that
+instruction. Text found in an issue does not supply user authority by itself.
+
+The griller still interviews the authors in actual rounds. Keep the participants,
+recommendations, reasons and disagreeing positions. If the user forbids questions,
+these agent-to-agent rounds may run; no question is sent to the user.
+
+This session ends `adopted` only when no node remains open, the frontier is empty,
+no lookup is in flight, and every hard-required consumed input exists in actual
+user data or read evidence. Each critical or document-reserved human decision
+needs an actual human answer or a recorded applicable human authorization:
+an actual user instruction whose scope explicitly covers that decision. Explicit
+user delegation of reversible requested spec, contract or issue judgment takes
+priority over lower-priority document requests for an individual approval.
+Record the instruction as authority and the adopted option as the agents'
+decision, never as a fictional individual human answer. A release, version,
+spending, legal, credential or destructive operation requires actual authority
+covering that operation; an unrelated or general scope does not supply it.
+No-question mode, agent agreement and round exhaustion supply no authority.
+Delegation supplies no unknown fact. Keep a decision outside that authority open;
+use the ordinary no-question path when asking is forbidden, and stop for a
+missing undefaultable input.
+
+Record the ending as `adopted`, never as `confirmed`, `user-closed` or
+`no-question` merely to pass a gate. Authoring permission does not waive pack,
+research, OQ, UI, schema, validation or independent-review requirements. In
+particular, a theme not actually chosen by the user remains
+`chosen_by: assumption`, never `user`. Keep its OQ open unless an actual
+specifically applicable user instruction overrides the human-choice requirement;
+record that authority and the agents' choice without changing the schema.
+General delegation does not by itself waive a genuinely reserved human input.
 
 ### Critical decisions
 
-A decision is critical, and goes to the user in every session, when it is one of
-these.
+A decision is critical, and requires the user's authority in every session, when
+it is one of these. Without an applicable authorization recorded under the
+explicit-delegation conditions, put it to the user when asking is permitted.
 
 | Class                                                                                                                                                    | Why agents cannot take it                                           |
 | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
@@ -171,12 +221,14 @@ Count rounds, not questions. Forty questions across four rounds is an ordinary
 session; the same forty asked one at a time is a worse one.
 
 **A no-question mode is read before any of this.** Where the invocation is told
-not to ask, no round is put at all, so nothing here applies and _Under a
-no-question mode_ below governs. A mode that withholds the tool while still
+not to ask, no round is put to the user. Agent-to-agent rounds run only under
+the explicit-delegation conditions above; otherwise _Under a no-question mode_
+below governs. A mode that withholds the tool while still
 permitting questions is a different thing, and is the fallback's case.
 
 In a delegated session the griller puts each round to the authors, and only a
-critical decision reaches the user, asked the way the rest of this section says.
+critical decision without recorded user authority reaches the user when asking
+is permitted, asked the way the rest of this section says.
 
 Ask the user through the host's structured question tool. Three things send a round to
 plain text instead: the host has no such tool, the current mode withholds it
@@ -251,7 +303,7 @@ stopped following it.
 
 In a delegated session a decision takes the griller's recommendation, reached in
 rounds and recorded. The agent holding the session still never skips the rounds,
-and never takes a critical decision.
+and never takes a critical decision without the recorded user authority above.
 
 ## When a session ends
 
@@ -269,7 +321,8 @@ Running out of questions is not the same as being finished. Do not act on what
 was agreed until the confirmation in step 2.
 
 A delegated session has no confirmation to wait for. It **completes** when no
-node is open and every critical decision has the user's answer, and it ends
+node is open and every critical decision has the user's answer or an explicit
+applicable authorization under the conditions above, and it ends
 `adopted`.
 
 There is no question cap, and adding one would not help: some plans need three
@@ -281,13 +334,13 @@ usually a subject too large to hold at once. Break it up and grill the pieces.
 
 A session ends in exactly one of these, and a record of one names which:
 
-| Ending        | Reached when                                                                                                   | The work may proceed                                     |
-| ------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
-| `confirmed`   | Both conditions above: no node open, and the user confirms                                                     | Yes                                                      |
-| `user-closed` | The user answered `proceed` or `done`; each decision still open is recorded as an assumption and labelled      | Yes                                                      |
-| `adopted`     | A delegated session: no node open, every critical decision answered by the user, the rest adopted and recorded | Yes, and the final report lists what was adopted         |
-| `no-question` | A no-question mode was active: the evidence settled what it could and every node left over is an open question | Yes, and whatever gates the work reports those questions |
-| `stopped`     | The user stopped the session                                                                                   | No. Report every open decision as open                   |
+| Ending        | Reached when                                                                                                        | The work may proceed                                     |
+| ------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `confirmed`   | Both conditions above: no node open, and the user confirms                                                          | Yes                                                      |
+| `user-closed` | The user answered `proceed` or `done`; each decision still open is recorded as an assumption and labelled           | Yes                                                      |
+| `adopted`     | A delegated session meeting the conditions above: no node open, required human authority recorded, the rest adopted | Yes, and the final report lists what was adopted         |
+| `no-question` | A no-question mode was active: the evidence settled what it could and every node left over is an open question      | Yes, and whatever gates the work reports those questions |
+| `stopped`     | The user stopped the session                                                                                        | No. Report every open decision as open                   |
 
 **`no-question` is an ending, not an exemption.** The completing condition needs
 the user's confirmation, and an invocation told not to ask cannot obtain one —
@@ -298,12 +351,12 @@ the absence of an ending.
 
 **A session between agents is a delegated session, and ends `adopted`.** Its
 budget ends the rounds: after two, every decision that is not critical takes the
-griller's recommendation, and every critical one goes to the user, who answers
-it or ends the session another way. **Under a no-question mode there is nobody
-to send them to**: they are opened as questions where the work's gates read
-them, and that register write ends the session `no-question`, as it ends any
-session the mode holds. How many went is a count a record carries, never an
-ending of its own.
+griller's recommendation. An uncovered critical decision goes to the user when
+asking is permitted; the user answers it or ends the session another way. **Under a no-question mode, an uncovered
+critical decision is not sent to the user**: it is opened where the work's
+gates read it, and that register write ends the session `no-question`.
+An explicitly delegated session with every node settled ends `adopted` instead.
+How many went is a count a record carries, never an ending of its own.
 
 **`stopped` is the one that does not let the work continue.** The other four
 close the asking; this one ends the session, and an agent that carried on
@@ -333,20 +386,22 @@ than inventing it.
 ### A session between agents
 
 Two rounds, then every decision that is not critical takes the griller's
-recommendation. A critical decision skips the rounds and goes to the user at
-once: rounds between agents produce agreement, and agreement is not what that
-class lacks. Under a no-question mode the critical decisions reach no user: they
-are opened as questions, and the session ends `no-question` on that write.
+recommendation. A critical decision needs an actual user answer or an explicit
+applicable authorization under the conditions above. Rounds between agents
+produce agreement, not authority. If it is uncovered, ask the user at once when
+permitted; under a no-question mode, register it open and end `no-question`.
 
 The count bounds the rounds between agents. It does not end the session while a
-critical decision is unanswered. The rules are in
+critical decision is unanswered and lacks an applicable recorded authorization.
+The rules are in
 `.qfai/assistant/rule/review-convergence.md`.
 
 ## Under a no-question mode
 
-A run told not to ask the user does not ask, and a session inside it does not
-either. It settles what the evidence settles — and in a delegated session what
-adoption settles — and opens **every node left over** as a question, where
+A run told not to ask the user sends no user question. An explicitly delegated
+session may run agent-to-agent rounds under the conditions above. It settles
+what the evidence settles — and in a delegated session what adoption settles —
+and opens **every node left over** as a question, where
 whatever gates the work will see it. Every node, not every
 decision: a fact only the user holds cannot be settled from evidence either, and
 a mode that opens the decisions and drops the facts loses exactly the nodes no
@@ -388,9 +443,11 @@ uncertainty.
   user or left open on purpose, and they said which. Agreeing with every
   recommendation is a fine outcome; a decision that closed without them is not,
   however sound it was.
-- In a delegated session, the user was asked the critical decisions and nothing
-  else, and every adopted decision is in the record and the final report.
+- In a delegated session, every critical decision has actual recorded user
+  authority; an uncovered one was asked when permitted or remains open. Every
+  adopted decision is in the record and the final report.
 - Nothing entered the tree that the request did not need.
+- No griller started for a step with no open design decision.
 - Later rounds ask what the first round could not have asked.
 - Facts were looked up rather than asked for.
 - Work running in the background did not stall the round — only the questions