qfai 2.1.0 → 2.1.2

package/assets/init/.qfai/assistant/rule/shared-skill-operating-baseline.md

@@ -4,70 +4,11 @@ Use this document to keep SKILL bodies compact. Skill files should reference thi
 
 ## Asset Authoring Shape (Mandatory)
 
-A `SKILL.md` states the contract and points at the file that carries the detail. It is not where the detail lives.
-
-- **Keep in `SKILL.md`**: what the skill is for, its non-goals, its hard constraints, the phase/step order, and the gate conditions. Enough for an agent to know what it must do and when it is done.
-- **Move out**: command sets, table schemas, field-by-field contracts, worked procedures, checklists and rationale. These go under the owning tree's own directory:
-  - `references/` — normative detail the body cites (`references/<topic>.md`)
-  - `templates/` — artifacts the file produces, as fillable skeletons
-  - `examples/` — worked instances that illustrate, and bind, nothing
-- **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.
-
-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.
-
-**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.
-
-Two shapes are not measured, and for the same reason — the author cannot make them narrower:
-
-| not measured   | why                                                       |
-| -------------- | --------------------------------------------------------- |
-| a table row    | markdown gives it no continuation, so it cannot wrap      |
-| a fenced block | its content is a command, a diagram or a sample, verbatim |
-
-A table is found by its delimiter row, not by a leading pipe: that pipe is optional, so a table written without one is still a table, and a paragraph that opens with one is still a paragraph. Rows a blank line has cut off from their delimiter are prose, because that is how they render.
-
-Some shipped files predate the ceiling and carry a recorded width of their own. It is the width each arrives with, so `npx qfai doctor` does not report a fresh tree for content you received rather than wrote. That record belongs to the package and shrinks there; it is not a per-project allowance, and it never loosens the ceiling on an asset you write. **Everything you author is held
-at 400.**
-
-The exemption from the line ceiling does not carry here. Its reason is about a file's length, not about how wide one line may be.
-
-No shipped prose asset has a line-ceiling exemption. Agent definitions are
-individual cards under `assistant/agent/`, so their count does not lengthen
-one roster file.
-
-### The owning tree is the one the file sits in
-
-The ceiling applies to **every** shipped assistant prose asset, including
-rules and cards. A rule at the ceiling moves topic detail to
-`rule/references/<topic>.md`; a skill uses its own `references/` directory.
-The tree that owns the file owns its detail.
-
-For a prose asset, raising the ceiling or claiming an exemption is not the remedy. An exemption claims no split is possible, and a Markdown file whose tree has a `references/` home available cannot make that claim.
-
-### Machine-readable assets split in their own format, or say why they cannot
-
-The ceiling is measured over YAML assets too — package routing and review-profile defaults and the shipped contract templates. The split above is not open to them: a validator parses those files as structured data, or a skill copies one whole into a project, so an entry moved into a Markdown sibling under `references/` leaves the parsed document and stops meaning anything. Prose about the
-file may move there; the file's own items may not.
-
-So for a machine-readable asset at the ceiling the remedy is, in order:
-
-1. **Split it in its own format** — a sibling of the same kind that the loader or schema already reads, so every item stays parsed.
-2. **Record an exemption** where the document has to stay whole — a file generated from another asset, one the schema admits only as a single document — naming what makes the split impossible. "This file is long" is not that reason, and a prose asset may not use this step.
+Read `.qfai/assistant/rule/references/asset-authoring.md` when you write or change a file under `.qfai/assistant/**` or another shipped asset, including its citation paths. It holds the shape every asset takes, which tree owns a file, how machine-readable assets split, and the form of a citation path. Not needed for a run that only reads assets or edits project files.
 
 ## Citation Path Form (Mandatory)
 
-A pointer only resolves if the reader knows what base to resolve it against. There is one base, and it is the project root.
-
-- **Cite a shared rule by its full path from the project root.** Write the path from the project root, with `#anchor` appended when one applies: `.qfai/assistant/rule/drift-protocol.md`. Not the bare filename, not a relative climb. That form resolves from every directory in the tree,
-  and the only one that still resolves when read with the cwd at the project root — which is where an agent's cwd is.
-- **The same holds when a rule cites another one**, including a sibling in its own directory. A bare name works there only by accident of where the citing file sits; it stops working the moment the text is quoted elsewhere.
-- **Within a skill's own directory, keep pointers relative to that directory**: `references/<topic>.md`, `templates/<name>.md`. Those name the skill's own parts, not a shared document, and the surrounding text already establishes which skill is meant.
+The form of a citation path is in `.qfai/assistant/rule/references/asset-authoring.md`, read under the same condition as the section above.
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -255,9 +196,9 @@ the policy check. The mode is `workflow.mode` in `qfai.config.yaml`. An absent k
   needs the operator's answer.
 - A QFAI work order binds the stage to its target: one business flow, or one
   new-story slot. The stage works on that target and no other.
