dreamteamer 0.6.3 → 0.7.0

package/src/compile.js

@@ -7,13 +7,17 @@ import path from 'node:path';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { load, dump } from './yaml.js';
-import { walk } from './records.js';
+import { slug } from './template.js';
+import { walk, patternRe } from './records.js';
 import { unknownOperators } from './filter.js';
+import {
+	normalizeNamespaces, namespaceProblems, unqualifiedProblems, defaultStoragePath, storageOverlaps,
+} from './namespace.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
 import { runHarnessAdapters } from './harnesses.js';
 import { satisfies } from './semver.js';
-import { readManifest, runtimeDir } from './runtime.js';
+import { DERIVED_KINDS, readManifest, runtimeDir } from './runtime.js';
 
 // re-exported, not moved: `readManifest` is in the VS Code extension's hand-maintained engine
 // contract as `compileMod.readManifest` (engine.ts), and a removed export is the same cross-repo
@@ -64,8 +68,30 @@ function staleDisplayKeywords(schema, prefix = '') {
 	return out;
 }
 
+/**
+ * Every `x-reference` in a schema, as `[fieldPath, target]` — the same traversal check.js uses to
+ * resolve refs in records, here to verify the SHAPE against the module dependency graph. Nested
+ * objects and array items both carry the keyword, so both are walked.
+ */
+function refTargets(schema, prefix = '') {
+	const out = [];
+	for (const [key, prop] of Object.entries(schema?.properties ?? {})) {
+		if (!prop || typeof prop !== 'object') continue;
+		const at = `${prefix}${key}`;
+		if (prop['x-reference']) out.push([at, prop['x-reference']]);
+		if (prop.items && typeof prop.items === 'object' && prop.items['x-reference']) out.push([`${at}[]`, prop.items['x-reference']]);
+		if (prop.properties) out.push(...refTargets(prop, `${at}.`));
+		if (prop.items?.properties) out.push(...refTargets(prop.items, `${at}[].`));
+	}
+	return out;
+}
+
 export const KINDS = ['collections', 'skills', 'agents', 'commands', 'command-bindings', 'ui-views', 'collection-templates'];
 const FOLDER_KINDS = new Set(['skills']); // folder-shape entities: copy the whole record folder
