qfai 2.1.2 → 2.2.0

package/assets/defaults/agent-routing/qfai-implement.yml

@@ -216,6 +216,15 @@ routing:
         rerun_policy: changed-scope-dependents
     review_profile: default
 
+  - step: implement-procedure
+    phases:
+      - id: documentation
+        mandatory_agents: [doc-steward]
+        conditional_agents: []
+        parallel_groups: []
+        rerun_policy: changed-scope-dependents
+    review_profile: default
+
   # Writes the bodies of empty acceptance tests, keeping each annotation.
   - step: implement-acceptance
     phases:

package/assets/defaults/agent-routing/qfai-triage.yml

@@ -4,6 +4,15 @@
 routing:
   # The triage steps change no tracked file, so each has one author and no
   # build or test phase.
+  - step: triage-operate
+    phases:
+      - id: operate
+        mandatory_agents: [devops-ci-engineer]
+        conditional_agents: []
+        parallel_groups: []
+        rerun_policy: changed-scope-dependents
+    review_profile: default
+
   - step: triage-owned-cleanup
     phases:
       - id: cleanup

package/assets/defaults/workflows/answer-in-session.yml

@@ -0,0 +1,8 @@
+route: answer-in-session
+family: close
+stages:
+  - id: answer
+    kind: triage
+    steps: [triage-answer]
+decisionPoints: []
+branchPoints: []

package/assets/defaults/workflows/quarantine-flaky.yml

@@ -29,6 +29,9 @@ stages:
     after: [note]
 decisionPoints: []
 branchPoints:
+  - step: implement-quarantine
+    outcomes:
+      - { outcome: failing-consistently, routes: decision-table }
   - step: implement-diagnose
     outcomes:
       - { outcome: product-race, routes: [fix-intermittent] }

package/assets/defaults/workflows/repair-consistency.yml

@@ -11,6 +11,7 @@ stages:
       - { step: sdd-flow, passThrough: true }
       - { step: sdd-story, passThrough: true }
       - { step: sdd-contract, passThrough: true }
+      - { step: common-design-md, passThrough: true }
       - { step: sdd-cycle, passThrough: true }
     after: [diagnose]
     review: spec

package/assets/defaults/workflows/run-operation.yml

@@ -0,0 +1,11 @@
+route: run-operation
+family: upkeep
+stages:
+  - id: operate
+    kind: triage
+    steps: [triage-operate]
+decisionPoints: []
+branchPoints:
+  - step: triage-operate
+    outcomes:
+      - { outcome: needs-change, routes: decision-table }

package/assets/defaults/workflows/write-procedure.yml

@@ -0,0 +1,18 @@
+route: write-procedure
+family: change
+stages:
+  - id: documentation
+    kind: documentation
+    steps: [implement-procedure]
+  - id: note
+    kind: verify
+    steps:
+      - { step: verify-change-note, passThrough: true }
+    after: [documentation]
+    review: code
+  - id: verify
+    kind: verify
+    steps: [verify-qfai-gate, verify-repo-gate, verify-commit]
+    after: [note]
+decisionPoints: []
+branchPoints: []

package/assets/graph/codegraph-native.mjs