-- The stage result names the agent instance that did the work in
-  `actor: { agentInstance }`. The run records that instance as the work's
-  author and never counts it as the work's independent reviewer.
+- The session report names the agent instance that authored the work and
+  each independent reviewer. The author never counts as the work's
+  independent reviewer.
 - These statements add to the constitution. They except no article.
 
 ## Running Steps (Mandatory)
@@ -327,12 +268,12 @@ writes nothing and states why; the stage's review reads that statement.
 
 ## Default Autopilot Policy inside a run
 
-Inside a run, each bucket of a skill's Default Autopilot Policy is
-satisfied by one kind of authorization the run records:
+Inside a run, record the authorization for each bucket in the session report:
 
-- An `ask-user` item is satisfied only by a `human_decision` that answers it.
-- A `hard-required` input is satisfied by `request_scope` or by the run's
-  binding.
+- An `ask-user` item is satisfied only by the operator's answer to it.
+  Name that answer and its source; an agent's choice is not an operator answer.
+- A `hard-required` input is satisfied by the operator's request or by the
+  run's binding. Name the request or work order that supplies it.
 - An `auto-decide` item needs no authorization.
 - `--auto` satisfies nothing. It answers no `ask-user` item and supplies no
   `hard-required` input.
@@ -351,69 +292,11 @@ can resolve stops at preflight.
 
 ## Gate Failure Autorepair Protocol
 
