qfai 2.1.1 → 2.1.2

package/assets/init/.qfai/assistant/skill/qfai-run/references/operator-screens.md

@@ -5,12 +5,20 @@ What the user sees while a request is worked, and how a question reaches them.
 ## Contents
 
 - Every screen
+- Launcher recovery
+- Refreshing installed instructions
+- Executing a step
 - The scope question
 - The announcement
 - Questions
+- Repair found by a question-only stage
 - A step only a person can take
+- Authorized external actions
+- Replies to a waiting step
+- Independent targets under one goal
 - Halt notice
 - Final report
+- Work orders summary
 
 ## Every screen
 
@@ -21,6 +29,49 @@ What the user sees while a request is worked, and how a question reaches them.
 - Show nothing while a call is running beyond the host's own activity
   indicator.
 
+## Launcher recovery
+
+Read this section if the canonical launcher is missing or its preflight fails,
+before planning.
+
+Use the project's package manager and declared install command in this checkout:
+
+- If `package.json` declares `qfai`, install the project's dependencies here.
+- If it does not, add `qfai` as a development dependency using that package manager.
+- Repeat the launcher preflight. Plan only after it succeeds.
+
+Never use a published, remote or cached QFAI launcher as a fallback.
+
+## Refreshing installed instructions
+
+Read this section before applying corrected guidance to an adopting project.
+
+Install or update its project-local QFAI dependency using the project's package
+manager and approved package source. Verify that the canonical launcher resolves
+that installation, then inspect the installed step and reference files for the
+required guidance. A source fix or package version string alone does not prove
+that a published package contains it.
+
+Preview the refresh with that verified local launcher using
+`npx qfai init --force --dry-run`. Review the managed files it would replace,
+including any direct local edits, before `npx qfai init --force`. Review the
+resulting diff. Force refresh overwrites managed assistant and rule masters;
+project specs, contracts, rule overlays, `skill.local/`, configuration overrides
+and existing entry documents remain project-owned. Keep them intact; do not
+replace them with templates to make the refresh pass.
+
+## Executing a step
+
+Read this section when a step is short or passes without edits.
+
+Read `STEP.md` at the plan's path and follow its Procedure. Run only its declared
+commands and pass its Gate.
+
+A `passThrough` step first reads what its Passes when section names. If that
+condition holds, write nothing and record the reason in the stage report.
+Do not skip the step. The planned independent review still runs, even when the
+step is only two lines.
+
 ## The scope question
 
 The scopes are the plan's, or the chosen candidate's after the candidate
@@ -52,8 +103,9 @@ Once the plan and its scope are known, and before the first stage:
 - the chosen stages in order;
 - the files the work may change.
 
-It asks nothing and lists no skipped stage. Text that is not a request gets no
-plan and no announcement.
+The announcement asks nothing and lists no skipped stage. Continue with the
+policy check and the first stage in the same turn without waiting for a reply.
+Text that is not a request gets no plan and no announcement.
 
 ## Questions
 
@@ -77,12 +129,33 @@ Independent questions go in one round; a dependent one waits for its answer.
 - Under a no-question mode nothing is asked. `SKILL.md` says what is done
   instead.
 
+## Repair found by a question-only stage
+
+Read this section when a question-only request finds a defect and its move to
+tracked-file repair lacks explicit authority for the same target.
+
+Show the defect and its evidence, the proposed repair scope and the planned
+checks. Put one question through the structured question tool in the form
+`.agents/rules/user-questions.md` requires:
+
+- **Repair:** authorize the stated repair and checks for this target.
+- **Report and stop:** report the finding and stop this target without edits.
+
+Write nothing before the answer. Repair permission takes the destination's
+existing plan; add no stage or scope. The guards for a third branch move, a
+scope that leaves stages out and release approval still apply.
+
+Under a no-question mode, report the defect and required repair permission and
+stop that target. Write no tracked `open-questions.md` row for this choice;
+asking for no questions alone supplies no repair authority. Other authorized
+independent targets may continue.
+
 ## A step only a person can take
 
