qualia-framework 5.4.0 → 5.8.0

package/README.md

@@ -1,14 +1,18 @@
-# Qualia Framework v5.3
+# Qualia Framework v5.8
 
 A harness engineering framework for [Claude Code](https://claude.ai/code). It installs into `~/.claude/` and wraps your AI-assisted development workflow with structured planning, execution, verification, and deployment gates.
 
-It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects — end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
+It is not an application framework like Rails or Next.js. It doesn't generate code, run servers, or process data. It's an opinionated workflow layer that tells Claude how to plan, build, and verify your projects end-to-end, from "tell me what you want to make" to "here's the handoff doc for your client."
 
-**The v5 line in three releases:**
-- **v5.0** — alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks (Vercel account, empty env-var, Supabase destructive guards).
-- **v5.1** — `/qualia-polish-loop` (autonomous visual-polish loop: screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch); multi-target installer (Claude Code + Codex AGENTS.md + Both); live-progress install UI.
-- **v5.2** — polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
-- **v5.3** — Matt Pocock gaps closed. `/qualia-prd` (synthesize conversation → durable PRD), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+**The v5 line:**
+- **v5.0**, alignment discipline. CONTEXT.md domain glossary, decisions/ ADRs, `/qualia-zoom`, `/qualia-issues`, `/qualia-triage`, slim CLAUDE.md per Matt Pocock's instruction-budget rule, insights-driven hooks.
+- **v5.1**, autonomous visual-polish loop. Screenshots a URL at three viewports, scores 8 design dimensions with vision, fixes top issues, loops until pass or kill-switch. Multi-target installer (Claude Code + Codex AGENTS.md + Both).
+- **v5.2**, polish-loop reliability. `--reduced-motion` capture flag, `--routes URL1,URL2` multi-route mode, first supervised end-to-end run.
+- **v5.3**, Matt Pocock gaps closed. `/qualia-hook-gen` (CLAUDE.md instruction to deterministic Claude Code hook), `/qualia-optimize --deepen` Step 5b parallel-interface design (3 fan-out agents producing radically different interfaces).
+- **v5.4-5.5**, token-discipline and plan-discipline. Cache-aware spawn ordering, scope-reduction prohibition, decision-coverage audit, requirement-coverage check.
+- **v5.6**, Demo vs Full Project gate at kickoff. Mandatory discovery interview via `/qualia-discuss` in PROJECT MODE (8 questions for demos, 14 for full projects). Demo-extension branch in `/qualia-milestone` for client-signs-after-demo conversion.
+- **v5.7**, `/qualia-feature` consolidates `/qualia-quick` + `/qualia-task` into one auto-scoped command.
+- **v5.8**, surface cleanup. `/qualia-polish --loop` replaces `/qualia-polish-loop`. `/qualia-quick`, `/qualia-task`, and `/qualia-prd` removed (deprecated in v5.7).
 
 The Full Journey architecture carries forward: `/qualia-new` maps the entire project arc from kickoff to client handoff upfront, and the Road chains end-to-end in `--auto` mode with only two human gates per project.
 
@@ -40,6 +44,8 @@ npx qualia-framework@latest traces     # View recent hook telemetry
 
 Open Claude Code in any project directory.
 
+> **New to Qualia?** Open [`docs/onboarding.html`](docs/onboarding.html) in a browser for a one-page roadmap of the golden path. Best file to send a new hire.
+
 ### The Road — guided mode (default)
 
 ```
@@ -53,7 +59,7 @@ Open Claude Code in any project directory.
 /qualia-polish      # Design pass — flexible scope: component, route, app, redesign, critique, quick
 /qualia-ship        # Deploy to production
 /qualia-handoff     # Enforce the 4 mandatory handoff deliverables
-/qualia-report      # Mandatory end-of-session report + ERP upload
+/qualia-report      # Mandatory shift report + ERP upload before clock-out
 ```
 
 ### The Road — auto mode
@@ -89,15 +95,13 @@ Two human gates per project. One halt case (gap-cycle limit exceeded on a failin
 /qualia-debug         # Structured debugging
 /qualia-review        # Production audit (scored diagnostics)
 /qualia-optimize      # Deep optimization pass (parallel specialist agents, --deepen mode with parallel-interface design)
-/qualia-quick         # Fast path for trivial fixes (skips planning)
-/qualia-task          # Build one thing properly (fresh builder, atomic commit, no phase plan)
+/qualia-feature       # Auto-scoped single-feature build (inline for trivia, fresh spawn for 1-5 files)
 /qualia-test          # Generate or run tests (--tdd mode for test-first workflow)
 /qualia-zoom          # Focus on a single file or function with full context
 /qualia-issues        # Break a phase plan into vertical-slice GitHub issues
 /qualia-triage        # Triage open issues through the ready-for-agent state machine
 /qualia-road          # View and navigate the project road (journey/milestone/phase status)
-/qualia-polish-loop   # Autonomous visual-polish loop: screenshot → vision-eval → fix → repeat (v5.1+)
-/qualia-prd           # Synthesize current conversation into a durable feature spec (v5.3+)
+/qualia-polish --loop # Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat
 /qualia-hook-gen      # Convert a CLAUDE.md/rules instruction into a deterministic hook (v5.3+)
 ```
 
@@ -127,8 +131,8 @@ Every project has a `.planning/JOURNEY.md` — the North Star document that maps
 Project
 └─ Journey (all milestones defined upfront)
    └─ Milestone (a release — 2-5 total, Handoff is always last)
-      └─ Phase (a feature-sized deliverable, 2-5 tasks)
-         └─ Task (atomic unit, one commit, one verification contract)
+      └─ Phase (a feature-sized deliverable, 2-5 internal tasks)
+         └─ Task (framework-internal unit, one commit, one verification contract)
 ```
 
 **Hard rules:**
@@ -137,11 +141,11 @@ Project
 - Every non-Handoff milestone needs **≥ 2 phases** (enforced by `state.js close-milestone`).
 - Milestone numbering is contiguous.
 
-**Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted.
+**Why it matters:** non-technical team members can follow the ladder from any entry point. `/qualia` and `/qualia-milestone` render JOURNEY.md as a visual ladder with current position highlighted. In the ERP, the primary operational dates are project deadline, milestone deadline, and employee shift submission date; framework tasks stay internal to agent execution.
 
-## What's Inside (v5.3.0)
+## What's Inside (v5.8.0)
 
-- **35 skills** — full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, quick, task, test, zoom, issues, triage), v5 flagships (`qualia-polish-loop`, `qualia-prd`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
+- **32 skills**, full Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (discuss, research, map), navigation (qualia router, idk, pause, resume, road, help), quality (debug, review, optimize with `--deepen` parallel-interface design, feature, test, zoom, issues, triage), v5 flagships (`qualia-polish --loop`, `qualia-hook-gen`), and meta (learn, skill-new, flush, postmortem)
 - **9 agents** (each runs in fresh context): planner, builder, verifier, qa-browser, researcher, research-synthesizer, roadmapper, plan-checker, visual-evaluator
 - **12 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking sync, migration-guard, pre-deploy-gate, pre-compact state save, stop-session-log, vercel-account-guard, env-empty-guard, supabase-destructive-guard
 - **6 always-loaded rules** (`rules/`): grounding, security, infrastructure, deployment, speed (CLI-first / MCP tier-list), architecture (deep modules / scout-for-shallow-code)

package/agents/builder.md

@@ -93,18 +93,26 @@ which is fine and means there is nothing to apply yet.
 - If the plan says "use library X" — use library X
 - If something in the plan seems wrong, flag it but still follow the plan
 
-### 4. Self-Verify Your Work
+### 4. Self-Verify Your Work (Auto-Heal Loop)
 
-Before committing:
+Before committing, run the checks below. If any fail, **fix and retry up to 2 times** before giving up. This is a tight self-heal loop — moving correctness checks here saves a verifier round.
 
-1. Run every command in **Validation:** — they must pass
+1. Run every command in **Validation:** — they must pass.
 2. Mentally walk through each **Acceptance Criterion** — does the code actually produce that observable behavior?
-3. Run `npx tsc --noEmit` if you touched TypeScript files
-4. **If you touched any `.tsx/.jsx/.css/.scss/.html` file: run `node bin/slop-detect.mjs {touched paths}`. Exit 1 (critical findings) BLOCKS the commit.** Fix the findings (apply the rewrite recipe in the script's output), re-run, repeat until exit 0.
-5. No `// TODO`, no placeholder text, no stub functions
-6. Imports are wired — not just declared but actually used
+3. Run `npx tsc --noEmit` if you touched TypeScript files. On failure, capture the first 50 lines of error output, fix the offending file(s), re-run. Cap at 2 retries.
+4. **If you touched any `.tsx/.jsx/.css/.scss/.html` file: run `node bin/slop-detect.mjs {touched paths}`. Exit 1 (critical findings) BLOCKS the commit.** Fix the findings (apply the rewrite recipe in the script's output), re-run, repeat until exit 0 (also capped at 2 retries before BLOCKED).
+5. No `// TODO`, no placeholder text, no stub functions.
+6. Imports are wired — not just declared but actually used.
 
-If any Validation command fails, slop-detect returns 1, or any AC is not met, fix before committing. Do not commit and hope the verifier catches it.
+**Auto-heal protocol:**
+
+```
+attempt 1:  run validation → fix what failed → run again
+attempt 2:  run validation → fix what failed → run again
+attempt 3:  if still failing, return BLOCKED — do not commit broken code
+```
+
+If any Validation command fails after 2 retries, slop-detect returns 1 after 2 retries, or any AC is not met after a fix attempt, return `BLOCKED — {validation failure}: {first 20 lines of last error output}`. Do not commit and hope the verifier catches it.
 
 ### 5. Commit
 One atomic commit per task:
@@ -115,6 +123,15 @@ git commit -m "{concise description of what was built}"
 
 Stage specific files — never `git add .` or `git add -A`.
 
+## Scope Reduction Prohibition
+
+The plan was written with the full spec in mind. Don't simplify it. If a task says "validate with Zod schema X covering 6 fields" don't ship 3 fields. If it says "redirect on success" don't ship a console.log placeholder.
+
+**Banned phrases in code, comments, and commit messages:**
+`v1`, `// for now`, `// TODO: wire this up later`, `// hardcoded for now`, `// stub`, `// placeholder`, `// minimal version`, `// will improve later`, `mock for now` (in production code paths).
+
+If you cannot deliver the full spec because a dependency is genuinely missing, return `BLOCKED — dependency missing: {what}` per the deviation table. Do NOT ship a watered-down version with a TODO note.
+
 ## Scope Discipline
 
 Before writing or editing any file, check: Is this file listed in the task's **Files** section?

package/agents/plan-checker.md

@@ -132,6 +132,54 @@ Every frontend task MUST include a `**Design:**` field with:
 
 Non-frontend tasks (backend, migrations, API routes without UI) MUST NOT have a `**Design:**` field. Warn but don't fail if one is mistakenly added.
 
+### Rule 11: Requirement Coverage (when ROADMAP.md lists REQ-IDs)
+
+If `.planning/ROADMAP.md` exists and the current phase's section lists `Requirements covered:` with `REQ-ID`s (format `[A-Z]+-\d+`, e.g. `AUTH-01`, `BILLING-03`), every REQ-ID must be covered by at least one task. Coverage = the task's `**Why:**`, `**Acceptance Criteria:**`, or `**Action:**` field references the REQ-ID, OR the task's content directly implements that requirement (read the requirement description from `.planning/REQUIREMENTS.md` and confirm).
+
+**FAIL if:**
+- A REQ-ID listed for the current phase appears nowhere in the plan.
+- A task claims a REQ-ID but its Action/AC obviously doesn't implement it.
+
+**How to detect:**
+```bash
+# Extract REQ-IDs for this phase from ROADMAP.md
+awk '/^### Phase {N}:/,/^---|^### Phase/' .planning/ROADMAP.md | grep -oE '[A-Z]+-[0-9]+' | sort -u
+# Check each appears in the plan
+grep -oE '[A-Z]+-[0-9]+' .planning/phase-{N}-plan.md | sort -u
+```
+
+The set difference (REQ-IDs in roadmap minus REQ-IDs in plan) must be empty.
+
+If a REQ-ID is missing from the plan, REVISE: "REQ AUTH-03 is in scope for this phase per ROADMAP.md but no task implements it." Plan-wide, not task-specific.
+
+### Rule 9: Decision Coverage (when phase-context.md exists)
+
+If `.planning/phase-{N}-context.md` exists with a `## Locked Decisions` section, every `D-NN` row must be covered by at least one task. Coverage = the task references the ID in its `**Why:**` or `**Action:**` field, OR the task's Action implements the decision content directly (read the task and confirm).
+
+**FAIL if:**
+- A `D-NN` row exists in phase-context.md but no task in the plan references it or implements it.
+- A row from `## Deferred Ideas` is being implemented by a task (deferred = explicitly out-of-scope).
+
+**How to detect:**
+```bash
+grep -E '^\| D-[0-9]+' .planning/phase-{N}-context.md     # extract decision IDs
+grep -E 'D-[0-9]+' .planning/phase-{N}-plan.md            # check IDs appear in plan
+```
+
+If a decision ID appears in phase-context.md but not the plan, REVISE: "D-03 is locked but no task implements it." Plus the deferred check: if a task's Action matches a Deferred-Ideas row, REVISE.
+
+### Rule 10: Scope Reduction Detection
+
+LLMs systematically simplify specs. Scan the plan for banned phrases that signal scope reduction:
+
+```bash
+grep -niE '\b(v1|v2|simplified version|static for now|hardcoded for now|placeholder|basic version|minimal implementation|will be wired later|dynamic in future phase|skip for now|stub|mock for now|we can improve this later|quick win for now)\b' .planning/phase-{N}-plan.md
+```
+
+**FAIL if:** any match. Quote the offending line in the issue. The planner must rewrite the task to deliver the actual thing, OR explicitly justify the split using one of the three legitimate reasons (context cost > 50%, missing info, dependency conflict).
+
+Exception: `v1` / `v2` is fine when referring to the project's actual versioning (e.g., `migrate to API v2`). Distinguish by context.
+
 ### Rule 8: Validation commands test behavior, not just existence
 
 Each task's `**Validation:**` list must contain at least one `grep-match` or `command-exit` check — a command that proves the code DOES something. A task whose ONLY validation is `test -f {file}` will pass even if the file contains only `// TODO`.
@@ -152,7 +200,7 @@ Each task's `**Validation:**` list must contain at least one `grep-match` or `co
 
 ## Tool Budget
 
-Read the plan file once. Grep the codebase only to validate Rule 7 (locked decisions). Do NOT speculatively check whether files listed in the plan already exist — that's the builder's job. Max 10 tool calls per invocation.
+Read the plan file once. Read `.planning/phase-{N}-context.md` once if it exists (Rules 7 + 9). Read `.planning/ROADMAP.md` once if it exists (Rules 4 + 11). Grep the plan for scope-reduction phrases (Rule 10), decision IDs (Rule 9), and REQ-IDs (Rule 11). Do NOT speculatively check whether files listed in the plan already exist — that's the builder's job. Max 14 tool calls per invocation.
 
 ## Output Format
 
@@ -215,6 +263,6 @@ Before returning, self-check:
 - [ ] Every issue has a specific task reference
 - [ ] Every issue has a concrete fix instruction
 - [ ] No issue is "make it better" or "be more specific" without saying how
-- [ ] If plan passes, you actually verified all 7 rules (not just 1-2)
+- [ ] If plan passes, you actually verified all 11 rules (not just 1-2)
 
 Don't pass a plan you didn't fully check. Don't fail a plan for style preferences.

package/agents/planner.md

@@ -212,12 +212,36 @@ When a phase involves frontend work (pages, components, layouts, UI):
    - Include responsive: "works on 375px mobile and 1440px desktop"
 4. **Reference `@.planning/DESIGN.md`** in the Context field of every frontend task so builders read it before coding
 
+## Scope Reduction Prohibition
+
+LLMs systematically simplify specs. You will not. If a locked decision or success criterion says X, the plan delivers X — not a watered-down version that "we can extend later."
+
+**Banned phrases in task Action / Acceptance Criteria / Why fields:**
+`v1`, `v2`, `simplified version`, `static for now`, `hardcoded for now`, `placeholder`, `basic version`, `minimal implementation`, `will be wired later`, `dynamic in future phase`, `skip for now`, `stub`, `mock for now`, `we can improve this later`, `quick win for now`.
+
+**The only legitimate reasons to split scope across phases:**
+1. Implementing it would force a single task above ~50% builder context.
+2. Required information genuinely does not exist (data shape unknown, external API not yet specified).
+3. A dependency is owned by a future phase and the wave-graph cannot resolve it.
+
+If none of these apply, deliver the full spec. A self-check before returning the plan: grep your draft for the banned phrases. If you find one, rewrite the task to deliver the actual thing.
+
+## Decision Coverage Audit
+
+If `.planning/phase-{N}-context.md` exists with a `## Locked Decisions` section, every decision row carries an ID (e.g., `D-01`, `D-02`). Before returning the plan, confirm:
+
+- Every `D-XX` is covered by at least one task whose Action implements it. Reference the ID in that task's Why or Action (e.g., `Why: D-03 requires session tokens stored database-side, not in JWT`).
+- No `Deferred Ideas` row appears in any task. Deferred = out-of-scope for this phase.
+- `Discretion` items are the planner's call — no audit needed.
+
+If a locked decision has no covering task, add one. If you genuinely cannot, the phase scope is wrong and the plan-checker will block — STOP and surface the gap to the user.
+
 ## Rules
 
 1. **Plans complete within ~50% context.** More plans with smaller scope = consistent quality. 2-3 tasks per plan is ideal.
 2. **Tasks are atomic.** Each task = one commit. If a task touches 10+ files, split it.
 3. **"Done when" must be testable.** Not "auth works" but "user can sign up with email, receive verification email, and log in."
-4. **Honor locked decisions.** If PROJECT.md says "use library X" — the plan uses library X.
+4. **Honor locked decisions.** If PROJECT.md or phase-context.md says "use library X" — the plan uses library X.
 5. **No enterprise patterns.** No RACI, no stakeholder management, no sprint ceremonies. One person + Claude.
 6. **Context references are explicit.** Use `@filepath` so the builder knows exactly what to read.
 

package/agents/research-synthesizer.md

@@ -33,6 +33,7 @@ You receive:
 - `.planning/research/ARCHITECTURE.md`
 - `.planning/research/PITFALLS.md`
 - Project context (PROJECT.md summary)
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 
 ## Output
 
@@ -72,7 +73,9 @@ Based on:
 - ARCHITECTURE.md build order → what depends on what, which foundation must land in Milestone 1 to support final-milestone requirements
 - PITFALLS.md → which risks stall later milestones and need to be addressed in Milestone 1 foundations
 
-Suggest a **2-5 milestone arc ending in Handoff**:
+**Quick scope (`<scope>quick</scope>`, demo projects):** Suggest a **single milestone** (no Handoff, no multi-milestone arc). The milestone is the demo itself — 2 to 4 phases that ship a real working surface end-to-end. Skip the "Handoff implications" section. The demo extends into a full project later via `/qualia-milestone` if the client signs; that conversion is handled there, not here.
+
+**Standard scope (default):** Suggest a **2-5 milestone arc ending in Handoff**:
 
 - **Milestone 1 · Foundation** — almost always. DB, auth, base layout, deploy pipeline.
 - **Milestone 2-{N-1} · Core + Expansion** — the value-delivering capabilities, ordered by dependency.

package/agents/researcher.md

@@ -25,11 +25,16 @@ You receive from the orchestrator:
 - `<domain>` — the project domain (e.g., "legal case management", "dental clinic booking", "voice agent for restaurants")
 - `<project_context>` — summary of PROJECT.md (core value, constraints, what they're building)
 - `<milestone_context>` — greenfield or subsequent
+- `<scope>` — optional: `quick` for demo projects, `standard` (default) for full projects
 - `<output_path>` — absolute path where you write your research file
 
 ## Tool Budget
 
-Maximum 8 external calls total per invocation: 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries. If you exhaust this budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
+**Standard scope (default):** Maximum 8 external calls total per invocation — 3 Context7 queries + 3 WebFetch calls + 2 WebSearch queries.
+
+**Quick scope (`<scope>quick</scope>`, used by demo projects):** Maximum 3 external calls total — 1 Context7 query + 1 WebFetch + 1 WebSearch. The demo only needs enough research to validate the stack and surface the top pitfall — depth is wasted when there's a single milestone to ship. Drain local sources first (Steps 0a + 0b below); if local sources cover the dimension, skip external calls entirely.
+
+If you exhaust the budget, write what you have and mark remaining sections as `confidence: LOW`. Research is time-boxed, not exhaustive — a 10-minute deep dive with concrete sources beats a 30-minute wander.
 
 **Local-first.** Before any external call, exhaust local sources (Steps 0a + 0b in *How to Research* below). Most domains have already been researched and the answers live in NotebookLM notebooks or `~/qualia-memory`. Hitting the web for content we already have is silent token waste — and the local source is usually higher-quality (curated synthesis vs raw search results).
 

package/agents/visual-evaluator.md

@@ -1,6 +1,6 @@
 ---
 name: qualia-visual-evaluator
-description: Vision-anchored evaluator for /qualia-polish-loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
+description: Vision-anchored evaluator for /qualia-polish --loop. Reads screenshots, scores 8 design dimensions against the rubric with cited evidence, returns top 3 issues + severity. Default: 3 (acceptable). Only deviates with quoted evidence.
 tools: Read, Grep, Glob
 ---
 

package/bin/install.js

@@ -390,10 +390,10 @@ async function main() {
       if (fs.existsSync(refSrc)) {
         copy(refSrc, path.join(CLAUDE_DIR, "skills", skill, "REFERENCE.md"));
       }
-      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish-loop ships
-      // playwright-capture.mjs, loop.mjs, score.mjs that the skill invokes at
-      // runtime). Recursive — preserves nested files. fixtures/ also copied
-      // for self-test scenarios.
+      // v5.1: Copy scripts/ subfolder if present (e.g. qualia-polish ships
+      // playwright-capture.mjs, loop.mjs, score.mjs that the --loop mode
+      // invokes at runtime). Recursive, preserves nested files. fixtures/
+      // also copied for self-test scenarios.
       for (const sub of ["scripts", "fixtures"]) {
         const subSrc = path.join(skillsDir, skill, sub);
         if (fs.existsSync(subSrc) && fs.statSync(subSrc).isDirectory()) {
@@ -893,8 +893,8 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
     excludeDefault: true,
     tips: [
       "⬢ Lost? Type /qualia for the next step",
-      "⬢ Small fix? Use /qualia-quick to skip planning",
-      "⬢ End of day? /qualia-report before you clock out",
+      "⬢ Single feature? Use /qualia-feature, it auto-scopes",
+      "⬢ End of day? /qualia-report submits your shift before clock-out",
       "⬢ Context isolation: every task gets a fresh AI brain",
       "⬢ The verifier doesn't trust claims — it greps the code",
       "⬢ Plans are prompts — the plan IS what the builder reads",
@@ -1104,8 +1104,8 @@ function printSummary({ member, target, claudeInstalled }) {
   }
   console.log("");
   console.log(`  ${DIM}New project?${RESET}    ${TEAL}/qualia-new${RESET}`);
-  console.log(`  ${DIM}Quick fix?${RESET}      ${TEAL}/qualia-quick${RESET}`);
-  console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(mandatory)${RESET}`);
+  console.log(`  ${DIM}Single feature?${RESET} ${TEAL}/qualia-feature${RESET}`);
+  console.log(`  ${DIM}End of day?${RESET}     ${TEAL}/qualia-report${RESET} ${DIM}(shift submission)${RESET}`);
   console.log(`  ${DIM}Stuck?${RESET}          ${TEAL}/qualia${RESET}`);
   console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);

package/bin/plan-contract.js

@@ -21,6 +21,28 @@ const CHECK_TYPES = new Set([
   "file-exists", "grep-match", "command-exit", "behavioral",
 ]);
 
+// Scope-reduction detection — phrases that signal an LLM has watered down the
+// spec. The plan-checker agent does the same scan on the markdown plan; this
+// function does it on the JSON contract's free-text fields (action +
+// acceptance_criteria) so both paths catch the same failure mode.
+const SCOPE_REDUCTION_PHRASES = [
+  /\bv1\b/i, /\bv2\b/i, /simplified version/i, /static for now/i,
+  /hardcoded for now/i, /\bplaceholder\b/i, /basic version/i,
+  /minimal implementation/i, /will be wired later/i,
+  /dynamic in future phase/i, /skip for now/i, /\bstub\b/i,
+  /mock for now/i, /we can improve this later/i, /quick win for now/i,
+];
+
+function findScopeReductionPhrases(text) {
+  if (typeof text !== "string") return [];
+  const hits = [];
+  for (const re of SCOPE_REDUCTION_PHRASES) {
+    const m = text.match(re);
+    if (m) hits.push(m[0]);
+  }
+  return hits;
+}
+
 function isStringArray(v) {
   return Array.isArray(v) && v.every((x) => typeof x === "string");
 }
@@ -98,7 +120,15 @@ function validateTask(task, idx, allIds) {
     errs.push(`${where}.acceptance_criteria: must be a non-empty string[]`);
   }
   if (typeof task.action !== "string") errs.push(`${where}.action: required string`);
-  else if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+  else {
+    if (task.action.length > 500) errs.push(`${where}.action: must be ≤ 500 characters (got ${task.action.length})`);
+    const actionHits = findScopeReductionPhrases(task.action);
+    if (actionHits.length) errs.push(`${where}.action: scope-reduction phrase(s) detected: ${actionHits.join(", ")} — rewrite to deliver the actual spec, or split via locked-decision channel`);
+  }
+  for (let i = 0; i < (task.acceptance_criteria || []).length; i++) {
+    const acHits = findScopeReductionPhrases(task.acceptance_criteria[i]);
+    if (acHits.length) errs.push(`${where}.acceptance_criteria[${i}]: scope-reduction phrase(s) detected: ${acHits.join(", ")}`);
+  }
   if (!isStringArray(task.context_files || [])) errs.push(`${where}.context_files: must be string[]`);
   if (!Array.isArray(task.verification) || task.verification.length === 0) {
     errs.push(`${where}.verification: must be a non-empty array`);
@@ -217,4 +247,5 @@ module.exports = {
   parseSafely,
   hashPlan,
   checkDrift,
+  findScopeReductionPhrases,
 };

package/bin/slop-detect.mjs

@@ -187,7 +187,7 @@ const SKIP_DIRS = new Set([
   "coverage", ".cache", "out", ".vercel", ".vscode", ".idea",
   ".planning", ".qa-screenshots",
   // v5.1: skip test fixtures by convention. Fixtures used as regression
-  // targets (e.g. /qualia-polish-loop's broken.html) intentionally violate
+  // targets (e.g. /qualia-polish --loop's broken.html) intentionally violate
   // the rules slop-detect enforces; scanning them flags real fixture bugs
   // as production slop.
   "fixtures", "__fixtures__",

package/docs/erp-contract.md

@@ -2,6 +2,17 @@
 
 The Qualia Framework optionally uploads session reports to the company ERP at `https://portal.qualiasolutions.net`. This document specifies the API shape.
 
+## Operating Model
+
+The ERP treats `/qualia-report` as an employee shift submission, not proof that an assigned task was finished. Employees clock out after their fixed daily hours and submit what happened during the shift: shipped work, partial progress, blockers, investigation, meetings, or no-code work.
+
+Primary ERP planning dates are:
+- Project deadline
+- Milestone deadline
+- Employee submission date from the uploaded report
+
+Phase and task counters remain framework telemetry. They help agents plan/build/verify, but they should not become the ERP's primary navigation, deadline model, or employee-performance label.
+
 ## Configuration
 
 Stored in `~/.claude/.qualia-config.json`: