@limina-labs/momentum 0.30.2

package/core/commands/sync-docs.md

@@ -0,0 +1,81 @@
+Sync all relevant documents based on the active phase's history log.
+Token-efficient: reads history + 2 tiny indexes first, then only targeted files.
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch — sync
+> from YOUR lane's history log. `status.md` is the fallback and the
+> cross-lane overview. Never sync another active lane's history from here.
+
+## Steps
+
+### Step 1: Load history and indexes (cheap reads)
+- Resolve your phase from the current branch: a `phase-*` branch with a
+  matching `specs/phases/<branch>/` directory binds to that phase; fallback =
+  the `specs/status.md` Active Phase table
+- Read the history log → extract all entries:
+  - **Phase lane**: `specs/phases/<phase-bound-to-your-branch>/history.md`
+  - **No active phase** (ad-hoc work just shipped): the relevant
+    `specs/adhoc/<id>/record.md` (and `specs/adhoc/history.md` if present).
+    If there is no phase and no ad-hoc record, there is nothing to sync —
+    report "nothing to sync" and stop.
+- Read the `tags:` frontmatter of each `specs/phases/*/overview.md` (OKF bundle)
+- Read `specs/decisions/impact-map.md` (~3KB)
+
+### Step 2: Build targeted file list
+For each history entry:
+  - Extract Topics list
+  - Match each topic against phase `tags:` frontmatter → collect affected phase tasks.md files
+  - Look up each topic in the impact-map.md table → collect affected spec files/sections
+  - Deduplicate the combined list
+  - For monorepo: EXCLUDE files in `specs/architecture/`
+    (constitution — never auto-synced, only amended via formal process)
+  - **Multi-repo: PARTITION OUT cross-repo entries.** If a history entry has an
+    `Affects-specs:` path starting with `../` (or otherwise outside this repo),
+    add it to a separate "cross-repo" list. NEVER edit those files — you only
+    own this repo's docs.
+
+### Step 3: Show sync plan (ALWAYS show before touching anything)
+Present to user:
+  "Based on phase history, I will check and potentially update:
+  - [list of files]
+  Proceed? (yes/no)"
+
+**If any cross-repo entries were partitioned out in Step 2:** also show them
+under a "Cross-repo impact (NOT touching — sync the other repo manually)"
+heading, listing each `Affects-specs: ../...` path. Tell the user which repo
+they need to edit and which entries pointed there. Do NOT prompt for approval
+on cross-repo paths — they're informational only.
+
+If user says no → stop.
+
+### Step 4: Read and assess (targeted reads only)
+For each file in the list:
+  - Read only the relevant section
+  - Assess: does it need updating based on history entries?
+
+### Step 5: Make updates (one at a time, fully visible)
+For each file that needs updating:
+  - Show the user what will change
+  - Use the Edit tool to make the change
+
+### Step 6: Update phase metadata if scope changed
+If any [SCOPE_CHANGE] entries exist:
+  - Update the active phase's `overview.md` frontmatter `tags:` list
+  - Run `momentum okf index` to refresh the bundle listings
+
+### Step 7: Commit all changes
+```bash
+git add <all modified spec files>
+git commit -m "docs(phase-N): sync specs from phase history"
+```
+
+### Step 8: Confirm completion
+"Spec sync complete. Updated N files:
+- [list]
+Ready to run /complete-phase."
+
+## Safeguards
+- NEVER update files not in the targeted list
+- NEVER update `specs/architecture/` (monorepo only — constitution is read-only)
+- NEVER update files in another repo (paths starting with `../`) — you only own this repo's docs. Flag cross-repo entries to the user instead.
+- ALWAYS show the plan (Step 3) before making any edits
+- History entries are NEVER modified — only read

package/core/commands/systematic-debug.md