-A change can depend on an action outside the repository that only the user can
-take: a setting in a hosted dashboard, or a credential issued in a service's
-web console. The plan stays the repository change. The work stops before the
-stage that needs the action and says three things:
+A change can depend on a step only a person can take: interactive login, a
+new permission grant or an expansion of authority. The plan stays the
+repository change. The work stops before the stage that needs that action
+and says three things:
 
 - what the user must do, in plain words, and where;
 - what shows it was done;
@@ -93,14 +166,130 @@ Put it as one question that ends the turn, in the form
 `.agents/rules/user-questions.md` sets out. The options are that the user did
 it, and `stop`.
 
-- The agent never types a password, token or key, and never changes an account
-  or service setting. The user does both in the service's own page.
+- The user completes person-only login, new permission grants and authority
+  expansion in the service's own page. A human-run or triage handoff never
+  performs the user's operation on their behalf.
 - The agent reads only the evidence it named. It reports the action as
   confirmed or not confirmed, and goes on after it only when confirmed or the
   user says to go on.
 - Under a no-question mode nothing is asked. The work that does not depend on
   the action goes on, and the final report lists the action as not done.
 
+## Authorized external actions
+
+Read this section when a repository change needs an account setting or a
+credential installed outside the repository.
+
+An agent may perform that action only when prior user instructions or project
+policy cover the specific target and action, and the host provides an allowed
+safe channel. A connector's availability alone proves neither authority nor
+access. Reuse covering authority without inventing a new permission grant.
+
+Check that the actual credential's account, project, scope and expiry fit that
+authority. One-time permission is not continuing access. Third-party credential
+ownership needs its own authority; permission for this project does not supply
+it. Use only the host's actual safe channel for credential installation. Never
+put a password, token or key in chat, logs or tracked files, or ask the user to
+paste it there. Interactive login, new permission grants and authority expansion
+remain person-only actions.
+
+If authority, credential ownership or a safe channel is absent or unknown, or
+the host denies the action, stop the dependent action. Give concrete manual
+steps, the evidence that would confirm them and a read-only verification check.
+Do not bypass the denial or infer missing authority from a generic request to
+proceed. Keep a human-run or triage handoff as a handoff; other authorized
+independent work may continue.
+
+Record host access or CI start, authorization, credential installation, CI
+results, merge and publication separately in the existing stage report. For
+each relevant effect state confirmed, pending, unverified or not requested,
+with its target, exact revision, evidence URL when available, blocker and
+resume condition where needed. Missing evidence stays unverified. A green CI
+result proves neither merge nor publication. Report the implemented repository
+change separately from unverified external effects.
+
+## Replies to a waiting step
+
+Read this section before treating a user's reply as a new request.
+
+- A reply answering a pending question or reporting the requested operation's
+  result resumes the same waiting step, including a reported failure. Use no
+  new plan and no skill invocation for that reply.
+- Free text supplying the requested value is an answer to that waiting step,
+  even if it does not repeat an option label.
+  Never treat an unrelated instruction as selection or approval of an option.
+- Dismissal or no response is not an answer or permission. Continue a routine
+  choice only under authorization the user already gave. A missing hard-required
+  fact, uncovered mandatory approval, cancellation or explicit tool block stays
+  protected; do only independent work that remains authorized.
+- An independent new request is planned under the extraction and scope rules
+  in `SKILL.md`. If a reply also contains one, resume the waiting step with its
+  answer and plan the independent request separately.
+- A separate explicit request to investigate the failure or repeat the operation
+  is planned as a new request under those same rules.
+- An answer to a closed request for information follows only the plan's branch
+  for received information. Add no branch or step.
+- For an ambiguous reply, do not assume success, completion, new facts or
+  approval. State what remains unconfirmed. Ask for any fact or decision still
+  needed under the normal question rules.
+
+Background waiting needs no question. Report the current state, awaited
+evidence or result and resume condition; promise no automatic restart unless
+the host provides it. Follow `.agents/rules/user-questions.md` § 6 when an
+answer is needed. A completion-only final report needs no question.
+
+## Independent targets under one goal
+
+Read this section before handling several independent targets under one goal
+or switching the checkout during a target's wait.
+
+Plan each target separately only when its scope is settled and independent.
+Keep each plan's scope, stage order, steps, review and release points. A target
+with an unfinished prerequisite waits; mixed findings with unsettled scopes
+still take the existing bundle/decomposition handling. Give newly eligible
+targets within the goal's criteria their own plans. Report an out-of-scope
+finding as a follow-up, never as an extra step in the current target.
+If no planned stage serves work this target needs, stop that target and name
+the owner and stage skill to invoke. Other authorized independent targets may
+continue.
+
+Use the existing stage reports and handoff messages to retain each target's
+plan and scope, stage and step, branch and exact head, evidence, open approval
+or blocker, and resume condition. Report waiting targets as waiting. Before
+writing or using a result, confirm its target and head. A green check for an
+older or different head does not pass the current one; pending checks do not
+complete verification. A matching red check resumes the planned gate and its
+fix procedure. Keep each review verdict bound to the commit reviewed; never
+relabel it as a review of a newer head or add a review the plan does not name.
+
+Before changing the shared checkout, wait for every writer and local gate
+using it, preserve target edits in a permitted commit of only its paths, and
+ensure the whole index and worktree are clean. Unknown dirty files postpone
+the switch; do not stash, reset or delete them to move on. A reviewer using
+live files or checkout-dependent execution must finish. A read-only reviewer
+using only `git show <fixed SHA>:<path>` may continue across a clean orchestrator switch;
+the reviewer never switches the checkout. CI-only pending gates use the
+existing DELEGATED commit allowance only under a user instruction or project
+policy covering that verification commit and its tracked paths. The project
+must declare the gate CI-only and name its actual check. Every nondelegated gate
+must pass. A delegated red check stops transport of the same unchanged candidate.
+Explicit CI-only delegation covering transport may instead carry actual changes
+addressing that failure through the existing planned fix into a new candidate,
+even while HEAD names the failed commit. Keep the prior head, check, run and
+observed result as FAIL; never relabel that evidence pending. Report the actual
+fix and the new head after committing. Its missing or pending CI result leaves
+verification incomplete. Ordinary FAIL or UNRUN still stops the commit. A commit
+grants no push or pull request authority: each remote action needs its own covered
+instruction or policy. Waiting alone never authorizes a commit or skipped gate.
+
+Use standing delegation only for the targets and actions it actually covers.
+Report routine choices as the agent's decisions under that authority, never
+as the user's individual option approval. A request to ask nothing supplies
+no uncovered approval. If a critical decision or release approval is missing,
+stop that target before dependent work and follow the existing question or
+no-question rules. Other authorized independent work may continue. A stop of
+the whole goal stops every target.
+
 ## Halt notice
 
 One notice when the work stops before its end:
