qualia-framework 6.6.0 → 6.7.1

package/docs/onboarding.html

@@ -546,7 +546,7 @@
       <div class="kit-group">
         <h4>Lock decisions before code</h4>
         <dl>
-          <dt>/qualia-discuss</dt><dd>Without args: project-level non-technical discovery (mandatory at kickoff). With <code>N</code>: phase-level technical alignment with locked decisions and ADRs.</dd>
+          <dt>/qualia-scope</dt><dd>Without args: project-level non-technical discovery (mandatory at kickoff). With <code>N</code>: phase-level archetype-aware grill with locked decisions and ADRs, gated on Definition-of-Done.</dd>
           <dt>/qualia-research</dt><dd>Deep-research a niche library or domain before planning a phase.</dd>
         </dl>
       </div>

package/guide.md

@@ -3,7 +3,7 @@
 > Follow the road. Type the commands. The framework handles the rest.
 > `--auto` chains the whole road end-to-end with only two human checkpoints per project.
 
-Surface: **23 active skills**. Use `/qualia-fix` for broken behavior, `/qualia-feature` for new single-feature work, `/qualia-discuss` in PROJECT MODE for kickoff capture, `/qualia-polish --loop` for the autonomous visual loop, and `/qualia-polish --vibe` for fast layout-preserving aesthetic pivots.
+Surface: **25 active skills**. Use `/qualia-fix` for broken behavior, `/qualia-feature` for new single-feature work, `/qualia-scope` in PROJECT MODE for kickoff capture, `/qualia-polish --loop` for the autonomous visual loop, and `/qualia-polish --vibe` for fast layout-preserving aesthetic pivots.
 
 For the identity statement see [`SOUL.md`](./SOUL.md). For every skill flag see [`FLAGS.md`](./FLAGS.md). When something breaks see [`TROUBLESHOOTING.md`](./TROUBLESHOOTING.md). For release history see [`CHANGELOG.md`](./CHANGELOG.md).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qualia-framework",