@@ -0,0 +1,174 @@
+import process from "node:process";
+import path from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+async function main() {
+  const sdk = await import(pathToFileURL(process.argv[2]).href);
+  const { default: CodeGraph, setLogger, silentLogger } = sdk.default;
+  setLogger(silentLogger);
+  const mode = process.argv[4];
+  const corpus = process.argv[3];
+  const graph = mode
+    ? await CodeGraph.open(process.argv[3], { readOnly: true })
+    : await CodeGraph.init(process.argv[3], { index: false });
+  try {
+    if (mode === "inventory") {
+      process.stdout.write(
+        JSON.stringify({ files: graph.getFiles().map((file) => file.path) }) + "\n",
+      );
+    } else if (mode === "coverage") {
+      process.stdout.write(JSON.stringify(await coverage(graph, corpus)) + "\n");
+    } else if (mode === undefined) {
+      const result = await graph.indexAll();
+      const build = graph.getIndexBuildInfo();
+      await writeFile(
+        path.join(corpus, ".codegraph", "qfai-native-evidence.json"),
+        JSON.stringify({
+          engineVersion: build.version,
+          extractionVersion: build.extractionVersion,
+          lastIndexedAt: graph.getLastIndexedAt(),
+          result: {
+            success: result.success,
+            filesDiscovered: result.filesDiscovered ?? null,
+            filesIndexed: result.filesIndexed,
+            filesSkipped: result.filesSkipped,
+            filesErrored: result.filesErrored,
+            filesSkippedUnsupported: result.filesSkippedUnsupported ?? 0,
+            topUnsupportedExtensions: result.topUnsupportedExtensions ?? [],
+            errors: result.errors.map((error) => ({
+              code: error.code ?? "unclassified",
+              severity: error.severity,
+              filePath: safeRelativeInput(corpus, error.filePath),
+            })),
+          },
+        }) + "\n",
+      );
+      process.stdout.write("CodeGraph native indexing completed.\n");
+    } else {
+      throw new Error("Unsupported native operation");
+    }
+  } finally {
+    graph.close();
+  }
+}
+
+function safeRelativeInput(corpus, file) {
+  if (typeof file !== "string" || !file) return "Unidentified native input";
+  const relative = (path.isAbsolute(file) ? path.relative(corpus, file) : file).replaceAll(
+    "\\",
+    "/",
+  );
+  if (
+    path.posix.isAbsolute(relative) ||
+    path.win32.isAbsolute(relative) ||
+    relative.split("/").some((part) => !part || part === "." || part === "..") ||
+    /(?:^|\/)(?:\.env(?:\.|$)|\.npmrc$|\.pypirc$|\.netrc$|credentials?(?:\.|$)|secrets?(?:\.|$))|\.(?:pem|key|p12|pfx)$/i.test(
+      relative,
+    )
+  )
+    return "Unidentified native input";
+  return relative;
+}
+
+async function coverage(graph, corpus) {
+  const unknown = { complete: false, unsupported: [], unreadable: [], unparsed: [] };
+  let evidence;
+  try {
+    evidence = JSON.parse(
+      await readFile(path.join(corpus, ".codegraph", "qfai-native-evidence.json"), "utf8"),
+    );
+  } catch {
+    return unknown;
+  }
+  const build = graph.getIndexBuildInfo();
+  const result = evidence?.result;
+  const counts = [
+    "filesDiscovered",
+    "filesIndexed",
+    "filesSkipped",
+    "filesErrored",
+    "filesSkippedUnsupported",
+  ];
+  if (
+    !record(evidence) ||
+    Object.keys(evidence).length !== 4 ||
+    evidence.engineVersion !== build.version ||
+    evidence.extractionVersion !== build.extractionVersion ||
+    !Number.isSafeInteger(evidence.lastIndexedAt) ||
+    evidence.lastIndexedAt !== graph.getLastIndexedAt() ||
+    !record(result) ||
+    Object.keys(result).length !== 8 ||
+    typeof result.success !== "boolean" ||
+    counts.some((key) => !Number.isSafeInteger(result[key]) || result[key] < 0) ||
+    !Array.isArray(result.errors) ||
+    !Array.isArray(result.topUnsupportedExtensions)
+  )
+    return unknown;
+  const unsupported = [];
+  const unreadable = [];
+  const unparsed = [];
+  let documentedInputs = 0;
+  for (const group of result.topUnsupportedExtensions) {
+    if (
+      !record(group) ||
+      typeof group.ext !== "string" ||
+      !Number.isSafeInteger(group.count) ||
+      group.count < 0
+    )
+      return unknown;
+    if (
+      /^\.(?:md|mdx|txt|rst|adoc|pdf|png|jpe?g|gif|svg|webp|ico|woff2?|ttf|mp[34]|wav)$/i.test(
+        group.ext,
+      )
+    ) {
+      documentedInputs += group.count;
+    } else {
+      unsupported.push(`${group.ext} (${group.count} inputs)`);
+    }
+  }
+  const namedUnsupported = result.topUnsupportedExtensions.reduce(
+    (count, group) => count + group.count,
+    0,
+  );
+  if (namedUnsupported < result.filesSkippedUnsupported)
+    unsupported.push("Other unsupported native inputs");
+  if (
+    namedUnsupported > result.filesSkippedUnsupported ||
+    documentedInputs > result.filesSkippedUnsupported
+  )
+    return unknown;
+  for (const error of [
+    ...result.errors,
+    ...graph.getFiles().flatMap((file) => file.errors ?? []),
+  ]) {
+    if (!record(error) || !["error", "warning"].includes(error.severity)) return unknown;
+    const file = safeRelativeInput(corpus, error.filePath);
+    if (error.code === "read_error") unreadable.push(file);
+    else unparsed.push(file);
+  }
+  if (result.filesErrored > 0 && unreadable.length === 0 && unparsed.length === 0)
+    unparsed.push("Unidentified native extraction errors");
+  const complete =
+    result.success &&
+    result.filesIndexed + result.filesSkipped + result.filesErrored >= result.filesDiscovered &&
+    result.filesErrored === 0 &&
+    unsupported.length === 0 &&
+    unreadable.length === 0 &&
+    unparsed.length === 0;
+  return {
+    complete,
+    unsupported,
+    unreadable: [...new Set(unreadable)],
+    unparsed: [...new Set(unparsed)],
+  };
+}
+
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+main().catch(() => {
+  process.stderr.write("CodeGraph native indexing failed.\n");
+  process.exitCode = 1;
+});