+// DERIVED_KINDS (projected, not staged) lives in runtime.js — the boundary both halves read. Not in
+// KINDS on purpose: a module folder named `modules/` would be nonsense, and `isSystem` below keys
+// off KINDS to decide `storage.base`, so a `modules` collection landing on `base: workspace` would
+// point the store at the SOURCE directory and read every module folder as a record.
 
 /**
  * A module's source folder for one kind. The layout is FLAT — `<module>/skills`, beside `data/` —
@@ -238,6 +264,8 @@ export function compile({ root, pkg }) {
 	const engineVer = engineVersion();
 	const declaredEnv = new Map(); // env key -> [module names]
 	const moduleIgnores = new Map(); // module name -> non-source folders it declares (strayKindDirs)
+	const moduleDeps = new Map();  // module name -> [module names]      — HARD, must be acyclic
+	const modulePeers = new Map(); // module name -> [collection names]  — SOFT, cannot cycle
 	for (const source of sources) {
 		let mpkg;
 		try { mpkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')); } catch { continue; }
@@ -246,6 +274,16 @@ export function compile({ root, pkg }) {
 			if (!Array.isArray(ignore)) fail(`module "${source.name}": "ignore" must be a list of folder names (got ${JSON.stringify(ignore)})`);
 			moduleIgnores.set(source.name, ignore.map(String));
 		}
+		// npm's TERMINOLOGY, deliberately not npm's namespace: these live under `dreamteamer` so
+		// npm's own resolver never tries to fetch an inline or git-channel module.
+		for (const [key, sink] of [['dependencies', moduleDeps], ['peerDependencies', modulePeers]]) {
+			const decl = mpkg.dreamteamer?.[key];
+			if (decl === undefined) continue;
+			if (!Array.isArray(decl) || decl.some((v) => typeof v !== 'string')) {
+				fail(`module "${source.name}": dreamteamer.${key} must be a list of ${key === 'dependencies' ? 'module names' : 'collection names'} (got ${JSON.stringify(decl)})`);
+			}
+			sink.set(source.name, decl);
+		}
 		const range = mpkg.dreamteamer?.engine;
 		if (range) {
 			const ok = satisfies(engineVer, range);
@@ -275,6 +313,36 @@ export function compile({ root, pkg }) {
 		}
 	}
 
+	// ---- the module dependency graph -------------------------------------------------
+	// `dependencies` names MODULES and must be acyclic. `peerDependencies` names COLLECTIONS and
+	// therefore cannot cycle at all — which is the whole reason it exists: two modules that each
+	// reference a concept the other owns (crm needs `products`, rnd needs `contacts`) would be an
+	// unbreakable ring under module-named deps, and are two independent peer declarations here.
+	const moduleNames = new Set(sources.map((s) => s.name));
+	for (const [mod, deps] of moduleDeps) {
+		for (const dep of deps) {
+			if (dep === mod) fail(`module "${mod}" declares itself as a dependency`);
+			if (!moduleNames.has(dep)) {
+				fail(`module "${mod}" depends on "${dep}", which is not installed — modules present: ${[...moduleNames].sort().join(', ')}`);
+			}
+		}
+	}
+	// DFS with an explicit path so the error can print the ring rather than just naming one module
+	{
+		const state = new Map(); // name -> 'open' | 'done'
+		const visit = (mod, trail) => {
+			if (state.get(mod) === 'done') return;
+			if (state.get(mod) === 'open') {
+				const ring = [...trail.slice(trail.indexOf(mod)), mod];
+				fail(`cyclic module dependencies: ${ring.join(' → ')}\n  a reference to a CONCEPT another module owns belongs in dreamteamer.peerDependencies (a collection name), which cannot cycle.`);
+			}
+			state.set(mod, 'open');
+			for (const dep of moduleDeps.get(mod) ?? []) visit(dep, [...trail, mod]);
+			state.set(mod, 'done');
+		};
+		for (const mod of moduleDeps.keys()) visit(mod, []);
+	}
+
 	const dataOwners = dataOwningModules(sources, fail, rel);
 
 	const disabled = new Set(config.disable ?? []);
@@ -322,7 +390,18 @@ export function compile({ root, pkg }) {
 			const srcDir = kindDir(source.root, kind);
 			if (!fs.existsSync(srcDir)) continue;
 			counts[kind] ??= 0;
-			for (const name of fs.readdirSync(srcDir).sort()) {
+			// `collections/` is enumerated RECURSIVELY, so a namespaced descriptor can be authored at
+			// `collections/health/doctors.collection.yaml` — mirroring where it lands in the runtime and
+			// letting a workspace group its descriptors the same way its data is grouped.
+			//
+			// ⚠ This is load-bearing, not cosmetic. `schema-ops` derives a descriptor's source path from
+			// its name, so `add-field` on `health/doctors` writes the nested path; with a flat readdir
+			// that file was written, silently skipped, and the verb reported ✔ while changing nothing —
+			// the decision-156 shape again. Every other kind stays flat: their ids are single segments.
+			const names = kind === 'collections'
+				? [...walk(srcDir)].map((f) => path.relative(srcDir, f).split(path.sep).join('/'))
+				: fs.readdirSync(srcDir).sort();
+			for (const name of names) {
 				if (name.startsWith('.')) continue;
 				const entityId = name.replace(/\.[^.]+\.(yaml|md|json)$/, '');
 				if (disabled.has(`${source.name}/${entityId}`)) { disabledHits.add(`${source.name}/${entityId}`); continue; }
@@ -413,10 +492,48 @@ export function compile({ root, pkg }) {
 		templateDocs.set(m[1], { template: doc.template ?? {}, src: entry.sources[0] });
 	}
 
+	// ---- namespaces: the declared list, validated against what actually compiled ----------
+	// Declared in the WORKSPACE package.json only, never per-module. A module that could declare a
+	// namespace could rename where another module's records live, and the whole point of a namespace
+	// is that the workspace decides how its own data is partitioned. `namespaces` is also config
+	// rather than records for the same bootstrap reason `git-modules` is (docs/repos-and-modules.md):
+	// a reference has to be parseable before anything has been compiled.
+	const namespaces = normalizeNamespaces(config.namespaces);
+	const collectionNames = [...descriptorGroups.keys()];
+	for (const p of namespaceProblems(namespaces, collectionNames)) fail(p);
+	// The silent failure this whole feature had to fix: a slash in a collection name used to compile
+	// clean, land at `.dreamteamer/collections/<ns>/<name>.collection.yaml`, and then vanish — the
+	// descriptor loader read one directory level, so the collection was simply absent from the
+	// runtime while compile reported ✔ (the same shape as decision 156).
+	for (const p of unqualifiedProblems(collectionNames, namespaces)) fail(p);
+
+	// ---- who owns which collection, and which module IS the workspace ----------------
+	// Needed before the resolution loop so each descriptor can be validated against the graph as it
+	// is merged. The owner is the group member that does NOT declare `extends`; a group with two of
+	// those is a name collision, and the loop below raises it properly — this pass only maps.
+	// A module's record id: the npm scope stripped, so `@dreamteamer/crm` reads as `crm` — which is
+	// what every message in this engine already calls it.
+	const moduleId = (n) => slug(String(n).replace(/^@[^/]+\//, ''));
+	const collOwner = new Map(); // collection name -> owning module name
+	const moduleColls = new Map(); // module name -> Set(collection names it contributed to)
+	for (const [name, group] of descriptorGroups) {
+		const base = group.find((g) => !g.doc.extends);
+		if (base) collOwner.set(name, base.moduleName);
+	}
+	// The engine's own nine collections are an implicit dependency of every module: seven entity
+	// kinds plus the two the compiler materializes. Requiring every module to declare a dependency
+	// on the host it cannot run without would be ceremony, not verification.
+	const CORE_COLLECTIONS = new Set([...KINDS, ...DERIVED_KINDS, 'users', 'repos']);
+	const wsDir = config['workspace-module'];
+	const wsModuleName = wsDir
+		? sources.find((s) => rel(s.root) === path.join('modules', wsDir))?.name
+		: pkg.name;
+
 	// ---- resolve descriptor groups (templates + extends merge) ---------------------
 	counts.collections = 0;
 	let mergedCount = 0;
 	let templatedCount = 0;
+	const storageEntries = []; // {name, path, base} per collection — checked for overlap after the loop
 	for (const [name, group] of descriptorGroups) {
 		// a template's bytes feed the compiled descriptor, so it MUST be one of that descriptor's
 		// declared sources — otherwise editing the template leaves every consumer silently stale
@@ -448,6 +565,11 @@ export function compile({ root, pkg }) {
 			if (ext.doc.extends !== expected) {
 				fail(`${ext.src.path}: extends "${ext.doc.extends}" does not name the base "${expected}"`);
 			}
+			// `extends` is the hardest dependency there is — the extender does not compile at all
+			// without the base (see the "no base found" failure above), so it must say so.
+			if (ext.moduleName !== base.moduleName && !(moduleDeps.get(ext.moduleName) ?? []).includes(base.moduleName)) {
+				fail(`${ext.src.path}: extends "${expected}" but module "${ext.moduleName}" does not declare "${base.moduleName}" in dreamteamer.dependencies — an overlay cannot compile without its base.`);
+			}
 			merged = mergeDescriptor(merged, ext.doc);
 		}
 		delete merged.extends;
@@ -463,8 +585,15 @@ export function compile({ root, pkg }) {
 		// the workspace root, read as zero records, and become writable through the store.
 		merged.storage ??= {};
 		const owned = dataOwners.get(storageOwnerOf(group, base));
+		// A namespaced collection's folder IS its namespace, nested: `health/doctors` →
+		// `data/health/doctors`. Derived rather than required so a descriptor never has to repeat its
+		// own name in a path, and so moving a collection between namespaces is a one-line edit.
+		// An authored `storage.path` still wins — registering an existing folder is a first-class case
+		// (skills/building-dreamteamer/references/collections.md).
+		merged.storage.path ??= defaultStoragePath(name, namespaces, config['data-path'] ?? 'data');
 		const storagePath = String(merged.storage.path ?? '');
-		const isSystem = KINDS.includes(storagePath) || KINDS.includes(storagePath.replace(/^system\//, ''));
+		const systemKinds = [...KINDS, ...DERIVED_KINDS];
+		const isSystem = systemKinds.includes(storagePath) || systemKinds.includes(storagePath.replace(/^system\//, ''));
 		merged.storage.base = isSystem ? 'runtime' : 'workspace';
 		if (owned && !isSystem) {
 			const modRel = rel(owned.root);
@@ -473,6 +602,7 @@ export function compile({ root, pkg }) {
 		} else {
 			merged.storage.repo = '.';
 		}
+		storageEntries.push({ name, path: merged.storage.path, base: merged.storage.base });
 		for (const [at, tpl, target] of staleDisplayKeywords(merged.schema)) {
 			const fix = target
 				? `either DELETE it (a reference to "${target}" now inherits that collection's \`title_template\`) or rename it to \`x-title-template\` if this field really needs its own`
@@ -487,6 +617,66 @@ export function compile({ root, pkg }) {
 		} catch (e) {
 			fail(`collection "${name}": schema is not a valid JSON Schema — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
 		}
+		// Same reasoning one line up, for the OTHER regex a descriptor carries. `patternRe` throws on a
+		// malformed pattern, and it is called from `store.add` and from `check` — so without this gate a
+		// typo'd `id.pattern` surfaces as a raw "Invalid regular expression" from inside a write instead
+		// of as a compile error naming the descriptor.
+		if (merged.id?.pattern !== undefined) {
+			if (typeof merged.id.pattern !== 'string') fail(`collection "${name}": id.pattern must be a string (got ${JSON.stringify(merged.id.pattern)})`);
+			try { patternRe(merged.id.pattern); } catch (e) {
+				fail(`collection "${name}": id.pattern is not a valid regular expression — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
+			}
+		}
+		// ---- the reference contract: every target is owned, depended on, or declared a peer ----
+		// Attribution is unioned across the whole group rather than taken from the base, because the
+		// merge keeps no per-field provenance — an overlay that adds a ref field would otherwise be
+		// judged against the BASE module's declarations, which it never wrote.
+		const groupModules = [...new Set(group.map((g) => g.moduleName))];
+		// WHO OWNS the concept — the module whose source is the base, not the ones overlaying it.
+		// An overlay adds fields to somebody else's collection (hq3 adds `tags` to crm's contacts);
+		// it does not take the concept over. Measured 2026-08-11: letting the overlay win moves
+		// `contacts` and `meetings` out of CRM, and a CRM without contacts reads as broken.
+		//
+		// ⚠ This is NOT the `module` provenance field an outside review rejected this morning. That
+		// one duplicated `group:` while claiming to name every contributor, and got the merged case
+		// wrong by taking the first source. This names ONE thing — the owner — for which the base
+		// IS the answer, and it exists to REPLACE `group:` as the workspace's partition rather than
+		// to sit beside it.
+		merged.owner = `modules/${moduleId(base?.moduleName ?? groupModules[0])}`;
+		// EVERY contributing module, not just the base — a collection merged from crm + hq3 belongs
+		// to both, and saying otherwise is what made a flat "which module owns this" field wrong.
+		for (const m of groupModules) {
+			if (!moduleColls.has(m)) moduleColls.set(m, new Set());
+			moduleColls.get(m).add(name);
+		}
+		const declaredDeps = new Set(groupModules.flatMap((m) => moduleDeps.get(m) ?? []));
+		const declaredPeers = new Set(groupModules.flatMap((m) => modulePeers.get(m) ?? []));
+		const owns = (t) => groupModules.includes(collOwner.get(t));
+		for (const [at, target] of refTargets(merged.schema)) {
+			if (target === '*') {
+				// The workspace module is the orchestrating parent and may reference anything —
+				// including modules that do not exist yet, which is what `tasks.item` means.
+				// Anywhere else a wildcard is a cross-module surface no declaration can cover.
+				if (!groupModules.includes(wsModuleName)) {
+					console.warn(`⚠ collection ${name}: field "${at}" uses x-reference: '*' outside the workspace module — an unverifiable cross-module surface; name the collections it may target`);
+				}
+				continue;
+			}
+			if (CORE_COLLECTIONS.has(target) || owns(target)) continue;
+			const owner = collOwner.get(target);
+			if (owner && declaredDeps.has(owner)) continue;
+			if (declaredPeers.has(target)) continue;
+			const fix = owner
+				? `add "${owner}" to dreamteamer.dependencies, or "${target}" to dreamteamer.peerDependencies if the module should work without it`
+				: `add "${target}" to dreamteamer.peerDependencies — no installed module provides it`;
+			fail(`collection "${name}": field "${at}" references "${target}", which ${groupModules.join('/')} neither owns nor declares.\n  ${fix}.`);
+		}
+		// Declared peers that nothing provides, stated as DATA on the descriptor so `check` can
+		// excuse their references without learning what a module is (the `storage.base` precedent —
+		// check.js is in the record layer and must not know modules exist).
+		const unresolved = [...declaredPeers].filter((p) => !collOwner.has(p)).sort();
+		if (unresolved.length) merged.unresolved_peers = unresolved;
+
 		// ---- resolved labels: what to CALL this collection, its records and its fields --------
 		// Written into the artifact next to `storage.base` and for the same reason: the nav, the
 		// browse page, the CLI and the extension then read ONE field instead of each carrying its
@@ -507,6 +697,70 @@ export function compile({ root, pkg }) {
 		if (extenders.length) mergedCount++;
 	}
 
+	// ---- no collection may sit inside another's folder -------------------------------
+	// Checked HERE because it is the first moment every path is resolved (namespace nesting, the
+	// `owns-data` module prefix and any authored override all already applied). See
+	// namespace.storageOverlaps for what this silently did before it was checked.
+	for (const p of storageOverlaps(storageEntries)) fail(p);
+
+	// ---- modules, projected ---------------------------------------------------------
+	// One record per discovered module, written from what discovery and the package pass already
+	// established. `package.json` remains the source of truth and compile keeps reading it — this
+	// is a photograph, never an input (see collections/modules.collection.yaml for why it earns a
+	// place in core at all).
+	//
+	// The id strips an npm scope so `@dreamteamer/crm` reads as `crm`, which is what every message
+	// in this engine already calls it. A collision is a hard failure rather than a silent overwrite:
+	// two modules answering to one id would make `dependencies` ambiguous, and an ambiguous edge is
+	// worse than no diagram.
+	const idByModule = new Map();
+	for (const source of sources) {
+		const id = moduleId(source.name);
+		const clash = idByModule.get(id);
+		if (clash && clash !== source.name) fail(`modules "${clash}" and "${source.name}" both resolve to the id "${id}" — rename one.`);
+		idByModule.set(id, source.name);
+	}
+	for (const source of sources) {
+		const id = moduleId(source.name);
+		let mpkg = {};
+		try { mpkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')).dreamteamer ?? {}; } catch { /* inline workspace source */ }
+		const record = {
+			name: source.name,
+			// Authored wins; the derived fallback title-cases the id the same way a collection's
+			// `title` is derived. `@dreamteamer/crm` -> "Crm" until crm declares "CRM" — which is
+			// the point: the module is the only place that knows.
+			title: typeof mpkg.title === 'string' && mpkg.title ? mpkg.title : titleCase(id),
+			channel: source.channel,
+			path: rel(source.root) || '.',
+			...(mpkg['owns-data'] === true ? { owns_data: true } : {}),
+			// Declared module names become record IDS here, because that is what an x-reference
+			// resolves against. An undeclared/unknown name would dangle, and `check` would say so —
+			// but compile has already failed on that case (the acyclicity pass resolves every one).
+			// ⚠ A reference VALUE is `<collection>/<id>`, never a bare id — `check` rejects the bare
+			// form, which is exactly what it did to the first pass of this projection (63 violations).
+			...(moduleDeps.get(source.name)?.length
+				? { dependencies: moduleDeps.get(source.name).map((n) => `modules/${moduleId(n)}`) }
+				: {}),
+			...(modulePeers.get(source.name)?.length
+				? { peer_dependencies: modulePeers.get(source.name).map((c) => `collections/${c}`) }
+				: {}),
+			...(moduleColls.get(source.name)?.size
+				? { collections: [...moduleColls.get(source.name)].sort().map((c) => `collections/${c}`) }
+				: {}),
+		};
+		const bytes = Buffer.from(dump(record));
+		// ⚠ The source hash is the hash of the SOURCE FILE, not of the projected record. Hashing the
+		// output made every source "differ" on the next run, so `staleness` reported the workspace
+		// stale immediately after a clean compile — the one signal that has to stay trustworthy.
+		const pkgPath = path.join(source.root, 'package.json');
+		const pkgBytes = fs.existsSync(pkgPath) ? fs.readFileSync(pkgPath) : bytes;
+		entries.set(path.join('modules', `${id}.module.yaml`), {
+			sources: [{ path: rel(pkgPath), hash: sha256(pkgBytes) }],
+			bytes,
+		});
+		counts.modules = (counts.modules ?? 0) + 1;
+	}
+
 	// ---- unresolved references are compile errors (an agent's declared skills)
 	const skillIds = new Set([...entries.keys()].filter((k) => k.startsWith('skills/')).map((k) => k.split('/')[1]));
 	for (const [rt, e] of entries) {
@@ -594,12 +848,17 @@ export function compile({ root, pkg }) {
 	const anyFlat = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, k))));
 	const anyNested = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, 'system', k))));
 	const sourceLayout = anyFlat && anyNested ? 'mixed' : anyNested ? 'nested' : 'flat';
-	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout });
+	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout, namespaces, version: engineVer });
 
 	// ---- provenance manifest ------------------------------------------------------
 	const manifest = {
 		compiled: new Date().toISOString(),
 		host: engineId(),
+		// The declared namespace list, carried across the boundary so the RECORD layer can split a
+		// reference without importing the compiler or re-reading package.json — the same reason
+		// `storage.base` is a field instead of a path test. An older runtime has no key here, which
+		// reads as "no namespaces", which is exactly right for a workspace that never declared any.
+		namespaces,
 		modules: sources.map((s) => ({ name: s.name, channel: s.channel, root: rel(s.root) || '.' })),
 		ui: uiModules.sort(),
 		'adapter-outputs': adapterOutputs.sort(),

package/src/harnesses.js

@@ -21,7 +21,7 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 const END = '<!-- dreamteamer:end -->';
 
-export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat' }) {
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown' }) {
 	const outputs = [];
 	const summary = [];
 	const rel = (p) => path.relative(root, p);
@@ -56,7 +56,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		}
 		summary.push(`claude-code → .claude (${n} files)`);
 	}
-	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version) : null);
 
 	// ---- shared cross-agent skills mirror (.agents/skills) — codex/pi discover it,
 	// cursor/gemini blocks point at it. written once no matter how many harnesses use it.
@@ -73,17 +73,17 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	}
 
 	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
-	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version) : null);
 	if (on('codex')) summary.push('codex → AGENTS.md block');
 	if (on('pi')) summary.push('pi → AGENTS.md block + .agents/skills');
 
 	// ---- gemini-cli: GEMINI.md is its context file -----------------------------------
-	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout) : null);
+	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -127,15 +127,25 @@ function buildSkillsIndex(entries) {
  *  'nested' (the pre-2026-08-05 `<module>/system/skills/`), or 'mixed'. It is passed in rather than
  *  assumed because generated prose that contradicts the workspace is worse than no prose: this block
  *  is the first thing an agent session reads, and a workspace still on the old layout was being told
- *  to write somewhere it does not keep its sources. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
+ *  to write somewhere it does not keep its sources.
+ *
+ *  `namespaces` is here for exactly the same reason, and it matters more. A reference is
+ *  `<collection>/<id>`, and an id is ALSO a slash path — so in a workspace with declared namespaces an
+ *  agent that splits `health/doctors/dana-levi` at the first slash reads a collection that does not
+ *  exist. Naming the declared list is what makes the grammar decidable from this block alone, without
+ *  the agent having to go read the manifest. A workspace with no namespaces gets no extra sentence. */
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown') {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		mixed: '`modules/<module>/<kind>/`, or `<module>/system/<kind>/` where a module still nests it —\n`collections/`, `skills/`, `agents/`, `commands/`,',
 	}[sourceLayout] ?? '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,';
 	const lines = [
-		'this workspace is operated by dreamteamer v0.6. **read the `using-dreamteamer` skill before',
+		// PASSED IN, never hardcoded: this string used to say "v0.6" literally, which was correct for
+		// exactly one minor release and then quietly wrong in every workspace it had been written into.
+		// Passed rather than imported because compile.js already computes it and imports THIS module —
+		// reaching back for `engineVersion` would close a cycle for the sake of one string.
+		`this workspace is operated by dreamteamer v${version}. **read the \`using-dreamteamer\` skill before`,
 		'working with data.** schemas (read): `.dreamteamer/collections/` (provenance:',
 		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
 		'`command-bindings/`, `ui-views/`, `collection-templates/`',
@@ -145,6 +155,17 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
 		'check`) after bulk edits; run `dreamteamer compile` (`npm run compile`) after changing any',
 		'source or installing modules.',
 	];
