qfai 2.1.1 → 2.2.0

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

@@ -6,7 +6,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI structured-question 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){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" structured-question",
+            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}\" structured-question",
             "timeout": 10
           }
         ]
@@ -16,7 +16,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI free-text entry 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){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}catch{}\" free-text-entry",
+            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}\" free-text-entry",
             "timeout": 10
           }
         ]
@@ -50,7 +50,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI grilling reminder: design artifact",
-            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" grilling-design-artifact",
+            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}\" grilling-design-artifact",
             "timeout": 10
           }
         ]
@@ -61,7 +61,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI grilling reminder: delegation",
-            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}catch{}\" grilling-delegation",
+            "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 j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))||{}}catch{}let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}catch{}\" grilling-delegation",
             "timeout": 10
           }
         ]
@@ -72,7 +72,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI api-budget reminder",
-            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/[^\\w.-]gh[^\\w.-]|api\\.github\\.com/.test(' '+i+' ')){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" api-budget",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/[^\\w.-]gh[^\\w.-]|api\\.github\\.com/.test(' '+i+' ')){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}}catch{}\" api-budget",
             "timeout": 10
           }
         ]
@@ -85,13 +85,13 @@
           {
             "type": "command",
             "statusMessage": "QFAI documentation-clarity reminder",
-            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Add File: .*\\.md\\r?\\n/m.test(i)){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-write",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Add File: .*\\.md\\r?\\n/m.test(i)){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-write",
             "timeout": 10
           },
           {
             "type": "command",
             "statusMessage": "QFAI documentation-clarity reminder",
-            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Update File: .*\\.md\\r?\\n/m.test(i)){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-edit",
+            "command": "node -e \"try{const j=JSON.parse(require('fs').readFileSync(0,'utf8')),i=j.tool_input.command;if(typeof i==='string'&&/^\\*\\*\\* Update File: .*\\.md\\r?\\n/m.test(i)){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 n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}}catch{}\" documentation-clarity-after-edit",
             "timeout": 10
           }
         ]
@@ -102,7 +102,7 @@
           {
             "type": "command",
             "statusMessage": "QFAI minimal-implementation 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 go=true,j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}try{const R=p.dirname(p.dirname(p.dirname(r))),n=(x=>{const s=x.split(p.sep),b=s.pop();return p.isAbsolute(x)||s[0]==='..'||s.some(y=>['tmp','test','tests','__tests__','node_modules','.qfai','.agents'].includes(y))||b[0]==='.'||/\\.(test|spec)\\./.test(b)||['.md','.mdx','.markdown','.txt','.rst','.yml','.yaml','.json','.jsonc','.json5','.toml','.ini','.csv','.tsv','.lock','.svg','.png','.jpg','.jpeg','.gif'].includes(p.extname(b).toLowerCase())}),a=[...j.tool_input.command.matchAll(/^\\*\\*\\* (?:(?:Add|Update|Delete) File|Move to): (.+)/gm)].map(m=>p.relative(R,p.resolve(process.cwd(),m[1].trim())));if(a.length>0&&a.every(n))go=false}catch{}if(go){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}if(Number.isInteger((n-1)/20)){const m=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];m===undefined||console.log(JSON.stringify(m))}}}}catch{}\" minimal-implementation",
+            "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 go=true,j={};try{j=JSON.parse(f.readFileSync(0,'utf8'))}catch{}try{const R=p.dirname(p.dirname(p.dirname(r))),n=(x=>{const s=x.split(p.sep),b=s.pop();return p.isAbsolute(x)||s[0]==='..'||s.some(y=>['tmp','test','tests','__tests__','node_modules','.qfai','.agents'].includes(y))||b[0]==='.'||/\\.(test|spec)\\./.test(b)||['.md','.mdx','.markdown','.txt','.rst','.yml','.yaml','.json','.jsonc','.json5','.toml','.ini','.csv','.tsv','.lock','.svg','.png','.jpg','.jpeg','.gif'].includes(p.extname(b).toLowerCase())}),a=[...j.tool_input.command.matchAll(/^\\*\\*\\* (?:(?:Add|Update|Delete) File|Move to): (.+)/gm)].map(m=>p.relative(R,p.resolve(process.cwd(),m[1].trim())));if(a.length>0&&a.every(n))go=false}catch{}if(go){let n=1;if(typeof j.session_id==='string'){try{const t=p.join(require('os').tmpdir(),['qfai-reminder',j.session_id,j.agent_id||'main',process.argv[1]].join('-').replace(/[^\\w.-]/g,'_'));f.appendFileSync(t,'.');n=f.statSync(t).size}catch{}}const e=JSON.parse(f.readFileSync(r,'utf8'))[process.argv[1]];if(e===undefined){}else{const {briefContext,...m}=e;if(n>1&&typeof briefContext==='string')m.hookSpecificOutput.additionalContext=briefContext;console.log(JSON.stringify(m))}}}}catch{}\" minimal-implementation",
             "timeout": 10
           }
         ]

