qualia-framework 7.1.0 → 7.2.1

package/CHANGELOG.md

@@ -8,6 +8,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 > Note: git tags for historical versions were not retained; commit references are approximate
 > and dates reflect commit history rather than npm publish timestamps.
 
+## [7.2.1] - 2026-06-27 (system-audit makeover — portability, least-privilege, the one-loop)
+
+Outcome of a full four-system audit. Doc-truth and portability fixes plus the
+memory-loop wiring that makes the brain learn again. No execution-kernel behavior
+change; additive and corrective only.
+
+### Fixed
+- **`/qualia-scope` portability** — replaced hardcoded `/home/qualia/` paths with
+  `${QUALIA_RULES}` / `${QUALIA_REFERENCES}` so the constitution + archetype DoD
+  actually load on every install (Claude and Codex). It was silently HALTing before.
+- **Doc truth** — Opus 4.7 to 4.8 strings; skill/hook/rule counts (28/16/12)
+  regenerated from disk with a `refs.test.sh` guard so they cannot drift again;
+  the 5 undiscoverable skills added to the guide.
+
+### Added
+- **Least-privilege on `zoho-workflow`** — the only money-moving skill that had no
+  `allowed-tools` boundary now has one.
+- **The one memory loop** — `knowledge-flush.js` dual-writes durable concepts into
+  the vault; one nightly `systemd --user` timer (installer-owned) runs
+  flush -> ingest-erp-reports -> export-team-wiki; `qualia-doctor` gains five
+  freshness gates so a frozen loop is loud.
+- **R6 golden verifier fixture** — a seeded panel that must FAIL, proving the
+  verifier cannot default to a passing score.
+
+## [7.2.0] - 2026-06-25 (journey spine — lifecycle UX for employees)
+
+A cosmetic/UX layer that gives an employee a continuous sense of place and
+momentum across the whole lifecycle — install → start → work → finish — reusing
+the existing teal palette and glyph set. No new commands to learn; the framework
+just shows "where am I, what's my forward motion, what's the one next move" at
+every touchpoint.
+
+### Added
+- **`qualia-ui.js spine`** — compact horizontal milestone ladder
+  (`M1 ●──M2 ◆──M3 ○`) with a caret aligned exactly beneath the current
+  milestone. Rendered by the session-start banner so the journey map is the
+  first thing an employee sees. Self-skips on single-milestone projects.
+- **`qualia-ui.js onboard <name>`** — first-run mental-model card (Plan → Build
+  → Verify → Ship + the one first move). Shown after install for non-OWNER
+  roles only.
+- **`qualia-ui.js phase-complete <n> <name> [k=v…]`** — per-phase celebration
+  with a milestone progress bar and optional streak; wired into `/qualia-ship`.
+- **`qualia-ui.js clockout <name> [k=v…]`** — end-of-day report card (shipped
+  counts, milestone %, streak); wired into `/qualia-report`. Every metric
+  self-omits when its data is unavailable — never fabricates.
+- **`barTicks(done,total,width)`** — reusable `▰▱` micro-bar helper.
+- **Always-visible progress in the statusline** — the phase pill now carries a
+  `▰▰▰▱▱` bar (`P3/5 ▰▰▰▱▱`) so forward motion is ambient while working.
+
+### Tests
+- New suite `journey-spine.test.sh` (33 cases): barTicks scaling/clamping, all
+  four cards, spine caret-alignment (exact column match), self-skip paths, and
+  the statusline bar. Full suite green: **28 shell suites + 179 node tests**.
+
 ## [7.1.0] - 2026-06-25 (harness gates — hallucinated deps, secrets, model routing)
 
 Hardening pass: reviewed Google's "The New SDLC With Vibe Coding" whitepaper

package/FLAGS.md

@@ -9,6 +9,7 @@ or another underlying CLI.
 | Skill | Flag | Effect |
 |---|---|---|
 | `/qualia-new` | `--auto` | Chain end-to-end after journey approval. Pauses only at milestone boundaries. |