@@ -121,10 +310,28 @@ reset, a stash, a branch switch or a worktree removal.
 | At the chosen scope                   | The chosen stages complete, the stages not chosen, and a verdict for each gate that ran, never that a change is done |
 | At a closing step                     | The closure outcome and each follow-up request, never that a change is done                                          |
 | With a gate failing                   | Each failing gate marked pre-existing or new, with its owner. Nothing reads as complete                              |
+| With delegated CI pending             | The verification commit, pending checks and resume condition; verification remains incomplete                        |
 
+- For a CI wait, name the target, current head, run ID or URL when available,
+  check, actual outcome and counts, blocker and resume condition. State when no
+  run exists. Missing, red or mismatched evidence stops formal completion or
+  merge; every required check needs actual passing evidence for the current head.
+- Report repository outcome separately from external publication. A local commit
+  is not a push or pull request, and passing repository checks do not prove a
+  deployment, package publication or other external effect occurred.
 - A gate shows its verdict only.
 - An external effect nobody requested is listed as not requested.
 - The report does not restate the history of the work.
-- The report ends with a question listing the next actions, the recommended one
-  first, as `.agents/rules/user-questions.md` § 6 sets out. Under a no-question
-  mode it lists them instead.
+- Ask for the next action only when proceeding requires the user's answer,
+  in the shape `.agents/rules/user-questions.md` § 6 requires. A report that
+  only states completion needs no question. Under a no-question mode, list any
+  remaining actions without asking.
+
+## Work orders summary
+
+Read this section when parts ran in parallel. Report one row per part given to
+a sub-agent.
+
+| Step | Role (sub-agent) | Agent instance  | Task title        | Input (refs)  | Output (refs) | Status (PASS/REVISE/PENDING) |
+| ---- | ---------------- | --------------- | ----------------- | ------------- | ------------- | ---------------------------- |
+| 1    | `<role>`         | `<instance id>` | `<part in words>` | The step file | The result    | PASS/REVISE                  |

