npm - qualia-framework - Versions diffs - 5.4.0 → 5.8.0 - Mend

qualia-framework 5.4.0 → 5.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

package/README.md +21 -17
package/agents/builder.md +25 -8
package/agents/plan-checker.md +50 -2
package/agents/planner.md +25 -1
package/agents/research-synthesizer.md +4 -1
package/agents/researcher.md +6 -1
package/agents/visual-evaluator.md +1 -1
package/bin/install.js +8 -8
package/bin/plan-contract.js +32 -1
package/bin/slop-detect.mjs +1 -1
package/docs/erp-contract.md +11 -0
package/docs/onboarding.html +623 -0
package/guide.md +8 -9
package/hooks/session-start.js +1 -1
package/package.json +1 -1
package/skills/qualia-discuss/SKILL.md +123 -9
package/skills/qualia-feature/SKILL.md +216 -0
package/skills/qualia-milestone/SKILL.md +73 -1
package/skills/qualia-new/SKILL.md +52 -25
package/skills/qualia-optimize/SKILL.md +1 -1
package/skills/{qualia-polish-loop → qualia-polish}/REFERENCE.md +5 -5
package/skills/qualia-polish/SKILL.md +13 -4
package/skills/{qualia-polish-loop → qualia-polish}/scripts/loop.mjs +2 -2
package/skills/{qualia-polish-loop → qualia-polish}/scripts/playwright-capture.mjs +1 -1
package/skills/qualia-report/SKILL.md +8 -6
package/skills/qualia-road/SKILL.md +10 -11
package/templates/CONTEXT.md +3 -2
package/templates/help.html +1 -1
package/templates/phase-context.md +5 -4
package/templates/project-discovery.md +83 -0
package/templates/project.md +7 -0
package/tests/bin.test.sh +104 -62
package/tests/lib.test.sh +21 -0
package/tests/slop-detect.test.sh +2 -2
package/docs/archive/session-report-2026-04-18.md +0 -199
package/docs/install-redesign-builder-prompt.md +0 -290
package/docs/install-redesign-pilot.md +0 -234
package/docs/instruction-budget-audit.md +0 -113
package/docs/journey-demo.html +0 -1008
package/docs/playwright-loop-builder-prompt.md +0 -185
package/docs/playwright-loop-design-notes.md +0 -108
package/docs/playwright-loop-tester-prompt.md +0 -213
package/docs/polish-loop-supervised-run.md +0 -111
package/skills/qualia-polish-loop/SKILL.md +0 -201
package/skills/qualia-prd/SKILL.md +0 -199
package/skills/qualia-quick/SKILL.md +0 -44
package/skills/qualia-task/SKILL.md +0 -98
/package/skills/{qualia-polish-loop → qualia-polish}/fixtures/broken.html +0 -0
/package/skills/{qualia-polish-loop → qualia-polish}/fixtures/clean.html +0 -0
/package/skills/{qualia-polish-loop → qualia-polish}/scripts/score.mjs +0 -0

package/docs/onboarding.html ADDED Viewed