package/assets/init/.qfai/assistant/agent/frontend-engineer.md

@@ -45,6 +45,11 @@ specialization_tags:
   a deliberate shortcut with its ceiling and the condition that lifts it.
 - Apply `.qfai/assistant/rule/ui-procurement.md`: install a component before writing one, and for anything the prototype does not show, take the adopted system's default rather than inventing one.
 - Apply `.agents/rules/interface-clarity.md`: label a control in the user's words, never the parameter's. The label stays; the sentence explaining it goes.
+- Read each screen's `supplements` and `structure` in its UI contract before adding any text.
+  Show the title, the group headings, the labels and the declared supplements, and no other text.
+  A text the screen needs that the contract lacks, or a declared one the screen should not show,
+  is a change to the contract and goes back to `/qfai-sdd`.
+  Element ids stay the same when only wording changes.
 
 ## Inputs you must read
 

package/assets/init/.qfai/assistant/agent/product-experience-architect.md

@@ -51,6 +51,10 @@ specialization_tags:
 - Apply `.agents/rules/minimal-implementation.md`: the first rung is this stage's — whether the thing needs to exist. After a spec row is agreed, that question is a Change Request.
 - Apply `.qfai/assistant/rule/ui-procurement.md`: the theme is adopted from a published one, and a screen's composition comes from a catalogue before it is drawn.
 - Apply `.agents/rules/interface-clarity.md`: a screen that needs explaining is a screen that needs redesigning. Hint text only where a need was demonstrated and the control was improved first.
+- Record the decisions that rule leads to in the screen contract: the `supplements` a screen shows,
+  each with the reason it is needed, and the `structure` of any heading beyond the title
+  (`.qfai/assistant/skill/qfai-sdd/references/ui-contract-guide.md`).
+  Fix the control before adding a supplement for it.
 
 ## Inputs you must read
 

package/assets/init/.qfai/assistant/agent/product-surface-reviewer.md

@@ -61,6 +61,13 @@ specialization_tags:
 - Require more work only on what `.qfai/assistant/rule/shared-skill-delegation-baseline.md#what-a-reviewer-may-demand-more-of-must` admits, and report any other gap as advisory.
 - Apply `.qfai/assistant/rule/ui-procurement.md`: report a region that was drawn where a catalogue had it, and name the item that would have served.
 - Apply `.agents/rules/interface-clarity.md`: report copy that explains the interface as a finding against the control under it, and name the control to fix.
+- Compare the rendered text with each screen's `supplements` and `structure` in its UI contract.
+  A text no contract key declares is excess; a declared supplement that is not shown is an unmet need.
+  Name the screen, the task or state, the duplicated meaning or unmet need, and the text to remove or the control or structure to repair.
+  Apply `.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md#copy-that-adds-no-meaning`.
+  Never cut a condition, cost, destination, result, recovery step, consequence, label, accessible name, role or state,
+  and never move one into a tooltip or placeholder.
+  Word counts are observations, never a verdict.
 
 ## Inputs you must read
 