package/assets/init/.qfai/assistant/skill/qfai-run/references/plan.md

@@ -181,9 +181,10 @@ keeps its scopes: `--route` returns none.
 `schema` for an extraction field, naming its `cause`: `missing` for a required
 field that is absent, `unknown` for a key the extraction does not take,
 `wrong-type` for a value of another type, `wrong-value` for a value outside the
-field's vocabulary, and `invalid` for the rule that ties `alternatives` to
-`confidence`; each cause states what was expected and received, or the field
-name. `unknown-route` for a route the catalog does
+field's vocabulary, and `invalid` for the rules tying `alternatives` to
+`confidence` or requiring `owned-temporary-cleanup` to use `intent: order` and
+empty `artifacts`, including alternative readings. Each cause states what was
+expected and received, or the field name. `unknown-route` for a route the catalog does
 not name, `plan-invalid` for a plan that does not load, naming its `file` and
 `cause`, `artifact-unserved` for an artifact the extraction names when no stage
 of the route writes any artifact it names, so the work stops before the first

package/assets/init/.qfai/assistant/skill/qfai-run/references/stage-points.md

@@ -8,6 +8,10 @@ Before a step `releasePoint` names runs, ask the user to approve the release; wh
 `verify-commit` runs after that, so the commit holds the approval. Nothing after it
 runs without the approval, which authorizes no push, merge, tag or publication.
 
+After approval at a handoff release point, `qfai-run` writes the required
+approval row in `decisions.md` before `triage-handoff` runs. Every triage step
+still changes no tracked file. No handed-off operation runs on the user's behalf.
+
 ## Decision point
 
 At a step `decisionPoints` names, put each critical
@@ -19,6 +23,16 @@ yourself, ask nothing, and list it with its reason in the final report.
 
 ## Branch point
 
+A question-only request with `artifacts: []` may move to a route that writes
+tracked files only under explicit same-target repair authority from the user's
+request or project policy. Reuse that authority without another repair
+question. Otherwise, show the defect evidence, repair scope and planned checks
+and ask through the structured question tool: repair, or report and stop.
+Write nothing before the answer. Under a no-question mode with no covering
+authority, report the defect and required permission and stop that target;
+write no tracked `open-questions.md` row. Asking for no questions alone grants
+no repair authority.
+
 When a step `branchPoints` names reports an outcome
 paired with one route, move there; with several, to the one the step
 names; with `decision-table`, to the route `plan --in` gives the step's

package/assets/init/.qfai/assistant/skill/qfai-sdd/SKILL.md

@@ -91,9 +91,10 @@ Report the source selected, BF and US IDs touched, decision and OQ IDs, contract
 files and index rows, each per-flow validation result and log, independent
 reviewer verdicts, adopted grilling decisions, rejected options still excluded,
 and remaining questions. The next implementation route is `/qfai-implement`; UI work
-may pass through `/qfai-prototyping` first. The report ends with a question
-listing those next actions, as `.agents/rules/user-questions.md` § 6 sets out.
-Under a no-question mode, list them in the report instead.
+may pass through `/qfai-prototyping` first. Ask about those next actions only
+when proceeding requires the user's answer, as `.agents/rules/user-questions.md`
+§ 6 sets out. A completion-only report needs no question. Under a no-question
+mode, list any remaining actions instead.
 
 ## Default Autopilot Policy
 

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/contract-artifact-rules.md

@@ -53,6 +53,7 @@ Discussion UI/UX files are **non-normative** discovery / reference artifacts —
   not only where the attribute is written out — a framework that builds the
   attribute from a variable still writes the marker somewhere.
 - **Every entry under `screens` is a screen, once.** Each UI-bearing contract declares one full `UI-NNNN` ID and a nonempty `screens[]` list. Each screen has an ID and route, unique within its contract. The prototyping cycle covers all declared UI-bearing contract IDs; filenames do not select a legacy spec tier. `QFAI-CONTRACT-042` names malformed screen entries.