+| `/qualia-new` | `--quick` | 4-phase flat wizard for trivial projects (landing pages, prototypes). Skips research and journey mapping. |
 | `/qualia-plan` | `--gaps` | Surgical-fix mode. Reads `phase-{N}-verification.md` FAILs, produces wave-1 fix tasks without touching passing items. |
 | `/qualia-verify` | `--adversarial` | Spawn a second-pass critic that attacks the verifier's own report. Required on auth / payment / migration phases. |
 | `/qualia-postmortem` | `--auto` | Auto-invoked by `/qualia-verify` on FAIL. Identifies which agent/rule/skill should have caught the failure and proposes a delta. |
@@ -59,6 +60,15 @@ or another underlying CLI.
 |---|---|---|
 | `/qualia-test` | `--tdd` | Drive a feature test-first via vertical-slice loop (one test → one impl → repeat). |
 
+## Specialized & post-launch
+
+| Skill | Flag | Effect |
+|---|---|---|
+| `/qualia-secure` | `--deep` | Run the optional Opus adversarial red/blue/auditor deep-analysis pass after the static scan. |
+| `/qualia-secure` | `--exit-code` | CI release-gate mode: non-zero exit on findings (wire into pipelines). |
+| `/qualia-recall` | `--scope <knowledge\|vault\|all>` | Restrict recall to the knowledge layer, the qualia-memory vault, or both (default `all`). |
+| `/qualia-recall` | `--json` | Machine-readable output. |
+
 ## Ship & report
 
 | Skill | Flag | Effect |

package/README.md

@@ -135,12 +135,12 @@ Project
 
 **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 (v6.3.0)
+## What's Inside
 
-- **25 installed skills**, focused into Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (scope, research, map), navigation (qualia router + road), quality (fix, review, optimize with `--deepen` parallel-interface design, feature, test), design (`qualia-polish --loop` and `--vibe`), health/reporting (doctor, learn, postmortem), and Zoho workflow support. Retired helper commands are pruned on install rather than exposed as default slash commands.
+- **28 installed skills** (`skills/` is the source of truth — run `qualia-framework doctor` for the live list), focused into Road (new / plan / build / verify / milestone / polish / ship / handoff / report), depth (scope, research, map), navigation (qualia router + road), quality (fix, review, optimize with `--deepen` parallel-interface design, feature, test), AI-feature evaluation (eval), security scanning (secure), post-launch operate mode (update), OWNER recall (recall), health/reporting (doctor, learn, postmortem), and Zoho workflow support. Retired helper commands are pruned on install rather than exposed as default slash commands.
 - **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 stamp, migration-guard, pre-deploy-gate, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard
-- **10 installed rules** (`rules/`): grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, and always-on command-output transparency.
+- **16 hooks** (pure Node.js, cross-platform): session-start, auto-update, git-guardrails, branch-guard, pre-push tracking stamp, migration-guard, pre-deploy-gate, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard, secret-guard, task-write-guard, pre-compact, usage-capture
+- **12 installed rules** (`rules/`): constitution, grounding, security, access, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, and always-on command-output transparency.
 - **7 lazy-loaded design files** (`qualia-design/`): design-laws, design-brand, design-product, design-rubric, design-reference, frontend, graphics — `Read` on demand by design-aware skills/agents only.
 - **25 template files**: project.md, journey.md, plan.md (story-file format), state.md, DESIGN.md, CONTEXT.md (domain glossary), work-packet.md (ERP-approved session context), decisions/ADR-template.md, tracking.json (with `milestone_name` + `milestones[]`), requirements.md (multi-milestone), roadmap.md (current milestone only), phase-context.md, 4 project-type templates (website, ai-agent, voice-agent, mobile-app), 5 research-project templates (STACK, FEATURES, ARCHITECTURE, PITFALLS, SUMMARY), knowledge templates, help.html
 - **Planning hygiene guard**: `planning-hygiene.js` scans `.planning/` for loose reports/assets and can organize them under `reports/`, `assets/`, `design/`, or `archive/loose/` only with explicit `--write`