-  "version": "6.6.0",
+  "version": "6.7.1",
   "description": "Claude Code and Codex workflow framework by Qualia Solutions. Plan, build, verify, ship.",
   "bin": {
     "qualia-framework": "./bin/cli.js"

package/rules/codex-goal.md

@@ -39,7 +39,7 @@ If the answer is `claude`, **skip this entire rule** — Claude Code has no equi
 
 - The user is on Claude Code (no `/goal` surface).
 - A goal is already active for this thread (Codex rejects `update_goal` when one exists — call `thread/goal/get` first if you're using the tool API directly).
-- The work is open-ended exploration with no clear objective (e.g. `/qualia`, `/qualia-discuss`). Goals are for executing a defined scope.
+- The work is open-ended exploration with no clear objective (e.g. `/qualia`, `/qualia-scope`). Goals are for executing a defined scope.
 
 ## Why
 

package/rules/one-opinion.md

@@ -1,6 +1,6 @@
 # One Opinion (design-decision discipline)
 
-Loaded on demand by design-adjacent skills: `/qualia-polish --vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-discuss` PROJECT MODE. Not always-on — most skills don't need it.
+Loaded on demand by design-adjacent skills: `/qualia-polish --vibe`, `/qualia-polish`, `/qualia-new` (DESIGN.md creation step), `/qualia-scope` PROJECT MODE. Not always-on — most skills don't need it.
 
 ## The rule
 

package/skills/qualia/SKILL.md

@@ -22,6 +22,8 @@ node ${QUALIA_BIN}/state.js check 2>/dev/null
 
 The JSON carries a `profile` field (`strict` or `standard`; env `$QUALIA_PROFILE` wins). `strict` = hard gates, no waivers; `standard` = gates advisory, a senior may waive with a reason logged to `.planning/decisions/`. Surface it when a gate is involved.
 
+**A5 — multi-person layout.** If the JSON has `"layout": "increments"`, this project is concurrency-aware: route by the increment fields, not the single phase cursor. Continue your own claim first (`my_claim`), else start `next_increment` (the first unclaimed, not-done increment). **Never** route the operator to anything in `claimed_increments[]` — those are held by another person on another branch. The status→command mapping in the table below still applies (it's computed into `next_command`); the increment fields just tell you *which* unit is yours. Legacy projects (no `layout` field) route exactly as before.
+
 Also gather context:
 ```bash
 test -f .continue-here.md && echo "HANDOFF_EXISTS" && head -20 .continue-here.md || echo "NO_HANDOFF"

package/skills/qualia-discuss/SKILL.md

@@ -11,6 +11,8 @@ allowed-tools:
   - AskUserQuestion
 ---
 
+> **RETIRED (v6.7, A4 collapse).** Folded into `/qualia-scope`: PROJECT MODE = this kickoff interview, PHASE MODE = the pre-plan grill, picked by qualia-scope's mode router. This file is no longer installed as a slash command. Kept for history.
+
 # /qualia-discuss — Alignment Interview
 
 Two modes. The skill picks one based on whether an arg is passed.

package/skills/qualia-idk/SKILL.md

@@ -91,7 +91,7 @@ Read ALL of the following if present:
   - .planning/tracking.json
   - .planning/phase-*-plan.md (ALL, not just latest)
   - .planning/phase-*-verification.md (ALL — flag any FAILs)
-  - .planning/phase-*-context.md (from /qualia-discuss PHASE MODE, if any)
+  - .planning/phase-*-context.md (from /qualia-scope PHASE MODE, if any)
   - .planning/phase-*-research.md (if any)
   - .planning/DESIGN.md (skim)
   - .planning/decisions/*.md (ADRs — short read)
@@ -209,7 +209,7 @@ With all three reports + `<user_confusion>` + `<session_context>` in hand, produ
 | Verify FAILed and no postmortem ran | `/qualia-postmortem` → `/qualia-plan {N} --gaps` → `/qualia-build` |
 | Stale `.continue-here.md`, ongoing context | `/qualia-resume` → `/qualia` |
 | Brownfield drift (plan and code diverged hard) | `/qualia-map` → `/qualia-plan {N} --gaps` |
-| Phase context missing (no `/qualia-discuss` ran) | `/qualia-discuss {N}` → `/qualia-plan {N}` |
+| Phase context missing (no `/qualia-scope` ran) | `/qualia-scope {N}` → `/qualia-plan {N}` |
 | Specific error, scope clear | `/qualia-fix '<symptom>'` |
 | Performance feels off, no profile | `/qualia-fix --perf '<route>'` or `/qualia-optimize --perf` |
 | Design feels off | `/qualia-polish --critique` then `/qualia-polish` |

package/skills/qualia-milestone/SKILL.md

@@ -59,7 +59,7 @@ If `PROJECT_TYPE=demo` AND `MILESTONE_COUNT=1`, the demo's one milestone is clos
 **If "Client signed — extend to full project":**
 
 1. Update `.planning/PROJECT.md` frontmatter: `project_type: full`.
-2. Run a brief discovery top-up — invoke `/qualia-discuss` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
+2. Run a brief discovery top-up — invoke `/qualia-scope` in PROJECT MODE, but only ask §9-§14 (the full-project-only questions). This adds the milestone arc, compliance, integrations, content ownership, handoff team, and budget shape.
 3. Spawn the roadmapper in `extend-to-full` mode (see prompt below). It reads the existing single milestone (now M1), the updated discovery, and produces a full JOURNEY.md with M2..M{N-1} sketches plus the Handoff milestone.
 4. Then proceed with the standard close-milestone flow (Steps 2-9) — M1 closes, M2 opens, the user is asked to continue.
 

package/skills/qualia-new/SKILL.md

@@ -94,22 +94,22 @@ The shape is locked, now capture the content in one sentence:
 
 > **"What are you building? One sentence — a stranger should understand it."**
 
-Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-discuss` will refine it through its 8 or 14 structured questions.
+Accept whatever the user says, even if broad. **Do NOT start an ad-hoc clarification round here.** Depth comes from the structured discovery interview in Step 4, not from free-form questioning. If the answer is "a SaaS platform" — that's fine, write it down, move on. `/qualia-scope` will refine it through its 8 or 14 structured questions.
 
 This is the ONLY free-text question in the kickoff flow. Everything else is `AskUserQuestion`.
 
 ### Step 4. Mandatory Discovery Interview (PROJECT MODE)
 
-**Hard rule:** This is the next tool call after Step 3. No ad-hoc clarification, no free-form follow-up, no "let me ask a few quick things first." If the one-line pitch was "a SaaS platform", you invoke `/qualia-discuss` NOW — that skill's structured questions are how breadth gets refined into depth.
+**Hard rule:** This is the next tool call after Step 3. No ad-hoc clarification, no free-form follow-up, no "let me ask a few quick things first." If the one-line pitch was "a SaaS platform", you invoke `/qualia-scope` NOW — that skill's structured questions are how breadth gets refined into depth.
 
-Invoke `/qualia-discuss` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the discuss skill skips the type question.
+Invoke `/qualia-scope` inline in PROJECT MODE — non-technical kickoff interview. 8 questions for demo, 14 for full project. Pass `PROJECT_TYPE` so the scope skill skips the type question.
 
-This step REPLACES the old free-form "deep questioning" loop. The discuss skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
+This step REPLACES the old free-form "deep questioning" loop. The scope skill captures answers verbatim into `.planning/project-discovery.md`, which seeds PROJECT.md, PRODUCT.md, CONTEXT.md, and (for full projects) JOURNEY.md milestone names.
 
 ```bash
-# Inline-invoke qualia-discuss in PROJECT MODE
+# Inline-invoke qualia-scope in PROJECT MODE
 # (no phase number arg = PROJECT MODE; PROJECT_TYPE env tells it which question set)
-PROJECT_TYPE=$PROJECT_TYPE qualia-discuss
+PROJECT_TYPE=$PROJECT_TYPE qualia-scope
 ```
 
 After the interview returns, `.planning/project-discovery.md` exists with the user's answers. Read it. Confirm understanding:
@@ -118,7 +118,7 @@ After the interview returns, `.planning/project-discovery.md` exists with the us
 - question: "I have what I need to write PROJECT.md and move forward. Continue?"
 - options: ["Continue", "More questions"]
 
-If "More questions": re-invoke `/qualia-discuss` for additional rounds. Otherwise continue.
+If "More questions": re-invoke `/qualia-scope` for additional rounds. Otherwise continue.
 
 ### Step 5. Detect Project Type
 
@@ -164,9 +164,13 @@ cp ${QUALIA_TEMPLATES}/CONTEXT.md .planning/CONTEXT.md
 # Initialize ADR folder with the template available for reference
 mkdir -p .planning/decisions
 cp ${QUALIA_TEMPLATES}/decisions/ADR-template.md .planning/decisions/_template.md
+
+# A5: gitignore the per-step-mutated state (STATE.md, tracking.json, cursor) so
+# only durable increment/release files are committed — multi-person safe.
+cp ${QUALIA_TEMPLATES}/planning.gitignore .planning/.gitignore
 ```
 
-Then **seed the glossary from the questioning answers**. For each domain term that came up during the Step 4 `/qualia-discuss` interview — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
+Then **seed the glossary from the questioning answers**. For each domain term that came up during the Step 4 `/qualia-scope` interview — entities, actions, statuses, key nouns the user repeatedly said — add an entry to `.planning/CONTEXT.md` under `## Language` with:
 - the term
 - a one-sentence definition
 - an `Avoid:` line listing rejected synonyms (terms the team should NOT use for this concept)
@@ -180,7 +184,7 @@ git add .planning/CONTEXT.md .planning/decisions/
 git commit -m "docs: seed CONTEXT.md domain glossary + decisions/ folder"
 ```
 
-The glossary stays terse — one sentence per entry. It's loaded into every agent spawn; bloat costs tokens. `/qualia-discuss` will grow it inline as decisions crystallize during phase planning.
+The glossary stays terse — one sentence per entry. It's loaded into every agent spawn; bloat costs tokens. `/qualia-scope` will grow it inline as decisions crystallize during phase planning.
 
 ### Step 8b. Write PRODUCT.md (REQUIRED)
 
@@ -418,8 +422,8 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 
 1. **Project type is the first question, period.** Step 1 (Demo / Full / Quick) is the literal first interaction with the user — even before "what are you building". Every downstream step branches on the answer. Don't skip it, don't infer it, don't ask anything before it.
 2. **AskUserQuestion for every discrete-choice question.** Project type, brownfield gate, design vibe, client type, approval gate, auto-chain — all use the interactive UI. The ONLY free-text question in the kickoff flow is the Step 3 one-line pitch. No plain-text prompts for anything that has a closed set of answers.
-3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-discuss`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the discuss skill's job — not yours.
-4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-discuss` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
+3. **No ad-hoc clarification questioning.** After Step 3 (one-line pitch), the next tool call is `/qualia-scope`. No "let me ask a few quick things first", no "that's too broad, can you clarify". Depth is the scope skill's job — not yours.
+4. **Discovery interview is mandatory.** Step 4 always invokes `/qualia-scope` in PROJECT MODE. No free-form questioning loop, no "I'll just sketch PROJECT.md from the user's first message." The interview is 8 questions for demo, 14 for full project.
 5. **Research runs automatically.** No permission ask. Only `--quick` skips it. Demo path uses `<scope>quick</scope>` (3-call budget per researcher); full project uses standard 8-call budget.
 6. **Demo design philosophy is non-negotiable.** Real backend always (Supabase, real auth), DESIGN.md mandatory, slop-detect hard-block, 1 milestone, focus on real agent/platform functionality + design quality. No mock data, no lorem ipsum, no broken flows. Speed comes from skipping multi-milestone planning, never from skipping design quality, mocking the backend, or cutting corners on the core flow. A demo that uses mock data is not a Qualia demo.
 7. **Demos are 1 milestone, full projects are 2-5.** Demo journeys have no "Handoff" — the demo IS the artifact. Full projects always end in Handoff (fixed 4 phases). The journey-tree adapts to both shapes.
@@ -427,6 +431,6 @@ Do NOT use `--quick` for: client projects, anything with compliance stakes, anyt
 9. **Single approval gate.** One gate for the whole journey. Not per-milestone, not per-phase.
 10. **Milestone 1 is fully detailed (full projects).** M2..M{N-1} are sketched. Detail fills in when each milestone opens. Demos are always fully detailed because they're 1 milestone.
 11. **STATE.md through state.js.** Never edit STATE.md or tracking.json by hand.
-12. **Inline skill invocation.** When Step 2 offers `/qualia-map` or Step 4 invokes `/qualia-discuss`, invoke it inline — don't exit.
+12. **Inline skill invocation.** When Step 2 offers `/qualia-map` or Step 4 invokes `/qualia-scope`, invoke it inline — don't exit.
 13. **CONTEXT.md is mandatory.** Every project gets a domain glossary at `.planning/CONTEXT.md`. Seeded from the discovery interview answers. Loaded by every road agent. Kept terse.
 14. **ADRs are scarce.** `.planning/decisions/` exists from day one but only fills with hard-to-reverse, surprising-without-context, real-tradeoff decisions. Cargo-culting ADRs ruins the signal.

package/skills/qualia-plan/SKILL.md

@@ -46,7 +46,7 @@ No phase number → current phase from STATE.md.
 
 **Phase-specific context (if exists):**
 ```bash
-cat .planning/phase-{N}-context.md 2>/dev/null   # from /qualia-discuss
+cat .planning/phase-{N}-context.md 2>/dev/null   # from /qualia-scope
 cat .planning/phase-{N}-research.md 2>/dev/null  # from /qualia-research
 ```
 
@@ -62,7 +62,7 @@ cat .planning/phase-{N}-research.md 2>/dev/null  # from /qualia-research
 
 **If phase has compliance/regulatory/architectural stakes AND no phase-{N}-context.md:**
 
-Suggest: *"Run /qualia-discuss {N} first to lock decisions? Optional."*
+Suggest: *"Run /qualia-scope {N} first to lock decisions? Optional."*
 
 ### 3. Spawn Planner (Fresh Context)
 

package/skills/qualia-research/SKILL.md

@@ -40,7 +40,7 @@ Phase N from args, or current phase from STATE.md.
 ```bash
 cat .planning/PROJECT.md 2>/dev/null
 cat .planning/ROADMAP.md 2>/dev/null
-cat .planning/phase-{N}-context.md 2>/dev/null  # if /qualia-discuss was run first
+cat .planning/phase-{N}-context.md 2>/dev/null  # if /qualia-scope was run first
 ```
 
 Identify what phase needs to know.

package/skills/qualia-road/SKILL.md

@@ -77,7 +77,7 @@ Screenshots at 3 viewports (375/768/1440), scores 9 design dimensions using visi
 Before high-stakes phases, run alignment skills against `.planning/CONTEXT.md` (domain glossary) and `.planning/decisions/` (ADRs):
 
 ```
-/qualia-discuss            → relentless one-question interview, updates CONTEXT.md inline
+/qualia-scope            → relentless one-question interview, updates CONTEXT.md inline
 /qualia-optimize --deepen  → find shallow modules, propose Ousterhout-style refactors
 /qualia-test --tdd         → vertical-slice red→green→refactor for one feature
 /qualia-map                → adapt Qualia to an existing brownfield repo's conventions (5th onboarding agent)
@@ -92,7 +92,7 @@ Broken thing? → /qualia-fix     (root cause, minimal patch, verify, report)
 Single feature? → /qualia-feature (new capability: inline for trivia, fresh spawn for 1-5 files)
 Paused?      → /qualia        (restore from .continue-here.md or STATE.md)
 End of day?  → /qualia-report (mandatory before clock-out; writes ERP payload)
-Unsure plan? → /qualia-discuss (capture decisions before planning)
+Unsure plan? → /qualia-scope (capture decisions before planning)
 ```
 
 ## Outside-road command boundaries

package/skills/qualia-scope/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-scope
-description: "Archetype-aware, adversarial project/increment intake. Loads the matching references/archetypes/*.md + constitution, grills the operator against its Grill variables, gates on Definition-of-Done coverage, writes spec + CONTEXT.md terms + decision ADRs. Triggers: 'scope this', 'intake', 'grill me on the build', 'what does v1 need', replaces the fixed 14-question interview."
+description: "Unified intake. PROJECT MODE = non-technical kickoff interview (before /qualia-new) → project-discovery.md. PHASE/INCREMENT MODE = archetype-aware adversarial grill (before /qualia-plan N or a new increment) → phase-N-context.md / scope-{slug}.md, gated on Definition-of-Done. Loads references/archetypes/*.md + constitution, writes CONTEXT.md terms + decision ADRs. Absorbs /qualia-discuss. Triggers: 'scope this', 'intake', 'kickoff interview', 'grill me on the build', 'what does v1 need'."
 allowed-tools:
   - Bash
   - Read
@@ -11,11 +11,87 @@ allowed-tools:
   - AskUserQuestion
 ---
 
-# /qualia-scope — Archetype-Aware Intake
+# /qualia-scope — Unified Intake
 
-Replaces the fixed-question interview with an **archetype-driven, adversarial, DoD-gated** grill. It does not transcribe answers — it pushes back on them. It does not exit until v1 is scoped and every clarification is resolved.
+The one intake skill. It absorbs `/qualia-discuss`: two intents, picked by mode.
 
-This skill scopes both a **new project** and a **new increment** (milestone/phase) of an existing one. Same contract either way: pick the archetype, grill its variables, close every DoD area, emit testable criteria.
+- **PROJECT MODE** — the non-technical kickoff that runs at the very start of `/qualia-new`. Captures the human shape of the project (audience, voice, constraints) in the client's own words → `.planning/project-discovery.md`. **Never technical here.**
+- **PHASE / INCREMENT MODE** — the archetype-driven, adversarial, DoD-gated grill before `/qualia-plan N` or a new increment. It does not transcribe — it pushes back. It does not exit until v1 is scoped and every clarification is resolved → `.planning/phase-{N}-context.md` (phase) or `.planning/scope-{slug}.md` (increment).
+
+## Mode routing
+
+```bash
+# Arg = a phase number → PHASE MODE. No arg / non-numeric → PROJECT MODE for a fresh
+# project (no .planning/STATE.md), else INCREMENT MODE for a new scope on an existing one.
+if [[ "$1" =~ ^[0-9]+$ ]]; then
+  MODE="phase"; PHASE_N="$1"
+elif [ ! -f .planning/STATE.md ] && [ ! -f .planning/PROJECT.md ]; then
+  MODE="project"
+else
+  MODE="increment"
+fi
+```
+
+- `MODE=project` → **PROJECT MODE** section below, then return to `/qualia-new`.
+- `MODE=phase` or `MODE=increment` → **PHASE / INCREMENT MODE** section (the archetype grill).
+
+---
+
+# PROJECT MODE — Kickoff Interview
+
+The non-technical conversation at the start of `/qualia-new`, BEFORE roadmapping or research. Captures what the client wants, who it's for, brand voice, and constraints — verbatim.
+
+**Hard rule: never go technical here.** No "Supabase or Postgres?", no architecture forks. Stack/DoD decisions happen in PHASE MODE, per phase. This mode is for the human shape.
+
+### P1. Project type (or accept it from `/qualia-new`)
+
+If `/qualia-new` already asked the Demo vs Full gate (its literal first question), it passes `PROJECT_TYPE=demo` | `PROJECT_TYPE=full` via env/arg — **skip the gate, do not re-ask.** Only ask it when invoked standalone, via **AskUserQuestion** (header "Project shape"): "Demo (single shippable milestone, sales conversation)" vs "Full project (multi-milestone arc to Handoff)". Demo runs §1–§8 of the discovery template; Full runs all 14.
+
+### P2. Open
+
+```bash
+node ${QUALIA_BIN}/qualia-ui.js banner scope 2>/dev/null || true
+```
+
+Say **"Eight quick questions for the demo path"** or **"Fourteen questions to shape the full project — we'll move fast."**
+
+### P3. One question at a time, from `templates/project-discovery.md`
+
+For each §1..§8 (demo) or §1..§14 (full), ask in plain language:
+
+```
+**Question {N}/{total}:** {question text from the template}
+
+({one-line clarifier showing the kind of answer that helps})
+```
+
+**NO "Recommend:" line in PROJECT MODE** — this is open discovery, not the grill. Wait for the answer; capture verbatim, don't paraphrase back. Thin answer → one follow-up max, then move on. `[Enter]` defaults exist on §2, §3, §5 only. Anti-references (§ "three sites this should NOT look like") are required — push back once, then capture whatever they give.
+
+### P4. Write `.planning/project-discovery.md`
+
+Fill `${QUALIA_TEMPLATES}/project-discovery.md` with verbatim answers; set frontmatter `project_type` and `discovered_at`.
+
+### P5. Hand back
+
+```bash
+git add .planning/project-discovery.md
+git commit -m "docs: project discovery interview ($PROJECT_TYPE)"
+```
+
+Invoked inline by `/qualia-new` → return control silently (it continues from its next step). Invoked standalone → `node ${QUALIA_BIN}/qualia-ui.js end "DISCOVERY CAPTURED" "/qualia-new"`.
+
+### Rules — PROJECT MODE
+
+1. **Never technical.** Stack/architecture forks are PHASE MODE.
+2. **Verbatim capture.** The client's exact phrasing feeds PRODUCT.md voice + the CONTEXT.md glossary — don't translate into framework-speak.
+3. **One question, one answer, move on.** No batching, no drilling past one follow-up.
+4. **Demo stops at §8.** Don't ask demo clients milestone-arc questions.
+
+---
+
+# PHASE / INCREMENT MODE — Archetype Grill
+
+The adversarial, DoD-gated intake. Scopes a **new increment** (phase/milestone) of an existing project, or a fresh project's first real scope after kickoff. Pick the archetype, grill its variables, close every DoD area, emit testable criteria.
 
 ## Inputs it honors
 
@@ -103,6 +179,12 @@ If the gate fails, name the exact open items and resume grilling at Step 4. Do n
 ### 8. Close
 
 ```bash
+# A5: if this project uses the per-increment layout, claim the increment you
+# just scoped so concurrent operators are routed around it (committed on this
+# branch). No-op on legacy projects that haven't run `state.js migrate`.
+if [ -d .planning/increments ]; then
+  node ${QUALIA_BIN}/state.js claim --id {id} --branch "$(git branch --show-current)"
+fi
 git add .planning/ && git commit -m "scope: {archetype} intake — v1 scoped, DoD closed"
 node ${QUALIA_BIN}/qualia-ui.js end "SCOPED" "/qualia-plan"   # or /qualia-new for a fresh project
 ```

package/skills/qualia-ship/SKILL.md

@@ -177,7 +177,14 @@ node ${QUALIA_BIN}/qualia-ui.js ok "Latency: ${LATENCY}s"
 ```
 
 ```bash
-node ${QUALIA_BIN}/state.js transition --to shipped --deployed-url "$URL"
+# A5: on the per-increment layout, `release` ships the active increment, runs
+# the Definition-of-Done gate, and clears its claim (one committed file → no
+# merge conflict). Falls back to the legacy phase-level transition otherwise.
+if [ -d .planning/increments ]; then
+  node ${QUALIA_BIN}/state.js release --deployed-url "$URL"
+else
+  node ${QUALIA_BIN}/state.js transition --to shipped --deployed-url "$URL"
+fi
 ```
 Do NOT manually edit STATE.md or tracking.json — state.js handles both.
 

package/templates/CONTEXT.md

@@ -1,6 +1,6 @@
 # {{PROJECT_NAME}} — Domain Glossary
 
-<!-- Domain glossary. Loaded by every road agent. Update via /qualia-discuss. Keep entries terse (1 sentence + Avoid line). -->
+<!-- Domain glossary. Loaded by every road agent. Update via /qualia-scope. Keep entries terse (1 sentence + Avoid line). -->
 
 ## Language
 

package/templates/help.html

@@ -350,7 +350,7 @@
       <h3>Phase Depth &mdash; Optional</h3>
       <p class="cmd-group-note">Used before / around /qualia-plan when a phase needs deeper context.</p>
       <div class="commands">
-        <div class="cmd"><span class="cmd-name">/qualia-discuss</span><span class="cmd-desc">Capture phase decisions, trade-offs, and constraints BEFORE planning. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that planner honors as locked input.</span></div>
+        <div class="cmd"><span class="cmd-name">/qualia-scope</span><span class="cmd-desc">Unified intake. No args: non-technical kickoff discovery before /qualia-new. With N: archetype-aware adversarial grill before /qualia-plan, gated on Definition-of-Done. Use for complex phases with regulatory, compliance, or architectural stakes. Creates .planning/phase-{N}-context.md that the planner honors as locked input.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-research</span><span class="cmd-desc">Deep-research a niche domain or library BEFORE planning a specific phase. Spawns the researcher agent with Context7/WebFetch access. Writes to .planning/phase-{N}-research.md.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-map</span><span class="cmd-desc">Map an existing codebase to infer architecture, stack, conventions, and what's already built. For brownfield projects &mdash; run BEFORE /qualia-new so Validated requirements get inferred from existing code.</span></div>
         <div class="cmd"><span class="cmd-name">/qualia-milestone</span><span class="cmd-desc">Close out a completed milestone and prep the next one. Archives the current milestone's artifacts, updates REQUIREMENTS.md to mark v1 requirements Complete, and creates the next milestone roadmap.</span></div>

package/templates/phase-context.md

@@ -5,7 +5,7 @@ captured: {date}
 
 # Phase {N} Context: {Phase Name}
 
-Captured during `/qualia-discuss {N}` — decisions, trade-offs, and constraints that must inform planning.
+Captured during `/qualia-scope {N}` — decisions, trade-offs, and constraints that must inform planning.
 
 ## Goal Restatement
 

package/templates/planning.gitignore

@@ -0,0 +1,10 @@
+# A5: per-step-mutated planning state is LOCAL (generated views), never committed.
+# Only increments/ and releases/ are the durable, committed source of truth —
+# so two people on two branches never conflict on the planning files.
+STATE.md
+tracking.json
+.cursor.json
+.state.lock
+.state.journal
+.backup/
+migration-manifest.json

package/templates/project-discovery.md

@@ -6,7 +6,7 @@ discovery_mode: project
 
 # Project Discovery, {Project Name}
 
-The non-technical kickoff interview output. `/qualia-discuss` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, and constraints in the user's own words.
+The non-technical kickoff interview output. `/qualia-scope` writes this in PROJECT MODE before `/qualia-new` generates JOURNEY.md. Captures intent, audience, brand, and constraints in the user's own words.
 
 Demo path: 8 questions. Full-project path: 14 questions.
 

package/templates/projects/ai-agent.md

@@ -51,5 +51,5 @@ Typical phase structure for a chatbot, AI assistant, tool-calling agent, or RAG
 ## Research Flags
 
 - **Domain-specific prompting** (legal, medical, financial advice) → run `/qualia-research` for the prompt engineering phase
-- **RAG over specific datasets** (vector DB, chunking strategy) → `/qualia-discuss` before planning
-- **Multi-step agent orchestration** → `/qualia-discuss` to lock tool boundaries before planning
+- **RAG over specific datasets** (vector DB, chunking strategy) → `/qualia-scope` before planning
+- **Multi-step agent orchestration** → `/qualia-scope` to lock tool boundaries before planning

package/templates/projects/mobile-app.md

@@ -51,6 +51,6 @@ Typical phase structure for a React Native / Expo app, iOS + Android.
 
 ## Research Flags
 
-- **App Store compliance** (in-app purchases, privacy, age ratings) → `/qualia-discuss` to lock scope
+- **App Store compliance** (in-app purchases, privacy, age ratings) → `/qualia-scope` to lock scope
 - **Native module choices** (notifications, maps, camera) → `/qualia-research` per phase
-- **Deep linking and universal links** → `/qualia-discuss` before navigation phase
+- **Deep linking and universal links** → `/qualia-scope` before navigation phase

package/templates/projects/voice-agent.md

@@ -51,5 +51,5 @@ Typical phase structure for a phone agent, VAPI bot, Retell agent, or call handl
 ## Research Flags
 
 - **Provider choice** (Retell vs VAPI vs ElevenLabs direct) → `/qualia-research 1` to compare for this specific use case
-- **Telephony setup** (DIDs, porting, SIP) → `/qualia-discuss` to lock decisions before wiring
+- **Telephony setup** (DIDs, porting, SIP) → `/qualia-scope` to lock decisions before wiring
 - **Prompt engineering for voice** → `/qualia-research` for the agent config phase

package/templates/projects/website.md

@@ -55,4 +55,4 @@ Typical phase structure for a client website, SaaS landing page, dashboard, or m
 ## Research Flags
 
 - **Niche domain integrations** (e.g., legal compliance, medical records, financial regulations) → run `/qualia-research N` before planning that phase
-- **Complex auth** (SSO, multi-tenant, RBAC) → run `/qualia-discuss N` first
+- **Complex auth** (SSO, multi-tenant, RBAC) → run `/qualia-scope N` first

package/tests/bin.test.sh

@@ -1076,18 +1076,18 @@ for SKILL in qualia-zoom qualia-issues qualia-triage; do
   fi
 done
 
-# 85. qualia-discuss SKILL.md mentions "grilling" (validates v5 fold of qualia-grill into discuss)
-if grep -qi "grilling" "$TMP/.claude/skills/qualia-discuss/SKILL.md"; then
-  pass "qualia-discuss documents grilling pattern (folded from qualia-grill)"
+# 85. A4 fold: qualia-discuss is RETIRED, its grill absorbed by qualia-scope (PHASE MODE).
+if [ ! -f "$TMP/.claude/skills/qualia-discuss/SKILL.md" ] && grep -qi "grill" "$TMP/.claude/skills/qualia-scope/SKILL.md"; then
+  pass "qualia-discuss retired; qualia-scope carries the grill (PHASE/INCREMENT MODE)"
 else
-  fail_case "qualia-discuss missing grilling reference"
+  fail_case "qualia-discuss should be retired and its grill absorbed by qualia-scope"
 fi
 
-# 86. qualia-discuss SKILL.md references CONTEXT.md (validates v5 substrate wiring)
-if grep -q "CONTEXT.md" "$TMP/.claude/skills/qualia-discuss/SKILL.md"; then
-  pass "qualia-discuss references CONTEXT.md"
+# 86. qualia-scope carries the CONTEXT.md substrate + PROJECT MODE kickoff discuss used to own.
+if grep -q "CONTEXT.md" "$TMP/.claude/skills/qualia-scope/SKILL.md" && grep -q "PROJECT MODE" "$TMP/.claude/skills/qualia-scope/SKILL.md"; then
+  pass "qualia-scope references CONTEXT.md + has PROJECT MODE (absorbed from qualia-discuss)"
 else
-  fail_case "qualia-discuss missing CONTEXT.md reference"
+  fail_case "qualia-scope missing CONTEXT.md reference or PROJECT MODE"
 fi
 
 # 87. qualia-road has disable-model-invocation: true (pure reference skill, user-only)