musememory 3.2.0 → 3.4.0

package/.agents/standards/anti-patterns.md

@@ -0,0 +1,116 @@
+# 🚫 Negative Constraints & Architectural Anti-Patterns
+
+> **Operating Invariant**: Negative constraints are as critical as positive rules. Preventing known architectural failure modes and speculative complexity cuts agent hallucinations and regressions by over 90%.
+
+---
+
+## 1. Universal Agent Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Strict Invariant |
+| :--- | :--- | :--- |
+| **Speculative Architecture** | Agents create unused folders, abstractions, or "future-proofing" files that add maintenance debt. | Implement strictly what is currently requested. **Current Needs > Future Possibilities (YAGNI)**. |
+| **Rogue Package Installation** | Casually running `npm install <pkg>` for minor utilities that modern runtimes provide natively. | All production dependencies are declared and reviewed; this repository ships three (`@modelcontextprotocol/sdk`, `ajv`, `js-yaml`). Never install Axios, Lodash, or Moment. Verify with the `updateagents` skill's `--stack-guard` check against the Golden Stack Fence. |
+| **Silent Error Swallowing** | Using empty `catch {}` blocks or returning default mocks when APIs fail. | Fail fast and loud. Log structured error details and exit cleanly with diagnostic codes. |
+| **Synthetic Artifact Leakage** | Leaving proprietary IDE markers (`ORCA_RICH_MD`, Cursor, Windsurf wrappers) in commits. | Always unwrap and decode to raw markdown; backtick template tokens (`<issue-id>`). |
+| **Context Window Overload** | Ingesting massive directories or entire logs into LLM context instead of surgical lookups. | Use targeted search/read tools to extract minimal verifiable evidence. Prefer `rg`/`fd`/`jq` where installed; fall back to the harness's grep/glob tools, which need no install. |
+
+---
+
+## 2. Frontend & UI Anti-Patterns
+
+- ❌ **`useEffect` Data Fetching**: Never use raw `useEffect` hooks for remote data fetching in React 19 / modern Next.js. Use Server Components, Actions, or TanStack Query.
+- ❌ **Cumulative Layout Shifts (CLS)**: Never render remote images or dynamic banners without explicit aspect-ratio or dimensions.
+- ❌ **Inline CSS Magic Numbers**: Avoid arbitrary pixel values (e.g. `margin: 17px`). Use locked DTCG spacing tokens (`space-4`, `space-6`) and OKLCH palettes.
+- ❌ **Client-Side Secret Ingestion**: Never import environment variables prefixed with database URLs or private keys into client components.
+
+### 🎭 Anti-Delta: Client-Side Data Fetching vs Server Component
+```tsx
+// ❌ DON'T: Client-side useEffect data fetching (Race conditions & waterfalls)
+function UserList() {
+  const [users, setUsers] = useState([]);
+  useEffect(() => {
+    fetch("/api/users").then((res) => res.json()).then(setUsers);
+  }, []);
+  return <div>{users.map((u) => <div key={u.id}>{u.name}</div>)}</div>;
+}
+
+// ✅ DO: React Server Component (Direct, type-safe, zero client JS waterfall)
+async function UserList() {
+  const users = await db.query.users.findMany();
+  return <div>{users.map((u) => <div key={u.id}>{u.name}</div>)}</div>;
+}
+```
+
+### 🖼️ Anti-Delta: Unsized Image vs Layout-Stable Media
+```tsx
+// ❌ DON'T: Unsized remote images causing layout jumps (CLS)
+<img src={heroUrl} alt="Hero banner" className="w-full" />
+
+// ✅ DO: Explicit dimensions, aspect ratio, and priority hints
+<Image
+  src={heroUrl}
+  alt="Hero banner"
+  width={1200}
+  height={630}
+  priority
+  className="w-full aspect-[1200/630] object-cover"
+/>
+```
+
+---
+
+## 3. Backend & API Anti-Patterns
+
+- ❌ **Unvalidated Request Payloads**: Never process `req.body` or query params without a validating Zod schema.
+- ❌ **N+1 Database Queries**: Avoid executing database queries inside map loops. Use batch queries or join loaders.
+- ❌ **Raw SQL String Interpolation**: Always use parameterized queries or type-safe ORM drivers (Drizzle, Kysely, Prisma).
+- ❌ **Inconsistent Error Envelopes**: APIs must return predictable envelopes: `{ success: false, error: { code, message } }`.
+
+### 🛡️ Anti-Delta: Unvalidated Payload vs Structured Zod Envelope
+```ts
+// ❌ DON'T: Unvalidated request parsing & silent mock fallback
+export async function POST(req: Request) {
+  try {
+    const data = await req.json();
+    return Response.json({ ok: true, data });
+  } catch {
+    return Response.json({ ok: false }); // Swallowed error, untyped payload
+  }
+}
+
+// ✅ DO: Strict Zod validation & predictable envelope
+const PayloadSchema = z.object({
+  email: z.string().email(),
+  plan: z.enum(["starter", "pro"]),
+});
+
+export async function POST(req: Request) {
+  const parsed = PayloadSchema.safeParse(await req.json());
+  if (!parsed.success) {
+    return Response.json(
+      { success: false, error: { code: "VALIDATION_FAILED", details: parsed.error.flatten() } },
+      { status: 400 },
+    );
+  }
+  const result = await provisionAccount(parsed.data);
+  return Response.json({ success: true, data: result }, { status: 201 });
+}
+```
+
+### 🗄️ Anti-Delta: SQL Injection vs Parameterized Queries
+```ts
+// ❌ DON'T: Raw SQL string interpolation (SQL Injection vulnerability)
+const user = await db.execute(`SELECT * FROM users WHERE id = '${userId}'`);
+
+// ✅ DO: Parameterized queries or type-safe ORM schema
+const user = await db.query.users.findFirst({ where: eq(users.id, userId) });
+```
+
+---
+
+## 4. Verification Gate Before Commit
+
+Before claiming any task complete:
+1. Did you add an unapproved dependency? Production dependencies are `@modelcontextprotocol/sdk`, `ajv` and `js-yaml` only — anything else is a stack change, not a fix. Run the `updateagents` skill's `--stack-guard` to check the Golden Stack Fence.
+2. Are the gates passing? Run `bun test`, `bunx tsc --noEmit`, `bun run claims:check` and `bun run docs:check` — the same set CI runs. There is no `lint` script; do not invent one.
+3. Are there any plaintext secrets or tokens exposed? Run `memory scan-secrets .`. It reports a non-zero count on this repository because 56 test fixtures deliberately embed fake credentials — treat a **new** finding in non-test code as a real leak.