+- **Every screen states the text it shows.** A screen declares `supplements` (`[]` when it shows none) and may declare `structure`. `QFAI-CONTRACT-043` names a key that is absent or malformed, `QFAI-CONTRACT-044` an id the screen does not declare, and `QFAI-CONTRACT-045` a text shown twice.
 - **A contract's ID comes from its directory.** `api/` holds `API` contracts,
   `db/` `DB` and `ui/` `UI`; the QFAI repository's own `cli/` holds `CLI`
   contracts. The ID is `<KIND>-NNNN`.

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/design-anti-patterns.md

@@ -22,6 +22,7 @@ naming the pattern is what works.
 - Placement
 - Motion and transitions
 - Copy in the UI
+- Copy that adds no meaning
 - Information architecture and flow
 - States and accessibility
 - Implementation defaults
@@ -51,11 +52,13 @@ naming the pattern is what works.
   flow_ and _States and accessibility_ do, `interface-clarity.md` and the spec
   are the rules. The entry is the form a breach of them takes on a generated
   screen.
-- The reviewer inside the prototyping loop does not apply this list. Root
-  `DESIGN.md` locks the brand values that reviewer sees, so
-  a pattern is caught where the design direction is reviewed and where
-  `DESIGN.md` is written. No entry here is a `lap-*` detection, and none blocks
-  the loop.
+- The reviewer inside the prototyping loop does not apply the sections about
+  identity. Root `DESIGN.md` locks the brand values that reviewer sees, so a
+  pattern there is caught where the design direction is reviewed and where
+  `DESIGN.md` is written. That reviewer does apply _Copy that adds no meaning_,
+  through the criterion on explanatory text, because those patterns are about
+  what the text tells the user, not about a brand. No entry here is a `lap-*`
+  detection.
 
 ## Color and background
 
@@ -269,6 +272,21 @@ naming the pattern is what works.
 - The screen shows technical detail nobody asked for, such as GPU status or
   average generation time.
 
+## Copy that adds no meaning
+
+These patterns are judged against the screen's tasks and the `supplements` its UI
+contract declares, in SDD, in implementation and in every surface review. A chosen
+visual direction does not exempt them. A disclosure about demo data, cost, storage
+or transmission that is true and shown where the user decides is not one of them:
+judge where it sits and what it lets the user do, not the word.
+
+- A second heading or a sentence repeats the main heading, an action label, a
+  state, or the content beside it.
+- A condition the user already knows is explained again where it adds nothing to
+  the decision being made.
+- Production copy carries a development instruction, implementation commentary,
+  or a demo note repeated on screen after screen.
+
 ## Information architecture and flow
 
 - Sections follow the stock order: hero, logos, three features, stats or

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/requirements-decomposition.md

@@ -25,6 +25,14 @@ Use source-backed discussion requirements to write one connected, testable story
 - An EX is one concrete input and expected result for exactly one AC. Split examples whose paths can pass or fail independently.
 - A BR is one independently falsifiable constraint. If removing a clause leaves another complete rule, split it.
 
+A capacity-only sibling may represent the same actual actor goal within the
+same BF when requested AC or EX additions exceed the source story's remaining
+capacity. Prefer preserving published cases and IDs, and place only new,
+cohesive incoming cases under their own covering change request. Confirm
+retired-inclusive capacity and the owning approval before writing; this
+exception invents no new product outcome and grants no future creation or move
+permission.
+
 Allocate each ID as the highest ID of its kind in its defined scope plus one, counting retired IDs. Never reuse an ID. The scopes and widths are in the `ID allocation` section of the triage reference.
 
 ## Ambiguity

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-execution-playbook.md

@@ -4,10 +4,35 @@ Use this sequence for /qfai-sdd. The shipped templates under ../templates/spec/
 
 ## Stage 0: source inventory
 