-Follow this protocol when any of the validate, doctor, test, lint, typecheck, build, capture, or report gates fail. A reviewer's `REVISE` is not a gate failure and is not rerun: the author fixes or answers each finding once, as `.qfai/assistant/rule/review-convergence.md` sets out.
-
-- inspect exit code, logs, `validate.json`, and cited files before reporting — in `validate.json`, read `counts` for the verdict and `issues[].code` for each finding; the array is `issues`, not `findings` (keys: `.qfai/assistant/skill/qfai-verify/references/validate-json-schema.md`);
-- classify each finding as skill-owned artifact, upstream spec/contract, code/test defect, environment/tooling, or user decision;
-- fix skill-owned artifacts and code/test defects autonomously when the fix is local and non-destructive;
-- **upstream spec/contract findings: never repair.** STOP and follow `.qfai/assistant/rule/drift-protocol.md` (Change Request + owner-skill rerun) — **even when the fix looks local and non-destructive, and even when it is one token and obviously correct**. "Local and non-destructive" is a permission for the two classes above it; it is not a test that upstream artifacts can pass.
-  Ownership, not size, decides;
-- environment/tooling findings: repair the environment when it is yours to repair (install a missing dev dependency, regenerate a lockfile, create a scratch directory). Stop for anything needing credentials, network access you do not have, or a change to CI configuration or the host machine;
-- user decision findings: never decide by default. Record the question, state the option you would take and why, and stop — a decision taken silently to keep a gate green is the same failure as repairing upstream, one layer up;
-- rerun the same failing gate after each fix batch, **and once with no intervening change** when the failure looks nondeterministic — see `#nondeterministic-gates` below. The confirmation rerun is bounded at one: after it the finding is classified, not re-rolled;
-- do not weaken profiles, lower `--fail-on`, waive errors, invent evidence, or skip required reviewers;
-- stop for destructive changes, **any upstream spec/contract finding**, ambiguous product/spec decisions, missing permissions/tools, or repeated no-progress failures — the stop list is closed over the classification above, so every class the agent is told to use has a defined next action;
-
-When stopping, report: cause, attempted fixes, remaining blocker, user action, retry gate, and **the work counts — how many items are complete, how many are blocked, and by which finding**.
-
-The counts are not decoration. Restating the ownership rule does not change the incentive that breaks it: an agent facing "repair five upstream defects or report most of the batch as blocked" reaches for the repair because the alternative reads as failure. `26 items: 21 complete, 5 blocked on DB-0007` is a report of work done, and it is what makes STOP a credible answer rather than a
-surrender. Blocked is a status, not a verdict on the run.
-
-### Nondeterministic gates
-
-A gate whose answer varies on identical inputs is a finding in its own right, not a run to discard. The protocol classifies it as `environment/tooling`; what follows is what that class obliges.
-
-**When a gate fails and a rerun with no intervening change passes**, all of the following are REQUIRED. A clean rerun on its own is not evidence for that gate.
-
-- **Record it as an `environment/tooling` finding.** Not as a pass, and not as a code/test defect — nothing was fixed between the two runs.
-- **Disclose every run.** Report the results of all runs of that gate, in order, with their commands. Reporting only the run that passed is [selective reporting](#selective-reporting-is-invented-evidence) and is forbidden: the evidence rules are satisfied by a clean run's command and output, so nothing else stops it.
-- **Re-run the failing selectors in isolation** and report that result too. A selector that passes alone and fails in the suite is the signature of shared state, not of a defect in that test.
-- **Name the suspected cause**, concretely: a contended port, a shared database or schema, an `os.tmpdir()` path, an un-namespaced cache or queue, ordering between workers. "Flaky" is not a cause.
-
-Do not fix the flake by rerunning until green, and do not fix it by weakening the test. Either the shared resource is isolated per worker or the run is serialised — both are real changes with a real cost, which is the point.
-
-A gate reported this way has **not passed**. It is a blocker with a named cause, and it goes in the stop report like any other.
-
-#### Selective reporting is invented evidence
-
-Reporting the clean run and omitting the red ones satisfies every existing evidence rule — a real command, a real result, freshly obtained — and still misrepresents what happened. Which of N runs is reported is itself part of the evidence, so omitting runs of the same gate is on the same footing as inventing one.
+Read `.qfai/assistant/rule/references/gate-failure-autorepair.md` when a gate command fails or its result cannot be trusted. It holds the repair loop (inspect, classify, fix, rerun), the findings that are never repaired, when to stop and what to report, and how a gate that does not give the same answer twice is handled. Not needed while every gate passes.
 
 ## Context Summary Contract
 
-When context is summarized, preserve the requests, decisions and stage state
-needed to continue.
-
-Every summary that replaces earlier context keeps these six:
-
-1. Difficulties that came up, and how each was resolved.
-2. Options raised, tried or set aside, and why.
-3. Everything asked for, decided, agreed, ruled out or established as a constraint — in the exact words.
-4. Where things stand: what is covered, settled or complete.
-5. What is still open, promised or expected next.
-6. Details that are hard to reconstruct: names, numbers, dates, exact wording, references.
-
-It also keeps the stage state. None of it can be recovered from the code, and a summary that keeps the six and drops it still misleads the next window.
-
-| Stage state                                                                               | What goes wrong when it is dropped                                                                                   |
-| ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| The execution ledger and the row in progress                                              | Finished rows are worked again, or a row in `red` is taken for untouched                                             |
-| Every open question, with its ID and status                                               | A question stays open with nobody tracking it, or is answered twice                                                  |
-| The clarification budget spent in this invocation, and the questions it was spent on      | The next window asks what the user already answered, or asks past the cap                                            |
-| Every assumption recorded under `--auto` or after the budget ran out, with its label      | A labelled assumption is read back as a decision someone took                                                        |
-| Whether the stage's review has run, and each finding's fix or answer                      | The review runs a second time, or an answered finding is raised again (`.qfai/assistant/rule/review-convergence.md`) |
-| A grilling session's decision tree, its current frontier, and the answers already settled | An answered question is asked again, or a question is put before the one it depends on (`.agents/rules/grilling.md`) |
-
-Keep what the user said close to their own words. Your own reasoning may be condensed to what it concluded, as long as nothing listed above is dropped. Be complete on these items even when that makes the summary longer.
+Read `.qfai/assistant/rule/references/context-summary.md` when you hand work to a sub-agent or summarize a context for the next stage. It holds what a summary that replaces earlier context must keep. Not needed when no summary is written.
 
 ## Completion Contract (Shared)
 
@@ -433,22 +316,8 @@ report instead of the completion claim.
 
 ### What the placeholder scan does not flag
 
-**`OQ` and `OPEN QUESTION` are exempt only as tracking structure.** Exempt: the `Open Questions` heading, a register
-table header, and a question row containing the fields required by its register. Story-tree `open-questions.md` uses
-`ID | Content | Approach | Status`; an empty register contains the heading and table header without a question row.
-Discussion registers use their own template fields. A register row's Status is structure too: `TODO` in the Status cell of a
-`decisions.md` or `open-questions.md` row is the row's state, not a placeholder. Article II and `.qfai/assistant/rule/workflow.md` both end an
-unverifiable fact by recording an Open Question, so the tracked record they prescribe must never be reported as an
-unresolved placeholder. Everywhere else the two strings are still scanned: a bare `OQ` or `OPEN QUESTION` left as a
-value in generated spec prose or a contract field, or a row missing a required field, is a hit like any other token.
-
-**A documented `TBD` is a compliant record.** `.qfai/assistant/rule/constitution.md` Article II and `.qfai/assistant/rule/thinking.md` require writing `TBD` together with a note of what evidence is missing, and `.qfai/assistant/rule/thinking.md` requires raising the matching Open Question for the same fact. Both halves together are the finished form, not an
-unfinished one; do not report it and do not delete it — deleting it destroys the record of the missing evidence, which is the whole point of the marker. A `TBD` missing either half — no note, or no Open Question — is a hit.
+Read `.qfai/assistant/rule/references/placeholder-scan.md` when the placeholder scan reports a hit or you decide a hit is not a defect. It lists what the scan does not flag and what a surviving hit obligates. Not needed while the scan reports nothing.
 
 ### What a surviving hit obligates
 
-A hit is **reported, not silently cleared**, and **cleared by a re-scan, not by assertion**. Fix what you can, then run the scan again over the same artifacts: _resolved_ is the verdict for a hit the re-run no longer reports, and that re-run is its evidence. It is not available for a hit still present at that file and line — a token still readable there is unresolved whatever the report
-calls it. List every hit the re-scan still finds alongside the completion claim — file, line, token — and state for each one whether it is deferred with rationale or recorded as an Open Question. A completion claim that omits a surviving hit is invalid evidence under the rules above. Completion is blocked while a surviving hit is neither of the two.
-
-**Severity floor on the verdict.** _Deferred with rationale_ and _recorded as an Open Question_ are NOT available for a hit that stands in for a concrete security defect, data loss or corruption, or a correctness defect that would break a released contract. Such a hit is cleared only by a named fix or by dropping the item from scope; recording it and declaring completion anyway is
-prohibited, exactly as `.qfai/assistant/rule/shared-skill-delegation-baseline.md` withholds that same exit for that same class. While neither of the two remaining verdicts applies, completion stays blocked.
+The obligation a surviving hit carries is in `.qfai/assistant/rule/references/placeholder-scan.md`, read under the condition above.

package/assets/init/.qfai/assistant/rule/stage-cost.md

@@ -1,6 +1,6 @@
 # Stage Cost
 
-What a stage costs, and the levers that change it: how deeply a model reasons
+What a stage costs, and the settings that change it: how deeply a model reasons
 per step, how long the stage is given, and how much of a file an edit rewrites.
 
 None of them is a cap. Where a hard limit is wanted, it is the per-request

package/assets/init/.qfai/assistant/rule/test-layers.md

@@ -26,6 +26,9 @@ locations; a file outside the selection does not establish coverage.
 
 Exercise one unit's observable decisions without real infrastructure. A
 `QFAI:EX-NNNN-NNNN-NN` annotation links a behavioral unit test to its example.
+The annotation counts only on the comment line directly before the `it(`,
+`test(` or `describe(` it marks, or the equivalent test declaration of another
+framework; a file header or a comment inside a test body covers nothing.
 
 ### L2 Component
 
@@ -91,6 +94,45 @@ EX may need an additional focused test even when its parent AC or BF is
 covered. Keep independently observable cases in separate tests so a failure
 points to the behavior that changed.
 
+## Test-suite sizing
+
+Every source change still carries test coverage, and every obligation still
+has its test. This section sizes that coverage. It never removes any.
+
+- **Size a new test file like the ones next to it.** Aim for roughly one
+  focused test per stated behaviour.
+- **Choose a process-per-case suite, never inherit one.** A suite that spawns a
+  process for every case is the shape that makes a CI lane expensive. Pick it
+  for the suite in hand, not because the file beside it has it.
+- **A scratch check is not a deliverable.** Verify the work in progress any way
+  you like. Do not turn a scratch check into a permanent test file. Scratch
+  files go where `.agents/rules/temporary-files.md` puts them.
+
+These are review signals, not gates. No validator reads them.
+
+## End-to-end test cost
+
+An end-to-end test is the slowest test a project runs, and a failing one costs
+the most. A test that cannot find an element waits for its whole timeout, and
+waits again for every retry. One failure costs the timeout times the attempts,
+and a red suite with no limit runs until the job is killed. The number of
+failures sets the bill more than the number of tests does.
+
+- **Set a failure limit.** Stop the run after a small number of failures.
+- **Set a job time limit** well below the CI platform's default.
+- **Lower the test timeout** to what a passing test needs. Allow at most one
+  retry in CI.
+- **Do not share one database across parallel workers.** Concurrent tests
+  change each other's data, so one commit gives different results and a
+  failure cannot be told from noise. Give each worker its own data, or run one
+  worker.
+- **Record traces only on a retry in CI,** not on every test.
+- **Hold a count ceiling that only moves down.** Count end-to-end tests per
+  business flow, not per story or example. Prove an acceptance criterion or an
+  example in a lower layer.
+
+These are review signals, not gates. No validator reads them.
+
 ## Test stub detection
 
 A test is incomplete if its body contains a placeholder, skips the

package/assets/init/.qfai/assistant/rule/ui-definition-protocol.md

@@ -27,6 +27,8 @@ A downstream skill reads the UI definition in this order.
    - primary tasks
    - states
    - actions
+   - supplements (the text shown beyond title, group headings and labels, each with
+     its reason) and, when written, structure (the groups and headings, in order)
 
 3. **Brand SSOT**
    - root `DESIGN.md` (front-matter + `# Brand Philosophy` body), the only
@@ -36,6 +38,10 @@ A downstream skill reads the UI definition in this order.
    prototyping loop ran): the final prototype, procurement and implementation
    notes
 