@@ -180,7 +180,7 @@ Splitting planner, builder, and verifier into separate agents with separate cont
 
 ### Production-Grade Hooks
 
-All 12 hooks are real ops engineering, not theoretical:
+All 16 hooks are real ops engineering, not theoretical:
 
 - **Pre-deploy gate** — TypeScript, lint, tests, build, and `service_role` leak scan before `vercel --prod`
 - **Fawzi approval guard** — Silently counts employee proxy-approval claims for ERP review
@@ -214,12 +214,12 @@ npx qualia-framework@latest install
      |
      v
 ~/.claude/ and/or ~/.codex/
-  ├── skills/             25 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
+  ├── skills/             28 installed skills (each may ship SKILL.md + REFERENCE.md + scripts/ + fixtures/)
   ├── agents/             9 agent definitions (Claude .md, Codex .toml)
-  ├── hooks/              11 Node.js hooks — cross-platform (no bash dependency)
+  ├── hooks/              16 Node.js hooks — cross-platform (no bash dependency)
   ├── bin/                state.js + qualia-ui.js + statusline.js + knowledge.js + knowledge-flush.js + slop-detect.mjs + planning-hygiene.js + plan-contract.js + agent-runs.js + ERP/report helpers
   ├── knowledge/          learned-patterns.md, common-fixes.md, client-prefs.md, daily-log/
-  ├── rules/              grounding, security, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, command-output
+  ├── rules/              constitution, grounding, security, access, infrastructure, deployment, speed, architecture, trust-boundary, codex-goal, one-opinion, command-output
   ├── qualia-design/      lazy-loaded design substrate — read on demand
   ├── qualia-templates/   project, journey, plan, state, DESIGN, CONTEXT, work-packet, decisions, tracking, requirements, roadmap, research, help
   ├── qualia-references/  questioning.md (deep project initialization methodology)

package/bin/cli.js