-1. Run npx qfai sdd preflight and read its selectedInputPath and source. Respect an explicitly selected discussion pack, including one older than the newest pack.
-2. Read the selected pack, completed reviews that target it, explicit user requirements, and the existing story tree. A pack is reference and provenance material. Disposition its applicable review advice in the SDD report, a decision row, or an open question. A pack discrepancy does not itself block SDD.
-3. Stop if there is no usable input source. Stop on an unresolved product decision that cannot safely be inferred; record the question in open-questions.md.
-4. If no discussion pack exists and an imported specification does, run npx qfai sdd preflight --import <path> with that file, which selects it as the source. An explicit user requirement is used as it is and named in the SDD report. Do not manufacture a discussion pack.
+1. Use the launcher established by
+   `.qfai/assistant/rule/shared-skill-operating-baseline.md#canonical-qfai-launcher-mandatory`.
+   Record its resolved package path and version in the SDD report. Check that
+   the installed Stage 0 instructions support the procedure being used.
+2. Run `npx qfai sdd preflight` and read its `selectedInputPath` and `source`.
+   Respect an explicitly selected discussion pack, including one older than the
+   newest pack.
+3. Read the selected pack, completed reviews that target it, explicit user
+   requirements, and the existing story tree. A pack is reference and provenance
+   material. Disposition its applicable review advice in the SDD report, a decision
+   row, or an open question. A pack discrepancy does not itself block SDD. For
+   the current request, read the existing purpose in
+   `<paths.specsDir>/01_policy/objective.md` and inspect related flows and stories.
+4. A missing discussion pack does not mean that specifications are missing. If
+   an existing readable specification is authoritative for this request, run
+   `npx qfai sdd preflight --import <path>` with that file. The fallback does
+   not replace a selected pack or bypass unsafe pack names, unreadable files,
+   invalid active pointers, config errors, or a mismatched tool.
+5. Use an explicit user requirement as supplied and name it in the SDD report.
+   Do not invent an import file from conversation. Without a file, CLI preflight
+   can remain blocked while SDD assesses that explicit requirement.
+6. Use `/qfai-discussion` only when no usable source exists; stop SDD until one
+   is available. Stop on an unresolved product decision that cannot safely be
+   inferred; record the question in `open-questions.md`. Do not manufacture or
+   regenerate a past discussion pack, or regenerate the existing purpose,
+   merely to clear preflight.
+7. Import-lite readiness identifies the input source. It does not establish
+   complete requirements or a validation PASS. Keep the existing purpose and
+   current request while updating only affected flow and story content.
 
 ## Stage 1: triage and decisions
 

package/assets/init/.qfai/assistant/skill/qfai-sdd/references/sdd-triage.md

@@ -7,6 +7,7 @@ Triage selects the smallest story-tree change that answers each incoming require
 - Inputs
 - Operation choice
 - Decision and question rows
+- Published decision prefix recovery
 - Approval and no-question mode
 - Retiring an EX, AC or BR
 - ID allocation
@@ -34,7 +35,7 @@ Inspect the impact cascade: policy → BF → US → AC → EX → enforcing con
 ## Decision and question rows
 
 Use <paths.specsDir>/decisions.md and <paths.specsDir>/open-questions.md, each with exactly ID, Content, Approach, Status. Append a row; later only Status may change, including to `PARTLY SUPERSEDED (by DEC-NNNN)` when a later row narrows a decision without replacing it.
-Do not edit the first three cells or remove the row. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
+Do not edit the first three cells or remove the row, except for explicit branch-added decision renumbering under ID allocation below or the bounded published decision prefix recovery below. Inherited rows retain those cells. Use the next highest ID in the table plus one. A retired item still reserves its BF or US ID.
 
 decisions.md records only what the user decided: each change request the user approved or declined,
 and each critical decision the user made. A row is appended once the user has decided what it records.
@@ -58,6 +59,45 @@ whose Content opens Unadjudicated:, at TODO until decided. A justified test exce
 decision Content with Test exception:, names the exact BF, AC, or EX it exempts, and puts the reason
 in Approach. It takes effect only at DONE; it never exempts descendant items.
 