+The supplements and structure are required input: implementation adds no text the
+contract does not declare, and surface review compares the rendered text with them.
+A screen that lacks them is returned to `/qfai-sdd`.
+
 The paths that render a user-visible surface are declared by `uiux.surfacePaths`
 in `qfai.config.yaml`, and nowhere else.
 
@@ -51,6 +57,5 @@ in `qfai.config.yaml`, and nowhere else.
 ## Forbidden Fallbacks
 
 - Do not infer downstream UI behavior from discussion-pack sidecars.
-- Do not use retired design contract files.
 - Do not use HTML mock sections as downstream source of truth.
 - Do not treat a competitor reference as a selected design direction.

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

@@ -1,7 +1,7 @@
 ---
 name: qfai-configure
 title: QFAI Configure (Tune qfai.config.yaml)
-description: "Analyze the repository and tune qfai.config.yaml test globs and project overrides."
+description: "Analyze the repository and tune qfai.config.yaml test globs and project overrides. Use when asked to configure QFAI for a repository, or to fix test globs that match the wrong files or none."
 argument-hint: "[--auto]"
 allowed-tools: [Read, Glob, Write, Edit, TodoWrite, Task, Agent]
 roles:
@@ -25,7 +25,7 @@ QFAI Skill Body (SSOT)
 
 ## /qfai-configure - Configure QFAI for this repository
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 ## User Questions (AskUserQuestion Protocol)
 
@@ -69,18 +69,6 @@ When unsure, read inputs in this order:
 
 Follow `.qfai/assistant/rule/shared-skill-delegation-baseline.md`.
 
-### Orchestrator Protocol
-
-- No additional overrides.
-
-### Capability Probe
-
-- No additional overrides.
-
-### Delegation Failure (Hard Stop)
-
-- No additional overrides.
-
 ### Work Orders Summary (evidence)
 
 Use the shared schema.
@@ -179,30 +167,13 @@ The final report includes:
 - gaps and open risks ("none" is acceptable if justified)
 - the final status (PASS/FAIL) and who confirmed it
 
-## Non-Negotiable Principles (QFAI Articles)
-
-These principles are inspired by "constitution / articles" patterns used by other agent frameworks, but adapted to QFAI.
-
-1. **SDD First (Specification is the source of truth)**  
-   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+## Working principles
 
-2. **Traceability is mandatory**  
-   Every meaningful change must connect a business flow, story, acceptance criterion, example, test, code, and verification evidence. BF is covered by E2E tests, AC by integration or API tests, and EX by a selected non-E2E test. Full rule: `.qfai/assistant/rule/constitution.md` Article V.
-
-3. **Evidence over confidence**  
-   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
-
-4. **Minimize scope, but never hide gaps**  
-   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.
-
-5. **Quality gates are the decision mechanism**  
-   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
-
-6. **Make it runnable**  
-   Outputs must be executable in terminal/CI. Provide copy-paste commands.
-
-7. **User time is expensive**  
-   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.
+Read `references/principles.md` when a choice is not settled by a step below.
+It holds the seven principles the steps follow: the specification is the
+source of truth, traceability, evidence over confidence, minimal scope without
+hidden gaps, quality gates, runnable output, and the user's time. A choice a step
+settles needs no reading of it.
 
 ## README Rule
 
