naive-framework 0.0.0-stage → 0.1.0

package/evidence/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "skill_name": "everything-ecosystem",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I have a project called another project. It's an organizational structure visualizer — it maps how companies, ecosystems, and institutions are structured. Right now it has an Astro-based web app (org-viz-app) that visualizes Google/Alphabet's corporate structure as a tree. It uses Neo4j for graph data. I also think this tool could be used as an AI-readable source of truth for any company — not just visualizing structure but actually storing and verifying all the entity profiles, decisions, and relationships of an entire ecosystem on something like Git. It could parse conversation logs from Slack or Discord to extract ideas and decisions. I'm not sure if this is just an internal tool for my own ecosystem, or if it's a standalone open source project, or if it could actually be a full product with its own business. Help me figure out what this is.",
+      "expected_output": "The AI should run Discovery Mode and recognize the complexity here — another project has multiple potential classifications depending on strategic intent. It could be (a) an internal tool for the user's own ecosystem, (b) an open source tool, or (c) a full subsidiary with product, brand, and business. The AI should walk through the independence test, note that the product pillar is partially built (the viz app exists), the brand is unintentional, and the business is conceptual at best. It should surface the tension between internal tool and potential product, ask clarifying questions about the user's intent, and produce an entity profile that captures the current state and the potential trajectories. It should also identify related concepts like the communication-to-Git pipeline as potential child entities or features.",
+      "files": [
+        "/sessions/relaxed-kind-albattani/mnt/Documents/projects/<entity>/ENTITY_PROFILE.md"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I want to analyze Tesla's ecosystem. Map out all their major products and entities, classify each one, and show me how they relate to each other. Include things like the vehicles, energy products, Optimus, the Gigafactories, FSD/AI, and Dojo.",
+      "expected_output": "The AI should run Analysis Mode, creating an entity inventory of Tesla's major entities, classifying each (vehicles as products within company, Gigafactories as vertical integration/shared infrastructure, Optimus as a product, FSD as a product, Dojo as internal tool/infrastructure, Solar/Powerwall as products). It should map relationships including horizontal, vertical, and diagonal movements (especially Optimus → SpaceX diagonal). Should produce entity profiles and a relationship map.",
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "I have an open source JavaScript library that I built. It started as just code on GitHub but now it has 2000 stars, a Discord community of 500 people, and companies are asking me about enterprise support. I'm trying to figure out if this is still just an open source tool or if it's becoming something bigger. What should I do with it?",
+      "expected_output": "The AI should recognize this as an entity in transition — it started as an open source tool (product only) but is developing brand (community, recognition) and business (enterprise demand) pillars. It should walk through the independence test, assess each pillar's current state, and help the user decide whether to keep it as an open source tool, develop it into a full company, or something in between. Should produce an entity profile reflecting the current transitional state.",
+      "files": []
+    }
+  ]
+}

package/evidence/evals/harness-evals.json