@@ -0,0 +1,623 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Qualia Framework: How a project flows</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,500;9..144,700&family=Newsreader:opsz,wght@6..72,400;6..72,500;6..72,600&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --bg:        oklch(96.5% 0.012 78);
+    --bg-soft:   oklch(94% 0.014 78);
+    --ink:       oklch(22% 0.025 245);
+    --ink-soft:  oklch(40% 0.025 245);
+    --muted:     oklch(58% 0.018 245);
+    --rule:      oklch(85% 0.02 78);
+    --rule-soft: oklch(90% 0.014 78);
+    --accent:    oklch(52% 0.12 195);
+    --accent-d:  oklch(38% 0.10 195);
+    --warn:      oklch(58% 0.14 50);
+    --space-1:   clamp(.25rem, .2rem + .25vw, .375rem);
+    --space-2:   clamp(.5rem, .4rem + .5vw, .75rem);
+    --space-3:   clamp(.75rem, .6rem + .75vw, 1.125rem);
+    --space-4:   clamp(1rem, .8rem + 1vw, 1.5rem);
+    --space-5:   clamp(1.5rem, 1.2rem + 1.5vw, 2.25rem);
+    --space-6:   clamp(2.25rem, 1.8rem + 2.25vw, 3.5rem);
+    --space-7:   clamp(3.5rem, 2.8rem + 3.5vw, 5.25rem);
+    --display:   "Fraunces", "Newsreader", Georgia, serif;
+    --body:      "Newsreader", Georgia, serif;
+    --mono:      "JetBrains Mono", ui-monospace, "SF Mono", monospace;
+  }
+  * { box-sizing: border-box; }
+  html { -webkit-text-size-adjust: 100%; scroll-behavior: smooth; }
+  body {
+    margin: 0;
+    background: var(--bg);
+    color: var(--ink);
+    font-family: var(--body);
+    font-size: clamp(15px, 14px + .25vw, 17px);
+    line-height: 1.55;
+    font-feature-settings: "kern", "liga", "ss01", "ss02";
+  }
+  main {
+    max-width: 64rem;
+    margin: 0 auto;
+    padding: var(--space-6) var(--space-4) var(--space-7);
+  }
+  /* Header */
+  .marque {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-3);
+    border-bottom: 1px solid var(--rule);
+    padding-bottom: var(--space-3);
+    margin-bottom: var(--space-6);
+  }
+  .marque .mark {
+    font-family: var(--mono);
+    font-size: .75rem;
+    letter-spacing: .14em;
+    text-transform: uppercase;
+    color: var(--accent);
+  }
+  .marque .meta {
+    font-family: var(--mono);
+    font-size: .75rem;
+    color: var(--muted);
+    margin-left: auto;
+  }
+  /* Hero */
+  .hero h1 {
+    font-family: var(--display);
+    font-weight: 500;
+    font-size: clamp(2.25rem, 1.5rem + 4vw, 4.5rem);
+    line-height: 1;
+    letter-spacing: -.02em;
+    margin: 0 0 var(--space-3);
+    font-variation-settings: "opsz" 144;
+  }
+  .hero h1 em {
+    font-style: italic;
+    color: var(--accent-d);
+    font-weight: 400;
+  }
+  .hero p.lede {
+    font-family: var(--display);
+    font-size: clamp(1.125rem, .9rem + .9vw, 1.5rem);
+    color: var(--ink-soft);
+    line-height: 1.4;
+    max-width: 36rem;
+    margin: 0 0 var(--space-5);
+    font-variation-settings: "opsz" 36;
+  }
+  /* Section heading */
+  section { margin-top: var(--space-7); }
+  section > h2 {
+    font-family: var(--mono);
+    font-size: .75rem;
+    letter-spacing: .14em;
+    text-transform: uppercase;
+    color: var(--accent);
+    margin: 0 0 var(--space-1);
+    font-weight: 500;
+  }
+  section > h3 {
+    font-family: var(--display);
+    font-size: clamp(1.5rem, 1.1rem + 1.5vw, 2.25rem);
+    font-weight: 500;
+    line-height: 1.1;
+    letter-spacing: -.015em;
+    margin: 0 0 var(--space-4);
+  }
+  section > p.intro {
+    color: var(--ink-soft);
+    max-width: 36rem;
+    margin: 0 0 var(--space-4);
+  }
+  /* Path step */
+  .step {
+    display: grid;
+    grid-template-columns: auto 1fr;
+    gap: var(--space-4);
+    align-items: baseline;
+    padding: var(--space-3) 0;
+    border-top: 1px solid var(--rule-soft);
+  }
+  .step:first-child { border-top: 1px solid var(--rule); }
+  .step:last-child { border-bottom: 1px solid var(--rule); }
+  .step .n {
+    font-family: var(--mono);
+    font-size: .85rem;
+    color: var(--muted);
+    width: 2.5rem;
+    font-variant-numeric: tabular-nums;
+    padding-top: .15rem;
+  }
+  .step .body { display: flex; flex-direction: column; gap: var(--space-1); }
+  .step .cmd {
+    font-family: var(--mono);
+    font-size: clamp(.95rem, .85rem + .25vw, 1.05rem);
+    font-weight: 500;
+    color: var(--ink);
+  }
+  .step .cmd .alt {
+    color: var(--muted);
+    font-weight: 400;
+    margin-left: .5rem;
+  }
+  .step .what {
+    font-family: var(--display);
+    font-size: clamp(1.05rem, .95rem + .25vw, 1.2rem);
+    color: var(--ink);
+    line-height: 1.35;
+  }
+  .step .why {
+    color: var(--muted);
+    font-size: .95rem;
+    line-height: 1.45;
+  }
+  /* Branch (Demo vs Project) */
+  .branch {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--space-3);
+    margin-top: var(--space-4);
+  }
+  @media (min-width: 720px) {
+    .branch { grid-template-columns: 1fr 1fr; }
+  }
+  .branch article {
+    border: 1px solid var(--rule);
+    background: var(--bg-soft);
+    padding: var(--space-4);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+  }
+  .branch h4 {
+    font-family: var(--display);
+    font-size: 1.4rem;
+    font-weight: 600;
+    margin: 0;
+    line-height: 1.1;
+  }
+  .branch h4 .tag {
+    font-family: var(--mono);
+    font-size: .65rem;
+    letter-spacing: .14em;
+    text-transform: uppercase;
+    color: var(--accent);
+    display: block;
+    margin-bottom: .25rem;
+    font-weight: 500;
+  }
+  .branch p { margin: 0; color: var(--ink-soft); }
+  .branch ul {
+    margin: var(--space-2) 0 0;
+    padding: 0;
+    list-style: none;
+    border-top: 1px solid var(--rule-soft);
+  }
+  .branch li {
+    padding: .35rem 0;
+    border-bottom: 1px solid var(--rule-soft);
+    font-family: var(--mono);
+    font-size: .85rem;
+    color: var(--ink-soft);
+    display: flex;
+    gap: var(--space-2);
+  }
+  .branch li::before { content: "›"; color: var(--accent); }
+  /* Toolkit grid */
+  .kit {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: var(--space-4);
+  }
+  @media (min-width: 720px) {
+    .kit { grid-template-columns: 1fr 1fr; gap: var(--space-5); }
+  }
+  .kit-group h4 {
+    font-family: var(--mono);
+    font-size: .75rem;
+    letter-spacing: .14em;
+    text-transform: uppercase;
+    color: var(--ink);
+    margin: 0 0 var(--space-2);
+    font-weight: 600;
+    padding-bottom: var(--space-1);
+    border-bottom: 1px solid var(--rule);
+  }
+  .kit-group dl {
+    margin: 0;
+    display: grid;
+    grid-template-columns: auto 1fr;
+    column-gap: var(--space-3);
+    row-gap: var(--space-2);
+    align-items: baseline;
+  }
+  .kit-group dt {
+    font-family: var(--mono);
+    font-size: .85rem;
+    font-weight: 500;
+    color: var(--ink);
+    white-space: nowrap;
+  }
+  .kit-group dd {
+    margin: 0;
+    color: var(--ink-soft);
+    font-size: .95rem;
+    line-height: 1.4;
+  }
+  /* Aside, callouts */
+  .callout {
+    margin-top: var(--space-4);
+    padding: var(--space-3) var(--space-4);
+    border-left: 2px solid var(--accent);
+    background: var(--bg-soft);
+    color: var(--ink-soft);
+    font-size: .95rem;
+  }
+  .callout strong { color: var(--ink); font-weight: 600; }
+  /* Footer */
+  footer {
+    margin-top: var(--space-7);
+    padding-top: var(--space-4);
+    border-top: 1px solid var(--rule);
+    display: flex;
+    justify-content: space-between;
+    align-items: baseline;
+    flex-wrap: wrap;
+    gap: var(--space-3);
+    font-family: var(--mono);
+    font-size: .8rem;
+    color: var(--muted);
+  }
+  footer a {
+    color: var(--accent);
+    text-decoration: none;
+  }
+  footer a:hover { text-decoration: underline; }
+  /* Selection */
+  ::selection { background: var(--accent); color: var(--bg); }
+  /* Print */
+  @media print {
+    body { background: white; }
+    main { padding: 1.5rem; }
+    section { break-inside: avoid; }
+  }
+</style>
+</head>
+<body>
+<main>
+  <header class="marque">
+    <span class="mark">Qualia Framework</span>
+    <span class="meta">For Moayad &amp; new hires · v5.5</span>
+  </header>
+  <section class="hero">
+    <h1>How a project flows<br><em>from idea to shipped.</em></h1>
+    <p class="lede">
+      You do not need to remember thirty commands. You need to remember <em>one path</em>.
+      The path takes a project from a vague client conversation to a deployed,
+      handed-off, billed product. Everything else is a side road you take when
+      something specific happens.
+    </p>
+  </section>
+  <section>
+    <h2>The path</h2>
+    <h3>Eight commands. In order. Most projects only ever use these.</h3>
+    <p class="intro">
+      Each command produces concrete artifacts. The next command reads them.
+      Nothing is improvised; the framework keeps state for you.
+    </p>
+    <div class="steps">
+      <div class="step">
+        <div class="n">01</div>
+        <div class="body">
+          <div class="cmd">/qualia-new</div>
+          <div class="what">Kick off a project from zero.</div>
+          <div class="why">
+            Asks <em>Demo or Full Project?</em>, runs a mandatory non-technical
+            discovery interview, then generates every artifact the rest of the
+            flow depends on (PROJECT, PRODUCT, DESIGN, JOURNEY, REQUIREMENTS,
+            ROADMAP, CONTEXT, STATE).
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">02</div>
+        <div class="body">
+          <div class="cmd">/qualia-plan N</div>
+          <div class="what">Break milestone N into 2 to 5 atomic tasks.</div>
+          <div class="why">
+            A planner subagent writes a story-file plan; a plan-checker
+            subagent grades it against eleven rules and sends it back for
+            revision up to twice if it falls short. You never see a vague plan.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">03</div>
+        <div class="body">
+          <div class="cmd">/qualia-build</div>
+          <div class="what">Execute the planned tasks in waves.</div>
+          <div class="why">
+            One fresh builder subagent per task, no shared memory, atomic git
+            commit each. Builders self-heal small lint failures up to twice
+            before reporting blocked. Wave parallelism for non-conflicting
+            tasks.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">04</div>
+        <div class="body">
+          <div class="cmd">/qualia-verify</div>
+          <div class="what">Prove the phase actually works.</div>
+          <div class="why">
+            A fresh verifier reads the codebase backwards from the phase goal,
+            checks every acceptance criterion against real grep / curl / tsc
+            output, then runs an adversarial second pass. Pass-or-revise.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">↻</div>
+        <div class="body">
+          <div class="cmd">Repeat 02 → 04 for each phase.</div>
+          <div class="what">Most milestones have two or three phases.</div>
+          <div class="why">
+            The phase loop is the heartbeat of every project. Each phase ends
+            in a working, committed, verified slice.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">05</div>
+        <div class="body">
+          <div class="cmd">/qualia-milestone</div>
+          <div class="what">Close the milestone, open the next one.</div>
+          <div class="why">
+            Archives M1 artifacts, regenerates ROADMAP.md for M2 from
+            JOURNEY.md, resets STATE. For a single-milestone demo, this is
+            also where "client signed, extend it" becomes a full project.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">06</div>
+        <div class="body">
+          <div class="cmd">/qualia-ship</div>
+          <div class="what">Deploy to production.</div>
+          <div class="why">
+            Quality gates, security scan, push, <code>vercel --prod</code>,
+            five-check post-deploy verification. No surprises.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">07</div>
+        <div class="body">
+          <div class="cmd">/qualia-handoff</div>
+          <div class="what">Deliver to the client.</div>
+          <div class="why">
+            Production URL, documentation, credentials, walkthrough. Four
+            mandatory deliverables, never fewer.
+          </div>
+        </div>
+      </div>
+      <div class="step">
+        <div class="n">08</div>
+        <div class="body">
+          <div class="cmd">/qualia-report</div>
+          <div class="what">Clock out.</div>
+          <div class="why">
+            End-of-shift submission to the Qualia ERP. Truthful, not
+            aspirational. "Blocked all afternoon" is a valid report.
+          </div>
+        </div>
+      </div>
+    </div>
+    <div class="callout">
+      <strong>The lazy version of remembering this:</strong> type <code>/qualia</code>
+      whenever you are unsure. The state router reads the project state and tells
+      you the exact next command to type.
+    </div>
+  </section>
+  <section>
+    <h2>The fork at the start</h2>
+    <h3>Demo or Full Project. Pick once, the artifacts adapt.</h3>
+    <p class="intro">
+      <code>/qualia-new</code> asks this question first. The artifact set
+      is identical for both; what changes is depth and milestone count.
+      A demo can grow into a full project later; nothing gets thrown away.
+    </p>
+    <div class="branch">
+      <article>
+        <h4><span class="tag">Path A</span>Demo / MVP</h4>
+        <p>
+          Single shippable milestone. Real backend, no mocks. Beautiful design
+          built fast. Designed to either stand alone or grow into a full
+          project if the client signs.
+        </p>
+        <ul>
+          <li>Discuss: 8 questions, ~5 min</li>
+          <li>Research: 1 round</li>
+          <li>JOURNEY.md: 1 milestone</li>
+          <li>ROADMAP.md: 1-3 phases</li>
+          <li>Extends via /qualia-milestone</li>
+        </ul>
+      </article>
+      <article>
+        <h4><span class="tag">Path B</span>Full Project</h4>
+        <p>
+          Multi-milestone arc planned at kickoff. Used when the scope is
+          known and there is a retainer. Every milestone ends with a
+          shippable, billable deliverable.
+        </p>
+        <ul>
+          <li>Discuss: 14 questions, ~15-20 min</li>
+          <li>Research: 4 parallel rounds + synthesis</li>
+          <li>JOURNEY.md: 2-5 milestones, includes Handoff</li>
+          <li>ROADMAP.md: M1 detailed, M2..MN sketched</li>
+          <li>Progresses via /qualia-milestone per ship</li>
+        </ul>
+      </article>
+    </div>
+  </section>
+  <section>
+    <h2>When something goes sideways</h2>
+    <h3>The fix verbs.</h3>
+    <p class="intro">
+      You only reach for these when the path stops working: a bug, a slow
+      page, an audit before a deploy.
+    </p>
+    <div class="kit">
+      <div class="kit-group">
+        <h4>Diagnose &amp; fix</h4>
+        <dl>
+          <dt>/qualia-debug</dt><dd>Investigative debugging. Finds root cause, applies a minimal fix, writes a debug report.</dd>
+          <dt>/qualia-review</dt><dd>Production audit with severity-scored findings. Run before a big deploy.</dd>
+          <dt>/qualia-optimize</dt><dd>Deep pass for performance, design, architecture. Spawns parallel specialists.</dd>
+          <dt>/qualia-postmortem</dt><dd>Self-healing layer. After a failed verify, identifies which agent or rule should have caught it and proposes a delta.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>Mid-flight design &amp; tests</h4>
+        <dl>
+          <dt>/qualia-polish</dt><dd>Manual design pass on a component, route, or full app.</dd>
+          <dt>/qualia-polish-loop</dt><dd>Autonomous screenshot → score → fix loop until rubric passes.</dd>
+          <dt>/qualia-test</dt><dd>Generate tests, run tests, or drive a feature TDD-style.</dd>
+        </dl>
+      </div>
+    </div>
+  </section>
+  <section>
+    <h2>Outside the phase</h2>
+    <h3>Single-feature work and session control.</h3>
+    <div class="kit">
+      <div class="kit-group">
+        <h4>Build something small</h4>
+        <dl>
+          <dt>/qualia-quick</dt><dd>Trivial inline fix. One file, no spawn. Typo, config tweak.</dd>
+          <dt>/qualia-task</dt><dd>Single feature, fresh builder spawn, atomic commit. 1 to 5 files.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>Navigate the session</h4>
+        <dl>
+          <dt>/qualia</dt><dd>State router. Tells you the exact next command.</dd>
+          <dt>/qualia-idk</dt><dd>"Something feels off." Diagnoses confusion across .planning + codebase.</dd>
+          <dt>/qualia-pause</dt><dd>Save context for handoff to a future session.</dd>
+          <dt>/qualia-resume</dt><dd>Restore context and routing from a paused session.</dd>
+          <dt>/qualia-road</dt><dd>Terminal map of the workflow. Headless-friendly.</dd>
+          <dt>/qualia-help</dt><dd>Open this kind of reference in the browser.</dd>
+        </dl>
+      </div>
+    </div>
+  </section>
+  <section>
+    <h2>Pre-planning depth</h2>
+    <h3>When a phase is high-stakes.</h3>
+    <p class="intro">
+      Most phases plan fine without ceremony. Auth, payments, multi-tenant,
+      regulatory and architectural-fork phases earn an upfront alignment.
+    </p>
+    <div class="kit">
+      <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-research</dt><dd>Deep-research a niche library or domain before planning a phase.</dd>
+          <dt>/qualia-prd</dt><dd>Synthesize the current conversation into a durable PRD document.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>Code archaeology</h4>
+        <dl>
+          <dt>/qualia-map</dt><dd>Brownfield onboarding. Map an existing codebase before adding to it.</dd>
+          <dt>/qualia-zoom</dt><dd>Map a small, unfamiliar code area in domain-glossary terms.</dd>
+        </dl>
+      </div>
+    </div>
+  </section>
+  <section>
+    <h2>Knowledge, queue, meta</h2>
+    <h3>Long-term scaffolding.</h3>
+    <div class="kit">
+      <div class="kit-group">
+        <h4>Knowledge</h4>
+        <dl>
+          <dt>/qualia-learn</dt><dd>Save a learning, pattern, fix, or client preference. Persists across projects and sessions.</dd>
+          <dt>/qualia-flush</dt><dd>Promote daily-log raw entries to the curated knowledge tier.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>Issue queue</h4>
+        <dl>
+          <dt>/qualia-issues</dt><dd>Break a phase plan into independent vertical-slice GitHub issues.</dd>
+          <dt>/qualia-triage</dt><dd>Route open issues into needs-info, ready-for-agent, ready-for-human.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>Extend the framework</h4>
+        <dl>
+          <dt>/qualia-skill-new</dt><dd>Author a new Qualia skill or agent.</dd>
+          <dt>/qualia-hook-gen</dt><dd>Convert an instruction into a deterministic Claude Code hook.</dd>
+        </dl>
+      </div>
+      <div class="kit-group">
+        <h4>External</h4>
+        <dl>
+          <dt>/zoho-workflow</dt><dd>Zoho Invoice and Mail operations via ERP-first routing.</dd>
+        </dl>
+      </div>
+    </div>
+  </section>
+  <section>
+    <h2>One more thing</h2>
+    <h3>Don't over-think it.</h3>
+    <p class="intro">
+      Ninety percent of project days you only touch <code>/qualia-plan</code>,
+      <code>/qualia-build</code>, <code>/qualia-verify</code> in a tight loop,
+      then <code>/qualia-report</code> at the end of the shift. The rest of
+      the surface is there for the ten-percent days. When in doubt, type
+      <code>/qualia</code>.
+    </p>
+  </section>
+  <footer>
+    <span>Qualia Framework v5.5.0 · Plan, build, verify, ship.</span>
+    <span><a href="https://github.com/Qualiasolutions/qualia-framework">github.com/Qualiasolutions/qualia-framework</a></span>
+  </footer>
+</main>
+</body>
+</html>