@@ -244,11 +215,6 @@ Return:
 - proposed globs + rationale + evidence refs
 ```
 
-### Failure rule
-
-- A delegation the orchestrator chose to make is its own capability check.
-- A failed delegation is handled as `.qfai/assistant/rule/shared-skill-delegation-baseline.md` sets out. Do not simulate roles.
-
 ## Completion Separation (mandatory)
 
 - Config changes (`devops-ci-engineer`) and their approval (`qa-gatekeeper`) must be separate.
@@ -327,7 +293,7 @@ Fill policy templates with repo evidence.
 - Keep existing content when already accurate.
 - When evidence is missing, write `TBD` and record what is missing.
 - Do not invent facts.
-- Fill `03_contract/tech.md` in its template's shape: a Stack row for the runtime, the platform and each tool detected, each runtime dependency with its reason, and the quality-gate commands under Standard commands, one labelled item each. It holds no rule and no constraint; a constraint goes to `01_policy/constraint.md`.
+- Fill `03_contract/tech.md` in its template's shape: a Stack row for the runtime, the platform and each tool detected, with one row per test layer whose Choice names the tool, the files it was observed in, and why it fits; each runtime dependency with its reason, and the quality-gate commands under Standard commands, one labelled item each. It holds no rule and no constraint; a constraint goes to `01_policy/constraint.md`.
 - Fill `## Architecture` of `03_contract/tech.md` from the codebase: one row per layer the module layout shows, what it is responsible for, and the layers its imports reach, or `-`. Name layers, never paths. Implementation places new code by this table and reviewers judge a change against it, so write the import directions the code has.
   - A layer is a group of modules whose imports point one way: an upper layer uses the layers below it, and a lower layer never imports an upper one.
   - Draw the layers first, as one `mermaid` `flowchart TD` with a node per layer and an `Upper --> Lower` edge per import direction. Then write the table rows from the uppermost layer down, so each Depends on names only rows below it. `npx qfai validate` reports a diagram and a table that disagree.
@@ -338,10 +304,10 @@ Edit:
 
 - `validation.traceability.testFileGlobs`
 - `validation.traceability.testFileExcludeGlobs` (only if needed)
-- `routing` or `reviewProfiles` only when the project needs an override; each matching entry replaces the shipped default as a whole
+- `routing` or `reviewProfiles` only when the user asks to change one; each matching entry replaces the shipped default as a whole
 - `uiux.surfacePaths`: the repository-relative globs of the paths observed to render a user-visible surface, or `[]` when the repository renders none. Keep an existing value unless the user asks to change it. An absent key leaves the UI impact decision unevaluable.
 
-Keep all other config keys unchanged.
+Keep all other config keys unchanged. Add no key the package already defaults, `paths.specsDir` included; a value the project set stays.
 
 ## Step 5 - Evidence sampling
 

package/assets/init/.qfai/assistant/skill/qfai-configure/references/principles.md

@@ -0,0 +1,25 @@
+# Working principles
+
+The seven principles behind the steps of this skill. Read them when a choice is
+not settled by a step.
+
+1. **SDD First (Specification is the source of truth)**  
+   If there is a conflict between code and spec, treat the spec as authoritative and either (a) fix code or (b) raise an explicit Open Question to change the spec.
+
+2. **Traceability is mandatory**  
+   Every meaningful change must connect a business flow, story, acceptance criterion, example, test, code, and verification evidence. BF is covered by E2E tests, AC by integration or API tests, and EX by a selected non-E2E test. Full rule: `.qfai/assistant/rule/constitution.md` Article V.
+
+3. **Evidence over confidence**  
+   Prefer observable proof (logs, commands, file diffs, test results). If you cannot verify, say so and record it.
+
+4. **Minimize scope, but never hide gaps**  
+   Keep changes minimal, but do not "paper over" missing decisions. If something blocks correctness, stop and ask.
+
+5. **Quality gates are the decision mechanism**  
+   Use tests/lint/typecheck/build/pack verification (whatever the repo defines) as the primary guardrail. Fix until PASS.
+
+6. **Make it runnable**  
+   Outputs must be executable in terminal/CI. Provide copy-paste commands.
+
+7. **User time is expensive**  
+   Ask only the questions that are truly blocking. Everything else: make reasonable assumptions and label them clearly.

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