package/assets/init/.qfai/assistant/agent/requirements-analyst.md

@@ -64,6 +64,14 @@ specialization_tags:
   `/qfai-prototyping` at the validate lane, under `QFAI-AUD-001`. The shipped
   `ui-contract.sample.yaml` carries filled entries; replace them with the
   screen's own rather than emptying the list.
+- For UI-bearing surfaces: every screen also declares `supplements` (`[]` when it
+  shows no text beyond its title, group headings and labels), and `structure` when
+  it shows a heading beyond its title. Check each proposed text element against the
+  screen's tasks and the information the user needs there, and write the ones that
+  stay into the contract with the reason. A text that only repeats a heading, an
+  action or a condition the user already has is left out. Discussion sidecars
+  inform these keys; they do not replace them. See
+  `.qfai/assistant/skill/qfai-sdd/references/ui-contract-guide.md`.
 
 ## Stop conditions
 

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

@@ -45,14 +45,24 @@ Applies to every text an agent produces: pull request and issue titles and
 bodies, source-code comments, and Markdown files — inside the current change
 only, never beyond its diff.
 
-- No issue or pull-request numbers, ticket identifiers, or names only this
-  project understands, anywhere in source code or Markdown files. Those belong
-  in the pull request, the commit message and the changelog.
-- No account of how the work went. State the current behaviour and why it is
-  that way; the history is already in the git log and the pull request.
-- Cut what is self-evident, repeated, or wordy.
-- Ordinary vocabulary, one claim per sentence, lines short enough to scan.
-- Bullet lists and tables for parallel items.
+- Keep out issue or pull-request numbers, ticket identifiers and names only
+  this project understands, anywhere in source code or Markdown files. Those
+  belong in the pull request, the commit message and the changelog.
+  Pull request and issue bodies may contain numbers and links.
+- Keep out any account of how the work went. State the current behaviour and
+  why it is that way; the history is already in the git log and the pull
+  request.
+- Settle the message, then open with the conclusion: the title or opening says
+  the result, with no preamble.
+- Cut what is self-evident, repeated or wordy, and announcements, recaps and
+  empty intensifiers.
+- Use ordinary vocabulary, one claim per sentence, and name who acts; software
+  does not know or decide.
+- Mark what is unverified, and say what a claim rests on.
+- Use bullet lists and tables for parallel items, with lines short enough to
+  scan.
+- Open a report with the outcome, and separate what was checked from what was
+  not.
 - Re-read every changed line afterwards. Text that reads as a literal
   translation is a defect in any language pair — rewrite it the way someone
   writing natively in that language would.

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

@@ -11,7 +11,22 @@ open-questions.md, and every file under paths.contractsDir. Production code and
 obligation may change in a later task, but the change must preserve or deliberately reapprove that obligation.
 QFAI-owned files under .qfai/assistant/rule/ are updated through the package, then synchronized by init.
 
-A new change-request row in decisions.md is permitted without an earlier change request. Existing rows are append-only records: a prior row may change its Status cell, while its ID, Content, and Approach stay fixed. A changed obligation needs a new row, even when an older row discusses the same topic.
+A new change-request row in decisions.md is permitted without an earlier change request.
+Existing rows are append-only records: a prior row may change its Status cell,
+while its ID, Content, and Approach stay fixed. The sole ID-change exception is
+explicit local renumbering of a unique branch-added decision absent from the
+unique common ancestor of HEAD and a required local base. That operation changes
+only its ID and provably branch-added exact references. Inherited row cells and
+references stay fixed. A changed obligation needs a new row, even when an older
+row discusses the same topic.
+
+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)
 
@@ -25,6 +40,105 @@ diff changes no file under `01_policy/`, `02_business-flow/` or
 paths.contractsDir appends no `Change request:` row. A row naming a story file
 the bugfix did not touch would state an upstream change that did not happen.
 
+## Published decision prefix recovery
+
+The SDD owner may prepend only an approved Evidence/Grounds prefix to a
+published malformed decision added by the branch. Approval of this protocol
+does not authorize any target. First obtain a separate new in-force recovery
+change request naming the target and its repository-relative file.
+
+1. Fix the explicit base commit and its unique common ancestor with current
+   HEAD. The target ID must be absent from both. The documented published
+   source commit must be an ancestor of current HEAD and expose the unique
+   original row. Inherited records and open-question rows are excluded.
+2. Read the original raw cell bytes. The row must be single-line valid UTF-8,
+   with exactly one ASCII padding space at each Approach delimiter and no
+   additional boundary whitespace. Hash the stored Approach bytes with
+   SHA-256, excluding only the delimiter pipes and those two padding spaces.
+   Do not decode escapes, trim text or normalize it. Ambiguous boundaries,
+   additional padding or invalid UTF-8 stop recovery.
+3. Confirm the original Residual risk and Rollback items already satisfy the
+   required ordered, nonempty form. The new Approach must be exactly
+   `- Evidence: <actual file references> - Grounds: `, including its trailing
+   space, followed by the complete original Approach as a byte-identical
+   suffix. Preserve the original wording, order, facts, authority and scope.
+   The prefixed row must satisfy the existing form checks.
+4. Record the target ID, published source commit, fixed base and common
+   ancestor, old and new Approach digests, exact prefix, actual file evidence,
+   approval authority, recovery reason, residual risk and rollback in the new
+   request. The old digest must match the published source Approach; the new
+   digest must match the exact prefix plus that source value. Record actual
+   authority; do not invent a user answer or approval.
+5. Immediately before writing, recheck the unique current target, its
+   byte-identical ID, Content and Status, and its recorded old Approach digest.
+   Unknown or unavailable provenance, inherited or duplicate targets, stale
+   data or a change beyond the approved prefix stops recovery before writing.
+   Apply only that prefix. Keep every other row byte-identical and run the existing
+   validation without an exemption.
+6. Rollback removes only the recorded prefix when the current new Approach
+   digest still matches. Otherwise preserve the current row and stop. Removal
+   restores the original Approach and its validation failure. Do not reset,
+   amend or force push.
+
+Status changes, supersession and a diagnostic's rewrite suggestion supply no
+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
@@ -112,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. 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/asset-authoring.md

@@ -14,11 +14,13 @@ A `SKILL.md` states the contract and points at the file that carries the detail.
 - **One topic per file.** Do not replace an oversized `SKILL.md` with an oversized `references/everything.md`; that is the same problem one directory down. Split by topic and keep each file readable on its own — a reader who followed one pointer should not have to scan past three unrelated subjects to reach the one they came for.
 - **Every pointer resolves.** A line that moves detail out must name the file (and anchor, when the file covers more than one topic) so the reader is never left guessing where the rule went.
 
-A hard line ceiling backs this up: **800 lines per assistant asset file**, for every `.qfai/assistant/**/*.{md,yml,yaml}` file, counted as `content.split(/\r?\n/).length` — blank lines included. `npx qfai doctor` measures it and reports every file over the ceiling as `assets.lineBudget`. The ceiling is a backstop, not the rule: a file approaching it is a signal to move a section out, not
-to raise the number.
+A hard line ceiling backs this up: **500 lines per Markdown assistant asset file** and **800 lines per YAML assistant asset file**, for every `.qfai/assistant/**/*.{md,yml,yaml}` file, counted as `content.split(/\r?\n/).length` — blank lines included.
+`npx qfai doctor` measures it and reports every file over its ceiling as `assets.lineBudget`.
+The ceiling is a backstop, not the rule: a file approaching it is a signal to move a section out, not to raise the number.
 