@@ -0,0 +1,140 @@
+{
+  "skill_name": "everything-ecosystem",
+  "harness_version": "1.0",
+  "description": "Testing suite for the Everything Ecosystem agent environment. Validates that the orchestrator routes correctly, system skills operate on the right files, handoff triggers fire, and end-to-end workflows complete with proper provenance.",
+  "evals": [
+    {
+      "id": 1,
+      "eval_name": "session-calibration-capture",
+      "prompt": "I have a bunch of ideas about a new recipe app I've been thinking about. I just want to get them out of my head.",
+      "expected_output": "Orchestrator detects capture session intent. Routes to idea dump system. Ideas are captured with sequential numbering, idea statuses, and provenance metadata. No push toward classification or routing. Routing mode defaults to batch.",
+      "systems_invoked": ["orchestrator", "idea-dump"],
+      "handoff_files_touched": ["IDEA_DUMP.md"],
+      "assertions": [
+        {"name": "session-type-detected", "check": "Orchestrator identifies this as a capture session"},
+        {"name": "idea-dump-invoked", "check": "Idea dump system skill is read and followed"},
+        {"name": "ideas-numbered", "check": "Each idea gets a sequential number"},
+        {"name": "statuses-assigned", "check": "Each idea gets an idea status"},
+        {"name": "provenance-recorded", "check": "Session date and number recorded as provenance"},
+        {"name": "no-premature-routing", "check": "Ideas are not routed during capture; routing is batch"},
+        {"name": "no-classification-push", "check": "Framework does not push toward entity classification"}
+      ]
+    },
+    {
+      "id": 2,
+      "eval_name": "entity-discovery-new-project",
+      "prompt": "I have a project called BrightPath — it's a mentoring platform that connects experienced professionals with early-career developers. It has a landing page, a matching algorithm, and a Stripe integration. I want to figure out what it is and where it fits.",
+      "expected_output": "Orchestrator detects focused session on entity classification. Routes to entity profiling system (discovery mode). A complete entity profile is produced with all 10 sections populated or given field statuses. Documentation audit identifies gaps. Classification is proposed with reasoning, then confirmed with user.",
+      "systems_invoked": ["orchestrator", "entity-profiling"],
+      "handoff_files_touched": ["ENTITY_PROFILE.md"],
+      "assertions": [
+        {"name": "discovery-mode-invoked", "check": "Entity profiling system is read; discovery mode process followed"},
+        {"name": "all-sections-present", "check": "Entity profile contains all 10 sections"},
+        {"name": "no-blanks", "check": "Every field has a value or a field status"},
+        {"name": "classification-proposed", "check": "Classification is proposed with reasoning before confirmation"},
+        {"name": "pillars-assessed", "check": "Product, brand, and business pillars each have lifecycle stage"},
+        {"name": "doc-audit-included", "check": "Documentation audit section identifies existing vs missing docs"},
+        {"name": "changelog-entry", "check": "Changelog records profile creation date and trigger"}
+      ]
+    },
+    {
+      "id": 3,
+      "eval_name": "idea-graduation-to-spec",
+      "prompt": "Look at the active ideas in the idea dump. Items 147 through 154 are ready to be formalized into a specification document. Graduate them.",
+      "expected_output": "Orchestrator routes to idea dump system to identify the ideas, then to design/spec system to produce the spec document. Ideas are marked as implemented in the dump with provenance trails. Entity profile documentation audit is updated. Entity profile is the last file touched.",
+      "systems_invoked": ["orchestrator", "idea-dump", "entity-profiling"],
+      "handoff_files_touched": ["IDEA_DUMP.md", "spec document (new)", "ENTITY_PROFILE.md"],
+      "assertions": [
+        {"name": "ideas-identified", "check": "Correct ideas (147-154) are read from the dump"},
+        {"name": "spec-created", "check": "A specification document is created with the graduated ideas"},
+        {"name": "spec-implementation-ready", "check": "Spec is structured for handoff to implementation agents"},
+        {"name": "provenance-recorded", "check": "Each idea gets provenance trail showing graduation to spec"},
+        {"name": "ideas-cleared", "check": "Ideas marked as implemented, not left active"},
+        {"name": "audit-updated", "check": "Entity profile documentation audit reflects new spec document"},
+        {"name": "entity-profile-last", "check": "Entity profile is the last file modified in the workflow"}
+      ]
+    },
+    {
+      "id": 4,
+      "eval_name": "diagnostic-ecosystem-health",
+      "prompt": "How is my ecosystem looking? What should I focus on this week?",
+      "expected_output": "Orchestrator routes to diagnostic system. Diagnostic reads all idea dumps, entity profiles, and session log. Surfaces implementation lag, inactivity signals, and clustering if present. Produces strategic recommendations linked to specific session types.",
+      "systems_invoked": ["orchestrator", "diagnostic"],
+      "handoff_files_touched": [],
+      "assertions": [
+        {"name": "diagnostic-invoked", "check": "Diagnostic system skill is read and followed"},
+        {"name": "dumps-analyzed", "check": "All active idea dumps are read and analyzed"},
+        {"name": "entity-profiles-checked", "check": "Entity profiles are read for lifecycle status"},
+        {"name": "lag-detected-if-present", "check": "Implementation lag is identified if ideas are aging"},
+        {"name": "recommendations-actionable", "check": "Recommendations suggest specific session types or actions"},
+        {"name": "skeptical-not-praising", "check": "Diagnostic is tuned toward finding problems, not confirming health"},
+        {"name": "no-structural-changes", "check": "Diagnostic does not create files or modify structure"}
+      ]
+    },
+    {
+      "id": 5,
+      "eval_name": "routing-batch-session-end",
+      "prompt": "I've been dumping ideas all session. Show me what's queued for routing and let me decide where things go.",
+      "expected_output": "Orchestrator routes to routing system. Routing system reads the idea dump and entity hierarchy. Presents a visible queue of ideas with suggested targets. For each idea, proposes a destination dump. Waits for user confirmation before executing routes. Provenance chains recorded for each movement.",
+      "systems_invoked": ["orchestrator", "routing", "idea-dump"],
+      "handoff_files_touched": ["IDEA_DUMP.md (source)", "IDEA_DUMP.md (target)"],
+      "assertions": [
+        {"name": "routing-invoked", "check": "Routing system skill is read and followed"},
+        {"name": "queue-visible", "check": "Queued ideas are presented with suggested targets"},
+        {"name": "targets-justified", "check": "Each suggested target is based on entity hierarchy"},
+        {"name": "user-confirms-before-move", "check": "No ideas are moved without user confirmation"},
+        {"name": "provenance-on-move", "check": "Each routed idea gets provenance chain entries in both dumps"},
+        {"name": "metadata-updated", "check": "Dump metadata updated in both source and target dumps"},
+        {"name": "dump-to-dump-only", "check": "Ideas route to other dumps, never directly to implementation"}
+      ]
+    },
+    {
+      "id": 6,
+      "eval_name": "return-session-recap",
+      "prompt": "Hey, I'm back. What were we working on?",
+      "expected_output": "Orchestrator detects return session. Routes to session management for 'Previously on...' recap. Session management reads the most recent session log entry and delivers the recap in the fun show-name format. Transitions to session calibration after recap.",
+      "systems_invoked": ["orchestrator", "session-management"],
+      "handoff_files_touched": ["SESSION_LOG.md"],
+      "assertions": [
+        {"name": "return-detected", "check": "Orchestrator identifies this as a return session"},
+        {"name": "session-log-read", "check": "Most recent session log entry is read"},
+        {"name": "recap-delivered", "check": "Recap is delivered in 'Previously on...' format"},
+        {"name": "show-name-used", "check": "A fun show name is used for the recap framing"},
+        {"name": "transition-to-calibration", "check": "After recap, orchestrator asks what to work on today"}
+      ]
+    },
+    {
+      "id": 7,
+      "eval_name": "person-profile-creation",
+      "prompt": "I'd like to create my person profile. I'm the owner, CEO of the reference project. I'm a developer and systems thinker. I have several projects: Another project (open source, passion), another project (commercial, building), and a news app concept (early exploration).",
+      "expected_output": "Orchestrator routes to person profile system. Person profile created with all schema sections. Capacities listed with development levels. Projects listed with commitment type, emotional investment, time horizon, and intended outcome. Context section captures any offhand remarks.",
+      "systems_invoked": ["orchestrator", "person-profile"],
+      "handoff_files_touched": ["PERSON_PROFILE.md"],
+      "assertions": [
+        {"name": "person-profile-invoked", "check": "Person profile system skill is read and followed"},
+        {"name": "all-sections-present", "check": "Profile contains all schema sections (Identity through Context)"},
+        {"name": "capacities-listed", "check": "Developer and systems thinker captured as capacities"},
+        {"name": "projects-with-metadata", "check": "Each project has commitment, investment, horizon, outcome"},
+        {"name": "ceo-position-noted", "check": "CEO position is distinguished from person capacities"},
+        {"name": "changelog-entry", "check": "Changelog records profile creation"}
+      ]
+    },
+    {
+      "id": 8,
+      "eval_name": "multi-modal-session-transitions",
+      "prompt": "Let me start by dumping some ideas about a new feature for another project... [ideas]... actually, let me look at the entity profile for another project and update the product pillar... and while we're at it, what does my idea dump backlog look like?",
+      "expected_output": "Orchestrator detects multi-modal session. Transitions between systems: idea dump (capture) → entity profiling (review/update) → diagnostic (backlog check). Each transition is tracked. At session end, session log captures sub-session transitions.",
+      "systems_invoked": ["orchestrator", "idea-dump", "entity-profiling", "diagnostic", "session-management"],
+      "handoff_files_touched": ["IDEA_DUMP.md", "ENTITY_PROFILE.md", "SESSION_LOG.md"],
+      "assertions": [
+        {"name": "multi-modal-detected", "check": "Orchestrator recognizes multi-modal session"},
+        {"name": "transitions-tracked", "check": "Each system transition is noted by the orchestrator"},
+        {"name": "idea-capture-correct", "check": "Ideas captured properly during capture phase"},
+        {"name": "entity-profile-updated", "check": "Entity profile updated during review phase"},
+        {"name": "diagnostic-runs", "check": "Diagnostic provides backlog analysis when requested"},
+        {"name": "session-log-captures-transitions", "check": "Session log entry notes the sub-session type shifts"},
+        {"name": "audit-trigger-fires", "check": "Entity profile audit updated after any document changes"}
+      ]
+    }
+  ]
+}

package/evidence/layer.json

@@ -0,0 +1,51 @@
+{
+  "layer": "evidence",
+  "purpose": "Prove what is true: results of running checks, eval suites, benchmarks, and audits of coverage, fidelity, findability and metrics.",
+  "skills": [
+    {
+      "id": "design-coverage",
+      "path": "evidence/skills/design-coverage/SKILL.md"
+    },
+    {
+      "id": "fidelity-ladder-audit",
+      "path": "evidence/skills/fidelity-ladder-audit/SKILL.md"
+    },
+    {
+      "id": "findability",
+      "path": "evidence/skills/findability/SKILL.md"
+    },
+    {
+      "id": "foreshadowing-audit",
+      "path": "evidence/skills/foreshadowing-audit/SKILL.md"
+    },
+    {
+      "id": "metrics-review",
+      "path": "evidence/skills/metrics-review/SKILL.md"
+    },
+    {
+      "id": "agent-capabilities",
+      "path": "evidence/skills/agent-capabilities/SKILL.md"
+    }
+  ],
+  "records": [
+    "evidence",
+    "eval-suite",
+    "design-documents-registry",
+    "benchmark",
+    "agent-capability"
+  ],
+  "reads": [
+    "handoff",
+    "design-document",
+    "venture-profile",
+    "decision"
+  ],
+  "writes": [],
+  "checks": [
+    "evidence/skills/design-coverage/check.mjs"
+  ],
+  "gaps": [
+    "Audits (coverage, fidelity, findability) print reports but do not write evidence records"
+  ],
+  "name": "evidence"
+}

package/evidence/skills/agent-capabilities/SKILL.md

@@ -0,0 +1,35 @@
+---
+type: knowledge
+tags: [everything-ecosystem, skills, evidence, agents, capabilities, research]
+ai-model: claude-opus-5.5
+created: 2026-10-27T20:45:13Z
+source: hybrid
+name: agent-capabilities
+description: >
+  Keep the agent capability register current: what agents can, cannot, may not,
+  or are not yet known to do, task by task, with sources and dates. Add entries
+  from new research and from our own evals; team plans read it to place human
+  loops (EE-029).
+  MANDATORY TRIGGERS: can an agent do, agent capability, what can AI do, human
+  in the loop, is this safe to delegate, new model release, agent benchmark,
+  eval result, update the capability register.
+---
+
+# Agent capabilities
+
+Evidence layer (EE-029). Writes `evidence/capabilities/agent-capabilities.json`; `schema/check-team.mjs` checks it.
+
+## Why
+
+The research on what agents can do is new and changes month to month. Without a dated register, every team plan guesses. With it, a gap becomes a question to research or an eval to run.
+
+## Adding or updating an entry
+
+1. **Task:** one task, worded as work in a venture ("hold sales conversations with buyers"), with its layer or tier.
+2. **Status:** `can`, `can-with-review`, `cannot`, `not-allowed` (decision rights or law reserve it to a person; cite the class) or `unknown`.
+3. **Basis:** a source fetched and dated (`find-reference`), or our own eval result file. No basis means `unknown`.
+4. **Re-check** entries with a URL after six months, and whenever a new model is adopted.
+
+## Producing evidence ourselves
+
+When a team plan puts a person in the loop for an `unknown` task, turn the task into an eval: the agent does it beside the person on real work, both results are recorded in `evidence/results/`, and the entry is updated from them.

package/evidence/skills/design-coverage/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: design-coverage
+description: "Check which design documents (domain, product, experience, interface, systems) exist for any project and flag gaps, using the registry in evidence/design-documents.registry.json and each entity's design-profile. Run --quick at every SAD session opening (PART 4 step 4b) for the entity in scope; deep (TypeSafe) at phase gates. Use whenever the owner says \"domain design\", \"systems design\", \"capability map\", \"categories\", \"product architecture\", \"user experience\", \"UX\", \"UI\", \"interface\", \"front-end contract\", or asks what docs are missing. MANDATORY TRIGGERS: session start on any project, domain design, systems design, capability map, design docs, what are we missing, design coverage, gaps."
+type: skill
+source: hybrid
+created: 2026-10-09
+ai-model: claude-opus-5.5
+tags: [skill, sad-v3, domain-design, systems-design, typesafe]
+---
+
+# design-coverage
+
+Method: [[DOMAIN_AND_SYSTEMS_DESIGN_METHOD]]. Registry: `evidence/design-documents.registry.json`.
+
+## When the owner says…
+
+- **"domain design"** → work in `DD-*` documents for the named scope. Say so.
+- **"systems design"** → first confirm domain readiness (DD-04, DD-05, DD-06 exist; DD-10 or DD-11 shows they hold). If not ready, say so and propose finishing the domain first. If ready, produce the full `SD-*` package for the next phase to be built, an outline (SD-04, SD-05, SD-21) for the phase after, nothing further.
+- Always state which layer the work is in and how it relates to the other.
+
+## Run the checker
+
+**Layers (SAD v3.0.14):** domain (DD) → product (PA) → experience (XD) → interface (UI) → systems (SD). Experience and interface are active by default; an entity with no human users declares `n/a` with the reason. A candidate needs a strong signal (title pattern in file name or title, a heading naming the ID, or a path match).
+
+**At every session opening on a project (SAD v3.0.13, PART 4 step 4b), quick, free:**
+
+```bash
+node evidence/skills/design-coverage/check.mjs --entity <vault>/projects/<entity> --quick
+```
+
+Read `<entity>/_meta/design-coverage/latest-quick.md`. Tell the owner, in one or two lines, which required documents bearing on today's task have no candidate (✗), and if the entity has no `design-profile`, say that first: it's the gap that hides the others. Don't start design work that depends on a missing document without writing it first or recording why not.
+
+**Deep (TypeSafe) at phase gates, before ratification, or when candidates need judging:**
+
+```bash
+node --env-file=<env file that sets TYPESAFE_API_KEY> evidence/skills/design-coverage/check.mjs --entity <vault>/projects/<entity>
+```
+
+**Vault-wide** (campaign start): `node evidence/skills/design-coverage/scan.mjs` writes `<vault>/_meta/design-coverage/STATUS.md`.
+
+**Explicit mode** (a scope that isn't one entity): `--root <dir> [--root …] [--include '<regex>'] --characteristics … --obligations … [--entity-class business] [--layer domain|product|system|all] --out <prefix>`.
+
+**Declaring a design profile** (when missing): add the `design-profile:` block to the entity profile (schema in `references/entity-profile-schema.md`): ARS characteristics and obligations, extra roots, `systems-design: active | not-started | n/a`. Propose values from the profile and mark them `declared: "<date>, proposed by <model>; confirm"` until the owner confirms.
+
+Writes `<prefix>.json` (per document: status, answered/total, unanswered questions, candidates) and `<prefix>.md` (table). Characteristics and obligations come from the scope's Asset Requirement Set; documents whose `required_when` isn't met are `not_applicable`. Never print the API key.
+
+## Layers
+
+- **Domain (DD-01..12):** includes the **capability map (DD-12)**, required for every project: categories by job, core / supporting / generic, build or integrate, dependencies, owners, success measures.
+- **Product (PA-01..03):** structure and naming (C-19), packaging and buyer mapping, competitive landscape by category (businesses).
+- **Systems (SD-01..23):** only when `systems-design: active`.
+
+## Interpreting
+
+- Deep: `exists` ≥ 80% of questions answered; `partial` ≥ 20%; `null` otherwise. Quick: `candidate` (judge it with a deep run) or `null` (nothing found).
+- `not_started`: systems design hasn't begun for this entity; `not_applicable`: the document's `required_when` isn't met.
+- Treat results as evidence for review: a concept spread over several files can read `partial`. Confirm by reading the unanswered questions.

package/evidence/skills/design-coverage/check.mjs

@@ -0,0 +1,192 @@
+// design-coverage: which design documents (domain, product, experience, interface, systems) exist for a scope, and which are missing.
+// Registry: evidence/design-documents.registry.json
+//
+// Entity mode (normal use; reads the entity profile's `design-profile:` block):
+//   node check.mjs --entity <vault entity folder> [--quick]
+// Explicit mode:
+//   node --env-file=<repo>/.env.local check.mjs --root <dir> [--root <dir> ...] [--include <regex>]
+//        [--characteristics C-01,...] [--obligations O-01,...] [--entity-class business] [--layer domain|product|experience|interface|system|all] [--out <prefix>] [--quick]
+//
+// --quick: no model calls, no key, no cost. Finds candidate documents by filename, title, headings and frontmatter
+//          type; reports `candidate` (something to check) or `null` (nothing found). For session start.
+// deep (default): TypeSafe (Jev) judges, per registry question, whether the best candidates answer it.
+//          Status: exists (>=80% answered) · partial (>=20%) · null · not_applicable (required_when not met) · not_started.
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, mkdirSync } from "node:fs";
+import { join, basename, dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+
+const HERE = dirname(new URL(import.meta.url).pathname);
+const REG = JSON.parse(readFileSync(join(HERE, "../../design-documents.registry.json"), "utf8"));
+const MODEL = "jev-1.13.0";
+const args = process.argv.slice(2);
+const opt = (k, d) => { const i = args.indexOf(k); return i >= 0 ? args[i + 1] : d; };
+const flag = (k) => args.includes(k);
+const home = (p) => p.replace(/^~(?=\/|$)/, homedir());
+const tilde = (p) => p.replace(homedir(), "~");
+const quick = flag("--quick");
+
+// ---------- the design profile ----------
+/** Reads `design-profile:` from an entity profile's frontmatter (a small, fixed shape; no YAML dependency). */
+export function readDesignProfile(entityDir) {
+  const p = join(entityDir, "entity-profile.md");
+  if (!existsSync(p)) return { found: false, why: "no entity-profile.md" };
+  const t = readFileSync(p, "utf8");
+  const fm = t.startsWith("---") ? t.slice(3, t.indexOf("\n---", 3)) : "";
+  const entityClass = (fm.match(/^entity-class:\s*([\w-]+)/m) || [])[1];
+  const name = (t.match(/^#\s+(.+)$/m) || [])[1] ?? basename(entityDir);
+  const i = fm.search(/^design-profile:\s*(#.*)?$/m);
+  if (i < 0) return { found: false, entityClass, name, why: "design-profile not declared in entity-profile.md" };
+  const dp = {};
+  for (const line of fm.slice(i).split("\n").slice(1)) {
+    if (!/^\s{2,}\S/.test(line)) break;
+    const m = line.match(/^\s+([\w-]+):\s*(.*)$/); if (!m) continue;
+    let v = m[2].trim().replace(/\s+#.*$/, "");
+    dp[m[1]] = v.startsWith("[") ? v.slice(1, -1).split(",").map((x) => x.trim().replace(/^["']|["']$/g, "")).filter(Boolean) : v.replace(/^["']|["']$/g, "");
+  }
+  return { found: true, entityClass, name, ...dp };
+}
+
+const entityDir = opt("--entity") ? resolve(home(opt("--entity"))) : null;
+const profile = entityDir ? readDesignProfile(entityDir) : null;
+const listArg = (k) => (opt(k, "") || "").split(",").filter(Boolean);
+const roots = [
+  ...(entityDir ? [entityDir] : []),
+  ...((profile?.roots ?? []).map(home)),
+  ...args.flatMap((a, i) => (a === "--root" ? [home(args[i + 1])] : [])),
+].filter((r) => existsSync(r));
+const includeSrc = opt("--include") ?? (profile?.include || null);
+const include = includeSrc ? new RegExp(includeSrc) : null;
+const chars = new Set(listArg("--characteristics").length ? listArg("--characteristics") : profile?.characteristics ?? []);
+const obls = new Set(listArg("--obligations").length ? listArg("--obligations") : profile?.obligations ?? []);
+const entityClass = opt("--entity-class") ?? profile?.entityClass ?? "";
+const systemsDesign = profile?.["systems-design"] ?? (entityDir ? "not-started" : "active"); // active | not-started | n/a
+// Experience and interface design apply to anything people use; they are active unless the profile says n/a (no human users)
+// or not-started. Default active so their gaps are visible (SAD v3.0.14).
+const layerState = { system: systemsDesign, experience: profile?.["experience-design"] ?? "active", interface: profile?.["interface-design"] ?? "active" };
+const layer = opt("--layer", "all");
+const outDefault = entityDir ? join(entityDir, "_meta", "design-coverage", quick ? "latest-quick" : "latest") : "design-coverage";
+const out = opt("--out", outDefault);
+if (!roots.length) { console.error("need --entity <dir> or --root <dir>"); process.exit(1); }
+if (!quick && !process.env.TYPESAFE_API_KEY) { console.error("deep check needs TYPESAFE_API_KEY (run with --env-file), or use --quick"); process.exit(2); }
+
+// ---------- collect documents ----------
+function walk(d, top, acc = []) {
+  for (const n of readdirSync(d)) {
+    if (n.startsWith(".") || ["node_modules", "_archive", "dist", "build", ".next", "data", "_meta"].includes(n)) continue;
+    const p = join(d, n); let s; try { s = statSync(p); } catch { continue; }
+    if (s.isDirectory()) {
+      // In entity mode, a nested child entity is its own scope.
+      if (entityDir && p !== top && existsSync(join(p, "entity-profile.md")) && !include) continue;
+      walk(p, top, acc);
+    } else if (/\.(md|json|ya?ml)$/i.test(n) && s.size < 2_000_000 && (!include || include.test(p))) acc.push(p);
+  }
+  return acc;
+}
+const files = roots.flatMap((r) => walk(r, r)).map((p) => {
+  const t = readFileSync(p, "utf8");
+  const fm = t.startsWith("---") ? t.slice(3, t.indexOf("\n---", 3)) : "";
+  const type = (fm.match(/^type:\s*(.+)$/m) || [])[1]?.trim() ?? "";
+  const title = (t.match(/^#\s+(.+)$/m) || [])[1] ?? basename(p);
+  const heads = [...t.matchAll(/^#{2,3}\s+(.+)$/gm)].map((m) => m[1]).join(" | ");
+  return { path: p, type, title, heads, text: t };
+});
+
+function score(doc, f) {
+  const hay = `${basename(f.path)} ${f.title} ${f.heads}`.toLowerCase();
+  let s = 0;
+  for (const t of doc.evidence.title_patterns) if (hay.includes(t.toLowerCase())) s += 2;
+  if (doc.evidence.frontmatter_types.includes(f.type)) s += 1;
+  if (new RegExp(`\\b${doc.id}\\b`, "i").test(`${f.title} ${f.heads}`)) s += 4; // a title or heading that names the id claims to answer it
+  for (const g of doc.evidence.path_globs) { const re = new RegExp(g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "(.*/)?").replace(/\*/g, "[^/]*")); if (re.test(f.path)) s += 3; }
+  for (const q of doc.questions) for (const w of q.text.toLowerCase().match(/[a-z]{6,}/g) || []) if (f.heads.toLowerCase().includes(w)) s += 0.2;
+  return s;
+}
+// A candidate needs a strong signal: a title pattern in the name, title or headings, a heading naming the id, or a path match.
+// A frontmatter type and shared question words alone matched unrelated documents (SAD v3.0.14 audit: 12 of 18 false).
+function strong(doc, f) {
+  const name = `${basename(f.path).replace(/[_-]+/g, " ")} ${f.title}`.toLowerCase(); // headings are too noisy for a strong signal
+  if (doc.evidence.title_patterns.some((t) => name.includes(t.toLowerCase()))) return true;
+  if (new RegExp(`\\b${doc.id}\\b`, "i").test(`${f.title} ${f.heads}`)) return true; // the id in the title or a heading
+  return doc.evidence.path_globs.some((g) => new RegExp(g.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*\//g, "(.*/)?").replace(/\*/g, "[^/]*")).test(f.path));
+}
+function required(doc) {
+  const st = layerState[doc.layer];
+  if (st && st !== "active") return { ok: false, status: st === "n/a" ? "not_applicable" : "not_started", why: st === "n/a" ? `${doc.layer} design not applicable to this entity` : `${doc.layer} design not started (design-profile ${doc.layer}-design)` };
+  const r = doc.required_when;
+  if (r === "always" || !r.includes(":")) return { ok: true, why: r };
+  const [k, v] = r.split(":"); const want = v.split("|");
+  const have = k === "characteristics" ? chars : k === "obligations" ? obls : k === "entity-class" ? new Set([entityClass]) : new Set();
+  return want.some((w) => have.has(w)) ? { ok: true, why: r } : { ok: false, status: "not_applicable", why: r };
+}
+
+// ---------- TypeSafe ----------
+const cachePath = `${out.replace(/latest(-quick)?$/, "")}typesafe-cache.json`;
+mkdirSync(dirname(out), { recursive: true });
+const cache = !quick && existsSync(cachePath) ? JSON.parse(readFileSync(cachePath, "utf8")) : {};
+let tokens = 0;
+async function ask(state, questions) {
+  const k = createHash("sha256").update(JSON.stringify({ state, questions })).digest("hex");
+  if (cache[k]) return cache[k];
+  for (let a = 0; a < 5; a++) {
+    const res = await fetch("https://api.typesafe.ai/v1/systemone", { method: "POST",
+      headers: { authorization: `Bearer ${process.env.TYPESAFE_API_KEY}`, "content-type": "application/json" },
+      body: JSON.stringify({ model: MODEL, state, questions }), signal: AbortSignal.timeout(90000) });
+    if (res.status === 429 || res.status >= 500) { await new Promise((r) => setTimeout(r, 2500 * (a + 1))); continue; }
+    if (!res.ok) throw new Error(`TypeSafe ${res.status}`);
+    const o = await res.json(); tokens += o.usage?.input_tokens ?? 0; cache[k] = o; return o;
+  }
+  throw new Error("retries exhausted");
+}
+function excerpt(f, doc) {
+  const t = f.text; const keep = [f.title, f.heads];
+  const words = [...doc.evidence.title_patterns, doc.id].map((w) => w.toLowerCase());
+  for (const s of t.split(/\n(?=#{2,3}\s)/)) if (words.some((w) => s.slice(0, 200).toLowerCase().includes(w))) keep.push(s);
+  keep.push(t.slice(0, 4000));
+  return keep.join("\n\n").slice(0, 9000);
+}
+
+const docs = REG.documents.filter((d) => layer === "all" || d.layer === layer);
+const results = [];
+for (const doc of docs) {
+  const base = { id: doc.id, name: doc.name, layer: doc.layer, stage: doc.stage };
+  const req = required(doc);
+  if (!req.ok) { results.push({ ...base, status: req.status, reason: req.why, candidates: [] }); continue; }
+  const cands = files.map((f) => ({ f, s: score(doc, f) })).filter((x) => x.s >= 2 && strong(doc, x.f)).sort((a, b) => b.s - a.s).slice(0, 3);
+  if (!cands.length) { results.push({ ...base, status: "null", answered: 0, total: doc.questions.length, unanswered: doc.questions.map((q) => q.text), candidates: [] }); continue; }
+  if (quick) { results.push({ ...base, status: "candidate", total: doc.questions.length, candidates: cands.map(({ f, s }) => ({ path: tilde(f.path), match_score: +s.toFixed(1) })) }); continue; }
+  const answered = new Array(doc.questions.length).fill(0); const per = [];
+  for (const { f, s } of cands) {
+    const r = await ask({ document_path: tilde(f.path), document_excerpt: excerpt(f, doc) },
+      Object.fromEntries(doc.questions.map((q, i) => [`q${i}`, { type: "noul",
+        instructions: `Does \`document_excerpt\` give a specific, written answer to this design question: "${q.text}"? A heading or a passing mention is not an answer.`,
+        criteria: { true: "Yes, it answers it specifically", false: "No, or only vaguely" } }])));
+    const vals = doc.questions.map((_, i) => r.answers[`q${i}`].noul);
+    vals.forEach((v, i) => { answered[i] = Math.max(answered[i], v); });
+    per.push({ path: tilde(f.path), match_score: +s.toFixed(1), answers: vals.map((v) => +v.toFixed(2)) });
+  }
+  const n = answered.filter((v) => v > 0.5).length, frac = n / doc.questions.length;
+  results.push({ ...base, status: frac >= 0.8 ? "exists" : frac >= 0.2 ? "partial" : "null", answered: n, total: doc.questions.length,
+    unanswered: doc.questions.filter((_, i) => answered[i] <= 0.5).map((q) => q.text), candidates: per });
+}
+if (!quick) writeFileSync(cachePath, JSON.stringify(cache));
+
+const required_ = results.filter((r) => !["not_applicable", "not_started"].includes(r.status));
+const gaps = required_.filter((r) => r.status !== "exists" && r.status !== "candidate");
+const report = { generated: new Date().toISOString(), mode: quick ? "quick" : "deep", model: quick ? null : MODEL, registry: REG.version,
+  entity: entityDir ? { path: tilde(entityDir), name: profile?.name, entityClass, designProfile: profile?.found ? "declared" : profile?.why, systemsDesign, experienceDesign: layerState.experience, interfaceDesign: layerState.interface } : null,
+  roots: roots.map(tilde), include: include?.source ?? null, characteristics: [...chars], obligations: [...obls],
+  tokens, usd: +((tokens / 1e6) * 0.042).toFixed(4),
+  summary: Object.fromEntries(["exists", "partial", "candidate", "null", "not_started", "not_applicable"].map((s) => [s, results.filter((r) => r.status === s).length])),
+  gaps: gaps.map((g) => `${g.id} ${g.name}: ${g.status}`), results };
+writeFileSync(`${out}.json`, JSON.stringify(report, null, 1));
+const sym = { exists: "✓", partial: "↺", null: "✗", candidate: "?", not_applicable: "N/A", not_started: "—" };
+const md = [
+  `# Design coverage${profile?.name ? `: ${profile.name}` : ""} (${report.generated.slice(0, 10)}, ${report.mode})`, "",
+  ...(profile && !profile.found ? [`> **Gap: ${profile.why}.** Declare it (SAD v3.0.13) so the right documents are required; until then only documents required for every scope are checked.`, ""] : []),
+  `Registry ${REG.version} · roots: ${report.roots.join(", ")}${report.include ? ` · include /${report.include}/` : ""} · entity-class: ${entityClass || "—"} · characteristics: ${[...chars].join(", ") || "none"} · obligations: ${[...obls].join(", ") || "none"} · systems: ${systemsDesign} · experience: ${layerState.experience} · interface: ${layerState.interface}${quick ? " · quick (no model calls; `?` = a candidate exists, run deep to judge it)" : ` · TypeSafe ${MODEL}, ≈$${report.usd}`}`, "",
+  `**Summary:** ${Object.entries(report.summary).filter(([, v]) => v).map(([k, v]) => `${sym[k]} ${k} ${v}`).join(" · ")}`, "",
+  "| ID | Document | Stage | Status | Answered | Best candidate |", "|---|---|---|---|---|---|",
+  ...results.map((r) => `| ${r.id} | ${r.name} | ${r.stage} | ${sym[r.status]} ${r.status} | ${r.answered !== undefined && r.total ? `${r.answered}/${r.total}` : "—"} | ${r.candidates?.[0]?.path.split("/").pop() ?? (r.reason ?? "")} |`)];
+writeFileSync(`${out}.md`, md.join("\n") + "\n");
+console.log(JSON.stringify({ out: tilde(out), mode: report.mode, summary: report.summary, gaps: report.gaps.length, usd: report.usd }));

package/evidence/skills/design-coverage/scan.mjs

@@ -0,0 +1,45 @@
+// Vault-wide design coverage: quick check (no model calls) on every live entity; writes _meta/design-coverage/STATUS.md.
+// Usage: node scan.mjs [--vault <vault root>]
+import { readdirSync, existsSync, statSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname, relative } from "node:path";
+import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+
+const HERE = dirname(new URL(import.meta.url).pathname);
+const vault = (process.argv[process.argv.indexOf("--vault") + 1] && process.argv.includes("--vault")) ? process.argv[process.argv.indexOf("--vault") + 1].replace(/^~/, homedir()) : join(homedir(), "workspace", "vault");
+const entities = [];
+function find(d, depth) {
+  if (depth > 5) return;
+  for (const n of readdirSync(d)) {
+    if (n.startsWith(".") || n.startsWith("_") || n === "node_modules") continue;
+    const p = join(d, n); if (!statSync(p).isDirectory()) continue;
+    if (existsSync(join(p, "entity-profile.md"))) {
+      const fm = readFileSync(join(p, "entity-profile.md"), "utf8").split("\n---")[0];
+      if (!/^entity-status:\s*archived/m.test(fm) && !/^entity-lifecycle-stage:\s*archived/m.test(fm)) entities.push(p);
+    }
+    find(p, depth + 1);
+  }
+}
+for (const root of ["companies", "projects"]) find(join(vault, root), 0);
+
+const rows = [];
+for (const e of entities) {
+  try {
+    const out = execFileSync("node", [join(HERE, "check.mjs"), "--entity", e, "--quick"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    const r = JSON.parse(readFileSync(join(e, "_meta", "design-coverage", "latest-quick.json"), "utf8"));
+    rows.push({ e: relative(vault, e), r });
+  } catch (err) { rows.push({ e: relative(vault, e), err: String(err.message).slice(0, 120) }); }
+}
+const declared = rows.filter((x) => x.r?.entity?.designProfile === "declared").length;
+const md = [
+  "---", "type: diagnostic", "source: machine", `created: ${new Date().toISOString().slice(0, 10)}`, "ai-model: none", "tags: [design-coverage, diagnostic, sad-v3]",
+  'description: "Vault-wide design coverage (quick mode): for every live entity, which required design documents have no candidate at all. Generated by evidence/skills/design-coverage/scan.mjs; regenerate, do not edit."', "---", "",
+  `# Design coverage across the vault (${new Date().toISOString().slice(0, 10)})`, "",
+  `Quick mode: no model calls. **✗ null** means no candidate document was found for a required design document; **?** means a candidate exists and a deep check is needed to judge it. ${declared} of ${rows.length} entities declare a \`design-profile\` (SAD v3.0.13); undeclared entities are checked only against documents required for every scope.`, "",
+  "| Entity | Class | Profile | ✗ null | ? candidate | Missing (first 6) |", "|---|---|---|---|---|---|",
+  ...rows.sort((a, b) => (b.r?.summary.null ?? 0) - (a.r?.summary.null ?? 0)).map(({ e, r, err }) => err ? `| ${e} | — | error | — | — | ${err} |`
+    : `| [[${e.split("/").pop()}/entity-profile\\|${e}]] | ${r.entity.entityClass ?? "—"} | ${r.entity.designProfile === "declared" ? "declared" : "**not declared**"} | ${r.summary.null} | ${r.summary.candidate} | ${r.results.filter((x) => x.status === "null").slice(0, 6).map((x) => x.id).join(", ")} |`),
+];
+mkdirSync(join(vault, "_meta", "design-coverage"), { recursive: true });
+writeFileSync(join(vault, "_meta", "design-coverage", "STATUS.md"), md.join("\n") + "\n");
+console.log(JSON.stringify({ entities: rows.length, declared, out: "_meta/design-coverage/STATUS.md" }));