+A test annotation may remain pending only when authority to change the
+specification covers that state and the test deferral is approved. Record the
+specification change in its own `Change request:` row. Record the deferral as a
+`Test exception:` decision naming the exact AC at DONE. Its Approach states
+the reason, untested scope, owner, next decision date and condition for restoring
+the annotation.
+
+DONE establishes the exception decision; it does not mean test completion.
+The existing info finding names the exempted AC and its decision without
+claiming test execution or coverage. The exception never exempts descendant EX
+obligations or authorizes changes to EX or BR scope. Do not silently substitute
+an EX or prose rewrite for an approved specification change. Use the next
+decision date for manual review; there is no automatic expiry and no automatic
+warning.
+
+When specification changes are forbidden or either authority is missing, first
+append an `Unadjudicated:` OQ at TODO. Name the affected IDs, expected versus
+actual behavior, implementation-change evidence, owner and required permission.
+Stop dependent AC, EX and BR edits; independent authorized work may continue.
+
+## Published decision prefix recovery
+
+When an approved request names a published malformed decision added by the
+branch, read `.qfai/assistant/rule/drift-protocol.md#published-decision-prefix-recovery`.
+That rule defines the source, byte boundaries, exact prefix and stop conditions.
+Approval of the generic protocol alone authorizes no target; append a separate
+new target-specific recovery change request using `templates/change-request.md`.
+
+Record the fixed base and unique common ancestor, absence of the target in both,
+the published source commit's ancestry, raw Approach digests and the exact
+approved prefix. Immediately before writing, recheck the unique current row,
+its original ID, Content and Status, and its old digest. Preserve every original
+Approach byte as the suffix and leave every other row unchanged. Recheck the
+existing form and validation; status or supersession clears no malformed form.
+Record actual results, including any stopped recovery, without claiming an
+automatic repair. Inherited records and open-question rows remain excluded.
+Rollback follows the recorded new-digest check and restores the original form
+failure; it never resets, amends or force pushes.
+
 ## Approval and no-question mode
 
 Use the shared user-question protocol for CREATE, DELETE, SPLIT, MERGE, SUPERSEDE, and UPDATE:REMOVE. Present the target and rationale. Do not self-approve. A request from the user in the session that names the operation and its effect is the approval, and no second question is asked.
@@ -81,7 +121,7 @@ A story-tree or contract file changes only on the user's approval:
    records who approved it, when, and the label of the option chosen.
 3. Move the row to DONE once every change it names is written.
 
-A row present before the stage started keeps its ID, Content and Approach.
+A row present before the stage started keeps its ID, Content and Approach, except for explicit branch-added decision renumbering under ID allocation below or published decision prefix recovery above. Inherited rows keep those cells without exception.
 Only a row this stage appended changes its Status.
 
 ## Retiring an EX, AC or BR
@@ -104,12 +144,74 @@ Read all IDs of the kind in the relevant scope, including IDs named by retiremen
 A contract number spans every contract kind, and a BR is numbered inside its contract. DEC and OQ each span their table.
 Empty numeric scopes begin at 0001, and AC/EX tails begin at 01. Do not reuse an ID because its file was removed or a row was rejected.
 