@@ -23,7 +23,7 @@ mode: interactive-by-default
 
 ## /qfai-discussion - Exploration Planner
 
-[DRIFT-PROTOCOL:MANDATORY]
+[DRIFT-PROTOCOL:REQUIRED]
 
 Run the entry check of
 `.qfai/assistant/rule/shared-skill-operating-baseline.md#workflow-run-entry-check-mandatory`

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/discussion-completion-matrix.md

@@ -2,6 +2,14 @@
 
 Use this file for the full completion logic behind `/qfai-discussion`.
 
+## Contents
+
+- All Packs
+- UI-bearing Packs
+- CLI Packs
+- Non-UI Packs
+- Notes
+
 ## All Packs
 
 Blocking for every pack, UI-bearing or not:
@@ -66,12 +74,9 @@ Completion is blocked until all are true:
    ordinary. This is the one visual decision made here, because no later stage asks the user for
    it: `/qfai-sdd`'s `common-design-md` step authors tokens from whatever is recorded. A direction taken without the
    user carries `chosen_by: assumption` and an open entry in `11_OQ-Register.md`.
-6. No forbidden legacy sidecar exists under `uiux/` (see
-   `templates/uiux/00_index.md#Forbidden Legacy Files`).
 
 Evaluation axes are global constants (4-step ordinal: weak / acceptable / strong /
-exceptional) and are NOT authored as discussion sidecars, so no scoring, override, strategy,
-taste-interview, option-comparison or selected-anchor sidecar is required or permitted.
+exceptional) and are NOT authored as discussion sidecars.
 
 ## CLI Packs
 
@@ -85,11 +90,9 @@ so conditions 1 and 5 above do not apply to it:
   `validators/designContractReadiness.ts` skips `QFAI-DCON-030`/`-033`/`-034` for it.
 - No design direction either: nothing downstream reads a theme for a surface that renders
   no tokens.
-- Conditions 2, 3, 4, 6 and 7 apply unchanged: all three canonical `uiux/` sidecars, the
-  full screen-contract schema, unranked exploration directions, no forbidden legacy
-  sidecar, and zero open OQs.
-- `route:` on a `cli` screen contract names the command invocation, not a web path (see
-  `ui-bearing-playbook.md#visual-prototyping-surfaces-vs-cli`).
+- Conditions 2, 3, 4 and 7 apply unchanged: all three canonical `uiux/` sidecars, the
+  full screen-contract schema, unranked exploration directions, and zero open OQs.
+- `route:` on a `cli` screen contract names the command invocation, not a web path, as the `cli` section of the UI-bearing playbook sets out.
 - No `prototyping.yaml`: `cli` is not a valid prototyping execution surface.
 - `primary_surface: cli` with a visual `secondary_surfaces` entry is NOT a cli-only pack —
   conditions 1 and 2 stay blocking for it.

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui-bearing-playbook.md

@@ -74,7 +74,5 @@ shadows:
 
 Trend Scan is **not** a sidecar file. Trend Scan lives at
 `04_Sources.md#Trend Scan` (part of the core nine-file discussion pack).
-The legacy `uiux/20_trend_scan.md` template and the whole `uiux/20-24`
-design-evaluation family were removed; evaluation axes are now global
-constants and are not authored as discussion sidecars. UI-bearing
-completion checks read Trend Scan from `04_Sources.md`.
+Evaluation axes are global constants and are not authored as discussion
+sidecars. UI-bearing completion checks read Trend Scan from `04_Sources.md`.

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui_ux/platform_baselines.md

@@ -2,6 +2,17 @@
 
 Use this file only when the current discussion needs platform-specific detail.
 
+## Contents
+
+- Cross-Platform Baseline
+- Web
+- Mobile
+- Desktop
+- CLI
+- States
+- Dark Mode
+- Motion
+
 ## Cross-Platform Baseline
 
 - Keep the same conceptual model across surfaces.

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui_ux/review_audit_playbook.md

@@ -2,6 +2,17 @@
 
 Use this file when the core checklist is not enough.
 
+## Contents
+
+- Heuristic Review Pass
+- Layout And Information Architecture
+- Forms And Actions
+- Screen States
+- Accessibility Audit
+- Anti-Pattern Red Flags
+- Documentation Expectations For QFAI
+- Recommended Audit Order
+
 ## Heuristic Review Pass
 
 Review the design direction against these durable heuristics:

package/assets/init/.qfai/assistant/skill/qfai-discussion/references/ui_ux_best_practices.md

@@ -5,6 +5,15 @@ This file is the compact, durable core for `qfai-discussion`.
 It is intentionally not an encyclopedia. Keep this file short, decision-oriented, and stable.
 Move volatile or bulky detail into the `ui_ux/` sidecar references and research current material at run time.
 
+## Contents
+
+- Why This File Is Compact
+- How To Use This Reference
+- Core Decision Rules
+- QFAI-Specific Authoring Guidance
+- Compact Review Checklist
+- Anti-Bloat Rules For Future Edits
+
 ## Why This File Is Compact
 
 - OpenAI recommends versioned prompts, variables, concise examples, and eval-backed iteration rather than piling all guidance into one prompt.
@@ -18,10 +27,7 @@ Move volatile or bulky detail into the `ui_ux/` sidecar references and research
 ## How To Use This Reference
 
 1. Read this file first for durable decision rules.
-2. Open only the appendix you need:
-   - `ui_ux/platform_baselines.md`
-   - `ui_ux/review_audit_playbook.md`
-   - `ui_ux/trend_scan_playbook.md`
+2. Open only the appendix the `discussion-uiux` step names for the current task.
 3. For trends, platform release details, or fast-moving conventions, do web research during the current discussion run and cite sources in `04_Sources.md`.
 
 ## Core Decision Rules
@@ -107,16 +113,10 @@ resolves through:
 
 Those three are the entire canonical sidecar family. Evaluation axes are global constants
 (4-step ordinal: weak / acceptable / strong / exceptional) fixed by the review validation the
-QFAI CLI applies — not by any file in this tree. The shipped
-`.qfai/assistant/skill/qfai-prototyping/references/reviewer-prompt.md` restates that axis set
-for the reviewer prompt; editing it does not change the set the CLI accepts. Axes are not
+QFAI CLI applies — not by any file in this tree. The reviewer prompt that
+`/qfai-prototyping` ships restates that axis set; editing it does not change the set the CLI accepts. Axes are not
 authored as discussion sidecars. Discussion is planner-first: it carries exploration directions
-unranked and does not select a single visual winner, so there is no strategy, taste-interview, scoring,
-override, option-comparison or selected-anchor sidecar. Do NOT create
-`10_implementation_strategy.md`, `11_design_taste_interview.md`, the `20-24`
-design-evaluation family, `30_option_comparison.md`, or `31_selected_anchor_screen.md` —
-those filenames are forbidden, see `templates/uiux/00_index.md#Forbidden Legacy Files`, and
-creating them fails validation.
+unranked and does not select a single visual winner.
 
 ### What must be explicit in the discussion pack
 
@@ -175,29 +175,6 @@ Use this as the first-pass gate before deeper review.
 - Are comparisons and rejections traceable?
 - Can prototyping and SDD proceed without guessing the intended UX?
 
-## When To Open The Appendices
-
-Open `ui_ux/platform_baselines.md` when you need:
-
-- touch target sizes
-- breakpoint heuristics
-- platform navigation baselines
-- dark mode and cross-platform adaptation notes
-
-Open `ui_ux/review_audit_playbook.md` when you need:
-
-- heuristic review structure
-- anti-pattern checklists
-- screen-spec documentation rules
-- audit/testing guidance
-
-Open `ui_ux/trend_scan_playbook.md` when you need:
-
-- trend-scan category coverage
-- freshness and citation rules
-- how to translate references into local decisions
-- how to keep trends from overwhelming product-specific needs
-
 ## Anti-Bloat Rules For Future Edits
 
 - Do not add long font-scale tables, full platform encyclopedias, or year-stamped trend lists to this file.
@@ -205,9 +182,3 @@ Open `ui_ux/trend_scan_playbook.md` when you need:
 - Do not repeat the same concept across multiple theoretical frameworks unless the duplication changes an actual QFAI decision.
 - Prefer one sharp rule plus a short verification cue over paragraph-heavy explanation.
 - If a section is mostly lookup material, move it to an appendix.
-
-## Appendix Index
-
-- [Platform Baselines](ui_ux/platform_baselines.md)
-- [Review Audit Playbook](ui_ux/review_audit_playbook.md)
-- [Trend Scan Playbook](ui_ux/trend_scan_playbook.md)