+	// ⚠ Only when the workspace HAS namespaces. Telling an agent about a feature this workspace does
+	// not use is the same failure as telling it the wrong source layout — prose that contradicts the
+	// workspace is worse than no prose.
+	if (namespaces.length) {
+		lines.push(
+			`this workspace declares NAMESPACES: ${namespaces.map((n) => `\`${n}\``).join(', ')}. a collection`,
+			'in one is named with its prefix (`health/doctors`), stores records under `data/<namespace>/`,',
+			'and is referenced as `<namespace>/<collection>/<id>` — so split a reference at the end of the',
+			'DECLARED prefix, not at the first slash. collections with no prefix are unaffected.',
+		);
+	}
 	// claude-code discovers skills natively (Skill tool) — an index in CLAUDE.md is pure
 	// context bloat there. every other harness gets the trigger index + discovery pointers.
 	if (flavor !== 'claude-code') {

package/src/namespace.js

@@ -0,0 +1,181 @@
+// NAMESPACES — how a collection name is scoped, and how a reference splits back apart.
+//
+// A namespace is a slash-delimited prefix on a collection name: `health/doctors` is the collection
+// `doctors` in the namespace `health`, and its records live under `data/health/doctors/`. A
+// reference to one of those records is `health/doctors/dana-levi`.
+//
+// ⚠ THE WHOLE PROBLEM IN ONE LINE: an id is ALSO a slash-delimited path (`meetings/2026/07/kickoff`
+// is one collection and a three-segment id), so `a/b/c` is either collection `a` + id `b/c` or
+// collection `a/b` + id `c`, and nothing about the STRING says which.
+//
+// So namespaces are DECLARED, in the workspace package.json:
+//
+//     "dreamteamer": { "namespaces": ["health", "finance", "work/clients"] }
+//
+// and every split consults that closed set, longest match first. The alternative — inferring the
+// boundary from whichever collections happen to exist — was rejected: it makes the meaning of a
+// reference depend on the current descriptor set, so installing a module could silently re-point
+// references in records nobody edited. A declared list also turns the dangerous case (a namespace
+// whose name collides with a collection's) into a compile error instead of a longest-prefix win.
+//
+// The DEFAULT namespace is the empty prefix. `tasks/kickoff` is a reference into it, `data/tasks/`
+// is where it lives, and that is exactly what every workspace already has — which is why adopting
+// namespaces migrates nothing. `default` is reserved precisely so there is never a second spelling
+// for the same collection.
+//
+// This module is deliberately PURE — the declared list arrives as an argument. compile validates it
+// and writes it into the manifest; runtime.js hands it to the record layer. Nothing here reads a
+// file, so all of it is unit-testable without a workspace.
+
+/** Never a namespace: it would give the default namespace a second, prefixed spelling. */
+export const RESERVED_NAMESPACES = new Set(['default']);
+
+/** One segment of a namespace or collection name: the id-safe alphabet the rest of the engine uses. */
+const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The declared list, cleaned and ordered for prefix matching: de-duplicated, slash-trimmed, and
+ * sorted LONGEST FIRST so a nested namespace (`work/clients`) is tested before its parent (`work`).
+ * Order is the correctness property here, not a nicety — parent-first would claim `work/clients/acme`
+ * for the namespace `work`, making the collection `clients` and the id `acme` on a workspace where
+ * `work/clients` is the namespace and the collection is something else entirely.
+ */
+export function normalizeNamespaces(list) {
+	if (!Array.isArray(list)) return [];
+	const seen = new Set();
+	for (const raw of list) {
+		if (typeof raw !== 'string') continue;
+		const ns = raw.trim().replace(/^\/+|\/+$/g, '');
+		if (ns) seen.add(ns);
+	}
+	return [...seen].sort((a, b) => b.length - a.length || a.localeCompare(b));
+}
+
+/**
+ * Everything wrong with a declared list, as sentences — or `[]`. `collectionNames` is every compiled
+ * collection's qualified name, which is what makes the collision check possible at all.
+ *
+ * compile calls this and fails on a non-empty result. It is a separate function from the compiler so
+ * the rules can be tested directly, and so the error text lives beside the semantics it protects.
+ */
+export function namespaceProblems(namespaces, collectionNames = []) {
+	const problems = [];
+	const names = new Set(collectionNames);
+	for (const ns of namespaces) {
+		const segments = ns.split('/');
+		for (const seg of segments) {
+			if (RESERVED_NAMESPACES.has(seg)) {
+				problems.push(`namespace "${ns}": "${seg}" is reserved — the default namespace is the EMPTY prefix, so a collection in it is spelled \`tasks\`, never \`default/tasks\`.`);
+			} else if (!SEGMENT.test(seg)) {
+				problems.push(`namespace "${ns}": segment "${seg}" must be lowercase alphanumeric with single hyphens (it becomes a folder name and part of every reference).`);
+			}
+		}
+		// The collision that makes a slash-delimited namespace dangerous: with BOTH a namespace
+		// `health` and a collection `health`, the reference `health/doctors/dana-levi` is a record of
+		// collection `health/doctors` AND a record of collection `health` with the nested id
+		// `doctors/dana-levi`. Longest-match would silently pick the first and make the second
+		// unreferenceable. Refused up front instead.
+		if (names.has(ns)) {
+			problems.push(`namespace "${ns}" collides with the collection of the same name — a reference like "${ns}/x/y" would be ambiguous. Rename one.`);
+		}
+	}
+	return problems;
+}
+
+/** `health` + `doctors` → `health/doctors`; the default namespace (empty) → `doctors`. */
+export function qualify(namespace, name) {
+	const ns = String(namespace ?? '').replace(/^\/+|\/+$/g, '');
+	return ns ? `${ns}/${name}` : String(name);
+}
+
+/**
+ * The declared namespace a qualified collection name sits in, or `''` for the default namespace.
+ * Matched against the declared list rather than by cutting at the last slash, because a collection
+ * name is only namespaced if its prefix was actually declared — see `unqualifiedProblems`.
+ */
+export function namespaceOf(qualified, namespaces) {
+	for (const ns of namespaces) if (qualified.startsWith(ns + '/')) return ns;
+	return '';
+}
+
+/** The bare collection name inside its namespace: `health/doctors` → `doctors`. */
+export function baseNameOf(qualified, namespaces) {
+	const ns = namespaceOf(qualified, namespaces);
+	return ns ? qualified.slice(ns.length + 1) : qualified;
+}
+
+/**
+ * A collection name carrying a slash whose prefix is NOT declared, which is the silent-failure this
+ * whole module exists to prevent: every reference to it would split at the first slash, name a
+ * collection that does not exist, and dangle. Returns problems as sentences, or `[]`.
+ */
+export function unqualifiedProblems(collectionNames, namespaces) {
+	const problems = [];
+	for (const name of collectionNames) {
+		if (!name.includes('/')) continue;
+		if (namespaceOf(name, namespaces)) continue;
+		const guess = name.slice(0, name.lastIndexOf('/'));
+		problems.push(`collection "${name}" is namespaced, but "${guess}" is not declared — add it to \`dreamteamer.namespaces\` in package.json, or every reference to this collection will split at the first slash and dangle.`);
+	}
+	return problems;
+}
+
+/**
+ * Split a reference into `{ collection, id }`, or `null` when it is not a reference shape.
+ *
+ * THE one place the boundary is decided. Everything that parses a reference — the store's write-time
+ * check, `check`'s report, the extension's go-to-definition — goes through here, so a namespace can
+ * never mean one thing on write and another on read.
+ */
+export function parseRef(ref, namespaces = []) {
+	if (typeof ref !== 'string' || !ref) return null;
+	for (const ns of namespaces) {
+		if (!ref.startsWith(ns + '/')) continue;
+		const rest = ref.slice(ns.length + 1);
+		const slash = rest.indexOf('/');
+		// `health/doctors` alone names a COLLECTION, not a record — there is no id, so it is not a
+		// reference. Falling through to the unnamespaced split would call it collection `health`,
+		// which is the ambiguity this module refuses everywhere else.
+		if (slash < 1 || slash === rest.length - 1) return null;
+		return { collection: `${ns}/${rest.slice(0, slash)}`, id: rest.slice(slash + 1) };
+	}
+	const slash = ref.indexOf('/');
+	if (slash < 1 || slash === ref.length - 1) return null;
+	return { collection: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+
+/**
+ * The folder a collection's records belong in, workspace-relative and WITHOUT any module prefix
+ * (compile adds that for an `owns-data` module). The namespace becomes real directory nesting, which
+ * is the point: `health/doctors` lands in `data/health/doctors/` rather than beside `data/tasks/`.
+ */
+export function defaultStoragePath(qualified, namespaces, dataPath = 'data') {
+	const ns = namespaceOf(qualified, namespaces);
+	const base = ns ? qualified.slice(ns.length + 1) : qualified;
+	return ns ? `${dataPath}/${ns}/${base}` : `${dataPath}/${base}`;
+}
+
+/**
+ * Storage paths that swallow each other, as sentences — or `[]`. `entries` is `[{name, path}]`.
+ *
+ * ⚠ MEASURED DATA LOSS, not a hypothetical. Give collection A the path `data/health` and collection
+ * B `data/health/doctors`, and A's recursive walk indexes B's records as its own: `dt A list` prints
+ * B's records under A's name, `check` reports B's fields as unknown fields of A, and a write through
+ * A can overwrite a record of B. compile reported ✔ through all of it, because nothing ever compared
+ * two collections' paths. Namespaces make near-misses like this ordinary, so the check is no longer
+ * optional.
+ *
+ * Segment-wise on purpose: `data/health` must not flag `data/health-notes`.
+ */
+export function storageOverlaps(entries) {
+	const problems = [];
+	const sorted = [...entries].filter((e) => e.path).sort((a, b) => a.path.localeCompare(b.path));
+	for (const outer of sorted) {
+		for (const inner of sorted) {
+			if (outer === inner || outer.base !== inner.base) continue;
+			if (!inner.path.startsWith(outer.path + '/')) continue;
+			problems.push(`collection "${inner.name}" stores records under "${inner.path}", which is INSIDE "${outer.name}"'s folder "${outer.path}" — the outer collection would index the inner one's records as its own. Give one of them a folder of its own.`);
+		}
+	}
+	return problems;
+}