-It was raised from 500 once, and on measurement rather than on the "this file is long" claim the number exists to refuse: three skill bodies had converged on that ceiling, and the changes in flight against one of them added 161 lines to a body already at 498 — eleven of them crossing the ceiling on their own. The detail those bodies carry is required to sit in the body rather than behind
-a pointer, so splitting could not absorb it. Converging on the limit was itself the signal — a body at the ceiling stops shedding topics and starts packing them into longer lines, and a line count cannot see that. Raise it again only against evidence of that kind.
+The Markdown ceiling is the limit an agent can follow in one file: it follows fewer instructions as its context grows, and follows those in the middle of a long file worst. A Markdown file has a `references/` home to move detail into. A YAML asset is parsed as data and cannot be split that way (see below), which is why its ceiling is higher.
+
+A body at its ceiling stops shedding topics and starts packing them into longer lines, and a line count cannot see that. The width ceiling below is what catches it.
 
 **A width ceiling makes the count honest: 400 characters per line.** A count of lines bounds reading cost only while a line is a roughly constant unit of reading, and packing broke that — one line in the shipped tree ran 9,104 characters against a median of 118, and cost the budget one unit. The two are read together, because each permits what the other refuses: width alone allows a thin
 file of a thousand short lines, and the count alone allows a packed one.

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

package/assets/init/.qfai/assistant/rule/references/worker-edit-boundary.md

@@ -0,0 +1,48 @@
+# Worker edits and work orders
+
+Read when assigning worker write paths or handling a refused edit.
+
+## Edit boundary
+
+The work order names the checkout assigned to the task by the host, the worker's
+write paths and the permitted edit method. Creating a Git worktree does not
+grant the host's tools permission to edit it. Even an assigned checkout can
+receive a refusal; verify the actual edit result rather than claiming access.
+
+If an edit is refused, stop writes to that target. Report the tool, working
+directory, target path and refusal text, omitting secrets. Return the owned
+paths and a reviewable diff that can be prepared within the worker's permitted
+area. Do not bypass the refusal through a shell, script or another tool.
+This does not forbid shell authoring where the host already permits it.
+
+The orchestrator checks the diff against the current files in its own permitted
+checkout before applying it. If that edit is refused too, leave the application
+pending and continue only independent work. Follow the existing worktree or
+shared-index mode in `.qfai/assistant/rule/workflow.md#concurrency-stage-independent-mandatory`
+when assigning writers and integrating their paths.
+
+## Work order template
+
+```text
+Task title: <short>
+Role: <sub-agent role>
+Review series: <reviewed artifact> + <reviewer role> + <replacement ordinal>   # review work orders only
+Goal: <what to decide/produce>
+Checkout: <absolute checkout assigned to this task by the host>
+Write paths: <exact owned paths, or none for a read-only task>
+Edit method: <host-permitted tool; worktree creation does not grant access>
+If an edit is refused: stop that target; return tool, cwd, target, refusal text, owned paths and a reviewable diff
+Inputs (refs):
+- <file/section>
+- .qfai/assistant/rule/drift-protocol.md#core-rule  <!-- the protected set, in front of the agent -->
+Constraints:
+- must: enforce Drift Protocol
+- must: follow applicable test-layer or validation policy
+- must_not: patch upstream artifacts directly; every upstream change requires
+  STOP + Change Request + owner rerun per .qfai/assistant/rule/drift-protocol.md
+Output format:
+- <headings / bullet schema>
+Time budget: none | <seconds>   # advisory: nothing stops at it. See .qfai/assistant/rule/stage-cost.md
+Elapsed line: end every message with `elapsed <seconds>s / <budget>s`, or `elapsed <seconds>s` when the budget is none
+Acceptance bar: <accept when ...> | <rework when ...>   # never `PASS`/`REVISE`: that is the reviewer's vocabulary and the completion gate matches on it, so a doer told to report in it emits a verdict on its own work
+```