package/.agents/standards/boundary-governance.md

@@ -0,0 +1,52 @@
+# 🛡️ Boundary Governance & Quality Assurance Standard
+
+> **Nexus Head Gate**: Mandatory verification protocol for all agency deliverables, code changes, and infrastructure mutations.
+
+---
+
+## 1. The 5 Boundary Checkpoints
+
+Before any branch is merged, deliverable signed off, or change deployed, the reviewing agent must verify each checkpoint:
+
+```mermaid
+flowchart LR
+    CP1[1. Goal] --> CP2[2. Facts]
+    CP2 --> CP3[3. Method]
+    CP3 --> CP4[4. Proof]
+    CP4 --> CP5[5. Boundaries]
+```
+
+### Checkpoint 1: Clear Intent & Scoped Goal
+- What exact outcome is expected?
+- Does the change directly serve the user's explicit request without scope creep?
+- Refuse unsolicited refactoring or aesthetic redesigns.
+
+### Checkpoint 2: Grounded Facts & Evidence
+- What are the verified facts of the current system state?
+- Are assumptions backed by real file contents, CLI outputs, and logs?
+- Never rely on assumptions or hallucinated APIs.
+
+### Checkpoint 3: Minimal & Intentional Method
+- Is this the minimum viable change required to achieve the goal?
+- Does it respect established patterns in the repository?
+- Does it preserve backward compatibility and existing configuration?
+
+### Checkpoint 4: Overwhelming Proof
+- Do tests pass completely (`bun test`, test runner output)?
+- Does the static type-checker report zero errors (`bunx tsc --noEmit`)? There is no `lint` script in this repository — do not invent one.
+- Has evidence been recorded in commit verification notes?
+
+### Checkpoint 5: Strict Boundaries & Blast Radius
+- Tenant isolation: Ensure no cross-client data leakage.
+- Secret protection: Guarantee zero API keys, tokens, or environment values are exposed.
+- Path portability: Ensure paths use `$HOME`, `~`, or relative project roots; no hardcoded host paths.
+
+---
+
+## 2. Rejection Criteria
+
+Changes failing ANY of the following must be immediately rejected:
+1. Hardcoded host or local developer paths in templates or shipped files.
+2. Committed secrets, unmasked environment variables, or private tokens.
+3. Failing automated tests or unhandled runtime promises.
+4. Monolithic multi-feature diffs combining unrelated functional changes.