package/guide.md CHANGED Viewed

@@ -1,9 +1,9 @@
-# Qualia Developer Guide (v5.3)
+# Qualia Developer Guide (v5.8)
 > 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.
-**v5.3 ships three Matt-Pocock gap closures:** `/qualia-prd` (synthesize conversation → durable spec), `/qualia-hook-gen` (CLAUDE.md instruction → deterministic hook), `/qualia-optimize --deepen` Step 5b (3 parallel-interface design variants for refactor RFCs). Plus the visual-polish loop (`/qualia-polish-loop`) from v5.1 with reduced-motion + multi-route flags from v5.2.
+**v5.8 cleans up the command surface:** `/qualia-polish-loop` is now `/qualia-polish --loop` (one flag instead of two skills). `/qualia-quick`, `/qualia-task`, and `/qualia-prd` are removed after their v5.7 deprecation window; use `/qualia-feature` for single-feature work and `/qualia-discuss` in PROJECT MODE for kickoff capture. Skill count goes from 35 to 32.
 ## The Road
@@ -52,14 +52,13 @@ Append `--auto` to `/qualia-new` and the framework chains every step:
 | Starting | `/qualia-new` | Set up project with full journey (all milestones → Handoff) |
 | Starting (auto) | `/qualia-new --auto` | Same + chain through building automatically |
 | Brownfield | `/qualia-map` | Map an existing codebase BEFORE `/qualia-new` |
