@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/runtime/inventory/precedence.js

@@ -0,0 +1,134 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The precedence resolver (design C4, contract IC-003 consumer, FR-004).
+ *
+ * Given a logical asset present at one or more scopes and the harness's recorded
+ * `scopePrecedence` block (`core/registry/harnesses.json`), names the copy the harness will load —
+ * or withholds that verdict and states why. This module is pure and synchronous: it looks at
+ * nothing on disk and reads no registry itself: the caller passes the one harness's precedence
+ * block, already loaded.
+ *
+ * **The winner is derived from `order` and `mode` together, never from either alone** (IC-003).
+ * An order alone is ambiguous between naming the winner first and naming it last, and the
+ * recorded corpus contains both conventions for the same field: `claude` records
+ * `["user","project"]` with `mode: "first-wins"` (the first entry, `user`, wins); `copilot`
+ * records `["project","user"]` with `mode: "last-wins"` (the *last* entry, `user`, wins — the same
+ * winner as `claude`, reached from the opposite order convention); `codex` records
+ * `["user","project"]` with `mode: "last-wins"` (the last entry, `project`, wins — a naive
+ * first-match reading of that same order would get it backwards).
+ *
+ * A `merged` mode means the copies are combined rather than chosen between, so no single copy
+ * "wins". An `unestablished` mode means the order may be documented (`gemini` documents one) or
+ * may not (`pi`, `antigravity` document neither), but either way the rule for choosing between
+ * copies is not — so no winner is named. Those two cases are separate states under IC-003 and the
+ * withheld reason says which: a documented order with an undocumented winner names the order it
+ * knows, an undocumented order says the order itself is unestablished. Neither may report as the
+ * other. All are withheld verdicts, never a guessed default
+ * (design A3: "if a default is later wanted, it becomes a recorded order with its basis stated,
+ * not an implicit fallback").
+ *
+ * An asset present at only one scope has no verdict to withhold and is not "shadowed" at all: it
+ * is reported plainly, with that one scope named as trivially where the harness's copy comes from,
+ * regardless of whether the harness has any precedence block, or what it says.
+ */
+
+/**
+ * @typedef {Object} ShadowVerdict The `SHADOW_VERDICT` entity of the feature's data model.
+ * @property {string[]} presentAt The scopes at which this logical asset has a recorded copy, in
+ *   the order given by the caller. Always at least one entry.
+ * @property {boolean} shadowed Whether more than one scope holds a copy of this asset. `false`
+ *   means there is exactly one copy and nothing to resolve between.
+ * @property {string|null} winner The scope whose copy the harness will load. Set to the sole
+ *   present scope when `shadowed` is `false`; set to the resolved scope when `shadowed` is `true`
+ *   and the precedence block names an unambiguous winner (`first-wins`/`last-wins`); `null` exactly
+ *   when `shadowed` is `true` and the verdict is withheld.
+ * @property {string|null} withheldReason Populated exactly when `winner` is `null`; states why no
+ *   winner is named. `null` in every other case, including the un-shadowed case, which never
+ *   withholds anything.
+ */
+
+/**
+ * Resolves the shadow verdict for one logical asset at one harness.
+ *
+ * @param {string[]} presentScopes The scopes at which a copy of this logical asset is recorded.
+ *   Order is not significant here — it is not read as a precedence order, only as "where does a
+ *   copy exist". Deduplicated internally; malformed entries (non-string, empty) are dropped.
+ * @param {Object|null|undefined} precedence The harness's recorded `scopePrecedence` block
+ *   (`core/registry/harnesses.json`), exactly as stored — at minimum `{ mode, order? }` — or
+ *   `null`/`undefined` when the harness has none recorded yet (IC-003's fifth state: the question
+ *   has not been asked). Never defaulted by this function.
+ * @returns {ShadowVerdict|null} `null` when `presentScopes` carries no usable scope name — there is
+ *   no asset to resolve a verdict for. Otherwise a `ShadowVerdict`.
+ */
+function resolveShadowVerdict(presentScopes     , precedence     )      {
+  const scopes = Array.isArray(presentScopes)
+    ? [...new Set(presentScopes.filter((scope     ) => typeof scope === 'string' && scope !== ''))]
+    : [];
+  if (scopes.length === 0) return null;
+
+  if (scopes.length === 1) {
+    return { presentAt: scopes, shadowed: false, winner: scopes[0], withheldReason: null };
+  }
+
+  // More than one scope holds a copy: a verdict is either named or withheld, never defaulted.
+  if (!precedence || typeof precedence !== 'object') {
+    return {
+      presentAt: scopes,
+      shadowed: true,
+      winner: null,
+      withheldReason: 'no scope-precedence is recorded for this harness',
+    };
+  }
+
+  const { mode, order } = precedence;
+
+  if (mode === 'merged') {
+    return {
+      presentAt: scopes,
+      shadowed: true,
+      winner: null,
+      withheldReason: 'the harness merges copies from every scope rather than choosing between them',
+    };
+  }
+
+  if (mode === 'unestablished') {
+    // IC-003 keeps these two states distinct: an order established with the mode explicitly
+    // unestablished (`gemini`) is not the same finding as an order sought and found undocumented
+    // (`pi`, `antigravity`). Both withhold the verdict; only one of them knows the reading order.
+    const orderIsEstablished = Array.isArray(order) && order.length > 0;
+    return {
+      presentAt: scopes,
+      shadowed: true,
+      winner: null,
+      withheldReason: orderIsEstablished
+        ? `the harness's consultation order is established (${order.join(' then ')}) but its rule for choosing between copies is not`
+        : "the harness's scope-resolution order is unestablished",
+    };
+  }
+
+  if (mode === 'first-wins' || mode === 'last-wins') {
+    if (!Array.isArray(order) || order.length === 0) {
+      return {
+        presentAt: scopes,
+        shadowed: true,
+        winner: null,
+        withheldReason: `the harness's precedence block records mode "${mode}" but no consultation order`,
+      };
+    }
+    const winner = mode === 'first-wins' ? order[0] : order[order.length - 1];
+    return { presentAt: scopes, shadowed: true, winner, withheldReason: null };
+  }
+
+  // An absent or unrecognized mode is never guessed at (IC-003: order alone is ambiguous).
+  return {
+    presentAt: scopes,
+    shadowed: true,
+    winner: null,
+    withheldReason: `the harness's precedence block records no usable resolution mode (got ${JSON.stringify(mode ?? null)})`,
+  };
+}
+
+module.exports = { resolveShadowVerdict };

package/src/runtime/inventory/read-scopes.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * C2 — dual-scope reader (FR-002, NFR-002).
+ *
+ * The rest of the CLI resolves scope once per invocation, as a boolean, and derives every root
+ * from it; a cross-scope report cannot be assembled that way. This module calls the existing
+ * scope-resolved lifecycle view twice — once per scope descriptor it constructs — and returns one
+ * snapshot per scope. It changes no other caller's scope handling and it reads only: nothing here
+ * writes, moves, or creates recorded state (NFR-001).
+ *
+ * Two constraints shape the interface:
+ *
+ * - **The global scope root is not an argument (design R7).** `registryLifecycleView` derives it
+ *   from `os.homedir()` whenever the scope descriptor carries `global: true`, and silently ignores
+ *   a `projectRoot` on that same descriptor. So this reader supplies only the project root; the
+ *   global root is inherited from the environment, which is correct at runtime. A test that needs
+ *   a synthetic global root must relocate `os.homedir` around the (synchronous) call.
+ * - **A scope with nothing recorded is a value, not a failure (NFR-002).** A repository never
+ *   installed into is the ordinary state, so its snapshot is returned empty and `recorded: false`
+ *   rather than raising, and reporting that absence creates no ledger on disk.
+ *
+ * Two further properties are load-bearing for the currency judgement downstream, because that
+ * judgement is read from the plan this module returns beside the resources:
+ *
+ * - **The restriction restricts the resources, not only the plan.** `targets` bounds the plan the
+ *   view computes, so a resource of an unrequested harness has no plan to be judged against. It is
+ *   therefore left out of the snapshot rather than returned beside a plan that never looked at it —
+ *   IC-001 makes `targets` a restriction to named harnesses, so a harness outside it is not part of
+ *   what was asked. Returning the whole ledger here made every unrequested harness's copy read as
+ *   current, which is the one thing this reader must not let a consumer conclude.
+ * - **The plan is computed with the selections the scope recorded.** `planLifecycle` gives each
+ *   harness the MCP servers handed to it for that harness, so an empty list is not a neutral
+ *   default: it is a positive statement that no server was chosen, and the plan then proposes to
+ *   remove every one the harness owns. `doflow reconcile` and `doflow status` derive each
+ *   harness's selection from the scope's own `doflow.lock` and ledger through
+ *   `recordedMcpSelections` (`src/install/mcp.js`); this reader calls the same function per scope,
+ *   so the plan a currency judgement is derived from is the plan the repair command would produce.
+ */
+
+const os = require('node:os');
+const { registryLifecycleView, LIFECYCLE_HARNESSES } = require('../../lifecycle/view.js');
+const { readLock } = require('../../state/lockfile.js');
+const { stateRoot, readLedger } = require('../../state/index.js');
+const { recordedMcpSelections } = require('../../install/mcp.js');
+const { readInstallManifest } = require('../../install/manifest.js');
+
+/**
+ * @typedef {Object} ScopeSnapshot The `SCOPE_SNAPSHOT` entity of the feature's data model.
+ * @property {'global'|'project'} scope Which scope was read.
+ * @property {string} scopeRoot The root that scope resolved to — home directory, or project root.
+ * @property {string} stateRoot The neutral state root beneath `scopeRoot`; may not exist on disk.
+ * @property {boolean} recorded Whether anything is recorded at this scope. Derived from the
+ *   ledger's contents rather than from the ledger file's existence, so a scope holding an empty
+ *   ledger and a scope holding no ledger at all report alike — both have nothing recorded. It
+ *   describes the **scope**, not the restriction: a scope holding a full install reports `true`
+ *   under a restriction that matches none of it, because "nothing is recorded here" would be false.
+ * @property {string[]} targets The harnesses this snapshot was read for — what `resources` is
+ *   restricted to, stated rather than left for a consumer to infer from the rows present.
+ * @property {Array<Object>} resources The `MANAGED_RESOURCE` records of the requested harnesses,
+ *   exactly as stored. Read only.
+ * @property {Object} ledger The whole neutral ledger, unrestricted, for consumers needing more than
+ *   the requested harnesses' resources.
+ * @property {Object} plan The lifecycle plan for this scope and these harnesses, already computed by
+ *   the view; it is what a currency judgement is derived from downstream.
+ */
+
+/** @returns {ScopeSnapshot} */
+function snapshot(scope     , view     , targets     )      {
+  const { ledger } = view;
+  const wanted = new Set(targets);
+  return {
+    scope,
+    scopeRoot: ledger.scopeRoot,
+    stateRoot: view.stateRoot,
+    recorded: ledger.resources.length > 0 || Object.keys(ledger.targets).length > 0,
+    targets,
+    resources: ledger.resources.filter((resource     ) => wanted.has(resource?.harness)),
+    ledger,
+    plan: view.plan,
+  };
+}
+
+/**
+ * Read the recorded state of both scopes within one invocation.
+ *
+ * @param {Object} options
+ * @param {Object} options.registry Registry loaded once by the caller and threaded through, as
+ *   every other lifecycle-view call site does.
+ * @param {string} options.repoRoot Root of the DoFlow source the view reads native sources from.
+ * @param {string} options.projectRoot Root of the project scope. The global scope's root is not a
+ *   parameter — see R7 above.
+ * @param {string[]} [options.targets] Harnesses to read. Defaults to every lifecycle harness,
+ *   which is what an inventory of the whole install wants. Both the plan and the returned resources
+ *   are restricted to these.
+ * @param {{global: Object|null, project: Object|null}} [options.locks] Lock documents per scope, for
+ *   a caller that already read them (the report reads them anyway, for repair coverage). Omitted,
+ *   each scope's lock is read from disk — `readLock` returns `null` for a scope with none, and a
+ *   scope with no lock is a normal value here, not a failure (NFR-002).
+ * @returns {{global: ScopeSnapshot, project: ScopeSnapshot, scopes: ScopeSnapshot[]}}
+ * @throws when a lock file exists but cannot be parsed. Propagated deliberately: the plan would be
+ *   computed from a selection nobody can read, so a currency judgement derived from it would be
+ *   fiction. `reconcile` fails on the same document.
+ */
+function readScopes({ registry, repoRoot, projectRoot, targets = LIFECYCLE_HARNESSES, locks }     )      {
+  const wanted = [...new Set(targets)];
+  const resolved = locks ?? {
+    // The global lock root is the home directory, the same root design R7 keeps out of this
+    // signature; `readLock` defaults to `os.homedir()`, so both halves agree without a parameter.
+    global: readLock({ scope: 'global' }),
+    project: readLock({ scope: 'project', projectRoot }),
+  };
+  const read = (scope     ) => {
+    // Each scope's own ledger, at the root the view itself reads it from.
+    const ledger = readLedger(scope === 'global'
+      ? stateRoot({ scope: 'global', homeDir: os.homedir() }) : stateRoot({ scope: 'project', projectRoot }));
+    const manifestServers = readInstallManifest({ scopeRoot: scope === 'global' ? os.homedir() : projectRoot })?.mcpServers ?? null;
+    const recorded = recordedMcpSelections({ registry, lock: resolved?.[scope] ?? null, ledger, targets: wanted, manifestServers });
+    return registryLifecycleView({
+      registry, repoRoot, targets: wanted, mcpSelections: recorded.selections, mcpAdoptable: recorded.adoptable,
+      scope: scope === 'global' ? { global: true } : { global: false, projectRoot },
+    });
+  };
+  const global = snapshot('global', read('global'), wanted);
+  const project = snapshot('project', read('project'), wanted);
+  return { global, project, scopes: [global, project] };
+}
+
+module.exports = { readScopes };

package/src/runtime/inventory/siblings.js

@@ -0,0 +1,192 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * C5 — sibling inspector (design C5, FR-007, R6).
+ *
+ * Reports files DoFlow does not manage that sit in a directory the harness loads **wholesale** —
+ * every file present becomes operative context — and that also holds a managed asset. Such a file
+ * is live context DoFlow did not put there, whatever it is called.
+ *
+ * **What this module deliberately does not report.** A directory the harness resolves **by name**
+ * is not inspected at all, not even to count its entries. There the harness loads the named file
+ * and nothing else, so a neighbouring file cannot take effect however it is named: a superseded
+ * `SKILL.md.pre-v1.2.0-backup-*` sitting beside `SKILL.md` is inert, and reporting it is noise.
+ * Within one scope DoFlow owns the path a same-named asset would occupy, so a same-scope name
+ * collision cannot arise either; genuine cross-scope outranking is FR-004's question, answered by
+ * `precedence.js`. This module therefore applies no filename heuristic whatsoever — in an inspected
+ * directory, presence is the whole test (requirement §9, 2026-09-27; design §9, C5).
+ *
+ * **The bound on cost (R6).** Only the parent directories of assets already enumerated from the
+ * ledger are read — one level, never recursed into. A managed tree that nests (Kiro's steering tree
+ * mirrors `core/shared/guidance/`, `rules/` and `mcp/` included) is still covered completely
+ * without a walk, because every subdirectory holding a managed file is itself the parent of a
+ * managed resource and so is inspected on its own account. `mcp-builder/` and `skill-creator/`
+ * sitting beside a managed skills directory are never enumerated: neither is the parent of a
+ * managed asset (requirement §5, "Out of Scope").
+ *
+ * Two hard rules follow directly from the design:
+ *   - No currency verdict is ever attached to a candidate (data-model `UNMANAGED_CANDIDATE`): there
+ *     is no recorded fingerprint for a file DoFlow does not manage, so it is reported as present,
+ *     never as diverged.
+ *   - Read-only throughout (NFR-001). Nothing here writes, moves, or deletes.
+ *
+ * Follows this repo's directory-reading idiom (`src/runtime/knowledge/index-store.js`): a bare
+ * `readdirSync(dir, { withFileTypes: true })` inside a try/catch that skips on failure. A managed
+ * asset's parent directory may legitimately not exist — a recorded resource whose file was since
+ * removed by hand — and that is not an error this read-only module raises.
+ */
+
+/**
+ * The asset/harness pairs whose native directory the harness loads wholesale.
+ *
+ * **Nothing in the registry declares load semantics.** This set is derived from adapter behaviour,
+ * read off two locators in this repository:
+ *
+ *   - `src/adapters/copy-tree.js` — the `copilot-rule-instructions` transform (line ~80) renders
+ *     *every* file it copies under an `applyTo: '**'` front-matter header, so every file landing in
+ *     `.github/instructions/` is always applied. Asset `instructions.copilot`, native dir
+ *     `instructions`.
+ *   - `src/adapters/kiro/index.js` (header comment, lines 8-12) — "Kiro receives DoFlow's *full*
+ *     guidance tree as steering files", with no single-file instruction surface at all. Asset
+ *     `guidance.context-layer` for the `kiro` harness only, native dir `steering`; the same asset's
+ *     `../.doflow/guidance` projection for claude/codex/gemini/antigravity is name-resolved by
+ *     explicit import and is not in this set.
+ *
+ * This is the single place to change. If the registry later declares load semantics per projection,
+ * replace this constant's contents with that lookup — do not add a second source of the fact, and
+ * do not infer it from a directory's name. An asset/harness pair absent here is name-resolved and
+ * its directory is skipped entirely.
+ *
+ * @type {Readonly<Object<string, ReadonlyArray<string>>>} harness id -> registry asset ids
+ */
+const WHOLESALE_ASSETS = Object.freeze({
+  copilot: Object.freeze(['instructions.copilot']),
+  kiro: Object.freeze(['guidance.context-layer']),
+});
+
+/**
+ * @typedef {Object} UnmanagedCandidate The `UNMANAGED_CANDIDATE` entity of the feature's data model.
+ * @property {string} name The entry's own filename, exactly as read from the directory.
+ * @property {string} path The entry's absolute path.
+ * @property {string} parentDir The absolute directory it was found in — a managed asset's own
+ *   parent, and one the harness loads wholesale.
+ * @property {'file'|'directory'} kind What the entry is. A `directory` is an unmanaged directory
+ *   inside a wholesale tree: its contents are loaded too, and were not enumerated because this
+ *   module does not recurse. A directory that itself holds a managed asset is not a candidate at
+ *   all — it is the managed tree's own structure.
+ * @property {string} harness The harness whose wholesale load makes this file operative.
+ * @property {string} assetId The registry asset whose directory it shares.
+ *
+ * No `currency` field exists on this shape, deliberately: an unmanaged file carries no recorded
+ * fingerprint, so it can never be judged to match or diverge from anything.
+ */
+
+/** Whether this harness loads this asset's native directory wholesale. `Array.isArray` also guards
+ * a harness id that collides with an `Object.prototype` key. */
+function loadsWholesale(harness     , assetId     )          {
+  const assets = (WHOLESALE_ASSETS       )[harness];
+  return Array.isArray(assets) && assets.includes(assetId);
+}
+
+/** Groups managed resources by parent directory. Every well-formed resource contributes its leaf
+ * filename (so a managed file is never mistaken for an unmanaged one) and its directory (so a
+ * subdirectory holding managed assets is recognised as structure, not as a foreign entry); only
+ * resources whose harness loads them wholesale contribute a `wholesale` target, and only a
+ * directory with at least one of those is ever read. */
+function groupByParentDir(resources     )      {
+  const byDir = new Map();
+  const managedDirs = new Set();
+  for (const resource of resources ?? []) {
+    const target = resource?.target;
+    if (typeof target !== 'string' || target === '') continue;
+    const dir = path.dirname(target);
+    managedDirs.add(dir);
+    if (!byDir.has(dir)) byDir.set(dir, { basenames: new Set(), wholesale: [] });
+    const entry = byDir.get(dir);
+    entry.basenames.add(path.basename(target));
+    if (loadsWholesale(resource.harness, resource.assetId)) {
+      entry.wholesale.push({ target, harness: resource.harness, assetId: resource.assetId });
+    }
+  }
+  return { byDir, managedDirs };
+}
+
+/** Whether a directory entry is part of the managed tree's own structure — it is, or contains at
+ * some depth, the parent directory of a managed resource. Scans `managedDirs`, which is bounded by
+ * the number of managed resources rather than by directory size (R6). */
+function holdsManagedAsset(candidatePath     , managedDirs     )          {
+  const prefix = candidatePath + path.sep;
+  for (const dir of managedDirs) {
+    if (dir === candidatePath || (dir          ).startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * Inspects the wholesale-loaded parent directories of already-enumerated managed resources for
+ * files DoFlow does not manage.
+ *
+ * @param {Object} options
+ * @param {Array<{harness: string, assetId: string, target: string}>} options.resources Managed
+ *   resources exactly as recorded — from one scope or both concatenated; this module does not care
+ *   which scope a resource came from, only where it lives on disk and how its harness loads it.
+ * @param {Object} [options.fsImpl] Injectable `node:fs`-shaped module, for hermetic tests.
+ * @returns {{
+ *   candidatesByTarget: Object<string, UnmanagedCandidate[]>,
+ *   directoriesInspected: number,
+ * }} `candidatesByTarget` maps a managed resource's absolute `target` to the unmanaged entries
+ *   sharing its directory (present only for targets whose directory held at least one);
+ *   `directoriesInspected` is how many wholesale directories actually existed and were read.
+ *
+ * **Nothing inspected is ever withheld, so no count of withheld entries is returned.** IC-002 names
+ * such a count, and this module used to return it as a literal 0 to satisfy that name. Under the
+ * narrowed FR-007 the two halves of this module's behaviour leave it no other value to hold: an
+ * inspected directory is read in full and every entry that is neither a managed basename nor
+ * managed structure is listed, and a directory that is not inspected is never read, so its entries
+ * are not inspected either. A field with one reachable value states nothing — and reporting 0
+ * beside eight reported siblings invited the reading that eight more had been hidden. IC-002's
+ * final field is dropped with it (task F.3); see `index.js#buildInventoryReport`.
+ */
+function inspectSiblings({ resources, fsImpl = fs }      = {})      {
+  const { byDir, managedDirs } = groupByParentDir(resources);
+  const candidatesByTarget      = {};
+  let directoriesInspected = 0;
+
+  for (const [dir, { basenames, wholesale }] of byDir) {
+    if ((wholesale         ).length === 0) continue; // name-resolved: never read, not even to count.
+
+    let entries;
+    try {
+      entries = fsImpl.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue; // the managed asset's parent legitimately may not exist; not an error.
+    }
+    directoriesInspected += 1;
+
+    const unmanaged        = [];
+    for (const entry of entries) {
+      const name = (entry       ).name;
+      if ((basenames               ).has(name)) continue; // the managed file itself.
+      const entryPath = path.join(dir          , name);
+      const isDirectory = (entry       ).isDirectory?.() === true;
+      if (isDirectory && holdsManagedAsset(entryPath, managedDirs)) continue; // managed structure.
+      unmanaged.push({ name, path: entryPath, parentDir: dir, kind: isDirectory ? 'directory' : 'file' });
+    }
+    if (unmanaged.length === 0) continue;
+
+    // Attributed per managed target rather than shared, so each candidate names the harness and
+    // asset whose wholesale load is the reason it is operative at all.
+    for (const { target, harness, assetId } of (wholesale         )) {
+      candidatesByTarget[target] = unmanaged.map((found     ) => ({ ...found, harness, assetId }));
+    }
+  }
+
+  return { candidatesByTarget, directoriesInspected };
+}
+
+module.exports = { inspectSiblings, WHOLESALE_ASSETS };

package/src/runtime/knowledge/chunker.js

@@ -0,0 +1,124 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Structure-aware markdown chunker. Chunks follow document
+// structure — frontmatter becomes metadata, headings bound sections, fenced code blocks never
+// split mid-block — because every downstream stage (indexing, ranking, prompting) inherits the
+// coherence this stage preserves. Character budgets approximate common token targets (~150-token
+// children ≈ 600 chars) without a tokenizer dependency: the corpus is
+// prose-dominant English/markdown, where chars/4 tracks tokens closely enough to rank with.
+
+const TARGET_CHUNK_CHARS = 600;
+const HARD_MAX_CHUNK_CHARS = 1200;
+
+/** Split raw markdown into chunks: {id, path, section, text}. Ids are stable path+ordinal pairs,
+ * not content hashes — the index manifest owns content addressing, and a chunk whose text changed
+ * should keep its identity so diffs are legible. */
+function chunkMarkdown(rawText     , { path: filePath }                    = {})        {
+  const { body, title } = stripFrontmatter(String(rawText ?? ''));
+  const sections = splitSections(body);
+  const chunks        = [];
+  let ordinal = 0;
+  for (const section of sections) {
+    for (const piece of packSection(section.text)) {
+      chunks.push({
+        id: `${filePath ?? 'memory'}#${ordinal}`,
+        path: filePath ?? null,
+        title: section.heading ? `${title ? `${title} › ` : ''}${section.heading}` : (title ?? null),
+        ordinal,
+        text: piece,
+      });
+      ordinal += 1;
+    }
+  }
+  return chunks;
+}
+
+function stripFrontmatter(text        )                                         {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+  if (!match) return { body: text, title: null };
+  const meta = match[1];
+  const titleMatch = /^title:\s*(.+)$/m.exec(meta) ?? /^#\s+(.+)$/m.exec(text.slice(match[0].length));
+  return { body: text.slice(match[0].length), title: titleMatch ? titleMatch[1].trim().replace(/^["']|["']$/g, '') : null };
+}
+
+/** Heading-bounded sections; a leading H1 is metadata (the title), not a section boundary. */
+function splitSections(body        )                                                  {
+  const lines = body.split(/\r?\n/);
+  const sections                                                  = [];
+  let current                                              = { heading: null, lines: [] };
+  const flush = () => {
+    if (current.lines.some((l) => l.trim() !== '')) {
+      sections.push({ heading: current.heading, text: current.lines.join('\n') });
+    }
+  };
+  for (const line of lines) {
+    const heading = /^(#{2,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      flush();
+      current = { heading: heading[2].trim(), lines: [] };
+      continue;
+    }
+    current.lines.push(line);
+  }
+  flush();
+  return sections.length ? sections : [{ heading: null, text: body }];
+}
+
+/** Group a section's blocks (paragraphs, lists, fenced code) into chunks near the target size.
+ * A block larger than the hard max (a long code fence) stands alone rather than being cut. */
+function packSection(text        )           {
+  const blocks = splitBlocks(text).filter((b) => b.trim() !== '');
+  const packed           = [];
+  let buffer = '';
+  for (const block of blocks) {
+    if (block.length > HARD_MAX_CHUNK_CHARS) {
+      if (buffer.trim()) packed.push(buffer.trim());
+      packed.push(block.trim());
+      buffer = '';
+      continue;
+    }
+    if (buffer && buffer.length + block.length + 2 > TARGET_CHUNK_CHARS) {
+      packed.push(buffer.trim());
+      buffer = block;
+    } else {
+      buffer = buffer ? `${buffer}\n\n${block}` : block;
+    }
+  }
+  if (buffer.trim()) packed.push(buffer.trim());
+  return packed;
+}
+
+/** Split into blocks at blank lines, keeping fenced code blocks intact across their blank lines. */
+function splitBlocks(text        )           {
+  const lines = text.split(/\r?\n/);
+  const blocks           = [];
+  let buffer           = [];
+  let fence                = null;
+  for (const line of lines) {
+    const opening = /^\s*(```|~~~)/.exec(line);
+    if (fence) {
+      buffer.push(line);
+      if (opening && opening[1] === fence) fence = null;
+      continue;
+    }
+    if (opening) {
+      if (buffer.some((l) => l.trim() !== '')) blocks.push(buffer.join('\n'));
+      buffer = [line];
+      fence = opening[1];
+      continue;
+    }
+    if (line.trim() === '' && !buffer.some((l) => l.trim() !== '')) continue;
+    if (line.trim() === '') {
+      blocks.push(buffer.join('\n'));
+      buffer = [];
+      continue;
+    }
+    buffer.push(line);
+  }
+  if (buffer.some((l) => l.trim() !== '')) blocks.push(buffer.join('\n'));
+  return blocks;
+}
+
+module.exports = { chunkMarkdown, TARGET_CHUNK_CHARS, HARD_MAX_CHUNK_CHARS };