genesis-compiler 1.5.2 → 1.6.0

package/README.md

@@ -28,7 +28,8 @@ genesis/
   engineering.md     selected engineering profile and project-specific requirements
   stack.md           selected components, resources, verification, and project-owned operation contracts
   stack/             optional per-component Description, Guidance, Adoption, Post-change, and Deslop customization
-  program/           concise explanations grouped into conceptual subsystems
+  subsystems.md      authored responsibilities, Program membership, and data ownership/use
+  program/           concise public-operation explanations
 .agents/skills/
   genesis-*          Genesis workflow skills
   <technology>/      authoritative skills installed by selected Stack pieces
@@ -977,3 +978,60 @@ project operations, and records exact verification evidence. Code, tests, Git
 review, and the user's chosen agent remain responsible for implementation. It
 does not claim universal semantic convergence, exhaustive coverage, or
 whole-product correctness.
+
+## Authored subsystems (version zero)
+
+`genesis/subsystems.md` is the single authored map connecting architectural
+responsibilities to Program operations and data. Program directories are only
+navigation; Genesis never infers subsystem membership from them. Blueprint
+remains non-technical product intent. Source, migrations and runtime behavior
+remain evidence; the map does not define application behavior or database DDL.
+
+```markdown
+# Subsystems
+
+## `forms` Forms
+
+Owns reusable form authoring, rendering, and answer validation.
+
+### Program
+- `genesis/program/forms/render.md`
+
+### Data owned
+- Table `database` `default` `form_definitions`
+
+### Data used
+- Nothing.
+```
+
+Each subsystem has a unique lowercase hyphenated id, title, responsibility
+prose, and exactly the three shown sections. Each Program module is assigned
+exactly once, by its complete project-relative path. Each table has at most one
+owner. Data used names a table owned by another declared subsystem. Empty
+sections explicitly say `- Nothing.`; an empty initialized map contains
+`# Subsystems` followed by `- Nothing.`. Data-only and code-only subsystems are
+valid. No subsystem hierarchy is inferred from paths.
+
+Table references contain three distinct values: declared Stack resource **id**,
+schema, and table. `default` selects that resource's default schema; other schema
+names are literal. Never put host database names or environment values here.
+Genesis validates declarations and resource references without opening a database.
+Hosts resolve table references against their inspected schema and show missing
+references and unassigned tables explicitly; the map is not a complete schema
+inventory. Table/column descriptions and relationships remain database metadata.
+
+`inspectSubsystems({ projectRoot })` and `genesis inspect subsystems --json`
+return `genesis.subsystems.v0`, normalized entries, status and a deterministic
+identity. Program inspection additionally validates membership and referenced
+modules. Context includes the relevant subsystem through its Program Sources;
+`context .` includes all subsystems. Program City uses authored titles and table
+associations, including data-only districts, and changes its hash when the map
+changes. Opening context stays concise; detailed associations load on demand.
+
+Adoption, Program refresh, work prompts, session guidance and installed workflow
+skills maintain the map alongside Program in the same turn. Review checks it
+read-only; Blueprint-only work leaves it alone. Ordinary private helper edits
+need no map change. Existing projects do not need a bulk update: missing or empty maps preserve
+Program access and instruct the agent to author the map from source before its
+next implementation task. Until then, operations have no declared subsystem;
+there is no folder-based compatibility reader or automatic ownership inference. Initialization creates an empty map without replacing one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genesis-compiler",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "type": "module",
   "description": "An agent-independent prompt, multi-language code-index, cleanup, and verification companion with project agent guidance.",
   "repository": {

package/prompts/adopt.txt

@@ -60,3 +60,18 @@ execute them. Finish with a clear inventory of what was imported, what remains
 unconfigured or blocked, and what would require a separately approved
 implementation port. Never claim the project is ready merely because Stack
 components were selected.
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/prompts/describe.txt

@@ -12,6 +12,21 @@ If the codebase is too large for one careful pass, use subagents as you judge
 appropriate, reconcile their findings, and remain responsible for one coherent
 result. Identify anything not inspected or genuinely uncertain.
 
-Edit only `genesis/blueprint.md` and explanatory Markdown below
+Edit only `genesis/blueprint.md`, `genesis/subsystems.md`, and explanatory Markdown below
 `genesis/program/`. Summarize every explanatory file created, updated, or
 removed.
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/prompts/program.txt

@@ -4,9 +4,24 @@ in complete Program-refresh mode.
 Explain the code that currently exists using the smallest useful
 subsystem-oriented Program. Read implementation, tests, Blueprint, and current
 Program material. Use Machine City as a navigation aid, then verify relevant
-source directly. Edit only explanatory Markdown below `genesis/program/`.
+source directly. Edit only `genesis/subsystems.md` and explanatory Markdown below `genesis/program/`.
 Delete stale or duplicate modules and do not edit code, tests, configuration,
 Blueprint, Stack, or `.genesis/`.
 
 When finished, summarize Program files created, updated, or removed and report
 genuine ambiguity.
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/prompts/review.txt

@@ -10,3 +10,5 @@ evidence from inference and state questions that require human intent.
 
 Do not edit any file. Return a concise report ordered by impact with exact file
 references, the evidence inspected, and the smallest sensible correction.
+
+Review `genesis/subsystems.md` responsibilities, Program membership, and data ownership/use against source and schema. Report missing, stale, or conflicting associations without editing them.

package/prompts/work.txt

@@ -38,3 +38,18 @@ explicit decision, and add the selection with the Genesis
 `stack add <piece...>` operation before relying on technology-specific
 operations. Do not end after only updating
 or summarizing the Blueprint while the Stack remains empty.
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/skills/genesis-program/SKILL.md

@@ -21,7 +21,8 @@ private design choice, or ambiguity into product intent.
 
 ## Program
 
-Organize Program beneath conceptual subsystem directories:
+Organize Program in readable directories; membership is declared only in
+`genesis/subsystems.md`, independently of directory names:
 
 ```text
 genesis/program/billing/invoices.md
@@ -64,3 +65,58 @@ The caller determines whether this is initial description, complete Program
 refresh, focused post-change reconciliation, Blueprint-only work, or read-only
 review. Respect the caller's edit boundary. Report ambiguity rather than
 inventing intent.
+
+## Subsystems
+
+Maintain `genesis/subsystems.md` alongside Program in description and refresh
+work. Blueprint-only work does not change the map; review remains read-only.
+The map is the authored association authority, but responsibilities and table
+references remain fallible explanations of application source and schema.
+
+Use this exact version-zero grammar:
+
+```markdown
+# Subsystems
+
+## `forms` Forms
+
+Owns reusable form rendering, validation, and submission capture.
+
+### Program
+- `genesis/program/forms/render.md`
+
+### Data owned
+- Table `database` `default` `form_definitions`
+
+### Data used
+- Nothing.
+```
+
+Use one stable lowercase hyphenated id and a human title per subsystem. Each
+entry needs responsibility prose and exactly the three sections shown. Empty
+sections say `- Nothing.`; a new empty map contains only `# Subsystems` and
+`- Nothing.`. Every Program module belongs to exactly one subsystem. No folder
+inference, globs, duplicated operations, or duplicated table owners.
+
+A table identity is three separate exact backticked values: the declared Stack
+resource id, schema, and table. `default` means the resource's default schema;
+use an explicit schema where applicable. Never record a host database name,
+credential, SQL expression, or environment value. Data used references a table
+owned by another declared subsystem. A subsystem may own data without Program
+operations, or operations without data. Read the real schema/migrations before
+assigning ownership; report uncertainty instead of inventing associations.
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/skills/genesis-project/SKILL.md

@@ -152,3 +152,20 @@ required inputs and resources, declared project operations, and focused evidence
 with what actually exists. Report files changed, checks actually run,
 anything not proven, and anything still requiring attention. Never claim that
 an unrun check passed or that passing checks prove the whole product.
+
+## Subsystem maintenance
+
+Maintain `genesis/subsystems.md` in the same implementation turn when a change
+adds, removes, or changes a subsystem responsibility, Program membership, or
+data ownership/use. Read the map before changing related code. Reuse existing
+subsystems unless a distinct responsibility is evidenced. Declare each Program
+module exactly once; folders do not determine membership. Keep table references
+grounded in schema/migrations; Genesis does not inspect databases. Private
+helper changes need no map edit when these associations remain unchanged.
+
+If `genesis/subsystems.md` is missing, or is empty in an existing explained
+application, create it from the actual source, schema, and existing Program
+before implementation. This is ordinary explanatory adoption, not a blocker or
+a reason to ask permission again. Preserve the existing Program and source;
+inspect the relevant responsibilities and complete the smallest truthful map.
+Initialization can create the empty file, but only the agent authors its meaning.

package/src/cli.js

@@ -14,6 +14,7 @@ import {
   inspectEngineering,
   inspectEnvironment,
   inspectStackSection,
+  inspectSubsystems,
   inspectProject,
   inspectSkills,
   installCodex,
@@ -62,6 +63,7 @@ const USAGE = `Usage:
   genesis context <path...>
   genesis index [function-or-path...]
   genesis migrate
+  genesis inspect subsystems
   genesis inspect environment
   genesis inspect project
   genesis inspect skills
@@ -182,12 +184,12 @@ function parseCommand(argv) {
   } else if (command === 'context' && operands.length === 0) {
     fail('CONTEXT_PATH_REQUIRED', 'Command context requires at least one project path.');
   } else if (command === 'inspect') {
-    const ordinaryInspection = operands.length === 1 && ['environment', 'project', 'skills'].includes(operands[0]);
+    const ordinaryInspection = operands.length === 1 && ['environment', 'project', 'skills', 'subsystems'].includes(operands[0]);
     const sectionInspection = operands.length >= 2 && operands[0] === 'section';
     if (!ordinaryInspection && !sectionInspection) {
       fail(
         'CLI_INSPECT_TARGET_REQUIRED',
-        'Command inspect requires project, environment, skills, or section <name>.',
+        'Command inspect requires project, environment, skills, subsystems, or section <name>.',
       );
     }
   } else if (command === 'hook' && (operands.length !== 1 || !['discover', 'session', 'turn'].includes(operands[0]))) {
@@ -272,7 +274,9 @@ function writeInspection(result) {
   line(process.stdout, `${title}: ${result.status}`);
   namedItems('Components', result.components);
   namedItems('Runtimes', result.runtimeRequirements);
-  if (result.inspection === 'environment') {
+  if (result.inspection === 'subsystems') {
+    namedItems('Subsystems', result.subsystems.map(({ id, title }) => `${id}: ${title}`));
+  } else if (result.inspection === 'environment') {
     namedItems('Public defaults', result.environmentDefaults.map(({ name, value }) => `${name}=${value}`));
     namedItems('Environment files', result.files.map(({ format, path: filePath }) => `${format}: ${filePath}`));
   } else if (result.inspection === 'section') {
@@ -511,7 +515,7 @@ async function execute({ command, operands, options }, { signal } = {}) {
         }),
       };
     }
-    const inspections = { environment: inspectEnvironment, project: inspectProject, skills: inspectSkills };
+    const inspections = { subsystems: inspectSubsystems, environment: inspectEnvironment, project: inspectProject, skills: inspectSkills };
     return {
       inspection: operands[0],
       ...await inspections[operands[0]]({ projectRoot, stackPackages }),

package/src/index/code-index.js

@@ -43,7 +43,7 @@ function subsystemId(value) {
 }
 
 function operationId(module) {
-  return `operation:${module.subsystem}/${module.name}`;
+  return `operation:${module.path}`;
 }
 
 function parentDirectory(value) {
@@ -70,18 +70,10 @@ function directoryRecords(paths) {
 }
 
 function subsystemRecords(subsystems) {
-  const paths = new Set();
-  for (const subsystem of subsystems) {
-    const segments = subsystem.split('/');
-    for (let count = 1; count <= segments.length; count += 1) {
-      paths.add(segments.slice(0, count).join('/'));
-    }
-  }
-  return [...paths].sort().map((subsystem) => ({
-    id: subsystemId(subsystem),
-    path: subsystem,
-    title: path.posix.basename(subsystem).replace(/-/gu, ' '),
-    parentId: subsystem.includes('/') ? subsystemId(parentDirectory(subsystem)) : null,
+  return subsystems.map((entry) => ({
+    id: subsystemId(entry.id), path: entry.id, title: entry.title,
+    description: entry.description, parentId: null,
+    dataOwned: entry.dataOwned, dataUsed: entry.dataUsed,
   }));
 }
 
@@ -195,7 +187,7 @@ async function programCity(projectRoot) {
       implementationMap: module.implementationMap,
       path: module.path,
       subsystem: module.subsystem,
-      districtId: subsystemId(module.subsystem),
+      districtId: module.subsystem === null ? null : subsystemId(module.subsystem),
       sources: module.sources,
       sourceFileIds: module.sources.map(fileId),
     }));
@@ -203,9 +195,9 @@ async function programCity(projectRoot) {
       schema: 'genesis.program-city.v1',
       schemaVersion: 1,
       status: program.status,
-      programHash: sha256(stableJson(operations)),
+      programHash: sha256(stableJson({ operations, subsystems: program.subsystemMap })),
       diagnostics: [],
-      districts: subsystemRecords(program.subsystems),
+      districts: subsystemRecords(program.subsystemMap.subsystems),
       buildings: operations,
       links: operations.flatMap((operation) => operation.sourceFileIds.map((targetId) => ({
         kind: 'implemented-by',

package/src/index/context.js

@@ -111,6 +111,11 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     '',
     'Use Program as a concise, fallible explanation. Code, tests, and runtime behavior remain the evidence.',
     '',
+    '## Relevant subsystems',
+    '',
+    ...(['missing', 'empty'].includes(program.subsystemMap?.status) ? ['The subsystem map needs authoring. Before implementation, create genesis/subsystems.md from source, schema, and existing Program; preserve existing explanations and do not infer ownership from folders.'] : []),
+    ...((program.subsystemMap?.subsystems || []).filter((entry) => targets.includes('') || modules.some((module) => module.subsystem === entry.id)).map((entry) => JSON.stringify(entry, null, 2))),
+    '',
     '## Relevant Program',
     '',
     ...programDetails,
@@ -147,6 +152,7 @@ export async function contextForProjectPaths({ paths, projectRoot, stackPackages
     status: 'ready',
     paths: targets,
     modules: moduleSources.map(({ source: _source, ...module }) => module),
+    subsystems: (program.subsystemMap?.subsystems || []).filter((entry) => targets.includes('') || modules.some((module) => module.subsystem === entry.id)),
     components: stack.components.map(({ id }) => id),
     engineeringProfile: engineering.profile.id,
     verificationCommands: stack.verificationCommands.map(({ label, argv }) => ({ label, argv })),

package/src/index/contracts.js

@@ -1,4 +1,5 @@
 export const GENESIS_CONTRACTS = Object.freeze({
+  subsystems: 'genesis.subsystems.v0',
   projectInspection: 'genesis.project-inspection.v1',
   templates: 'genesis.templates.v1',
   templateApplication: 'genesis.template-application.v1',

package/src/index/init.js

@@ -1,3 +1,4 @@
+import { SUBSYSTEMS_PATH, EMPTY_SUBSYSTEMS_SOURCE } from './subsystems.js';
 import { mkdir, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 
@@ -40,6 +41,7 @@ export async function initializeProject({ projectRoot, stackPackages = [] } = {}
   const projectFormat = await inspectProjectFormatAtRoot(root);
   requireCurrentProjectFormat(projectFormat, { allowUninitialized: true });
   const created = (await Promise.all([
+    createIfMissing(root, SUBSYSTEMS_PATH, EMPTY_SUBSYSTEMS_SOURCE),
     createIfMissing(root, BLUEPRINT_PATH, BLUEPRINT_SKELETON_SOURCE),
     createIfMissing(root, COLLABORATION_PATH, COLLABORATION_SKELETON_SOURCE),
     createIfMissing(root, ENGINEERING_PATH, ENGINEERING_SKELETON_SOURCE),

package/src/index/program.js

@@ -1,6 +1,7 @@
 import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 
+import { inspectSubsystems } from './subsystems.js';
 import { GenesisError } from './errors.js';
 import { isProjectContentPath, PROGRAM_ROOT } from './paths.js';
 import { normalizeRelative } from './utils.js';
@@ -55,16 +56,15 @@ function moduleIdentity(programPath) {
   const relative = programPath.slice(`${PROGRAM_ROOT}/`.length, -3);
   const normalized = normalizeRelative(relative);
   const segments = normalized.split('/');
-  if (segments.length < 2 || segments.some((segment) => !CONCEPT_NAME.test(segment))) {
+  if (segments.some((segment) => !CONCEPT_NAME.test(segment))) {
     throw new GenesisError(
       'PROGRAM_INVALID',
-      `Program module needs lowercase conceptual subsystem and operation names: ${programPath}.`,
+      `Program module needs lowercase path names: ${programPath}.`,
       { path: programPath },
     );
   }
   return {
     name: segments.at(-1),
-    subsystem: segments.slice(0, -1).join('/'),
   };
 }
 
@@ -136,8 +136,13 @@ function moduleContents(source, programPath) {
 
 export async function inspectProgram(projectRoot) {
   const { files, found } = await markdownFiles(projectRoot);
+  const subsystemMap = await inspectSubsystems({ projectRoot });
+  const assignments = new Map(subsystemMap.subsystems.flatMap((entry) => entry.program.map((file) => [file, entry.id])));
+  for (const file of assignments.keys()) {
+    if (!files.includes(file)) throw new GenesisError('SUBSYSTEMS_PROGRAM_MISSING', `Subsystem cites missing Program module: ${file}.`);
+  }
   if (!found || files.length === 0) {
-    return { status: 'missing', files: [], modules: [], subsystems: [] };
+    return { status: subsystemMap.status === 'valid' ? 'valid' : 'missing', files: [], modules: [], subsystems: subsystemMap.subsystems.map(({ id }) => id), subsystemMap };
   }
 
   const modules = [];
@@ -150,6 +155,7 @@ export async function inspectProgram(projectRoot) {
     }
     const identity = moduleIdentity(programPath);
     const contents = moduleContents(source, programPath);
+    if (subsystemMap.status === 'valid' && !assignments.has(programPath)) throw new GenesisError('SUBSYSTEMS_PROGRAM_UNASSIGNED', `Program module has no declared subsystem: ${programPath}.`);
     const { sources } = contents;
     for (const sourcePath of sources) {
       if (!sourcePath || !isProjectContentPath(sourcePath) || !await sourceExists(projectRoot, sourcePath)) {
@@ -164,7 +170,7 @@ export async function inspectProgram(projectRoot) {
       path: programPath,
       name: identity.name,
       sources,
-      subsystem: identity.subsystem,
+      subsystem: assignments.get(programPath) ?? null,
       title: contents.title,
       description: contents.description,
       publicContract: contents.publicContract,
@@ -176,6 +182,7 @@ export async function inspectProgram(projectRoot) {
     status: 'valid',
     files,
     modules,
-    subsystems: [...new Set(modules.map(({ subsystem }) => subsystem))].sort(),
+    subsystems: subsystemMap.subsystems.map(({ id }) => id),
+    subsystemMap,
   };
 }

package/src/index/project-inspection.js

@@ -16,6 +16,7 @@ import { readStack } from './stack.js';
 export const GENESIS_BOOTSTRAP_PATHS = Object.freeze([
   'genesis/version',
   'genesis/blueprint.md',
+  'genesis/subsystems.md',
   'genesis/stack.md',
   'genesis/collaboration.md',
   'genesis/engineering.md',

package/src/index/prompt.js

@@ -74,6 +74,7 @@ function programContext(program) {
   return {
     status: program.status,
     files: program.files,
+    subsystemMap: program.subsystemMap,
     subsystems: program.subsystems,
     modules: program.modules.map(({ path, name, sources, subsystem }) => ({
       path,
@@ -90,6 +91,7 @@ function startProgramContext(program) {
     status: program.status,
     subsystems: program.subsystems,
     moduleCount: program.modules.length,
+    subsystemMapStatus: program.subsystemMap?.status,
     ...(program.diagnostic ? { diagnostic: program.diagnostic } : {}),
   };
 }

package/src/index/session-context.js

@@ -149,6 +149,8 @@ export async function projectSessionContext({
     ...skills.diagnostics.map(({ message }) => `- Agent Skill maintenance: ${message}`),
     ...(skills.diagnostics.length > 0 ? ['- Skill inspection is read-only. Synchronization is an explicit source change; follow the current task authorization and host write boundary before running it.'] : []),
     '- After locating source, run `genesis context <path...>`; before adding a helper or public operation, run `genesis index <name-or-path...>` and reuse an existing owner.',
+    '- If genesis/subsystems.md is missing or empty in an existing explained application, author it from source, schema and existing Program before implementation. This is ordinary explanatory adoption, not a startup blocker; do not run tests or application commands merely to create the map.',
+    '- Read genesis/subsystems.md for declared subsystem responsibilities, Program membership, and data ownership/use. Maintain it in the same implementation turn when those facts change; reuse existing boundaries, verify source/schema, and never infer membership from folders.',
     '- Program is fallible explanation; code, tests, and runtime behavior remain evidence.',
     '- Keep Blueprint and affected Program explanations aligned with intentional observable product behavior in the same implementation turn. Private restructuring may need only source citations or no explanatory change.',
     '- Before reporting completion, compare the requested observable behavior, required inputs and resources, declared project operations, and focused evidence with what actually exists. State anything not proven.',

package/src/index/subsystems.js

@@ -0,0 +1,106 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { GenesisError } from './errors.js';
+import { normalizeRelative, sha256, stableJson } from './utils.js';
+
+export const SUBSYSTEMS_PATH = 'genesis/subsystems.md';
+export const EMPTY_SUBSYSTEMS_SOURCE = '# Subsystems\n\n- Nothing.\n';
+
+// Table identities are declarations, never database queries or SQL identifiers.
+export async function inspectSubsystems({ projectRoot = process.cwd() } = {}) {
+  projectRoot = (await gitContext(projectRoot)).repositoryRoot;
+  let source;
+  try { source = await readFile(path.join(projectRoot, SUBSYSTEMS_PATH), 'utf8'); }
+  catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return { contract: 'genesis.subsystems.v0', status: 'missing', path: SUBSYSTEMS_PATH, subsystems: [] };
+  }
+  const invalid = (message) => { throw new GenesisError('SUBSYSTEMS_INVALID', `${SUBSYSTEMS_PATH}: ${message}`); };
+  const lines = source.replace(/\r\n?/gu, '\n').trim().split('\n');
+  if (lines.shift() !== '# Subsystems') invalid('Expected # Subsystems.');
+  const subsystems = [];
+  let current;
+  let section;
+  const sections = new Set();
+  const finish = () => {
+    if (!current) return;
+    if (!current.description.trim() || sections.size !== 3) invalid(`Subsystem ${current.id} needs a responsibility and Program, Data owned, Data used sections.`);
+    current.description = current.description.trim();
+    subsystems.push(current);
+  };
+  const empty = lines.join('\n').trim() === '- Nothing.';
+  if (!empty && !lines.some((line) => line.trim())) invalid('An empty map must say - Nothing.');
+  if (!empty) for (const line of lines) {
+    if (!line.trim()) continue;
+    const heading = line.match(/^## `([a-z0-9]+(?:-[a-z0-9]+)*)` (\S.*)$/u);
+    if (heading) {
+      finish();
+      current = { id: heading[1], title: heading[2], description: '', program: [], dataOwned: [], dataUsed: [] };
+      section = null;
+      sections.clear();
+      continue;
+    }
+    if (!current) invalid('Expected a subsystem heading or - Nothing.');
+    const sectionHeading = line.match(/^### (Program|Data owned|Data used)$/u);
+    if (sectionHeading) {
+      section = { Program: 'program', 'Data owned': 'dataOwned', 'Data used': 'dataUsed' }[sectionHeading[1]];
+      if (sections.has(section)) invalid(`Duplicate ${sectionHeading[1]} section.`);
+      sections.add(section);
+      continue;
+    }
+    if (line.startsWith('#')) invalid(`Unexpected heading: ${line}`);
+    if (!section) { current.description += `${line}\n`; continue; }
+    if (line === '- Nothing.') {
+      if (current[section].length || current[`${section}Empty`]) invalid('Nothing must be the only section entry.');
+      current[`${section}Empty`] = true;
+      continue;
+    }
+    if (current[`${section}Empty`]) invalid('Nothing must be the only section entry.');
+    if (section === 'program') {
+      const match = line.match(/^- `([^`]+)`$/u);
+      if (!match || !/^genesis\/program\/[a-z0-9-]+(?:\/[a-z0-9-]+)*\.md$/u.test(match[1]) || normalizeRelative(match[1]) !== match[1]) invalid(`Invalid Program reference: ${line}`);
+      current.program.push(match[1]);
+    } else {
+      const match = line.match(/^- Table `([^`]+)` `([^`]+)` `([^`]+)`$/u);
+      if (!match) invalid(`Expected Table resource, schema, and table: ${line}`);
+      current[section].push({ resource: match[1], schema: match[2], table: match[3] });
+    }
+  }
+  finish();
+  const ids = new Set();
+  const programs = new Set();
+  const owners = new Map();
+  for (const subsystem of subsystems) {
+    if (ids.has(subsystem.id)) invalid(`Duplicate subsystem ${subsystem.id}.`);
+    ids.add(subsystem.id);
+    for (const key of ['program', 'dataOwned', 'dataUsed']) {
+      if (!subsystem[key].length && !subsystem[`${key}Empty`]) invalid(`${subsystem.id}: empty sections must say - Nothing.`);
+      delete subsystem[`${key}Empty`];
+      const entries = subsystem[key].map((entry) => JSON.stringify(entry));
+      if (new Set(entries).size !== entries.length) invalid(`${subsystem.id}: duplicate ${key} entry.`);
+    }
+    for (const file of subsystem.program) {
+      if (programs.has(file)) invalid(`Program operation has multiple owners: ${file}.`);
+      programs.add(file);
+    }
+    for (const table of subsystem.dataOwned) {
+      const key = JSON.stringify(table);
+      if (owners.has(key)) invalid(`Table has multiple owners: ${key}.`);
+      owners.set(key, subsystem.id);
+    }
+  }
+  const tables = subsystems.flatMap((entry) => [...entry.dataOwned, ...entry.dataUsed]);
+  if (tables.length) {
+    const stack = await readStack(projectRoot);
+    const resources = new Set(stack.resources.map(({ resource }) => resource.id));
+    for (const table of tables) if (!resources.has(table.resource)) invalid(`Undeclared Stack resource: ${table.resource}.`);
+  }
+  for (const subsystem of subsystems) for (const table of subsystem.dataUsed) {
+    const owner = owners.get(JSON.stringify(table));
+    if (!owner || owner === subsystem.id) invalid(`${subsystem.id}: Data used must reference a table owned by another declared subsystem.`);
+  }
+  return { contract: 'genesis.subsystems.v0', status: subsystems.length ? 'valid' : 'empty', path: SUBSYSTEMS_PATH,
+    identity: sha256(stableJson(subsystems)), subsystems };
+}

package/src/index.js

@@ -223,3 +223,5 @@ export async function syncSkills(options) {
     guidance: 'Review changed skills in the ordinary Git diff. An assistant that already loaded them needs its supported context refresh before using the new guidance.',
   };
 }
+
+export { inspectSubsystems } from './index/subsystems.js';