-| Mid-project spec | `/qualia-prd` | Synthesize the current conversation into a durable feature spec (v5.3+) |
 | Building | `/qualia-plan` | Plan the current phase |
 | | `/qualia-build` | Build it (parallel tasks) |
 | | `/qualia-verify` | Check it actually works |
 | Milestone | `/qualia-milestone` | Close current, open next from JOURNEY.md |
-| Quick fix | `/qualia-quick` | Skip planning, just do it |
-| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick) |
-| | `/qualia-polish-loop` | Autonomous visual-polish loop — screenshot → vision-eval → fix → repeat (v5.1+) |
+| Single feature | `/qualia-feature` | Auto-scoped: inline for trivia, fresh spawn for 1-5 files |
+| Finishing | `/qualia-polish` | Design and UX pass (scope-adaptive: component / route / app / redesign / critique / quick / loop) |
+| | `/qualia-polish --loop` | Autonomous visual-polish loop: screenshot, vision-eval, fix, repeat |
 | | `/qualia-ship` | Deploy to production |
 | | `/qualia-handoff` | Deliver to client (4 mandatory deliverables) |
 | Reporting | `/qualia-report` | Log what you did (mandatory before clock-out) |
@@ -109,7 +108,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 ## Session Start / End
 **Start:** Claude loads your project context automatically. The router banner shows your journey position ("M2 of 4 · P2 of 3").