package/assets/graph/graphify-native.py

@@ -0,0 +1,72 @@
+"""Inspect the managed corpus with Graphify's native freshness operation."""
+
+import json
+import sys
+from pathlib import Path
+
+from graphify.detect import detect_incremental
+
+
+def input_inventory(output, graph):
+    manifest = json.loads((output / "manifest.json").read_text(encoding="utf-8"))
+    if not isinstance(manifest, dict):
+        raise ValueError("Invalid native manifest")
+    files = set(manifest.keys())
+    groups = [graph["nodes"]]
+    for name in ("edges", "links", "hyperedges"):
+        if name in graph:
+            groups.append(graph[name])
+    nested = graph.get("graph", {})
+    if not isinstance(nested, dict):
+        raise ValueError("Invalid native graph attributes")
+    if "hyperedges" in nested:
+        groups.append(nested["hyperedges"])
+    for group in groups:
+        if not isinstance(group, list):
+            raise ValueError("Invalid native graph references")
+        for item in group:
+            if not isinstance(item, dict):
+                raise ValueError("Invalid native graph reference")
+            for field in ("source_file", "definition_file", "path"):
+                value = item.get(field)
+                if value is None or value == "":
+                    continue
+                if not isinstance(value, str):
+                    raise ValueError("Invalid native input path")
+                files.add(value)
+    return sorted(files)
+
+
+def main():
+    root = Path(sys.argv[1])
+    kind = sys.argv[2]
+    output = root / "graphify-out"
+    graph = json.loads((output / "graph.json").read_text(encoding="utf-8"))
+    if not isinstance(graph, dict) or not isinstance(graph.get("nodes"), list):
+        raise ValueError("Invalid native graph")
+    if kind == "inventory":
+        print(json.dumps({"files": input_inventory(output, graph)}))
+        return
+    if kind not in ("semantic", "ast"):
+        raise ValueError("Unsupported native inspection")
+    state = detect_incremental(
+        root,
+        manifest_path=str(output / "manifest.json"),
+        kind=kind,
+        cache_root=output,
+    )
+    print(json.dumps({
+        "current": state["new_total"] == 0
+        and not state["deleted_files"]
+        and not state["excluded_files"],
+        "unsupported": state.get("unclassified", []),
+        "unreadable": state.get("unreadable", []),
+    }))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        sys.stderr.write("Graphify freshness inspection failed.\n")
+        sys.exit(1)

package/assets/init/.claude/settings.json

@@ -30,7 +30,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}const p=i.prompt;if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(e!==undefined){const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}const p=i.prompt;if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake|ci-monitor-event)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(e!==undefined){const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "structured-question"
             ]
@@ -46,7 +46,7 @@
             "command": "node",
             "args": [
               "-e",
-              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}const p=i.prompt;if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(e!==undefined){const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}",
+              "try{const f=require('fs');let i={};try{i=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}const p=i.prompt;if(!(typeof p==='string'&&/^[ \\t]*(<(task-notification|wake|ci-monitor-event)[\\s>]|\\[SYSTEM NOTIFICATION)/m.test(p))){let n=1;if(typeof i.session_id==='string'){try{const t=require('path').join(require('os').tmpdir(),['qfai-reminder',i.session_id,i.agent_id||'main',process.argv[2]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(e!==undefined){const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}",
               "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
               "free-text-entry"
             ]
@@ -198,24 +198,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "statusMessage": "QFAI session feedback reminder",
-            "command": "node",
-            "args": [
-              "-e",
-              "try{const f=require('fs');let i;try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{process.exit(0)}const l=typeof i.last_assistant_message==='string'?i.last_assistant_message.trim():'';if(i.stop_hook_active===true||(l.length>0&&('?'+String.fromCharCode(65311)).includes(l.slice(-1))))process.exit(0);const m=JSON.parse(f.readFileSync(process.argv[1],'utf8'))[process.argv[2]];if(m!==undefined)console.log(JSON.stringify(m))}catch{}",
-              "${CLAUDE_PROJECT_DIR}/.agents/rules/reminders.json",
-              "session-feedback"
-            ]
-          }
-        ]
-      }
     ]
   }
 }

package/assets/init/.codex/hooks.json

@@ -107,18 +107,6 @@
           }
         ]
       }
-    ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "statusMessage": "QFAI session feedback reminder",
-            "command": "node -e \"try{const f=require('fs'),p=require('path');let d=process.cwd(),r;for(;;){const c=p.join(d,'.agents','rules','reminders.json');if(r===undefined&&f.existsSync(c))r=c;if(f.existsSync(p.join(d,'.git')))break;const u=p.dirname(d);if(u===d){r=undefined;break}d=u}if(r){let i;try{i=JSON.parse(f.readFileSync(0,'utf8'))}catch{process.exit(0)}const l=typeof i.last_assistant_message==='string'?i.last_assistant_message.trim():'';if(i.stop_hook_active===true||(l.length>0&&('?'+String.fromCharCode(65311)).includes(l.slice(-1))))process.exit(0);const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" session-feedback",
-            "timeout": 10
-          }
-        ]
-      }
     ]
   }
 }

package/assets/init/.qfai/assistant/rule/constitution.md

@@ -3,6 +3,13 @@
 This document defines **non‑negotiable operating rules** for QFAI agents and subagents.
 It is inspired by proven “constitution / articles / guardrails” patterns in existing SDD toolchains, but adapted to QFAI’s minimal workflow.
 
+Actual user instructions take priority over repository guidelines. Recorded
+applicable user authority is defined in
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`: an explicit
+in-scope delegation may authorize reversible requested judgment without a
+fictional individual approval answer. It supplies no unknown fact or authority
+for an operation outside its scope.
+
 Inside an `npx qfai workflow` run, what authorizes the run's work and the one target a work order binds its stage to are stated in `.qfai/assistant/rule/shared-skill-operating-baseline.md#what-authorizes-a-runs-work`. They add to these articles and except none.
 
 ---
@@ -260,7 +267,7 @@ sanctioned move, and neither is asking a sixth clarification anyway.
 **A grilling session survives exhaustion too**, and for the same reason: its
 questions never spent budget, so there is none left to run out of. A session
 already under way continues to its own end condition, a delegated one still
-putting its critical decisions to the user, and a stage reached after
+requiring actual user authority for critical decisions, and a stage reached after
 exhaustion still opens one where its work calls for it. Treating a spent budget
 as the end of a session would put the design decisions back where this article
 found them — settled quietly, on an assumption nobody was asked about.
@@ -322,16 +329,18 @@ If confidence is low, inspect the repository further.
 
 **Stop on detection.** Where a contradiction in the spec, an unconsidered case,
 or a technical obstacle surfaces mid-run, stop rather than deciding alone.