@@ -0,0 +1,46 @@
+Systematically isolate, reproduce, and resolve task execution failures.
+
+This recipe enforces the **3-strikes systematic debugging/retry budget** defined under the Autonomous Execution Contract. If validation fails for a task, execute the strikes sequentially:
+
+---
+
+## Strike 1 — Analyze and Adjust
+
+1.  **Analyze validation output**: Look closely at the stdout/stderr, stack trace, and exit code.
+2.  **Hypothesize the cause**: Identify if the failure is due to a simple syntax error, a missing import, incorrect pathing, or a basic logical gap.
+3.  **Adjust**: Implement the simple correction directly.
+4.  **Re-run validation**: Execute the group's verification command.
+    *   *Passes* → Check task `[x]` and proceed.
+    *   *Fails* → Proceed to **Strike 2**.
+
+---
+
+## Strike 2 — Reproduce and Isolate
+
+1.  **Write reproduction test**: Create a minimal unit test or a temporary scratch script that isolates the failing code path and reproduces the exact failure.
+2.  **Run isolation**: Run the reproduction case to confirm it fails in isolation.
+3.  **Implement isolation fix**: Fix the code under the reproduced test case.
+4.  **Verify isolation**: Confirm the reproduction case now passes.
+5.  **Re-run validation**: Execute the main group verification command.
+    *   *Passes* → Check task `[x]` and proceed. Clean up any temporary scratch scripts.
+    *   *Fails* → Proceed to **Strike 3**.
+
+---
+
+## Strike 3 — Re-Read and Reframe
+
+1.  **Re-read specs**: Completely stop coding. Re-read:
+    *   `specs/status.md` (to check active context)
+    *   `specs/phases/phase-N-*/overview.md` (to re-read goals and deliverables)
+    *   `specs/phases/phase-N-*/plan.md` (to review architectural choices)
+2.  **Identify gaps**: Figure out if the implementation approach is fundamentally incompatible with a spec constraint.
+3.  **Reframe**: Redesign the approach to align with specs.
+4.  **Draft proposed change**: Discuss the re-framed approach with the user in conversation. Do not write changes to specs.
+5.  **Obtain Approval**: Wait for user review before implementing the reframed code.
+
+---
+
+## See Also
+
+*   **Rule 12 (Verify Before Claim)**: Always run the actual verification command and capture output.
+*   **start-phase**: Automates end-to-end execution utilizing this debugging recipe on task failures.

package/core/commands/track.md

@@ -0,0 +1,54 @@
+Track a backlog item — bug, feature, tech debt, or enhancement.
+
+## Steps
+
+1. Read `specs/backlog/backlog.md` to find next available ID
+
+2. Determine item type:
+   - Bug → `BUG-NNN`
+   - Feature → `FEAT-NNN`
+   - Tech Debt → `TD-NNN`
+   - Enhancement → `ENH-NNN`
+
+3. Add row to appropriate table in `specs/backlog/backlog.md`:
+   - Priority: infer from urgency (default P2)
+   - Status: `open`
+   - Phase: target phase or `unscheduled`
+   - Detail: `—` for one-liners, `[→](details/{ID}.md)` if a detail file is created
+
+4. Decide: one-liner or detail file?
+
+   **One-liner (no detail file needed):**
+   - Clear, self-contained issue (< 2 sentences to describe)
+   - No design choices to make
+   - Single file or single function affected
+   - Fix is obvious from the description
+
+   **Detail file required (`specs/backlog/details/{ID}.md`):**
+   - Requires design or multiple options to evaluate
+   - Touches multiple files, commands, or systems
+   - Has a non-obvious implementation path
+   - Cross-cutting impact (affects other phases or specs)
+   - Estimated > 30 min of work
+
+   If a detail file is needed, create it now with: context, options considered, open questions.
+
+5. If P0, also update Critical Items table in `specs/status.md`
+
+6. Commit:
+   ```bash
+   git add specs/backlog/
+   git commit -m "docs(backlog): add {ID} - {short title}"
+   ```
+
+## Cross-repo backlog items
+
+`/track` operates on the current repo's `specs/backlog/`. The ecosystem
+layer (Phase 9) does NOT aggregate backlogs across member repos in
+Tier 1 — each repo's backlog stays authoritative for its own work. If
+an item's scope genuinely spans repos, file it in the repo that owns
+the most surface area and add a one-line cross-link from the others.
+
+For cross-repo features as a whole (vs. individual backlog items), use
+`/initiative create <slug>` — see the `/ecosystem` and `/initiative`
+command recipes.

package/core/commands/validate.md

@@ -0,0 +1,96 @@
+Check the spec structure health of the current momentum project.
+
+Run with no arguments for a fast index-first check, or pass `--deep` for a full scan.
+
+> **Which phase is yours (Rule 15):** the phase bound to your branch;
+> `status.md` is the fallback and the cross-lane overview. Validation checks
+> the whole board, not just your lane.
+
+## Default Mode (index-first)
+
+1. Read `specs/status.md` — verify required fields are present:
+   - `Last Updated`, `Current Phase`, `Latest Release`, `Health`
+   - Active Phase table exists. **"No active phase" is a VALID state** — a
+     single row reading `_(none)_` / `no active phase` (e.g. between phases, or
+     during ad-hoc `/hotfix` work) is NOT a failure. **Multiple rows are also
+     valid** — one row per active lane (Rule 15, concurrent workstreams). Only
+     flag a structurally missing/empty table.
+   - Report any missing fields as failures
+
+2. Read `specs/backlog/backlog.md` — verify all 4 section tables present:
+   - Bugs, Features, Tech Debt, Enhancements
+   - Report any missing table as a failure
+
+3. For each phase directory under `specs/phases/` (OKF bundle, ADR-0005):
+   - Verify all 4 files present: `overview.md`, `plan.md`, `tasks.md`, `history.md`
+   - Verify `overview.md` frontmatter carries `type: Phase` and a `status:`
+     (legacy projects may still have `specs/phases/index.json` instead —
+     recommend `momentum upgrade` to migrate)
+   - Report missing files or missing status frontmatter as failures
+
+4. Cross-check active phase consistency:
+   - If an active phase is named, its directory must exist and its
+     `overview.md` frontmatter must say `status: in-progress` — report
+     mismatch as a failure. With multiple active lanes (Rule 15), check EVERY
+     row: each row's branch must bind to an existing phase directory.
+   - If `Current Phase` is "none" / no active phase, **skip this check** (valid
+     between-phases state).
+
+4b. OKF conformance (delegates to the CLI):
+   - Run `momentum okf check` — report its violations as failures verbatim
+   - Run `momentum okf index` if listings are stale (safe — regenerates only
+     `specs/index.md`, `specs/phases/index.md`, `specs/decisions/index.md`)
+
+5. Check `.claude/commands/` for standard momentum commands:
+   - Required: `brainstorm-idea`, `brainstorm-phase`, `start-project`, `start-phase`,
+     `complete-phase`, `log`, `sync-docs`, `track`, `migrate`, `validate`, `hotfix`
+   - Report any missing commands as warnings (not failures — project may predate them)
+
+6. Report results:
+   ```
+   ✓ N checks passed
+   ✗ N issues found:
+     - specs/phases/phase-3-gap-fixes/overview.md: missing `status:` frontmatter
+     - specs/status.md: missing field "Latest Release"
+   ```
+
+## `--deep` Flag (full scan)
+
+Run all default mode checks, then additionally:
+
+7. Walk ALL directories under `specs/phases/` — flag any directory whose
+   `overview.md` lacks `status:` frontmatter as an untracked phase
+
+8. For each phase directory, read `tasks.md`:
+   - Extract all backlog ID references: `BUG-NNN`, `FEAT-NNN`, `TD-NNN`, `ENH-NNN`
+   - Verify each ID exists as a row in `specs/backlog/backlog.md`
+   - Report unresolved IDs as failures
+
+9. For each phase directory, read `history.md`:
+   - Verify each entry has all required fields: type tag `[TYPE]`, date in `YYYY-MM-DD`
+     format, `Topics:`, `Affects-phases:`, `Affects-specs:`, `Detail:`
+   - Report malformed entries (missing fields) as warnings
+
+10. Check `specs/changelog/` — for each phase whose `overview.md` frontmatter
+    says `status: complete`, verify at least one changelog file exists under
+    `specs/changelog/`
+    - Report completely absent changelog as a warning
+
+11. Swarm member integrity (Phase 17+, only when ecosystem context exists):
+    - For each `<ecosystem-root>/swarms/<id>/manifest.json`:
+      - Validate against `core/swarm/schema/manifest.schema.json` (load + structural check)
+      - Every `manifest.repos.<id>` must reference a real `ecosystem.json` member
+      - Each repo's `phase_slug` must point at an existing phase directory
+        in that member repo
+    - For every phase brief that carries swarm frontmatter (parsed via
+      `core/swarm/lib/brief.js`):
+      - `swarm:` must resolve to a real swarm manifest at the ecosystem root
+      - `wave:` must match the wave that swarm has assigned this repo
+      - `initiative:` must match the swarm manifest's `initiative` field
+      - Report mismatch as a failure
+    - For every swarm with `status: complete`, verify the initiative's
+      `Per-repo contributions` section lists all swarm members.
+    - Report unresolved swarm references as failures; report orphaned
+      brief frontmatter (swarm: refers to non-existent swarm) as failures.
+
+12. Append deep-scan results to the report before printing.

package/core/ecosystem/layout.md

@@ -0,0 +1,128 @@
+# Ecosystem Root: On-Disk Layout
+
+> A momentum **ecosystem** is a sibling git repo that coordinates a set
+> of related momentum-installed repos as one product. Reading this
+> file tells you everything about what lives where.
+
+## Layout
+
+```
+<ecosystem-root>/
+├── ecosystem.json        ← manifest (members, roles, dep edges)
+├── README.md             ← human-readable description + worked example
+├── initiatives/          ← cross-repo feature files
+│   ├── README.md
+│   ├── 0001-<slug>.md
+│   └── 0002-<slug>.md
+├── sessions/             ← daily activity logs
+│   ├── .gitkeep
+│   ├── 2026-06-07.md
+│   └── 2026-06-08.md
+├── .state/               ← runtime state (gitignored)
+│   ├── active-initiative ← contents = slug or empty
+│   └── last-session      ← contents = ISO date
+└── .gitignore            ← `.state/` plus standard noise
+```
+
+## File contracts
+
+### `ecosystem.json`
+Single source of truth for the ecosystem's membership and inter-repo
+edges. Schema: `core/ecosystem/schema/ecosystem.schema.json`. Validated
+on read.
+
+### `initiatives/NNNN-<slug>.md`
+Cross-repo feature record. Top YAML frontmatter block conforms to
+`core/ecosystem/schema/initiative.schema.json`. Body is markdown
+sections from the initiative template
+(`core/ecosystem/templates/initiative-template.md`):
+- **Why** — one paragraph
+- **Per-repo contributions** — per-member bullets
+- **Linked decisions** — ADR pointers (cross-repo OK)
+- **Deploy chronology** — timestamps, repos, SHAs
+- **Close** — populated by `momentum ecosystem initiative close`
+
+Numbering is monotonically increasing across the ecosystem. The
+filename slug is for human readability; the `id` integer is canonical.
+
+### `sessions/YYYY-MM-DD.md`
+One file per UTC date. Appended to atomically by the PostToolUse hook
+in each member repo. Header line (first write of the day) names the
+active initiative if any. Subsequent lines have the format:
+
+```
+HH:MMZ [<member-id>] <event-summary> (<context>)
+```
+
+Examples:
+```
+03:24Z [sapience] commit 8a086117 — fix(memory): caller-accessible fanout
+04:30Z [sapience] deploy success — image_tag=8a086117
+09:50Z [sapience] PR #42 merged — list[T] query binding fix
+```
+
+### `.state/active-initiative`
+A single line, either empty or containing the slug of the currently
+active initiative. Set by `momentum ecosystem initiative create`;
+cleared by `… close`. The session-log hook reads this to inject the
+"Active initiative: …" header line.
+
+### `.state/last-session`
+The ISO date of the most recent session file. Cheap cache so the hook
+doesn't re-stat every directory entry.
+
+## Discovery & limits
+
+The ecosystem root is **discovered** by walking up from `$PWD` (max 5
+parents by default) until a directory containing `ecosystem.json` is
+found. The resolution is memoized per session.
+
+**Configurable depth (ENH-022).** Override the parent-walk limit via
+the `MOMENTUM_MAX_PARENT_WALK` environment variable. Honored in both
+the JS path (`core/ecosystem/lib/index.js`, `core/ecosystem/lib/state.js`)
+and the shell path (`core/ecosystem/scripts/session-append.sh`).
+Non-numeric or negative values fall back to the default of 5.
+
+```
+MOMENTUM_MAX_PARENT_WALK=10 momentum ecosystem status
+```
+
+**Location-agnostic CLI (ENH-021).** `momentum ecosystem add`,
+`remove`, and `status` resolve the ecosystem root from CWD by default
+(via the walk-up above). Use `--ecosystem <path>` to override
+explicitly:
+
+```
+momentum ecosystem add ./client --ecosystem ../my-eco
+```
+
+**Concurrency (BUG-004).** Session-log writes are serialized via a
+`mkdir`-based lock per session file (atomic on POSIX filesystems,
+portable across macOS and Linux without depending on `flock`). Lock
+acquisition has a ~5s budget; on timeout the event is dropped
+silently rather than risking file corruption.
+
+## Conventions
+
+- The ecosystem layer **never writes** into a member repo's `specs/`.
+  It only writes to its own directories above. The single touch on a
+  member is one fenced line in its `CLAUDE.md` / `AGENTS.md`:
+  ```html
+  <!-- ecosystem:begin -->
+  > Member of `<name>` ecosystem at `../<name>`. See ecosystem.json.
+  <!-- ecosystem:end -->
+  ```
+- The ecosystem root is a normal git repo. `momentum ecosystem init`
+  runs `git init` and produces the initial commit; subsequent changes
+  are user-managed (the ecosystem doesn't enforce a workflow on itself
+  beyond the schema check).
+
+## What lives where
+
+| Question | File |
+|----------|------|
+| What repos are in this ecosystem? | `ecosystem.json` |
+| What are we shipping right now? | `.state/active-initiative` + `initiatives/<slug>.md` |
+| What happened today? | `sessions/<today>.md` |
+| What's the cross-repo dependency graph? | `ecosystem.json` `dependencies` |
+| Where does a member repo's per-repo planning live? | Inside that member's own `specs/` (unchanged) |