-**End:** Run `/qualia-report` — this is mandatory before clock-out. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
+**End:** Run `/qualia-report` — this is the mandatory clock-out submission. It reports what happened during the work shift, even if the work is unfinished. The report is committed to git and (if ERP is enabled) uploaded to https://portal.qualiasolutions.net.
 ## How It Works (you don't need to know this, but if curious)
@@ -120,7 +119,7 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 - **Story-file plans:** Every task has Why / Acceptance Criteria / Depends on / Validation inline — the plan IS the brief.
 - **Wave execution:** Independent tasks run in parallel. Dependent tasks wait.
 - **Milestone-boundary pauses:** In `--auto` mode, the framework pauses only at real decision points. Everything else runs on rails.
-- **tracking.json:** Updated on every push. The ERP reads it automatically. Includes `milestone_name` + `milestones[]` so the ERP renders a proper tree instead of a flat list.
+- **tracking.json:** Updated on every push. The ERP reads it automatically. Includes `milestone_name` + `milestones[]` so the ERP can show project and milestone progress without exposing framework tasks as the main employee workflow.
 ## Quick Reference
@@ -134,4 +133,4 @@ If neither helps, paste the error and ask Claude directly. If Claude can't fix i
 | Finished the last phase of a milestone | `/qualia-milestone` |
 | About to ship | `/qualia-ship` |
 | Client is ready to take over | `/qualia-handoff` |
-| End of workday | `/qualia-report` (mandatory) |
+| End of workday / clock-out | `/qualia-report` (mandatory shift submission) |

package/hooks/session-start.js CHANGED Viewed

@@ -173,7 +173,7 @@ try {
     console.log(`  ${DIM}Start here:${RESET}`);
     console.log(`    ${TEAL}/qualia-new${RESET}    ${DIM}Set up a new project${RESET}`);
     console.log(`    ${TEAL}/qualia${RESET}        ${DIM}What should I do next?${RESET}`);
-    console.log(`    ${TEAL}/qualia-quick${RESET}  ${DIM}Quick fix (skip planning)${RESET}`);
+    console.log(`    ${TEAL}/qualia-feature${RESET} ${DIM}Single feature (auto-scoped)${RESET}`);
     console.log("");
   }
 } catch (e) {