-Settle it between the agents, and put a critical decision to the user
-(`.agents/rules/grilling.md#critical-decisions`). A contradiction with the spec
-is critical. Nothing is recorded beyond the stage's final report.
+Settle it between the agents. A critical decision needs an actual user answer
+or recorded applicable authorization under
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`; without it,
+ask when permitted or register it open. A contradiction with the spec is
+critical. Nothing is recorded beyond the stage's final report.
 
 **Only one outcome is the Drift Protocol's.**
 
-| The stop concludes                                                                       | What follows                                                                                                   |
-| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
-| Settled input must change                                                                | `.qfai/assistant/rule/drift-protocol.md`: stop the dependent work, raise the Change Request, wait for approval |
-| The obstacle is this run's to solve — an unavailable dependency, an approach that failed | The run solves it. Nothing upstream changes, so there is nothing to approve                                    |
+| The stop concludes                                                                       | What follows                                                                                                                                        |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Settled input must change                                                                | `.qfai/assistant/rule/drift-protocol.md`: stop dependent work, raise the Change Request, record actual applicable user authority before changing it |
+| The obstacle is this run's to solve — an unavailable dependency, an approach that failed | The run solves it. Nothing upstream changes, so there is nothing to approve                                                                         |
 
 Stopping does not change settled input and is not a second way to. What it
 contributes to a Change Request is what that protocol asks of the class: for
@@ -366,7 +375,9 @@ rule master names.
 Rules:
 
 0. **A no-question mode is read first.** Where rule 4 applies, no question is put
-   at all, so there is nothing whose availability rules 1 to 3 could judge. Read
+   to the user, so there is nothing whose availability rules 1 to 3 could judge.
+   Actual qualifying explicit delegation may still permit agent-to-agent rounds
+   under the master; no-question mode alone does not. Read
    the other way round, a mode that withholds the tool would make it unavailable,
    route the question to rule 3's plain-text fallback, and hand the agent a rule
    that says to ask beside one that says not to.
@@ -406,12 +417,14 @@ Rules:
    this rule is activated by the `--auto` flag alone.
 6. **A grilling session does not reach the user under `--auto`.** Its questions
    are exempt from the Article VI budget, not from rule 4: a no-question mode
-   asks nothing, whatever the question is for. The session still runs — it
+   sends no question to the user, whatever it is for. The session still runs — it
    settles what the repository settles, dispatches sub-agents for the facts, and
-   in a delegated session adopts the griller's recommendation for every decision
-   that is not critical — and every **node** left over (in a delegated session,
-   each critical decision and each fact only the user holds) is **opened as a
-   question in the register the stage reads**, so the stage cannot complete over it. Every node, not every
+   in a delegated session adopts the griller's recommendation for non-critical
+   decisions. A critical decision needs an actual user answer or recorded
+   applicable authorization; without it the node stays open. It opens every **node**
+   left over, including uncovered critical decisions and unavailable user-held
+   facts, **as a question in the register the stage reads**, so the
+   stage cannot complete over it. Every node, not every
    decision: a fact only the user holds cannot be settled from evidence either,
    and opening the decisions while dropping the facts loses exactly the nodes no
    lookup could have reached. Where a document requires the field to hold
@@ -419,7 +432,10 @@ Rules:
    open question; a labelled value under an open question is not a settled
    decision. What rule 4 does not license is the assumption **alone**, which
    reads as settled to whoever finds it next. A fact declared undefaultable has
-   no value to write down at all: the run stops and names it.
+   no value to write down at all: the run stops and names it. A qualifying
+   explicitly delegated session ends `adopted` only with the master's empty-tree,
+   actual-input and authority conditions met. No-question mode alone cannot
+   close a node or authorize a reserved decision.
 
 This article survives context compaction because `.qfai/assistant/rule/constitution.md` is a P1 reload target.
 

package/assets/init/.qfai/assistant/rule/drift-protocol.md

@@ -24,6 +24,10 @@ The sole Approach-change exception is the published decision prefix recovery
 below. It preserves the target's ID, Content, Status and complete original
 Approach suffix. It excludes inherited rows and open-question rows.
 
+The sole row-removal exception is the merge-added identical decision copy
+recovery below. It removes only proven raw-identical surplus copies of a
+decision and keeps one original. It excludes open-question rows.
+
 ## Allowed exceptions (minimal whitelist)
 
 - A project may add a local overlay beside a shipped rule. The overlay adds project guidance; it does not repeal a shipped rule.
@@ -81,6 +85,60 @@ recovery authority and clear no form error. Inherited malformed records need a
 separate owning change request; this operation cannot repair them. These are
 owner instructions, not an automatic recovery command or a concurrency guarantee.
 
+## Merge-added identical decision copy recovery
+
+The SDD owner may manually remove only raw-identical surplus copies of a
+decision row that an exact two-parent bad merge introduced. Approval of this
+protocol authorizes no target. First append a separate new in-force change
+request that names the exact `decisions.md` path and the decision ID.
+
+1. Name the bad merge. It must be an available ancestor of current HEAD with
+   exactly two parents, and it must expose the introduced surplus. Name both
+   parents and their unique common ancestor. Each of the three must hold exactly
+   one byte-identical original of the row. Fix the explicit base and its unique
+   comparison ancestor; both must hold one original and no surplus selected for
+   removal. A missing or non-ancestor merge, a third parent, a non-unique
+   ancestor or a source that does not hold exactly one original stops recovery.
+2. Read the complete stored UTF-8 raw row of every selected current occurrence:
+   all four cells, delimiters, padding and line ending. Hash each with SHA-256,
+   including the line ending. Do not trim, decode escapes or normalize endings.
+   Nonidentical cells, padding or endings are a different collision and are
+   outside this recovery.
+3. Record in the request the path, the ID, the bad merge, both parents, the
+   ancestor, the base and its comparison ancestor, the location of each
+   occurrence, the raw hash, the retain/remove mapping, the actual authority,
+   the residual risk and the rollback. Record actual authority; invent no
+   answer. The request fixes input lineage only.
+4. After the request is appended, have the evidence for the write reviewed
+   independently and adopted. It fixes the actual write HEAD, base and
+   comparison ancestor, the complete preimage and replacement bytes and hashes,
+   the mapping and the current authority. The request does not name its own
+   commit, so the actual write revision stays distinct from the lineage above.
+   This adds no receipt grammar and no validator input.
+5. Immediately before writing, recheck the refs, their availability, the path,
+   the authority, the occurrence count, the mapping and the bytes. Stale,
+   missing, ambiguous, conflicting or changed proof stops before writing.
+   Changed observations need refreshed reviewed evidence. A changed target or
+   operation needs a new request; do not rewrite the cells of an earlier one.
+6. Remove only the mapped surplus occurrences. Keep one complete original, every
+   distinct decision and reference, every unrelated current byte and the Git
+   history. Do not change a Status, rewrite a reference or reorder other
+   history. Open-question rows, nonidentical collisions, ordinary duplicate
+   cleanup and surplus that the base or its comparison ancestor already holds
+   are excluded.
+7. Rollback restores the recorded complete preimage only while the current file
+   is byte-identical to its owned replacement. Otherwise keep the current bytes,
+   stop and name the unrestored path. Restoring brings back the duplicate
+   failure. Do not reset, amend or force push.
+
+The existing duplicate check, positional drift, consumed-DONE authorization and
+valid Status-only rules keep applying without an exemption. Other drift that
+the file already has stays diagnosed; it is not a prerequisite for this
+correction. An actual required stage gate still stops dependent work. Correcting
+the copies is not a whole-target PASS, and the request stays at WIP while a named
+action or required check is unfinished. These are owner instructions, not a
+command, an executor or a concurrency, atomicity or power-loss guarantee.
+
 ## Drift classes
 
 Intent drift means an approved obligation should change. Record the current obligation, the proposed behavior, realistic
@@ -168,6 +226,9 @@ copy of a locked file before deciding its lock is wrong.
 ## Non-negotiable constraints
 
 - Downstream stages do not patch protected upstream artifacts before an in-force Change request: decision row authorizes the path. The drift profile compares the branch against baseBranch and reports QFAI-DRIFT-001 for an unapproved protected change. The SDD owner may create the request row itself without a prior row.
-- Existing decisions.md and open-questions.md rows retain their ID, Content, and Approach, except for the explicit branch-added decision renumbering and published decision prefix recovery above. Inherited rows retain those cells without exception. A former row may change Status; new content is appended as a new row.
+  QFAI-DRIFT-003 is a warning that nothing was compared, because baseBranch does not resolve.
+  QFAI-DRIFT-004 is a warning that an uncommitted edit to a protected file is not compared:
+  record the Change request row before you commit the change.
+- Existing decisions.md and open-questions.md rows retain their ID, Content, and Approach, except for the explicit branch-added decision renumbering, published decision prefix recovery and merge-added identical decision copy recovery above. Inherited rows retain those cells without exception. A former row may change Status; new content is appended as a new row.
 - Vendored assistant rules are changed in the package and synchronized into projects by `npx qfai init --force`, which overwrites a local edit. A project rule lives in a `*.local.md` overlay beside the vendored one.
 - When approval is unavailable, keep the affected items stopped and report the decision needed. Continue unrelated work.

package/assets/init/.qfai/assistant/rule/references/codex-delegation.md

@@ -0,0 +1,27 @@
+# Codex Delegation
+
+Read before the first `spawn_agent` call when the host is Codex.
+
+## Codex delegation notes
+
+A sub-agent should cost the orchestrator one brief and one final answer. A call
+that only checks progress, such as a short wait, a sleep or an agent listing,
+is one more model call, so the orchestrator makes none.
+
+- **Self-contained brief.** Call `spawn_agent` with `fork_turns: "none"` and a
+  `message` that holds everything the sub-agent needs: the task, the files to
+  read, the paths it may write, the checks to run and the shape of its answer.
+  `fork_turns` defaults to `"all"`, which copies the whole parent thread into
+  the sub-agent. Where the tool takes `fork_context` instead, leave it out or
+  pass `false`.
+- **One final answer, no interim messages.** The brief tells the sub-agent to
+  send no `send_message` updates and to return its result once, as its final
+  answer. Where `wait_agent` takes no `targets`, every queued message ends the
+  orchestrator's wait early.
+- **Long wait.** With no work of its own left, the orchestrator calls
+  `wait_agent` with a `timeout_ms` of minutes within the maximum the tool states,
+  such as `600000`, not 10 to 60 seconds. A wait that times out is
+  followed by another long wait.
+- **No polling.** Never wait with `sleep`, a loop of short `wait_agent` calls or
+  repeated `list_agents` calls. `followup_task` gives a sub-agent a new task; it
+  never asks for progress.

package/assets/init/.qfai/assistant/rule/references/griller-recommendations.md

@@ -6,15 +6,27 @@ Read when a griller's recommendation is used.
 
 A grilling session puts a recommended answer beside each question (`.agents/rules/grilling.md`). Who settled the decision decides what happens next.
 
-| The decision was settled                              | What follows                                                                      |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------- |
-| By the user, from the recommendation among the inputs | The decision is theirs. The griller may review the artifact                       |
-| Agent to agent, not critical                          | The decision stands. The griller that recommended it does not review the artifact |
-| Agent to agent, critical, with no user adjudication   | The artifact is wrong, and no reviewer can clear it                               |
-
-**The second row is how a delegated session is meant to end** (`.agents/rules/grilling.md`), not a finding. The reviewer checks that the decision is in the final report and is not critical. A reviewer that doubts its merit raises that as an ordinary finding against the artifact, under its own remit, as it would for any other content.
-
-**The third row is not a routing problem.** A critical decision is the user's in every session, and a run that could not ask records it as an open question rather than adopting it. An agent-adopted critical decision is therefore an artifact carrying something nobody with the standing decided, and handing it to a different reviewer would launder it.
+| The decision was settled                                                                 | What follows                                                                      |
+| ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| By the user, from the recommendation among the inputs                                    | The decision is theirs. The griller may review the artifact                       |
+| Agent to agent, non-critical or with recorded applicable human authority                 | The decision stands. The griller that recommended it does not review the artifact |
+| Agent to agent, critical, without an actual user answer or recorded applicable authority | The artifact is wrong, and no reviewer can clear it                               |
+
+**The second row is how a delegated session is meant to end**
+(`.agents/rules/grilling.md`), not a finding. The reviewer checks the final
+report and, for a critical decision, the actual
+applicable user authority defined in
+`.agents/rules/grilling.md#explicit-delegation-for-a-discussion`.
+An explicit delegation covering reversible requested judgment is authority,
+not an individual human option answer. The recommending griller remains
+disqualified from reviewing an agent adoption. A reviewer that doubts its merit
+raises an ordinary finding against the artifact under its own remit.
+
+**The third row is not a routing problem.** Without an actual answer or
+recorded applicable user authority, a critical decision stays open. A run that
+cannot ask records it as an open question rather than adopting it. Agent
+agreement cannot supply authority, and a different reviewer cannot repair its
+absence. No-question mode alone authorizes no decision.
 The reviewer must return `REVISE` and name the decision: it is reopened and put to the user, or recorded open where no question can be asked.
 
 The first row needs a reason, because the intuitive one is wrong. A sub-agent starting with a reset context cannot defer to something it does not remember, so deference is not the risk. **Correlation** is: a fresh instance of the same agent, on the same model, over the same evidence, re-derives the preference that produced the recommendation and finds it good on the merits. Resetting the