package/core/ecosystem/lib/index.js

@@ -0,0 +1,245 @@
+'use strict';
+
+/**
+ * Ecosystem helpers — pure, dependency-free.
+ *
+ * Provides four building blocks the rest of Phase 9 depends on:
+ *
+ *   - findRoot(startPath)        — locate the ecosystem root by walking up
+ *   - loadManifest(rootPath)     — read + parse ecosystem.json
+ *   - listMembers(manifest)      — convenience accessor
+ *   - validateManifest(obj)      — minimal schema check (no external deps)
+ *
+ * Schema validation is deliberately hand-rolled: momentum has a
+ * zero-dependency posture for the CLI (no ajv, no joi). The check
+ * is structural — type + required fields — and surfaces the first
+ * violation with a human-readable path. The full JSON Schema in
+ * `../schema/ecosystem.schema.json` remains the authoritative
+ * contract; this validator is its operational counterpart.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Default upper bound on parent-directory walk-up. Honored by both this
+// module's findRoot and core/ecosystem/scripts/session-append.sh. The
+// authoritative export lives in core/ecosystem/lib/state.js as of
+// Phase 10 (ENH-022); we keep MAX_WALK_DEPTH as a backward-compat alias.
+const MAX_PARENT_WALK_DEFAULT = 5;
+const MAX_WALK_DEPTH = MAX_PARENT_WALK_DEFAULT;
+const MANIFEST_FILENAME = 'ecosystem.json';
+
+function resolveMaxParentWalk() {
+  const raw = process.env.MOMENTUM_MAX_PARENT_WALK;
+  if (raw === undefined || raw === '') return MAX_PARENT_WALK_DEFAULT;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return MAX_PARENT_WALK_DEFAULT;
+  return Math.floor(n);
+}
+
+// Per-process cache: absolute-startPath-prefix → resolved root (or null)
+const rootCache = new Map();
+
+/**
+ * Walk up from `startPath` looking for a directory containing
+ * `ecosystem.json`. Returns the absolute root path or null.
+ * Bounded to `resolveMaxParentWalk()` parents (default 5, override via
+ * the `MOMENTUM_MAX_PARENT_WALK` env var) so a misconfigured caller
+ * can't scan the entire filesystem.
+ *
+ * Memoized: repeated calls with paths under the same root return
+ * instantly. Cache key is the absolute starting path.
+ */
+function findRoot(startPath) {
+  if (typeof startPath !== 'string' || startPath.length === 0) {
+    return null;
+  }
+  const abs = path.resolve(startPath);
+  if (rootCache.has(abs)) {
+    return rootCache.get(abs);
+  }
+  const maxDepth = resolveMaxParentWalk();
+  let current = abs;
+  for (let i = 0; i <= maxDepth; i++) {
+    const candidate = path.join(current, MANIFEST_FILENAME);
+    let stat;
+    try {
+      stat = fs.statSync(candidate);
+    } catch (_err) {
+      stat = null;
+    }
+    if (stat && stat.isFile()) {
+      rootCache.set(abs, current);
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break; // reached filesystem root
+    current = parent;
+  }
+  rootCache.set(abs, null);
+  return null;
+}
+
+/**
+ * Read + parse the manifest at `rootPath/ecosystem.json`.
+ * Throws on missing file or invalid JSON; caller decides recovery.
+ */
+function loadManifest(rootPath) {
+  if (typeof rootPath !== 'string' || rootPath.length === 0) {
+    throw new TypeError('loadManifest: rootPath must be a non-empty string');
+  }
+  const file = path.join(rootPath, MANIFEST_FILENAME);
+  const raw = fs.readFileSync(file, 'utf8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new SyntaxError(`Invalid JSON in ${file}: ${err.message}`);
+  }
+  return parsed;
+}
+
+/**
+ * Returns the members array, defaulting to [] if absent.
+ * Does not validate; assumes caller already passed validateManifest.
+ */
+function listMembers(manifest) {
+  if (!manifest || typeof manifest !== 'object') return [];
+  return Array.isArray(manifest.members) ? manifest.members : [];
+}
+
+/**
+ * Find a member by id. Returns the member object or null.
+ */
+function findMember(manifest, id) {
+  return listMembers(manifest).find((m) => m && m.id === id) || null;
+}
+
+/**
+ * Hand-rolled structural validation. Returns
+ *   { ok: true } on success
+ *   { ok: false, errors: [{ path, message }] } on failure.
+ *
+ * Catches every issue (does not bail on first); the caller can render
+ * a useful error report. Authoritative schema is
+ * `core/ecosystem/schema/ecosystem.schema.json` — keep them in sync.
+ */
+function validateManifest(obj) {
+  const errors = [];
+  const slug = /^[a-z][a-z0-9-]*$/;
+
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, errors: [{ path: '$', message: 'manifest must be a JSON object' }] };
+  }
+
+  // name
+  if (typeof obj.name !== 'string' || obj.name.length === 0) {
+    errors.push({ path: '$.name', message: 'required non-empty string' });
+  } else if (!slug.test(obj.name)) {
+    errors.push({ path: '$.name', message: 'must match /^[a-z][a-z0-9-]*$/' });
+  } else if (obj.name.length > 64) {
+    errors.push({ path: '$.name', message: 'must be at most 64 chars' });
+  }
+
+  // version
+  if (obj.version !== 1) {
+    errors.push({ path: '$.version', message: 'must be the integer 1 (no other schema version supported)' });
+  }
+
+  // created — optional, must be a valid ISO date if present
+  if (obj.created !== undefined) {
+    if (typeof obj.created !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(obj.created)) {
+      errors.push({ path: '$.created', message: 'must be an ISO-8601 date (YYYY-MM-DD)' });
+    }
+  }
+
+  // members
+  if (!Array.isArray(obj.members)) {
+    errors.push({ path: '$.members', message: 'required array' });
+  } else {
+    const seenIds = new Set();
+    obj.members.forEach((m, i) => {
+      const base = `$.members[${i}]`;
+      if (m === null || typeof m !== 'object' || Array.isArray(m)) {
+        errors.push({ path: base, message: 'must be an object' });
+        return;
+      }
+      if (typeof m.id !== 'string' || m.id.length === 0) {
+        errors.push({ path: `${base}.id`, message: 'required non-empty string' });
+      } else {
+        if (!slug.test(m.id)) errors.push({ path: `${base}.id`, message: 'must match slug pattern' });
+        if (m.id.length > 64) errors.push({ path: `${base}.id`, message: 'must be at most 64 chars' });
+        if (seenIds.has(m.id)) errors.push({ path: `${base}.id`, message: `duplicate member id "${m.id}"` });
+        seenIds.add(m.id);
+      }
+      if (typeof m.path !== 'string' || m.path.length === 0) {
+        errors.push({ path: `${base}.path`, message: 'required non-empty string' });
+      }
+      const validRoles = ['platform', 'client', 'library', 'infra', 'bench', 'other'];
+      if (!validRoles.includes(m.role)) {
+        errors.push({ path: `${base}.role`, message: `must be one of: ${validRoles.join(', ')}` });
+      }
+      if (m.owns !== undefined && !isArrayOfStrings(m.owns)) {
+        errors.push({ path: `${base}.owns`, message: 'must be array of strings' });
+      }
+      if (m.consumes !== undefined && !isArrayOfStrings(m.consumes)) {
+        errors.push({ path: `${base}.consumes`, message: 'must be array of strings' });
+      }
+    });
+  }
+
+  // dependencies — optional
+  if (obj.dependencies !== undefined) {
+    if (!Array.isArray(obj.dependencies)) {
+      errors.push({ path: '$.dependencies', message: 'must be array if present' });
+    } else {
+      const memberIds = new Set(
+        Array.isArray(obj.members) ? obj.members.map((m) => m && m.id).filter(Boolean) : [],
+      );
+      const validKinds = ['api-contract', 'library', 'deploy', 'build-time', 'other'];
+      obj.dependencies.forEach((d, i) => {
+        const base = `$.dependencies[${i}]`;
+        if (d === null || typeof d !== 'object' || Array.isArray(d)) {
+          errors.push({ path: base, message: 'must be an object' });
+          return;
+        }
+        if (typeof d.from !== 'string' || !memberIds.has(d.from)) {
+          errors.push({ path: `${base}.from`, message: 'must reference a known member id' });
+        }
+        if (typeof d.to !== 'string' || !memberIds.has(d.to)) {
+          errors.push({ path: `${base}.to`, message: 'must reference a known member id' });
+        }
+        if (!validKinds.includes(d.kind)) {
+          errors.push({ path: `${base}.kind`, message: `must be one of: ${validKinds.join(', ')}` });
+        }
+      });
+    }
+  }
+
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+
+function isArrayOfStrings(v) {
+  return Array.isArray(v) && v.every((s) => typeof s === 'string');
+}
+
+/**
+ * Clear the findRoot memo cache. Tests use this; production code
+ * doesn't need to.
+ */
+function _clearRootCache() {
+  rootCache.clear();
+}
+
+module.exports = {
+  MAX_WALK_DEPTH,
+  MAX_PARENT_WALK_DEFAULT,
+  MANIFEST_FILENAME,
+  resolveMaxParentWalk,
+  findRoot,
+  loadManifest,
+  listMembers,
+  findMember,
+  validateManifest,
+  _clearRootCache,
+};