@@ -453,6 +453,7 @@ async function cmdUninstall() {
     safeRmDir(path.join(home, "qualia-templates"), counters);
     safeRmDir(path.join(home, "qualia-design"), counters);
     safeRmDir(path.join(home, "qualia-references"), counters);
+    safeRmDir(path.join(home, "references"), counters);
 
     if (!preserveKnowledge) {
       safeRmDir(path.join(home, "knowledge"), counters);
@@ -466,10 +467,39 @@ async function cmdUninstall() {
 
     safeRmDir(path.join(home, ".qualia-traces"), counters);
 
+    // Memory-loop runner (installed alongside bin/, not a .js so not in QUALIA_BIN_FILES).
+    safeUnlink(path.join(home, "bin", "qualia-loop.sh"), counters);
+
     if (isCodexHome(home)) cleanCodexHooksJson(home, counters);
     else cleanSettingsJson(home, counters);
   }
 
+  // ── Memory loop systemd --user timer teardown ─────────────
+  // installMemoryTimer() (bin/install.js) enables a nightly timer + writes unit
+  // files. Disable + remove them so uninstall leaves no scheduled job behind.
+  try {
+    const os = require("os");
+    const { spawnSync } = require("child_process");
+    const unitDir = path.join(os.homedir(), ".config", "systemd", "user");
+    const units = ["qualia-loop.timer", "qualia-loop.service"];
+    const probe = spawnSync("systemctl", ["--user", "--version"], { stdio: "ignore" });
+    if (probe.status === 0) {
+      spawnSync("systemctl", ["--user", "disable", "--now", "qualia-loop.timer"], { stdio: "ignore" });
+    }
+    let removedUnit = false;
+    for (const u of units) {
+      const p = path.join(unitDir, u);
+      if (fs.existsSync(p)) { try { fs.unlinkSync(p); removedUnit = true; counters.filesRemoved++; } catch (e) { counters.errors.push(`systemd unit ${u}: ${e.message}`); } }
+    }
+    const loopLog = path.join(os.homedir(), ".claude", ".qualia-loop.log");
+    if (fs.existsSync(loopLog)) { try { fs.unlinkSync(loopLog); counters.filesRemoved++; } catch {} }
+    if (probe.status === 0 && removedUnit) {
+      spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+    }
+  } catch (e) {
+    counters.errors.push(`memory-loop timer teardown: ${e.message}`);
+  }
+
   // Summary.
   console.log("");
   console.log(`${TEAL}  ⬢ Uninstall complete${RESET}`);
@@ -1478,11 +1508,29 @@ function cmdDoctor() {
     projectAdvisories.push(`project contract health unavailable: ${e.message}`);
   }
 
+  // ── Memory-loop freshness gates (advisory) ─────────────
+  // Surfaces a silently-frozen loop: stale capture, an unscheduled flush, a
+  // stale export, partial coverage, or deprecated rows leaking into the export.
+  let memoryGates = [];
+  try {
+    memoryGates = require("./qualia-doctor.js").runGates();
+  } catch (e) {
+    memoryGates = [{ gate: "memory-loop gates", status: "FAIL", detail: e.message }];
+  }
+
   // ── Render ────────────────────────────────────────────
   for (const c of checks) {
     const mark = c.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
     console.log(`  ${mark} ${c.label}`);
   }
+  if (memoryGates.length > 0) {
+    console.log("");
+    console.log(`  ${WHITE}Memory loop:${RESET}`);
+    for (const g of memoryGates) {
+      const mark = g.status === "PASS" ? `${GREEN}✓${RESET}` : g.status === "WARN" ? `${YELLOW}!${RESET}` : `${RED}✗${RESET}`;
+      console.log(`  ${mark} ${g.gate} ${DIM}— ${g.detail}${RESET}`);
+    }
+  }
   if (projectAdvisories.length > 0) {
     console.log("");
     console.log(`  ${WHITE}Project trust:${RESET}`);

package/bin/host-adapters.js

@@ -69,7 +69,11 @@ function adapter(name) {
       QUALIA_RULES: `${home}/rules`,
       QUALIA_TEMPLATES: `${home}/qualia-templates`,
       QUALIA_KNOWLEDGE: `${home}/knowledge`,
-      QUALIA_REFERENCES: `${home}/qualia-references`,
+      // Canonical references tree (methodology docs + archetypes/). The
+      // archetype DoD files (read by qualia-scope) live ONLY under this canonical
+      // path, so the token points here — NOT at the flat `qualia-references/`
+      // mirror, which carries questioning.md but not the nested archetypes/ tree.
+      QUALIA_REFERENCES: `${home}/references`,
       QUALIA_DESIGN: `${home}/qualia-design`,
     },
   };

package/bin/install.js

@@ -629,6 +629,111 @@ function resolveTeamCode(input) {
   return null;
 }
 
+// ─── Memory loop scheduler (systemd --user timer) ────────────────────────
+// THE ONE LOOP, installer-owned. A single nightly timer runs, in order:
+//   1. knowledge-flush.js     → promote daily-log + dual-write vault concepts
+//   2. ingest-erp-reports.py  → pull team reports from ERP into the vault
+//   3. export-team-wiki.py    → rebuild the sanitized team export
+// Fedora is the target (crontab is empty); systemd --user is the native
+// scheduler. Idempotent: re-running install rewrites the unit files and
+// re-enables the timer. If systemctl --user is unavailable (non-systemd host,
+// or no user bus), we write the units anyway and print manual-run fallback
+// instructions instead of failing the install.
+function installMemoryTimer() {
+  printSection("Memory loop scheduler");
+
+  const os = require("os");
+  const { spawnSync } = require("child_process");
+  const HOME = os.homedir();
+
+  const unitDir = path.join(HOME, ".config", "systemd", "user");
+  const binFlush = path.join(CLAUDE_DIR, "bin", "knowledge-flush.js");
+  const vaultRoot = process.env.QUALIA_MEMORY || path.join(HOME, "qualia-memory");
+  const scriptsDir = path.join(vaultRoot, "scripts");
+  const ingest = path.join(scriptsDir, "ingest-erp-reports.py");
+  const exportWiki = path.join(scriptsDir, "export-team-wiki.py");
+  const logFile = path.join(CLAUDE_DIR, ".qualia-loop.log");
+
+  // The runner script chains the three steps; non-fatal per step so one failure
+  // (e.g. ERP down) doesn't block the others. node for the flush, python3 for
+  // the vault scripts (skipped gracefully if absent — the vault may be on
+  // another machine).
+  const runner = path.join(CLAUDE_DIR, "bin", "qualia-loop.sh");
+  const runnerBody = [
+    "#!/usr/bin/env bash",
+    "# qualia-loop.sh — nightly memory-loop runner (installed by qualia-framework).",
+    "# One loop: flush → ingest ERP team reports → export team wiki. Each step is",
+    "# non-fatal so a single failure does not block the others.",
+    "set -u",
+    `LOG="${logFile}"`,
+    'echo "[$(date -Iseconds)] qualia-loop start" >> "$LOG"',
+    `node "${binFlush}" >> "$LOG" 2>&1 || echo "[$(date -Iseconds)] flush failed" >> "$LOG"`,
+    `if [ -f "${ingest}" ]; then python3 "${ingest}" >> "$LOG" 2>&1 || echo "[$(date -Iseconds)] ingest failed" >> "$LOG"; else echo "[$(date -Iseconds)] ingest skipped (no vault scripts)" >> "$LOG"; fi`,
+    `if [ -f "${exportWiki}" ]; then python3 "${exportWiki}" >> "$LOG" 2>&1 || echo "[$(date -Iseconds)] export failed" >> "$LOG"; else echo "[$(date -Iseconds)] export skipped (no vault scripts)" >> "$LOG"; fi`,
+    'echo "[$(date -Iseconds)] qualia-loop done" >> "$LOG"',
+    "",
+  ].join("\n");
+
+  const serviceBody = [
+    "[Unit]",
+    "Description=Qualia memory loop (flush → ingest ERP → export team wiki)",
+    "",
+    "[Service]",
+    "Type=oneshot",
+    `Environment=QUALIA_MEMORY=${vaultRoot}`,
+    `ExecStart=/usr/bin/env bash ${runner}`,
+    "",
+  ].join("\n");
+
+  const timerBody = [
+    "[Unit]",
+    "Description=Nightly Qualia memory loop",
+    "",
+    "[Timer]",
+    "OnCalendar=*-*-* 03:00:00",
+    "Persistent=true",
+    "",
+    "[Install]",
+    "WantedBy=timers.target",
+    "",
+  ].join("\n");
+
+  try {
+    if (!fs.existsSync(unitDir)) fs.mkdirSync(unitDir, { recursive: true });
+    fs.writeFileSync(runner, runnerBody);
+    try { fs.chmodSync(runner, 0o755); } catch {}
+    fs.writeFileSync(path.join(unitDir, "qualia-loop.service"), serviceBody);
+    fs.writeFileSync(path.join(unitDir, "qualia-loop.timer"), timerBody);
+    ok("unit files written (~/.config/systemd/user/qualia-loop.{service,timer})");
+  } catch (e) {
+    warn(`memory-loop unit files — ${e.message}`);
+    return;
+  }
+
+  // Only enable if systemctl --user is usable. On non-systemd hosts or where
+  // there's no user bus (e.g. CI), print manual fallback and move on.
+  const probe = spawnSync("systemctl", ["--user", "--version"], { stdio: "ignore" });
+  if (probe.status !== 0) {
+    log(`${DIM}systemctl --user unavailable — units written but not enabled.${RESET}`);
+    log(`${DIM}Manual run:${RESET} ${TEAL}node ${binFlush}${RESET}`);
+    log(`${DIM}Or schedule via cron:${RESET} ${TEAL}0 3 * * * bash ${runner}${RESET}`);
+    return;
+  }
+
+  const reload = spawnSync("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+  const enable = spawnSync("systemctl", ["--user", "enable", "--now", "qualia-loop.timer"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (reload.status === 0 && enable.status === 0) {
+    ok("nightly timer enabled (qualia-loop.timer · 03:00 daily)");
+  } else {
+    log(`${DIM}timer written but enable failed — run manually:${RESET}`);
+    log(`  ${TEAL}systemctl --user daemon-reload && systemctl --user enable --now qualia-loop.timer${RESET}`);
+    if (enable.stderr) log(`${DIM}${enable.stderr.trim().split("\n").slice(0, 2).join(" ")}${RESET}`);
+  }
+}
+
 // ─── Main ────────────────────────────────────────────────
 async function main() {
   // Piped install: drain stdin once up front. Avoids EOF/'close' racing
@@ -1479,10 +1584,19 @@ Client-specific preferences, design choices, and requirements. Loaded by \`/qual
   fs.writeFileSync(settingsTmp, JSON.stringify(settings, null, 2));
   fs.renameSync(settingsTmp, settingsPath);
 
-  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, git-guardrails, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard");
+  ok("Hooks: session-start, auto-update, branch-guard, pre-push, migration-guard, deploy-gate, git-guardrails, stop-session-log, fawzi-approval-guard, vercel-account-guard, env-empty-guard, supabase-destructive-guard, secret-guard, task-write-guard, pre-compact, usage-capture");
   ok("Status line + spinner configured");
   ok("Environment variables + permissions");
 
+  // ─── Memory loop scheduler (systemd --user timer) ─────────
+  // Installs ONE nightly timer: knowledge-flush → ingest-erp-reports →
+  // export-team-wiki. Idempotent; safe-skips when systemctl --user is absent.
+  try {
+    installMemoryTimer();
+  } catch (e) {
+    warn(`memory-loop scheduler — ${e.message}`);
+  }
+
   // ─── Codex (optional second target) ──────────────────────
   if (installCodexTarget) {
     await installCodex(member, target, employeeMode);
@@ -1572,6 +1686,12 @@ function printSummary({ member, target, claudeInstalled }) {
   console.log(
     `  ${DIM}              performance audit. Opt out:${RESET} ${TEAL}erp.capturePrompts=false${RESET} ${DIM}in ~/.claude/.qualia-config.json${RESET}`
   );
+  // New employees get the milestone mental model up front — OWNERs already
+  // know how the flow works, so we skip the card for them to avoid noise.
+  if (member.role !== "OWNER") {
+    try { ui.onboard(member.name); } catch {}
+  }
+
   console.log("");
   console.log(`  ${DIM2}${RULE}${RESET}`);
   console.log(`  ${TEAL}${BOLD}Welcome to the future with Qualia.${RESET}`);
@@ -1796,6 +1916,10 @@ async function installCodex(member, target, employeeMode = false) {
     const referencesSrc = path.join(FRAMEWORK_DIR, "references");
     if (fs.existsSync(referencesSrc)) {
       copyTreeTransform(referencesSrc, path.join(CODEX_DIR, "qualia-references"), codexText);
+      // Canonical copy: ${QUALIA_REFERENCES} resolves to <home>/references on both
+      // runtimes, and qualia-scope reads references/archetypes/*.md from it. Mirror
+      // the whole tree (incl. nested archetypes/) so the token resolves on Codex.
+      copyTreeTransform(referencesSrc, path.join(CODEX_DIR, "references"), codexText);
     }
     const knowledgeSrc = path.join(FRAMEWORK_DIR, "templates", "knowledge");
     const knowledgeDest = path.join(CODEX_DIR, "knowledge");

package/bin/knowledge-flush.js

@@ -6,10 +6,19 @@
 // memory loop end-to-end:
 //
 //   Stop hook (auto, every turn) → <install-home>/knowledge/daily-log/{date}.md
-//   THIS SCRIPT (weekly cron)    → spawns the installed agent CLI
-//   flush prompt                 → promotes raw → curated tier
+//   THIS SCRIPT (nightly timer)  → spawns the installed agent CLI
+//   flush prompt                 → promotes raw → curated tier (~/.claude/knowledge)
+//                                → ALSO dual-writes durable concepts into the vault
+//                                  at ${QUALIA_MEMORY:-~/qualia-memory}/wiki/sessions/concepts/
 //   bin/knowledge.js (every spawn) → reads index.md → reaches the right file
 //
+// PROMOTE step (the agreed one-loop contract, replacing Cole's compile.py):
+// after the agent CLI flush succeeds, this script reads the freshly-promoted
+// curated concepts and dual-writes a deterministic markdown file per concept
+// into the qualia-memory vault. The vault is resolved from $QUALIA_MEMORY (else
+// ~/qualia-memory); if the vault dir does not exist the dual-write is skipped
+// gracefully with a logged notice — it never crashes the flush.
+//
 // Usage:
 //   node ~/.claude/bin/knowledge-flush.js               # 7-day flush
 //   node ~/.claude/bin/knowledge-flush.js --days 14     # custom window
@@ -50,6 +59,24 @@ const KNOWLEDGE_DIR = path.join(QUALIA_HOME, "knowledge");
 const DAILY_DIR = path.join(KNOWLEDGE_DIR, "daily-log");
 const LOG_FILE = path.join(QUALIA_HOME, ".qualia-flush.log");
 
+// ── Vault dual-write target (PROMOTE step of the one-loop contract) ──────
+// Resolve the qualia-memory vault from $QUALIA_MEMORY, else ~/qualia-memory.
+// Durable concepts promoted into the curated tier are mirrored into
+// <vault>/wiki/sessions/concepts/ so the brain (qualia-memory) and the
+// framework-local curated tier stay in sync. If the vault dir is absent the
+// mirror is skipped gracefully (logged "vault-absent"), never crashing.
+function vaultRoot() {
+  return process.env.QUALIA_MEMORY || path.join(HOME, "qualia-memory");
+}
+const VAULT_ROOT = vaultRoot();
+const VAULT_CONCEPTS_DIR = path.join(VAULT_ROOT, "wiki", "sessions", "concepts");
+
+// The curated concept sources to mirror into the vault. Top-level curated
+// files (promoted by the agent flush) plus anything the flush wrote under
+// knowledge/concepts/. Deterministic so each run overwrites idempotently.
+const CURATED_CONCEPT_FILES = ["learned-patterns.md", "common-fixes.md", "client-prefs.md"];
+const CURATED_CONCEPTS_SUBDIR = path.join(KNOWLEDGE_DIR, "concepts");
+
 const _start = Date.now();
 
 function logEvent(event) {
@@ -65,6 +92,82 @@ function logEvent(event) {
   } catch {}
 }
 
+// ── PROMOTE → vault dual-write ──────────────────────────────────────────
+// Mirror the curated concept tier into the qualia-memory vault. Each curated
+// source becomes a deterministic file at <vault>/wiki/sessions/concepts/ —
+// stable name (slug of the source path) so re-runs overwrite idempotently
+// rather than accumulating duplicates. Returns a structured summary for the
+// flush log. NEVER throws — a vault-write failure must not fail the flush.
+function dualWriteVault() {
+  // Resolve the set of curated concept files to mirror.
+  const sources = [];
+  for (const f of CURATED_CONCEPT_FILES) {
+    const p = path.join(KNOWLEDGE_DIR, f);
+    if (fs.existsSync(p)) sources.push({ abs: p, slug: f.replace(/\.md$/, "") });
+  }
+  try {
+    if (fs.existsSync(CURATED_CONCEPTS_SUBDIR)) {
+      for (const f of fs.readdirSync(CURATED_CONCEPTS_SUBDIR)) {
+        if (!f.endsWith(".md")) continue;
+        sources.push({
+          abs: path.join(CURATED_CONCEPTS_SUBDIR, f),
+          slug: `concept-${f.replace(/\.md$/, "")}`,
+        });
+      }
+    }
+  } catch {}
+
+  if (sources.length === 0) {
+    return { event_detail: "no-curated-concepts", written: 0 };
+  }
+
+  // Vault must exist on disk; if not, skip gracefully (the brain may live on a
+  // different machine than the one running the timer).
+  if (!fs.existsSync(VAULT_ROOT)) {
+    return { event_detail: "vault-absent", vault: VAULT_ROOT, written: 0 };
+  }
+
+  let written = 0;
+  const failures = [];
+  try {
+    if (!fs.existsSync(VAULT_CONCEPTS_DIR)) {
+      fs.mkdirSync(VAULT_CONCEPTS_DIR, { recursive: true });
+    }
+  } catch (e) {
+    return { event_detail: "vault-mkdir-failed", vault: VAULT_CONCEPTS_DIR, error: e.message, written: 0 };
+  }
+
+  const stamp = new Date().toISOString();
+  for (const src of sources) {
+    try {
+      const body = fs.readFileSync(src.abs, "utf8").trim();
+      if (!body) continue;
+      // Deterministic filename: slug of the curated source. Idempotent overwrite.
+      const safeSlug = src.slug.replace(/[^a-z0-9._-]/gi, "-").toLowerCase();
+      const dest = path.join(VAULT_CONCEPTS_DIR, `${safeSlug}.md`);
+      const frontMatter = [
+        "---",
+        "source: qualia-framework/knowledge-flush",
+        `promoted_from: knowledge/${path.relative(KNOWLEDGE_DIR, src.abs)}`,
+        `last_promoted: ${stamp}`,
+        "share: team",
+        "---",
+        "",
+      ].join("\n");
+      fs.writeFileSync(dest, frontMatter + body + "\n");
+      written++;
+    } catch (e) {
+      failures.push(`${src.slug}: ${e.message}`);
+    }
+  }
+  return {
+    event_detail: "vault-mirrored",
+    vault_dir: VAULT_CONCEPTS_DIR,
+    written,
+    failures: failures.length ? failures : undefined,
+  };
+}
+
 function which(cmd) {
   // Cross-platform `which`. Returns the first PATH match or null.
   // We don't shell out to `which` itself because it doesn't exist on Windows
@@ -109,6 +212,18 @@ function dailyLogHasRecentEntries(windowDays) {
   return false;
 }
 
+// When required as a module (tests), export the pure helpers and stop here —
+// do not spawn the agent CLI or touch process exit.
+if (require.main !== module) {
+  module.exports = {
+    dualWriteVault,
+    vaultRoot,
+    VAULT_CONCEPTS_DIR,
+    CURATED_CONCEPT_FILES,
+  };
+  return;
+}
+
 // ── Preflight ────────────────────────────────────────────
 // Per-host facts (which CLI, how to invoke it) come from the adapter — the one
 // place runtime differences live. See bin/host-adapters.js.
@@ -171,6 +286,11 @@ if (status !== 0) {
   process.exit(1);
 }
 
+// Success: the curated tier has just been (re)written by the agent flush.
+// PROMOTE step — mirror the durable concepts into the qualia-memory vault.
+const vault = dualWriteVault();
+logEvent({ event: "vault-dual-write", ...vault });
+
 // Success: parse stdout for the skill's summary line if present, else log
 // the full output tail.
 const summaryMatch = stdout.match(/⬢ Flushed daily-log .+/);
@@ -178,6 +298,7 @@ logEvent({
   event: "ok",
   prompt,
   summary: summaryMatch ? summaryMatch[0] : stdout.split("\n").slice(-3).join(" | "),
+  vault: vault.event_detail,
 });
 
 // Echo the user-facing summary to stdout so cron logs / interactive runs