+### Capacity before writing
+
+AC and EX tails stay two digits, from 01 through 99. Before writing a planned
+batch, report each affected kind and story, its high-water number H (0 when
+empty), remaining capacity 99-H and the number of requested additions. Count
+valid IDs in the tree and decisions, including retired IDs, plus observed
+published parallel heads and known reservations under the project's existing
+method. Name the fixed observation and what it did not cover. A snapshot
+reserves nothing and cannot cover unpublished concurrent work.
+
+If requested additions exceed 99-H, stop before any partial allocation or
+invalid declaration. Never fill gaps, reuse retired IDs or emit tail 100.
+An empty scope has capacity 99. H = 98 allows one addition at tail 99, not two;
+a retired 99 still exhausts the scope. Recheck newly published claims or
+collisions before publication.
+
+### Capacity partition
+
+Only additions exceeding an actual AC or EX scope's remaining 99-H qualify for
+a capacity-only story partition. Record the source story, affected kind, H,
+remainder and requested count first. Prefer leaving every published case and ID
+in place and putting a cohesive incoming group in a capacity-checked sibling
+under the same BF and actual actor goal. An in-force owning change request must
+explicitly approve this partition and its affected paths before writing.
+
+State the sibling's truthful cohesive scope and settle each criterion's owner;
+do not invent a new product outcome, duplicate an obligation or weaken it.
+A different actor, goal, flow or intended behavior needs its existing owning
+approval path. Additions that fit the original scope do not qualify. Missing
+authority, insufficient destination capacity or no truthful partition stops
+the dependent write. This prospective split places new overflow cases; moving
+an existing case also needs the complete map below. These instructions approve
+no future specific creation, move or split.
+
+### Actual moves and incoming collisions
+
+Before an approved actual AC/EX move or incoming collision repair, make a
+complete one-to-one map of:
+
+- the fixed source commit and declaration path;
+- each original BF/US/AC/EX identity and its case meaning;
+- destination story, AC/EX IDs and paths;
+- every affected active BR citation and counted adjacent test declaration;
+- unaffected cases and the input, expected outcome and executable assertion
+  each mapped case preserves.
+
+Check both scopes' retired-inclusive capacity. Each destination EX needs one
+existing destination AC; each AC needs an EX. Preserve every moved EX's
+owning BR link and counted test obligation. An ID change alone proves no
+coverage. Retire old moved IDs in a new approved record and never refill them.
+Inherited published DEC ID, Content and Approach cells and their old-ID
+references remain historical and unchanged; update only approved active
+references.
+
+Keep unaffected published cases and IDs. Identify same-number branch cases by
+fixed provenance and meaning, and change only the provably incoming item,
+without blanket replacement. Unknown ownership, ambiguous collisions,
+uncovered declarations, missing counted test links, changed assertions or an
+incomplete map stops the move without a completion claim. This is a manual
+approval and mapping procedure, not a relocation executor or mapping schema.
+
 Two branches can take the same next ID. When a merge leaves one ID on two items:
 
 1. The merge target's item keeps the ID. Renumber the incoming item, the one the merge brings in.
 2. Give it the next ID of its scope.
    A renumbered BF or US takes its child IDs and its directory names with it, as a move to another BF does below.
-3. Change every citation of the old ID in the same commit.
+3. Change every citation belonging to the incoming item in the same commit.
+   For a decision, leave inherited references unchanged.
 4. State the old ID, the new ID and the renamed record's subject or path in the commit message.
    A citation of the old ID elsewhere is then told apart from the item that kept it.
 
@@ -118,7 +220,33 @@ A row the incoming branch added takes the next ID of its table.
 An ID that two merged records already share is not renumbered:
 ask the user for a change request row that states which record each citation meant.
 
-A move to another BF changes the story's US ID and all child AC and EX IDs. Record the old IDs as retired, allocate new IDs in the destination scope, and update every citation before the move is complete.
+For a unique decision added by the incoming branch, repair its ID before merging:
+
+```text
+qfai sdd renumber-decision --from <old-DEC-ID> --to <new-DEC-ID> --base <local-ref>
+```
+
+The explicit base and HEAD must resolve locally and have one common ancestor
+that declares no source row. The base may already use that ID; the current
+tree must declare it only once. Choose an unused destination above both story trees'
+highest decision number, retired IDs included, within the four-digit grammar.
+The command reserves no number and chooses no final number automatically.
+
+Read the preview's fixed SHAs, IDs, relative paths and replacement lines or
+counts. It writes nothing and dumps no original lines or full files. Each
+invocation builds its own plan. Run with `--apply` to recheck that invocation's
+fixed refs and original bytes before writing; changed refs after a preview can
+produce a different plan. Preflight-only
+`--format`, `--fail-on`, `--import` and `--assume` are not accepted here.
+Only provably branch-added exact references change. Inherited references stay
+fixed; ambiguous ownership, dirty or linked candidates, unsupported text or
+failed reads stop the whole plan before writing. Unrelated links and dirty
+files are not candidates. Apply rechecks original bytes before each write.
+Rollback restores a changed file only if its bytes still match this invocation's
+replacement, preserving concurrent changes and naming any unrestored path.
+These checks guarantee neither atomic concurrency nor power-loss safety.
+
+A move to another BF changes the story's US ID and all child AC and EX IDs. It follows the existing approval path, not the same-BF capacity exception. Apply the complete map above to approved active citations and retire old IDs in a new approved record; inherited DEC cells and their historical references stay unchanged.
 
 ## Completion of triage