package/.agents/standards/frontend-astro.md

@@ -1,6 +1,6 @@
 # 🚀 Astro Frontend Engineering Standards
 
-> **Runtime Target**: Astro v7.3.x · Bun / Node runtime · TypeScript Strict
+> **Runtime Target**: Astro v7.4.7 · Bun / Node runtime · TypeScript Strict
 > **Applies to**: `apps/website/` — the Muse Memory marketing and documentation site.
 
 ---
@@ -130,3 +130,5 @@ bun run --cwd apps/website scripts/audit-visual.ts
 bun test                    # the whole repository suite
 bunx tsc --noEmit           # type check
 ```
+
+> Build note: the site runs the Astro CLI through Node (`apps/website/scripts/astro.mjs`); Bun’s CJS/ESM interop rejects Astro’s `cookie` import.

package/.agents/standards/language-policy.md

@@ -0,0 +1,115 @@
+# Language Policy — Universal English Working Language & Script Guard
+
+> **Scope:** every agent working in this repository, and every project scaffolded from this template.
+> **Authority:** mandatory, not optional background reading. Routed from `AGENTS.md` (Working rules → Evidence and language).
+
+## 1. The Working Language Rule
+
+English is the universal working language across all projects and agents:
+
+- **Universal scope**: Agent responses, internal chain-of-thought/reasoning, code, identifiers, comments, commits, pull requests, specifications, and documentation are strictly written in English; **narration between tool calls counts as output**.
+- **An English final answer does not excuse non-English narration earlier in the same turn.** A model that treats only its closing summary as "the answer" will narrate in the source language and believe it complied.
+- **Input language never changes output language**: A reference site, documentation page, screenshot, PDF, video, audio file, chat message, or media asset may be provided in Japanese, Chinese, Korean, Arabic, Hindi, Cyrillic, Hebrew, Thai, Devanagari, or any other script. Read it, extract what is needed, translate the information, and respond and code in English.
+- **Translate, never mirror**: Quote non-English source material only when the exact original wording matters, and always provide the English translation immediately beside it.
+- **Never switch language to match the user**: Never switch languages to match the conversational language of the user or prompt, including informal chat, short replies, single words, greetings, or acknowledgments.
+
+---
+
+## 2. Site-Content Carve-Out
+
+- **Public copy**: Public site copy, user interfaces, and marketing copy remain in English unless the user explicitly approves a localized locale or multilingual target in project specifications.
+- **Proper nouns & cultural terms**: Proper nouns (people, places, brands), specific culinary dish names, and localized prices with native currency symbols may retain their original script where semantically and culturally appropriate.
+
+---
+
+## 3. Why a Written Rule Is Not Enough
+
+A language model reading a non-English reference can inadvertently mirror or carry non-English script into replies, comments, and committed files without noticing. Prompt instructions alone cannot eliminate attention bias or accidental script leakage.
+
+Because instructions alone cannot prevent this failure mode, this policy is paired with an automated mechanical guard.
+
+---
+
+## 4. Enforcement Pattern (Stack-Agnostic)
+
+Enforcement runs through **the project's own test runner** (e.g. `bun test`, `npm test`, `pytest`, `cargo test`, `go test`), not a specific vendor tool:
+
+- **Scan scope**: The guard scans all tracked source code, configuration files, and documentation.
+- **Detected scripts**: The guard checks for non-English scripts, including:
+  - CJK Unified Ideographs (Chinese, Japanese Kanji)
+  - Japanese Hiragana & Katakana
+  - Korean Hangul
+  - Cyrillic
+  - Arabic
+  - Hebrew
+  - Thai
+  - Devanagari
+  - Fullwidth ASCII and punctuation characters
+- **Failure output**: On encountering unlisted non-English script, the test runner fails with the exact `file`, `line number`, and `script name`.
+
+### Contract self-check assertions
+
+Each project's test runner should assert the policy contract itself, not only scan source files. At minimum, assert that:
+
+- `AGENTS.md` contains the policy heading and the phrase `narration between tool calls` (case-insensitive).
+- `AGENTS.md` contains an input-language clause (phrase: `input language never changes`, case-insensitive).
+- This standard contains a `Known limit` heading.
+- This standard states that narration counts as output.
+
+### Hook Note
+
+Where the project has a pre-commit hook (or CI workflow), it runs the same guard before commits are accepted so that a language policy violation cannot enter version history.
+
+---
+
+## Known limit
+
+The guard reads files. It cannot see an agent's streaming narration between tool calls, so a non-English sentence in chat passes every automated check while still breaking the policy. Only the rule text covers that surface, which is why the narration clause is stated explicitly rather than assumed to follow from "output is English".
+
+Do not describe the guard as complete enforcement. Claiming coverage it does not have is worse than the gap itself, because it stops anyone from looking.
+
+---
+
+## If you catch yourself narrating in another language
+
+Switch to English on the next sentence and continue. Do not restate the previous sentence in English — the reader already saw it, and repeating it draws more attention to the slip than moving on. Do not silently translate the remainder of a paragraph; start the thought again in English.
+
+---
+
+## 5. Explicit Allowlist
+
+The mechanical guard respects an explicit allowlist for legitimate non-ASCII usage in English text:
+
+1. **Typography and mathematical symbols**:
+   - Em dashes (`—`) and en dashes (`–`)
+   - Curly quotes and apostrophes (`“`, `”`, `‘`, `’`)
+   - Middle dots (`·`), bullets, and section signs (`§`)
+   - Arrows (`→`, `←`, `↑`, `↓`, `↔`)
+   - Comparison and math operators (`≥`, `≤`, `×`, `÷`, `°`, `±`, `≠`, `≈`)
+   - Currency symbols (`$`, `€`, `£`, `₹`, `¥`)
+   - Box-drawing characters and approved diagrams
+   - Standard Unicode emoji where permitted by project style
+2. **Accented Latin for genuine English usage**:
+   - Common loanwords with diacritics (e.g., `café`, `naïve`, `résumé`, `cliché`)
+   - Accented proper nouns and geographic names (e.g., `São Paulo`, `München`, `Beyoncé`)
+3. **Byte-identical vendor tokens & protocol fixtures**:
+   - Vendor token markers, cryptographic digests, protocol payload signatures, or upstream API mock fixtures that must stay byte-identical to an external specification.
+
+---
+
+## 6. If the Guard Fails
+
+When the test runner or pre-commit hook reports a language violation:
+
+1. **Read the report**: Note the reported file, line number, and script name.
+2. **Translate**: Read the offending line and translate the non-English characters to English.
+3. **Evaluate necessity**: Retain the original script only if it represents an approved proper noun, culturally specific dish name, or byte-identical vendor token.
+4. **Allowlist with documentation**: If the token must be preserved, add that token or file path to the project guard's allowlist accompanied by a comment explaining why its exact bytes matter.
+
+---
+
+## See Also
+
+- `AGENTS.md` — Working rules (Rule 6: Evidence and language).
+- `.agents/standards/anti-patterns.md` — Negative constraints and anti-patterns.
+- `.agents/standards/execution-kernel.md` — Refactoring discipline and verification gates.

package/.agents/standards/memory-context.md

@@ -36,7 +36,7 @@ The `./.memory` directory at the project root is the local persistent memory sto
 
 ---
 
-## 3. Creed Native Context & Canonical LifeOS Sources
+## 3. Creed Native Context & Canonical Memory Sources
 
 Agents reference these canonical sovereign Muse Memory sources:
 

package/.agents/standards/security-vibeguard.md

@@ -1,4 +1,4 @@
-# 🛡️ LifeOS Vibeguard & Core Safety Protocol
+# 🛡️ Vibeguard Security & Core Safety Protocol
 
 All agents operating in this workspace must strictly follow these security and system safety guardrails:
 

package/.agents/standards/test-failure-audit.md

@@ -0,0 +1,46 @@
+# Test-Failure Audit — Self-Triage on Repeated Red
+
+> **Scope:** every agent working in this repository, and every project scaffolded from this template.
+> **Authority:** routed from `AGENTS.md` (Working rules → Test-Failure Audit).
+
+## The failure this rule exists to prevent
+
+An agent ran the same failing test three times, each time applying a
+symptom-level tweak, and reported "still investigating" without ever
+checking whether its own previous change had landed, whether the test was
+even exercising the new code, or whether the failure was a pre-existing
+flaky/environment issue. The root cause is that repeated red was treated as
+"try again" instead of as a signal to audit the agent's own outputs.
+
+## The rule
+
+When **the same test (or the same failure signature) fails on two or more
+consecutive runs** during one task:
+
+1. **Stop changing code.** No further edits until the audit below completes.
+2. **Run the self-audit** over the agent's own outputs for this task:
+   - Did the previous edit actually land on disk? (`git diff`, `git show --stat HEAD`)
+   - Is the test even exercising the changed code path? (trace the call site)
+   - Is the failure pre-existing on the clean tree? (`git stash` → run test → `git stash pop`)
+   - Is it environment/flaky (timeout, network, sandbox)? Check exit codes and logs.
+   - Did a guard get widened or a test get weakened? (re-read the test as the spec)
+3. **Triage** the root cause into one of: (a) my change broke a contract,
+   (b) pre-existing/inherited failure, (c) flaky/environment, (d) wrong
+   assumption about the input. Record the triage verdict in the report.
+4. **Only then** apply a fix targeted at the triaged root cause, and re-run
+   the full suite (not just the one test).
+5. **Report** the audit: the runs attempted, the triage verdict, the fix, and
+   the final verification command + exit code.
+
+## Verdict names
+
+- `SELF-AUDIT COMPLETE` — audit ran, triage recorded, fix applied, suite green.
+- `SELF-AUDIT PENDING` — red persists; no fix applied yet; do not claim progress.
+
+Never report "still investigating" without the audit above.
+
+## See also
+
+- `AGENTS.md` — Working rules (Test-Failure Audit entry).
+- `.agents/standards/execution-kernel.md` — systematic root-cause discipline.
+- `.agents/standards/workflows.md` — the verification gates this audit re-enters.

package/.agents/standards/visual-inspection.md

@@ -0,0 +1,31 @@
+# 👁️ Visual Context & Multimodal UI Verification
+
+> **Operating Invariant**: For UI, styling, and design work, verbal claims of completion are insufficient. Agents must verify rendered DOM appearance, responsiveness, and contrast using visual artifacts or layout assertions.
+
+---
+
+## 1. Visual Verification Protocol
+
+When creating or modifying frontend components, landing pages, or user interfaces:
+1. **Rendered Layout Verification**:
+   - Verify layout stability and responsive behavior across viewport breakpoints:
+     - Mobile: `390px` (iPhone baseline)
+     - Tablet: `768px` (iPad baseline)
+     - Desktop: `1280px` (Standard desktop)
+2. **Contrast & Accessibility (A11y)**:
+   - All body text must maintain a minimum WCAG AA contrast ratio of **4.5:1** against backgrounds.
+   - Large headers (>24px) must maintain at least **3:1** contrast.
+   - Interactive elements must possess clear `:focus-visible` outlines with at least 2px offset.
+3. **Screenshot Storage Invariant**:
+   - Verified UI screenshots, component mocks, and visual error captures live strictly inside `./.agents/brand/screenshots/`.
+   - Never commit raw uncompressed images to the root repository or documentation tree.
+
+---
+
+## 2. Multimodal Debugging Workflow
+
+If an agent encounters a layout bug, visual regression, or misaligned element:
+1. **Capture**: Save the rendered viewport or error capture to `./.agents/brand/screenshots/[name]-[timestamp].png`.
+2. **Inspect**: Ingest the image file into multimodal context or analyze computed CSS properties.
+3. **Remediate**: Address the specific box-model or flex/grid constraint causing the alignment flaw.
+4. **Re-Verify**: Confirm that zero layout shifts or visual clipping remain.

package/README.md

@@ -439,10 +439,13 @@ curl -fsSL https://raw.githubusercontent.com/harshsinghmp/musememory/main/script
 ```
 
 #### What `memory upgrade` automatically handles:
-1. **Package Manager Auto-Detection**: Detects whether your workstation runs `bun`, `npm`, `pnpm`, or `yarn` and pulls the latest published binary.
-2. **Self-Healing Storage Repair**: Recovers missing `.memory/`, `CURRENT.md` constraints, or `USER.md` persona files if corrupted or deleted.
-3. **Coding Agent Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, and the rest of the mainstream field) and auto-wires them with zero permissions.
-4. **AST Symbol Graph Re-Indexing**: Re-synchronizes CodeGraph/Graphify symbol caches under `.memory/graph-symbols.json`.
+1. **Package Manager Auto-Detection**: Detects whether your workstation runs `bun`, `npm`, `pnpm`, or `yarn` and updates to the latest release without redundant downgrades.
+2. **Global vs. Per-Project Scoping**:
+   - **Per-Project (`memory upgrade`)**: Operates on `./.memory/`. Repairs local constraints (`CURRENT.md`), project user persona overrides (`USER.md`), re-indexes AST code symbols via CodeGraph/Graphify, and installs Git pre-commit transcript harvesting hooks.
+   - **Global (`memory upgrade --global`)**: Operates on `~/.memory/`. Re-aligns sovereign master profiles (`USER.md`), validates machine-wide constraints, updates global SQLite schemas, heals `~/.local/bin` symlinks, and auto-wires all detected agent platforms workstation-wide.
+3. **Self-Healing Storage Repair**: Recovers missing `.memory/`, `CURRENT.md` constraints, or `USER.md` persona files if corrupted or deleted.
+4. **Coding Agent Re-Discovery**: Scans for newly installed coding agents (Cursor, Claude Code, Windsurf, OpenCode, Codex, Gemini CLI, Hermes, and the rest of the mainstream field) and auto-wires them with zero permissions.
+5. **AST Symbol Graph Re-Indexing**: Re-synchronizes CodeGraph/Graphify symbol caches under `.memory/graph-symbols.json`.
 
 ---
 

package/claims.json

@@ -1,7 +1,7 @@
 {
   "$comment": "Generated by scripts/generate-claims.ts. Do not hand-edit: test/marketing_claims.test.ts re-derives every value from src/ and fails on drift.",
-  "version": "3.2.0",
-  "mcpTools": 115,
+  "version": "3.4.0",
+  "mcpTools": 126,
   "mcpProfiles": 7,
   "agentPlatforms": 52,
   "migratorProviders": 30,
@@ -14,8 +14,8 @@
     "networkMillis": 300
   },
   "tests": {
-    "count": 1441,
-    "assertions": 6654,
-    "files": 217
+    "count": 1592,
+    "assertions": 7597,
+    "files": 252
   }
 }