@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/dist/core/links/corpus.js

@@ -1,42 +1,15 @@
-/**
- * WHICH documents loam reads links out of — the corpus, spelled once.
- *
- * Two readers need it and must not disagree. `commands/validate/links/` grades
- * each target's own documents for `link.unresolved`; `core/glossary/backlinks.ts`
- * reads the WHOLE fleet's, because "which documents use this term" is a question
- * no single target can answer. A corpus that differed between them would report
- * a term as unused while the very document citing it was being graded one target
- * over.
- *
- * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is
- * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam
- * WRITES them: a finding against generated prose names a defect its reader
- * cannot fix by editing, since the next `loam init` restores it. Their links are
- * loam's own problem, held on this side of the boundary by
- * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.
- *
- * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was
- * written down at all: an ADR that supersedes another says which, by linking to
- * it. They are also the first documents loam reads that it previously only
- * counted, which is what `link.unreadable` exists for.
- *
- * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.
- * The one thing a delta holds that addresses another file — `metadata { op }` —
- * has its own resolution and its own findings.
- */
-import { featureCapabilityDeltas } from "../capabilities/delta/tree.js";
-import { readCapabilityTree } from "../capabilities/tree.js";
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
 import { featureGlossary } from "../glossary/delta.js";
 import { readGlossary } from "../glossary/tree.js";
 import { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt } from "../repo/paths.js";
-import { capabilityDocsDir, glossaryDir } from "../repo/authored/paths.js";
+import { glossaryDir } from "../repo/authored/paths.js";
 import { featureSpecServices, listFeatures, listServices } from "../repo/repo.js";
 import { markdownFiles } from "../repo/tree/fs.js";
 /**
  * One service's authored documents: the two requirement specs, the runbook, and
- * every ADR. The specs cost nothing extra when a `FleetContext` is in play — it
- * has already read both to parse their requirements, and the memo hands back the
- * same text.
+ * every ADR. The specs cost nothing extra: the run's `FleetContext` has already
+ * read both to parse their requirements, and the memo hands back the same text.
  */
 export async function serviceDocuments(paths) {
     return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];
@@ -52,7 +25,7 @@ export async function featureDocuments(featureDir, fleet) {
         const spec = featureSpecPaths(featureDir, svc);
         docs.push(spec.spec, spec.archSpec);
     }
-    const capabilities = fleet === undefined ? await featureCapabilityDeltas(featureDir) : await fleet.featureCapabilityDeltas(featureDir);
+    const capabilities = await fleet.featureCapabilityDeltas(featureDir);
     docs.push(...capabilities.docs.map((d) => d.spec));
     // The definitions this feature introduces. Their own links are graded like
     // any other document's — a term that cites a term the feature is not adding
@@ -70,9 +43,7 @@ export async function featureDocuments(featureDir, fleet) {
  * the fleet repeated on every service target is the report.
  */
 export async function fleetDocuments(docsDir, fleet) {
-    const capabilities = fleet === undefined
-        ? await readCapabilityTree(capabilityDocsDir(docsDir))
-        : (await fleet.capabilities(docsDir)).tree;
+    const capabilities = (await fleet.capabilities(docsDir)).tree;
     const glossary = await readGlossary(glossaryDir(docsDir));
     return [
         ...(await markdownFiles(fleetAdrsDir(docsDir))),
@@ -89,7 +60,11 @@ export async function fleetDocuments(docsDir, fleet) {
  * describe a change that already shipped, its links point at whatever the tree
  * looked like then, and grading them would make every directory rename a
  * retroactive error against a record nobody may edit. `listFeatures` excludes
- * them by default, which is the same judgement one enumeration up.
+ * them by default, which is the same judgement one enumeration up. "Then" is
+ * the commit that archived the feature, and not the one before it: the archive
+ * re-expresses the links in the documents it moves (`movedMarkdown` below,
+ * `commands/archive/plan/document/links.ts`), because its own rename is the one
+ * change to the tree it knows exactly and makes in the same breath.
  */
 export async function allAuthoredDocuments(docsDir, fleet) {
     const docs = await fleetDocuments(docsDir, fleet);
@@ -101,4 +76,43 @@ export async function allAuthoredDocuments(docsDir, fleet) {
     }
     return docs;
 }
+/**
+ * Every `.md` file under `dir`, at any depth, sorted — the documents a rename
+ * of `dir` carries with it, which is a different list from the corpus above:
+ * a rename moves a runbook, a subsystem's own notes, a feature's
+ * `legacy/proposal.md` exactly as it moves an ADR, and owes them all the same
+ * link correction whether or not anything grades them.
+ *
+ * Real directories and files only: a symlink is not followed — what it points
+ * at is not moved by the rename — and dot-directories and `node_modules` are
+ * machinery, never authored documents, exactly as every other walk in loam
+ * treats them. The archive's own `.loam-before/` is one of them: its
+ * pre-images are bytes to put back, not documents to correct.
+ *
+ * Two callers, the two directory renames loam makes: `subsystem move`
+ * (`commands/subsystem/txn/links.ts`) and `archive`
+ * (`commands/archive/plan/document/links.ts`). Here, below both, because the
+ * rule for "what does the rename carry" is one rule.
+ */
+export async function movedMarkdown(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const entry of entries) {
+        const path = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!entry.name.startsWith(".") && entry.name !== "node_modules")
+                out.push(...(await movedMarkdown(path)));
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md")) {
+            out.push(path);
+        }
+    }
+    return out.sort();
+}
 //# sourceMappingURL=corpus.js.map

package/dist/core/links/corpus.js.map

@@ -1 +1 @@
-{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../src/core/links/corpus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WHICH documents loam reads links out of — the corpus, spelled once.\n *\n * Two readers need it and must not disagree. `commands/validate/links/` grades\n * each target's own documents for `link.unresolved`; `core/glossary/backlinks.ts`\n * reads the WHOLE fleet's, because \"which documents use this term\" is a question\n * no single target can answer. A corpus that differed between them would report\n * a term as unused while the very document citing it was being graded one target\n * over.\n *\n * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is\n * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam\n * WRITES them: a finding against generated prose names a defect its reader\n * cannot fix by editing, since the next `loam init` restores it. Their links are\n * loam's own problem, held on this side of the boundary by\n * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.\n *\n * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was\n * written down at all: an ADR that supersedes another says which, by linking to\n * it. They are also the first documents loam reads that it previously only\n * counted, which is what `link.unreadable` exists for.\n *\n * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.\n * The one thing a delta holds that addresses another file — `metadata { op }` —\n * has its own resolution and its own findings.\n */\nimport { featureCapabilityDeltas } from \"../capabilities/delta/tree.js\";\nimport { readCapabilityTree } from \"../capabilities/tree.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureGlossary } from \"../glossary/delta.js\";\nimport { readGlossary } from \"../glossary/tree.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt, type ServicePaths } from \"../repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir } from \"../repo/authored/paths.js\";\nimport { featureSpecServices, listFeatures, listServices } from \"../repo/repo.js\";\nimport { markdownFiles } from \"../repo/tree/fs.js\";\n\n/**\n * One service's authored documents: the two requirement specs, the runbook, and\n * every ADR. The specs cost nothing extra when a `FleetContext` is in play — it\n * has already read both to parse their requirements, and the memo hands back the\n * same text.\n */\nexport async function serviceDocuments(paths: ServicePaths): Promise<string[]> {\n  return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];\n}\n\n/**\n * One feature's authored documents: the intent, each addressed service's two\n * spec deltas, every ADR, and each capability delta document.\n */\nexport async function featureDocuments(featureDir: FeatureDir, fleet?: FleetContext): Promise<string[]> {\n  const paths = featurePaths(featureDir);\n  const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];\n  for (const svc of await featureSpecServices(featureDir, fleet)) {\n    const spec = featureSpecPaths(featureDir, svc);\n    docs.push(spec.spec, spec.archSpec);\n  }\n  const capabilities =\n    fleet === undefined ? await featureCapabilityDeltas(featureDir) : await fleet.featureCapabilityDeltas(featureDir);\n  docs.push(...capabilities.docs.map((d) => d.spec));\n  // The definitions this feature introduces. Their own links are graded like\n  // any other document's — a term that cites a term the feature is not adding\n  // is a broken join whether or not it has shipped yet.\n  docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));\n  return docs;\n}\n\n/**\n * The documents that belong to no service and no feature: the fleet's own\n * decision records, the living capability tree, and the glossary.\n *\n * Graded at fleet scope, so `validate --all` reports them once. A single-target\n * run says nothing about them — the rule `permissions.unenforced` and\n * `capability.invalid` already follow, and for the same reason: a finding about\n * the fleet repeated on every service target is the report.\n */\nexport async function fleetDocuments(docsDir: DocsDir, fleet?: FleetContext): Promise<string[]> {\n  const capabilities =\n    fleet === undefined\n      ? await readCapabilityTree(capabilityDocsDir(docsDir))\n      : (await fleet.capabilities(docsDir)).tree;\n  const glossary = await readGlossary(glossaryDir(docsDir));\n  return [\n    ...(await markdownFiles(fleetAdrsDir(docsDir))),\n    ...capabilities.docs.map((d) => d.spec),\n    ...glossary.terms.map((t) => t.path),\n  ];\n}\n\n/**\n * Every authored document in the repository — the union of the three above over\n * every service and every in-flight feature.\n *\n * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an\n * oversight. `features/archive/<FEAT>/` is the evolution history: its documents\n * describe a change that already shipped, its links point at whatever the tree\n * looked like then, and grading them would make every directory rename a\n * retroactive error against a record nobody may edit. `listFeatures` excludes\n * them by default, which is the same judgement one enumeration up.\n */\nexport async function allAuthoredDocuments(docsDir: DocsDir, fleet?: FleetContext): Promise<string[]> {\n  const docs = await fleetDocuments(docsDir, fleet);\n  for (const service of await listServices(docsDir, fleet)) {\n    docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));\n  }\n  for (const feature of await listFeatures(docsDir, {}, fleet)) {\n    docs.push(...(await featureDocuments(feature.dir, fleet)));\n  }\n  return docs;\n}\n"]}
+{"version":3,"file":"corpus.js","sourceRoot":"","sources":["../../../src/core/links/corpus.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * WHICH documents loam reads links out of — the corpus, spelled once.\n *\n * Two readers need it and must not disagree. `commands/validate/links/` grades\n * each target's own documents for `link.unresolved`; `core/links/backlinks.ts`\n * reads the WHOLE fleet's, because \"which documents use this term\" is a question\n * no single target can answer. A corpus that differed between them would report\n * a term as unused while the very document citing it was being graded one target\n * over. The two directory renames read it too — `subsystem move`\n * (`commands/subsystem/txn/links.ts`) and `archive`\n * (`commands/archive/plan/document/links.ts`) rewrite the links INTO what they\n * move from every document here — for the same reason from the other side: a\n * document `validate` grades that a rename did not relink is `link.unresolved`\n * the commit after.\n *\n * THE CORPUS IS EVERY AUTHORED MARKDOWN DOCUMENT, and the word doing the work is\n * authored. `AGENTS.md` and the scaffolded `README.md` are excluded because loam\n * WRITES them: a finding against generated prose names a defect its reader\n * cannot fix by editing, since the next `loam init` restores it. Their links are\n * loam's own problem, held on this side of the boundary by\n * `test/docs-facts.test.ts` and `test/package-docs.test.ts`.\n *\n * ADRs AND RUNBOOKS ARE IN IT, and they are the reason the convention was\n * written down at all: an ADR that supersedes another says which, by linking to\n * it. They are also the first documents loam reads that it previously only\n * counted, which is what `link.unreadable` exists for.\n *\n * `delta.likec4` IS NOT, and neither is any YAML: this is a markdown question.\n * The one thing a delta holds that addresses another file — `metadata { op }` —\n * has its own resolution and its own findings.\n */\nimport type { Dirent } from \"node:fs\";\nimport { readdir } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport { featureGlossary } from \"../glossary/delta.js\";\nimport { readGlossary } from \"../glossary/tree.js\";\nimport type { DocsDir, FeatureDir } from \"../kernel/ids/dirs.js\";\nimport { featurePaths, featureSpecPaths, fleetAdrsDir, servicePathsAt, type ServicePaths } from \"../repo/paths.js\";\nimport { glossaryDir } from \"../repo/authored/paths.js\";\nimport { featureSpecServices, listFeatures, listServices } from \"../repo/repo.js\";\nimport { markdownFiles } from \"../repo/tree/fs.js\";\n\n/**\n * One service's authored documents: the two requirement specs, the runbook, and\n * every ADR. The specs cost nothing extra: the run's `FleetContext` has already\n * read both to parse their requirements, and the memo hands back the same text.\n */\nexport async function serviceDocuments(paths: ServicePaths): Promise<string[]> {\n  return [paths.spec, paths.archSpec, paths.runbook, ...(await markdownFiles(paths.adrsDir))];\n}\n\n/**\n * One feature's authored documents: the intent, each addressed service's two\n * spec deltas, every ADR, and each capability delta document.\n */\nexport async function featureDocuments(featureDir: FeatureDir, fleet: FleetContext): Promise<string[]> {\n  const paths = featurePaths(featureDir);\n  const docs = [paths.intent, ...(await markdownFiles(paths.adrsDir))];\n  for (const svc of await featureSpecServices(featureDir, fleet)) {\n    const spec = featureSpecPaths(featureDir, svc);\n    docs.push(spec.spec, spec.archSpec);\n  }\n  const capabilities = await fleet.featureCapabilityDeltas(featureDir);\n  docs.push(...capabilities.docs.map((d) => d.spec));\n  // The definitions this feature introduces. Their own links are graded like\n  // any other document's — a term that cites a term the feature is not adding\n  // is a broken join whether or not it has shipped yet.\n  docs.push(...(await featureGlossary(featureDir)).terms.map((t) => t.path));\n  return docs;\n}\n\n/**\n * The documents that belong to no service and no feature: the fleet's own\n * decision records, the living capability tree, and the glossary.\n *\n * Graded at fleet scope, so `validate --all` reports them once. A single-target\n * run says nothing about them — the rule `permissions.unenforced` and\n * `capability.invalid` already follow, and for the same reason: a finding about\n * the fleet repeated on every service target is the report.\n */\nexport async function fleetDocuments(docsDir: DocsDir, fleet: FleetContext): Promise<string[]> {\n  const capabilities = (await fleet.capabilities(docsDir)).tree;\n  const glossary = await readGlossary(glossaryDir(docsDir));\n  return [\n    ...(await markdownFiles(fleetAdrsDir(docsDir))),\n    ...capabilities.docs.map((d) => d.spec),\n    ...glossary.terms.map((t) => t.path),\n  ];\n}\n\n/**\n * Every authored document in the repository — the union of the three above over\n * every service and every in-flight feature.\n *\n * ARCHIVED FEATURES ARE OUT, and the omission is the point rather than an\n * oversight. `features/archive/<FEAT>/` is the evolution history: its documents\n * describe a change that already shipped, its links point at whatever the tree\n * looked like then, and grading them would make every directory rename a\n * retroactive error against a record nobody may edit. `listFeatures` excludes\n * them by default, which is the same judgement one enumeration up. \"Then\" is\n * the commit that archived the feature, and not the one before it: the archive\n * re-expresses the links in the documents it moves (`movedMarkdown` below,\n * `commands/archive/plan/document/links.ts`), because its own rename is the one\n * change to the tree it knows exactly and makes in the same breath.\n */\nexport async function allAuthoredDocuments(docsDir: DocsDir, fleet: FleetContext): Promise<string[]> {\n  const docs = await fleetDocuments(docsDir, fleet);\n  for (const service of await listServices(docsDir, fleet)) {\n    docs.push(...(await serviceDocuments(servicePathsAt(service.dir))));\n  }\n  for (const feature of await listFeatures(docsDir, {}, fleet)) {\n    docs.push(...(await featureDocuments(feature.dir, fleet)));\n  }\n  return docs;\n}\n\n/**\n * Every `.md` file under `dir`, at any depth, sorted — the documents a rename\n * of `dir` carries with it, which is a different list from the corpus above:\n * a rename moves a runbook, a subsystem's own notes, a feature's\n * `legacy/proposal.md` exactly as it moves an ADR, and owes them all the same\n * link correction whether or not anything grades them.\n *\n * Real directories and files only: a symlink is not followed — what it points\n * at is not moved by the rename — and dot-directories and `node_modules` are\n * machinery, never authored documents, exactly as every other walk in loam\n * treats them. The archive's own `.loam-before/` is one of them: its\n * pre-images are bytes to put back, not documents to correct.\n *\n * Two callers, the two directory renames loam makes: `subsystem move`\n * (`commands/subsystem/txn/links.ts`) and `archive`\n * (`commands/archive/plan/document/links.ts`). Here, below both, because the\n * rule for \"what does the rename carry\" is one rule.\n */\nexport async function movedMarkdown(dir: string): Promise<string[]> {\n  let entries: Dirent[];\n  try {\n    entries = await readdir(dir, { withFileTypes: true });\n  } catch {\n    return [];\n  }\n  const out: string[] = [];\n  for (const entry of entries) {\n    const path = join(dir, entry.name);\n    if (entry.isDirectory()) {\n      if (!entry.name.startsWith(\".\") && entry.name !== \"node_modules\") out.push(...(await movedMarkdown(path)));\n    } else if (entry.isFile() && entry.name.endsWith(\".md\")) {\n      out.push(path);\n    }\n  }\n  return out.sort();\n}\n"]}

package/dist/core/links/findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/links/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `link.unresolved` — a markdown link in an authored document whose target is\n * not there, or is there under a different spelling.\n *\n * The convention this grades has been written down since the fleet-ADR work and\n * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing\n * validated it. This module is what makes that sentence false, and the reason\n * the convention was chosen is the reason it can: the target of a standard\n * markdown link is a real relative path, so \"does this resolve\" has a\n * filesystem answer, where a wikilink would need Obsidian's\n * shortest-unique-path search reimplemented — guessing, which loam does not do.\n *\n * ERROR, and the severity is the decision the maintainer took against the\n * alternative of warning outside `glossary/`. A link is a join of the same kind\n * as `Operations:` and `Covers:`, both of which error when they resolve to\n * nothing; the fact that this one is written in prose changes who typed it, not\n * whether it points at something. A fleet adopting loam with rotted links sees\n * them on its first run — a user-visible widening of the same class as the two\n * the use-case and business axes shipped, and recorded in CHANGELOG as one.\n *\n * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document\n * whose links have rotted is one editing session and one reviewer, not ten\n * separate breaches, and per-link findings would let a single stale directory\n * rename fill a `validate --all` report with the same fix restated.\n *\n * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second\n * reader needs the other half of the answer: the glossary grades a term by who\n * links TO it, which is this same walk read forwards instead of backwards.\n */\nimport { existsSync } from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { isPathInside } from \"../kernel/path-safety.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { pathCaseIndex, type PathCaseIndex } from \"./case.js\";\nimport { documentLinks, type DocumentLink } from \"./parse.js\";\n\n/** One authored document, and the text somebody already read out of it. */\nexport interface LinkedDocument {\n  /** Absolute path of the document — the directory every relative target resolves against. */\n  path: string;\n  text: string;\n}\n\n/** What the finding is filed under, and the tree it may look inside. */\nexport interface LinkScope {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  /**\n   * The directory-listing memo behind the case check, shared across a whole\n   * run by whoever owns the walk. Omitted, each call builds its own — correct,\n   * just not shared. Never a module-level cache: a listing that outlived one\n   * command would answer for a directory that has since changed.\n   */\n  cases?: PathCaseIndex;\n  /**\n   * Absolute paths that do not exist yet but WILL once an in-flight feature\n   * archives — today, the glossary terms that feature introduces.\n   *\n   * A feature cites the word it is adding at the word's FUTURE living path,\n   * because that is where the link has to point once the change lands; citing\n   * the delta's own path would resolve now and rot on the day it ships. Without\n   * this set, the axis would refuse its own headline case — which is exactly\n   * the overlay the capability axis had to add to `Realizes:` after shipping\n   * without one.\n   */\n  overlay?: ReadonlySet<string>;\n}\n\n/** A link that points at a real file inside the docs repo, and the file it points at. */\nexport interface ResolvedLink {\n  link: DocumentLink;\n  /** The absolute path the link names, as `node:path` resolves it. */\n  target: string;\n}\n\n/** One document's links, split by whether the docs repo answers for them. */\nexport interface DocumentLinkage {\n  resolved: ResolvedLink[];\n  /** Links inside the docs repo that name nothing — with the stored spelling, where there is one. */\n  broken: Array<{ link: DocumentLink; storedAs?: string }>;\n}\n\n/**\n * Every link in one document, resolved against the docs repo.\n *\n * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the\n * exclusion is honesty rather than leniency. A docs repo is routinely checked\n * out beside nothing else, so `../../payments-svc/README.md` is a path loam\n * cannot answer for: the file's absence here is evidence about this checkout,\n * not about the link. Only a target that stays inside `docsDir` gets a verdict,\n * which is the same boundary every other reader in loam observes and the reason\n * the finding below can afford to be an error at all.\n *\n * CASE COUNTS, and it must, because the alternative is a check that passes on\n * the author's machine and fails where the work is read. `existsSync` is\n * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI\n * runner are not. So a resolving link is one that exists AND is spelled the way\n * the filesystem stores it — and when it is not, `storedAs` carries the real\n * name into the message, on every platform alike, so the diagnosis does not\n * depend on which operating system ran the check.\n */\nexport function resolveLinks(doc: LinkedDocument, scope: LinkScope): DocumentLinkage {\n  const cases = scope.cases ?? pathCaseIndex();\n  const dir = dirname(doc.path);\n  const linkage: DocumentLinkage = { resolved: [], broken: [] };\n  for (const link of documentLinks(doc.text)) {\n    const target = resolve(dir, link.path);\n    if (!isPathInside(scope.docsDir, target)) continue;\n    // The overlay is checked FIRST and without the spelling test: the file is\n    // not on disk, so there is no stored name to compare against, and the id it\n    // came from was a `readdir` entry in the feature's own tree.\n    if (scope.overlay?.has(resolve(target)) === true) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    const storedAs = cases.storedAs(dirname(target), basename(target));\n    linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });\n  }\n  return linkage;\n}\n\n/** The links in one document that resolve to nothing, as at most one finding. */\nexport function unresolvedLinkFindings(doc: LinkedDocument, scope: LinkScope): Finding[] {\n  const where = repoPath(scope.docsDir, doc.path);\n  const { broken } = resolveLinks(doc, scope);\n  if (broken.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"link.unresolved\",\n      ...(scope.subject === undefined ? {} : { subject: scope.subject }),\n      message:\n        `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +\n        \"A link between documents here is a join — fix the path, or write the document it points at. \" +\n        \"Targets outside the docs repo and links to a heading (`#section`) are not graded.\",\n      details: broken.map((one) => detail(where, one)),\n    },\n  ];\n}\n\n/**\n * One broken link, spelled so the author can find it: the file and line first,\n * then the link exactly as written. `raw` rather than the decoded path, because\n * the decoded form is not the string that is in the document.\n *\n * The stored spelling is appended when the only thing wrong is case, because\n * without it the message reads as a lie — the file the author is being told to\n * write is already sitting beside the one they linked from.\n */\nfunction detail(where: string, one: { link: DocumentLink; storedAs?: string }): string {\n  const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;\n  return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;\n}\n"]}
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../../../src/core/links/findings.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `link.unresolved` — a markdown link in an authored document whose target is\n * not there, or is there under a different spelling.\n *\n * The convention this grades has been written down since the fleet-ADR work and\n * said, in both `SCHEMA.md` and the generated `AGENTS.md`, that nothing\n * validated it. This module is what makes that sentence false, and the reason\n * the convention was chosen is the reason it can: the target of a standard\n * markdown link is a real relative path, so \"does this resolve\" has a\n * filesystem answer, where a wikilink would need Obsidian's\n * shortest-unique-path search reimplemented — guessing, which loam does not do.\n *\n * ERROR, and the severity is the decision the maintainer took against the\n * alternative of warning outside `glossary/`. A link is a join of the same kind\n * as `Operations:` and `Covers:`, both of which error when they resolve to\n * nothing; the fact that this one is written in prose changes who typed it, not\n * whether it points at something. A fleet adopting loam with rotted links sees\n * them on its first run — a user-visible widening of the same class as the two\n * the use-case and business axes shipped, and recorded in CHANGELOG as one.\n *\n * ONE FINDING PER DOCUMENT, with every broken link in `details`. A document\n * whose links have rotted is one editing session and one reviewer, not ten\n * separate breaches, and per-link findings would let a single stale directory\n * rename fill a `validate --all` report with the same fix restated.\n *\n * THE RESOLUTION IS EXPORTED SEPARATELY from the finding, because a second\n * reader needs the other half of the answer: the glossary grades a term by who\n * links TO it, which is this same walk read forwards instead of backwards.\n */\nimport { existsSync } from \"node:fs\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { repoPath } from \"../envelope/json.js\";\nimport { isPathInside } from \"../kernel/path-safety.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport { pathCaseIndex, type PathCaseIndex } from \"./case.js\";\nimport { documentLinks, type DocumentLink } from \"./parse.js\";\n\n/** One authored document, and the text somebody already read out of it. */\nexport interface LinkedDocument {\n  /** Absolute path of the document — the directory every relative target resolves against. */\n  path: string;\n  text: string;\n}\n\n/** What the finding is filed under, and the tree it may look inside. */\nexport interface LinkScope {\n  docsDir: DocsDir;\n  /** The service or feature the report is about; absent at fleet scope. */\n  subject?: string;\n  /**\n   * The directory-listing memo behind the case check, shared across a whole\n   * run by whoever owns the walk. Omitted, each call builds its own — correct,\n   * just not shared. Never a module-level cache: a listing that outlived one\n   * command would answer for a directory that has since changed.\n   */\n  cases?: PathCaseIndex;\n  /**\n   * Absolute paths that do not exist yet but WILL once an in-flight feature\n   * archives — today, the glossary terms that feature introduces.\n   *\n   * A feature may cite the word it is adding at the word's FUTURE living path,\n   * because that is where the link points once the change lands. Without this\n   * set, the axis would refuse its own headline case — which is exactly the\n   * overlay the capability axis had to add to `Realizes:` after shipping\n   * without one. (Citing the term inside the feature resolves without it, and\n   * archive re-points that spelling when it merges the text that carries it —\n   * SCHEMA \"Conventions\" states the rule.)\n   */\n  overlay?: ReadonlySet<string>;\n}\n\n/** A link that points at a real file inside the docs repo, and the file it points at. */\nexport interface ResolvedLink {\n  link: DocumentLink;\n  /** The absolute path the link names, as `node:path` resolves it. */\n  target: string;\n}\n\n/** One document's links, split by whether the docs repo answers for them. */\nexport interface DocumentLinkage {\n  resolved: ResolvedLink[];\n  /** Links inside the docs repo that name nothing — with the stored spelling, where there is one. */\n  broken: Array<{ link: DocumentLink; storedAs?: string }>;\n}\n\n/**\n * Every link in one document, resolved against the docs repo.\n *\n * TARGETS OUTSIDE THE DOCS REPO ARE NEITHER RESOLVED NOR BROKEN, and the\n * exclusion is honesty rather than leniency. A docs repo is routinely checked\n * out beside nothing else, so `../../payments-svc/README.md` is a path loam\n * cannot answer for: the file's absence here is evidence about this checkout,\n * not about the link. Only a target that stays inside `docsDir` gets a verdict,\n * which is the same boundary every other reader in loam observes and the reason\n * the finding below can afford to be an error at all.\n *\n * CASE COUNTS, and it must, because the alternative is a check that passes on\n * the author's machine and fails where the work is read. `existsSync` is\n * case-insensitive on Windows and macOS; GitHub's renderer and every Linux CI\n * runner are not. So a resolving link is one that exists AND is spelled the way\n * the filesystem stores it — and when it is not, `storedAs` carries the real\n * name into the message, on every platform alike, so the diagnosis does not\n * depend on which operating system ran the check.\n */\nexport function resolveLinks(doc: LinkedDocument, scope: LinkScope): DocumentLinkage {\n  const cases = scope.cases ?? pathCaseIndex();\n  const dir = dirname(doc.path);\n  const linkage: DocumentLinkage = { resolved: [], broken: [] };\n  for (const link of documentLinks(doc.text)) {\n    const target = resolve(dir, link.path);\n    if (!isPathInside(scope.docsDir, target)) continue;\n    // The overlay is checked FIRST and without the spelling test: the file is\n    // not on disk, so there is no stored name to compare against, and the id it\n    // came from was a `readdir` entry in the feature's own tree.\n    if (scope.overlay?.has(resolve(target)) === true) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    if (existsSync(target) && cases.spelledExactly(scope.docsDir, target)) {\n      linkage.resolved.push({ link, target });\n      continue;\n    }\n    const storedAs = cases.storedAs(dirname(target), basename(target));\n    linkage.broken.push({ link, ...(storedAs === undefined ? {} : { storedAs }) });\n  }\n  return linkage;\n}\n\n/** The links in one document that resolve to nothing, as at most one finding. */\nexport function unresolvedLinkFindings(doc: LinkedDocument, scope: LinkScope): Finding[] {\n  const where = repoPath(scope.docsDir, doc.path);\n  const { broken } = resolveLinks(doc, scope);\n  if (broken.length === 0) return [];\n  return [\n    {\n      severity: \"error\",\n      code: \"link.unresolved\",\n      ...(scope.subject === undefined ? {} : { subject: scope.subject }),\n      message:\n        `${where}: ${broken.length} markdown link(s) resolve to nothing. ` +\n        \"A link between documents here is a join — fix the path, or write the document it points at. \" +\n        \"Targets outside the docs repo and links to a heading (`#section`) are not graded.\",\n      details: broken.map((one) => detail(where, one)),\n    },\n  ];\n}\n\n/**\n * One broken link, spelled so the author can find it: the file and line first,\n * then the link exactly as written. `raw` rather than the decoded path, because\n * the decoded form is not the string that is in the document.\n *\n * The stored spelling is appended when the only thing wrong is case, because\n * without it the message reads as a lie — the file the author is being told to\n * write is already sitting beside the one they linked from.\n */\nfunction detail(where: string, one: { link: DocumentLink; storedAs?: string }): string {\n  const line = `${where}:${one.link.line}: [${one.link.text}](${one.link.raw})`;\n  return one.storedAs === undefined ? line : `${line} — stored as '${one.storedAs}'`;\n}\n"]}

package/dist/core/links/parse.js

@@ -153,12 +153,29 @@ function decodePath(raw) {
  * It is a positional rewrite, never a re-render: the matched target's own span
  * is replaced and every other byte of the line — the link text, the title, the
  * prose around it — is left exactly as written.
+ *
+ * WHEN THE TARGET MOVES TOO, `retarget` says where to. The same archive that
+ * moves a requirement two directories up moves the rest of the feature as
+ * well: a term the feature defines is copied into `glossary/`, and the feature
+ * directory itself — its ADRs, its intent — goes to `features/archive/<FEAT>/`.
+ * A link into the feature re-expressed against the target's OLD place was
+ * therefore re-expressed correctly and still rotted on the commit that made it.
+ * And a document that does not move at all can still need rewriting, when the
+ * directory it links into does (`subsystem move`) — which is why `from === to`
+ * is no longer a reason to stop when a `retarget` is given.
+ *
+ * A LINK WHOSE TEXT STILL REACHES ITS TARGET FROM THE NEW PLACE KEEPS ITS
+ * SPELLING: a sibling that moves with its document, or a target nothing moved
+ * under a document that stays, comes out of the rewrite exactly as the author
+ * wrote it rather than normalised into `./` form by a commit that had no
+ * reason to touch it.
  */
 export function rebaseLinks(md, move) {
     const from = resolve(move.from);
     const to = resolve(move.to);
-    if (from === to)
+    if (from === to && move.retarget === undefined)
         return md;
+    const route = { from, to, retarget: move.retarget ?? ((target) => target) };
     const fenced = fenceTracker();
     // `split` with a capturing group keeps the separators, so a document's own
     // mixture of CRLF and LF survives a rewrite that touches neither.
@@ -167,19 +184,19 @@ export function rebaseLinks(md, move) {
         const rawLine = parts[i];
         if (fenced(rawLine))
             continue;
-        parts[i] = rebaseLine(rawLine, from, to);
+        parts[i] = rebaseLine(rawLine, route);
     }
     return parts.join("");
 }
 /** One line's links re-expressed, right to left so earlier spans keep their offsets. */
-function rebaseLine(rawLine, from, to) {
+function rebaseLine(rawLine, route) {
     const blanked = rawLine.replace(CODE_SPAN_RE, (m) => " ".repeat(m.length));
     const spans = [];
     const collect = (m) => {
         const at = m.indices?.[2];
         if (at === undefined)
             return;
-        const rebased = rebaseTarget(m[2], from, to);
+        const rebased = rebaseTarget(m[2], route);
         if (rebased !== null)
             spans.push([at[0], at[1], rebased]);
     };
@@ -198,16 +215,18 @@ function rebaseLine(rawLine, from, to) {
     return out;
 }
 /**
- * One target, re-expressed from `to` instead of `from`, or null when there is
- * nothing to re-express.
+ * One target, re-expressed from `to` instead of `from` — and pointed at wherever
+ * `retarget` says the file itself will be — or null when there is nothing to
+ * re-express.
  *
  * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a
  * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET
  * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that
  * silently changed `<a b.md>` into `a%20b.md` would be editing the author's
- * spelling under cover of moving their file.
+ * spelling under cover of moving their file. A route that comes out unchanged
+ * is null for the same reason (`rebaseLinks` says when that happens).
  */
-function rebaseTarget(target, from, to) {
+function rebaseTarget(target, route) {
     const angled = target.startsWith("<") && target.endsWith(">");
     const raw = angled ? target.slice(1, -1) : target;
     if (raw === "" || raw.startsWith("#") || raw.startsWith("/"))
@@ -220,7 +239,17 @@ function rebaseTarget(target, from, to) {
     if (pathPart === "")
         return null;
     const encoded = pathPart.includes("%");
-    let rebased = relative(to, resolve(from, decodePath(pathPart))).split(sep).join("/");
+    const was = resolve(route.from, decodePath(pathPart));
+    const will = resolve(route.retarget(was));
+    // The author's TEXT, read from the new place, still reaching the target —
+    // not two computed routes compared. A link that climbs above a moved
+    // directory and comes back down through its old name
+    // (`../../../services/payment-service/spec.md` from inside that service)
+    // normalises to the same route either side of the move, and comparing
+    // routes kept a spelling that names a directory the move just removed.
+    if (resolve(route.to, decodePath(pathPart)) === will)
+        return null;
+    let rebased = relative(route.to, will).split(sep).join("/");
     // `relative` returns a bare name for a sibling, which markdown reads as a
     // path relative to the file anyway — but `./` is what an author writes and
     // what keeps the link distinguishable from a reference label.

package/dist/core/links/parse.js.map

@@ -1 +1 @@
-{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/links/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every markdown link a document writes, as data.\n *\n * A link between documents in a docs repo is a JOIN, not decoration — a\n * requirement that names a domain term points at that term's definition, and an\n * ADR that supersedes another says which. `SCHEMA.md` and the generated\n * `AGENTS.md` have stated the convention (standard markdown links, relative\n * path targets) since the fleet-ADR work; this module is what finally reads\n * one, so `./findings.ts` can answer the only question the convention was\n * chosen for: does the target exist.\n *\n * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false\n * positive make the naive `\\[.*\\]\\(.*\\)` unusable on the documents loam owns,\n * and both occur in loam's OWN generated prose. A fenced block is where a\n * document SHOWS the convention — the `AGENTS.md` section that teaches the link\n * format contains a link nobody wrote to be followed — and an inline code span\n * is where prose quotes a path. Both must read as text. The fence rule is the\n * one `core/document/parse.ts` already applies to headings, and it is imported\n * rather than restated for the reason that module gives about its own sampler:\n * two readers disagreeing about what a fence encloses prescribe a document no\n * author can satisfy.\n */\nimport { relative, resolve, sep } from \"node:path\";\nimport { fenceTracker } from \"../kernel/fences.js\";\n\n/** One link written in a markdown document. */\nexport interface DocumentLink {\n  /** The target exactly as written, angle brackets stripped, fragment included. */\n  raw: string;\n  /**\n   * The FILE half — `raw` with any `#fragment` removed and percent-escapes\n   * decoded. This is what resolves against the filesystem; `raw` is what the\n   * finding quotes back, because that is the string the author has to find.\n   */\n  path: string;\n  /** The link text, or the reference label for a definition. Quoted in the finding. */\n  text: string;\n  /** 1-based line the link was written on. */\n  line: number;\n}\n\n/**\n * Inline links and images: `[text](target)`, `![alt](target)`,\n * `[text](<target with spaces>)`, `[text](target \"title\")`.\n *\n * The target alternation takes `<...>` first so an angle-bracketed path\n * containing spaces stays one token; the bare form stops at whitespace or `)`,\n * which gives up on the balanced-parens spelling markdown also allows\n * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody\n * writes, where over-reading would swallow the rest of a sentence and report a\n * target no author would recognise.\n */\nconst INLINE_RE = /!?\\[([^\\]]*)\\]\\(\\s*(<[^>\\n]*>|[^\\s)]*)(?:\\s+(?:\"[^\"]*\"|'[^']*'|\\([^)]*\\)))?\\s*\\)/gd;\n\n/**\n * A reference DEFINITION — `[label]: target \"title\"` on its own line. Included\n * because the target is the same join written in a different place: a document\n * that collects its links at the bottom is following the convention, and a\n * reader that only saw inline links would grade it as having none.\n */\nconst DEFINITION_RE = /^ {0,3}\\[([^\\]]+)\\]:\\s*(<[^>\\n]*>|\\S+)/d;\n\n/**\n * Code spans, blanked before matching. `\\`[a](b)\\`` is prose ABOUT a link and\n * resolving it would convict a document for explaining the convention. Blanked\n * to spaces rather than removed so every column after it — and therefore any\n * real link later on the same line — keeps its position.\n */\nconst CODE_SPAN_RE = /(`+)(?:[^`]|(?!\\1)`)*\\1/g;\n\n/**\n * Every link in `md`, in document order.\n *\n * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`\n * is not a link loam wrote a field for, and the alternative — teaching this\n * module where frontmatter ends — would make it read the one part of a document\n * loam's own doctrine says is structured. A link that resolves is a link that\n * resolves wherever it is written.\n */\nexport function documentLinks(md: string): DocumentLink[] {\n  const fenced = fenceTracker();\n  const out: DocumentLink[] = [];\n  md.split(/\\r?\\n/).forEach((rawLine, i) => {\n    if (fenced(rawLine)) return;\n    const line = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n    const definition = DEFINITION_RE.exec(line);\n    if (definition) {\n      push(out, definition[2]!, definition[1]!, i + 1);\n      return;\n    }\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {\n      push(out, m[2]!, m[1]!, i + 1);\n    }\n  });\n  return out;\n}\n\n/**\n * Record one link, unless its target is not a path this repository can answer\n * for. Four exclusions, each of them a question with no filesystem answer\n * rather than a link loam declines to grade:\n *\n * - an EMPTY target (`[text]()`) addresses nothing;\n * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses\n *   something outside this repository;\n * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved\n *   by whatever renders the document — a site root, not the file's directory —\n *   so loam does not know what it points at;\n * - a PURE fragment (`#section`) addresses this same document, and grading it\n *   means resolving heading anchors, which is a different question from \"does\n *   this file exist\".\n *\n * The last two are DEFENSIVE rather than decisive, and a mutation run says so:\n * removing either leaves every test green, because a pure fragment leaves an\n * empty path and a site-root target resolves outside the docs repo, where\n * `./findings.ts` declines to answer anyway. They are kept because the reason\n * differs from that boundary's — loam is not silent about these because they\n * are elsewhere, it is silent because it does not know where they are — and a\n * later reader deleting them as dead would be removing an intention, not a\n * branch.\n */\nfunction push(out: DocumentLink[], target: string, text: string, line: number): void {\n  const raw = target.startsWith(\"<\") && target.endsWith(\">\") ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return;\n  const path = decodePath(raw.split(\"#\")[0]!);\n  if (path === \"\") return;\n  out.push({ raw, path, text, line });\n}\n\n/**\n * Percent-decode a link target, or keep it verbatim when it does not decode.\n *\n * `[Order line](order%20line.md)` is how every editor writes a path holding a\n * space, so a resolver that skipped this step would report the one spelling\n * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a\n * literal percent in a filename is legal and rarer than the escape — and the\n * honest answer there is the string as written, which then resolves or does not\n * on its own terms.\n */\nfunction decodePath(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Re-express every relative link in `md` from a new base directory — the merge's\n * half of the link convention.\n *\n * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's\n * `specs/<svc>/spec.md` sits four directories below the docs root; the living\n * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a\n * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —\n * correct where it was written, and clickable in the pull request that reviewed\n * it — lands in the living document pointing two directories above the\n * repository. The same is true of a delta requirement citing an ADR, which has\n * been possible since before this module existed.\n *\n * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative\n * considered was to have authors write the link relative to where the text will\n * END UP, leaving loam to touch nothing — but that link does not resolve in the\n * delta, and \"it renders as a link in pull-request review, which is where these\n * documents are actually read\" is the convention's own first argument. So the\n * author writes what is true where they write it, and the merge makes it true\n * where it lands. The target is unchanged: only the route to it is.\n *\n * It is a positional rewrite, never a re-render: the matched target's own span\n * is replaced and every other byte of the line — the link text, the title, the\n * prose around it — is left exactly as written.\n */\nexport function rebaseLinks(md: string, move: { from: string; to: string }): string {\n  const from = resolve(move.from);\n  const to = resolve(move.to);\n  if (from === to) return md;\n  const fenced = fenceTracker();\n  // `split` with a capturing group keeps the separators, so a document's own\n  // mixture of CRLF and LF survives a rewrite that touches neither.\n  const parts = md.split(/(\\r?\\n)/);\n  for (let i = 0; i < parts.length; i += 2) {\n    const rawLine = parts[i]!;\n    if (fenced(rawLine)) continue;\n    parts[i] = rebaseLine(rawLine, from, to);\n  }\n  return parts.join(\"\");\n}\n\n/** One line's links re-expressed, right to left so earlier spans keep their offsets. */\nfunction rebaseLine(rawLine: string, from: string, to: string): string {\n  const blanked = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n  const spans: Array<[number, number, string]> = [];\n  const collect = (m: RegExpExecArray): void => {\n    const at = m.indices?.[2];\n    if (at === undefined) return;\n    const rebased = rebaseTarget(m[2]!, from, to);\n    if (rebased !== null) spans.push([at[0], at[1], rebased]);\n  };\n  const definition = DEFINITION_RE.exec(blanked);\n  if (definition) collect(definition);\n  else {\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked)) collect(m);\n  }\n  let out = rawLine;\n  for (const [start, end, replacement] of spans.reverse()) {\n    out = out.slice(0, start) + replacement + out.slice(end);\n  }\n  return out;\n}\n\n/**\n * One target, re-expressed from `to` instead of `from`, or null when there is\n * nothing to re-express.\n *\n * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a\n * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET\n * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that\n * silently changed `<a b.md>` into `a%20b.md` would be editing the author's\n * spelling under cover of moving their file.\n */\nfunction rebaseTarget(target: string, from: string, to: string): string | null {\n  const angled = target.startsWith(\"<\") && target.endsWith(\">\");\n  const raw = angled ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return null;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return null;\n  const hash = raw.indexOf(\"#\");\n  const pathPart = hash === -1 ? raw : raw.slice(0, hash);\n  const fragment = hash === -1 ? \"\" : raw.slice(hash);\n  if (pathPart === \"\") return null;\n  const encoded = pathPart.includes(\"%\");\n  let rebased = relative(to, resolve(from, decodePath(pathPart))).split(sep).join(\"/\");\n  // `relative` returns a bare name for a sibling, which markdown reads as a\n  // path relative to the file anyway — but `./` is what an author writes and\n  // what keeps the link distinguishable from a reference label.\n  if (rebased !== \"\" && !rebased.startsWith(\".\")) rebased = `./${rebased}`;\n  if (rebased === \"\") return null;\n  if (!angled && (encoded || rebased.includes(\" \"))) rebased = rebased.split(\" \").join(\"%20\");\n  const rewritten = rebased + fragment;\n  return angled ? `<${rewritten}>` : rewritten;\n}\n"]}
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../../src/core/links/parse.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Every markdown link a document writes, as data.\n *\n * A link between documents in a docs repo is a JOIN, not decoration — a\n * requirement that names a domain term points at that term's definition, and an\n * ADR that supersedes another says which. `SCHEMA.md` and the generated\n * `AGENTS.md` have stated the convention (standard markdown links, relative\n * path targets) since the fleet-ADR work; this module is what finally reads\n * one, so `./findings.ts` can answer the only question the convention was\n * chosen for: does the target exist.\n *\n * WHY A PARSER RATHER THAN A REGEX AT THE CALL SITE. Two classes of false\n * positive make the naive `\\[.*\\]\\(.*\\)` unusable on the documents loam owns,\n * and both occur in loam's OWN generated prose. A fenced block is where a\n * document SHOWS the convention — the `AGENTS.md` section that teaches the link\n * format contains a link nobody wrote to be followed — and an inline code span\n * is where prose quotes a path. Both must read as text. The fence rule is the\n * one `core/document/parse.ts` already applies to headings, and it is imported\n * rather than restated for the reason that module gives about its own sampler:\n * two readers disagreeing about what a fence encloses prescribe a document no\n * author can satisfy.\n */\nimport { relative, resolve, sep } from \"node:path\";\nimport { fenceTracker } from \"../kernel/fences.js\";\n\n/** One link written in a markdown document. */\nexport interface DocumentLink {\n  /** The target exactly as written, angle brackets stripped, fragment included. */\n  raw: string;\n  /**\n   * The FILE half — `raw` with any `#fragment` removed and percent-escapes\n   * decoded. This is what resolves against the filesystem; `raw` is what the\n   * finding quotes back, because that is the string the author has to find.\n   */\n  path: string;\n  /** The link text, or the reference label for a definition. Quoted in the finding. */\n  text: string;\n  /** 1-based line the link was written on. */\n  line: number;\n}\n\n/**\n * Inline links and images: `[text](target)`, `![alt](target)`,\n * `[text](<target with spaces>)`, `[text](target \"title\")`.\n *\n * The target alternation takes `<...>` first so an angle-bracketed path\n * containing spaces stays one token; the bare form stops at whitespace or `)`,\n * which gives up on the balanced-parens spelling markdown also allows\n * (`[x](a(1).md)`). That is a deliberate under-read: it costs a link nobody\n * writes, where over-reading would swallow the rest of a sentence and report a\n * target no author would recognise.\n */\nconst INLINE_RE = /!?\\[([^\\]]*)\\]\\(\\s*(<[^>\\n]*>|[^\\s)]*)(?:\\s+(?:\"[^\"]*\"|'[^']*'|\\([^)]*\\)))?\\s*\\)/gd;\n\n/**\n * A reference DEFINITION — `[label]: target \"title\"` on its own line. Included\n * because the target is the same join written in a different place: a document\n * that collects its links at the bottom is following the convention, and a\n * reader that only saw inline links would grade it as having none.\n */\nconst DEFINITION_RE = /^ {0,3}\\[([^\\]]+)\\]:\\s*(<[^>\\n]*>|\\S+)/d;\n\n/**\n * Code spans, blanked before matching. `\\`[a](b)\\`` is prose ABOUT a link and\n * resolving it would convict a document for explaining the convention. Blanked\n * to spaces rather than removed so every column after it — and therefore any\n * real link later on the same line — keeps its position.\n */\nconst CODE_SPAN_RE = /(`+)(?:[^`]|(?!\\1)`)*\\1/g;\n\n/**\n * Every link in `md`, in document order.\n *\n * The whole document is scanned, frontmatter included: a YAML `see: [x](y.md)`\n * is not a link loam wrote a field for, and the alternative — teaching this\n * module where frontmatter ends — would make it read the one part of a document\n * loam's own doctrine says is structured. A link that resolves is a link that\n * resolves wherever it is written.\n */\nexport function documentLinks(md: string): DocumentLink[] {\n  const fenced = fenceTracker();\n  const out: DocumentLink[] = [];\n  md.split(/\\r?\\n/).forEach((rawLine, i) => {\n    if (fenced(rawLine)) return;\n    const line = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n    const definition = DEFINITION_RE.exec(line);\n    if (definition) {\n      push(out, definition[2]!, definition[1]!, i + 1);\n      return;\n    }\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(line); m !== null; m = INLINE_RE.exec(line)) {\n      push(out, m[2]!, m[1]!, i + 1);\n    }\n  });\n  return out;\n}\n\n/**\n * Record one link, unless its target is not a path this repository can answer\n * for. Four exclusions, each of them a question with no filesystem answer\n * rather than a link loam declines to grade:\n *\n * - an EMPTY target (`[text]()`) addresses nothing;\n * - a SCHEME (`https:`, `mailto:`, and a Windows `C:` drive with it) addresses\n *   something outside this repository;\n * - a ROOT-relative or protocol-relative target (`/x`, `//host/x`) is resolved\n *   by whatever renders the document — a site root, not the file's directory —\n *   so loam does not know what it points at;\n * - a PURE fragment (`#section`) addresses this same document, and grading it\n *   means resolving heading anchors, which is a different question from \"does\n *   this file exist\".\n *\n * The last two are DEFENSIVE rather than decisive, and a mutation run says so:\n * removing either leaves every test green, because a pure fragment leaves an\n * empty path and a site-root target resolves outside the docs repo, where\n * `./findings.ts` declines to answer anyway. They are kept because the reason\n * differs from that boundary's — loam is not silent about these because they\n * are elsewhere, it is silent because it does not know where they are — and a\n * later reader deleting them as dead would be removing an intention, not a\n * branch.\n */\nfunction push(out: DocumentLink[], target: string, text: string, line: number): void {\n  const raw = target.startsWith(\"<\") && target.endsWith(\">\") ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return;\n  const path = decodePath(raw.split(\"#\")[0]!);\n  if (path === \"\") return;\n  out.push({ raw, path, text, line });\n}\n\n/**\n * Percent-decode a link target, or keep it verbatim when it does not decode.\n *\n * `[Order line](order%20line.md)` is how every editor writes a path holding a\n * space, so a resolver that skipped this step would report the one spelling\n * authors do not type by hand. `decodeURIComponent` throws on a lone `%` — a\n * literal percent in a filename is legal and rarer than the escape — and the\n * honest answer there is the string as written, which then resolves or does not\n * on its own terms.\n */\nfunction decodePath(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw;\n  }\n}\n\n/**\n * Re-express every relative link in `md` from a new base directory — the merge's\n * half of the link convention.\n *\n * THE DEFECT THIS CLOSES is structural and predates the glossary. A feature's\n * `specs/<svc>/spec.md` sits four directories below the docs root; the living\n * `services/<svc>/spec.md` it merges into sits two. `loam archive` copies a\n * requirement's text verbatim, so `[Order](../../../../glossary/order.md)` —\n * correct where it was written, and clickable in the pull request that reviewed\n * it — lands in the living document pointing two directories above the\n * repository. The same is true of a delta requirement citing an ADR, which has\n * been possible since before this module existed.\n *\n * REWRITING IS THE ONLY ANSWER THAT KEEPS BOTH PROPERTIES. The alternative\n * considered was to have authors write the link relative to where the text will\n * END UP, leaving loam to touch nothing — but that link does not resolve in the\n * delta, and \"it renders as a link in pull-request review, which is where these\n * documents are actually read\" is the convention's own first argument. So the\n * author writes what is true where they write it, and the merge makes it true\n * where it lands. The target is unchanged: only the route to it is.\n *\n * It is a positional rewrite, never a re-render: the matched target's own span\n * is replaced and every other byte of the line — the link text, the title, the\n * prose around it — is left exactly as written.\n *\n * WHEN THE TARGET MOVES TOO, `retarget` says where to. The same archive that\n * moves a requirement two directories up moves the rest of the feature as\n * well: a term the feature defines is copied into `glossary/`, and the feature\n * directory itself — its ADRs, its intent — goes to `features/archive/<FEAT>/`.\n * A link into the feature re-expressed against the target's OLD place was\n * therefore re-expressed correctly and still rotted on the commit that made it.\n * And a document that does not move at all can still need rewriting, when the\n * directory it links into does (`subsystem move`) — which is why `from === to`\n * is no longer a reason to stop when a `retarget` is given.\n *\n * A LINK WHOSE TEXT STILL REACHES ITS TARGET FROM THE NEW PLACE KEEPS ITS\n * SPELLING: a sibling that moves with its document, or a target nothing moved\n * under a document that stays, comes out of the rewrite exactly as the author\n * wrote it rather than normalised into `./` form by a commit that had no\n * reason to touch it.\n */\nexport function rebaseLinks(md: string, move: LinkMove): string {\n  const from = resolve(move.from);\n  const to = resolve(move.to);\n  if (from === to && move.retarget === undefined) return md;\n  const route: Route = { from, to, retarget: move.retarget ?? ((target) => target) };\n  const fenced = fenceTracker();\n  // `split` with a capturing group keeps the separators, so a document's own\n  // mixture of CRLF and LF survives a rewrite that touches neither.\n  const parts = md.split(/(\\r?\\n)/);\n  for (let i = 0; i < parts.length; i += 2) {\n    const rawLine = parts[i]!;\n    if (fenced(rawLine)) continue;\n    parts[i] = rebaseLine(rawLine, route);\n  }\n  return parts.join(\"\");\n}\n\n/** Where a document's text is moving, and where each file it links to will be. */\nexport interface LinkMove {\n  /** The directory the text was written in. */\n  from: string;\n  /** The directory the text will be read from. */\n  to: string;\n  /**\n   * Where a link's target will be once the same change lands: an absolute path\n   * in, an absolute path out, the input itself for a target that stays put.\n   * Omitted, every target stays put — the requirement merge's original case.\n   */\n  retarget?: (target: string) => string;\n}\n\n/** `LinkMove` with both directories resolved and the retarget defaulted — what each line is rewritten against. */\ninterface Route {\n  from: string;\n  to: string;\n  retarget: (target: string) => string;\n}\n\n/** One line's links re-expressed, right to left so earlier spans keep their offsets. */\nfunction rebaseLine(rawLine: string, route: Route): string {\n  const blanked = rawLine.replace(CODE_SPAN_RE, (m) => \" \".repeat(m.length));\n  const spans: Array<[number, number, string]> = [];\n  const collect = (m: RegExpExecArray): void => {\n    const at = m.indices?.[2];\n    if (at === undefined) return;\n    const rebased = rebaseTarget(m[2]!, route);\n    if (rebased !== null) spans.push([at[0], at[1], rebased]);\n  };\n  const definition = DEFINITION_RE.exec(blanked);\n  if (definition) collect(definition);\n  else {\n    INLINE_RE.lastIndex = 0;\n    for (let m = INLINE_RE.exec(blanked); m !== null; m = INLINE_RE.exec(blanked)) collect(m);\n  }\n  let out = rawLine;\n  for (const [start, end, replacement] of spans.reverse()) {\n    out = out.slice(0, start) + replacement + out.slice(end);\n  }\n  return out;\n}\n\n/**\n * One target, re-expressed from `to` instead of `from` — and pointed at wherever\n * `retarget` says the file itself will be — or null when there is nothing to\n * re-express.\n *\n * The exclusions are `push`'s exactly — an absolute URL, a site-root path and a\n * bare fragment mean the same thing from every directory — and the ANGLE-BRACKET\n * and PERCENT-ESCAPE forms are preserved rather than normalised: a rewrite that\n * silently changed `<a b.md>` into `a%20b.md` would be editing the author's\n * spelling under cover of moving their file. A route that comes out unchanged\n * is null for the same reason (`rebaseLinks` says when that happens).\n */\nfunction rebaseTarget(target: string, route: Route): string | null {\n  const angled = target.startsWith(\"<\") && target.endsWith(\">\");\n  const raw = angled ? target.slice(1, -1) : target;\n  if (raw === \"\" || raw.startsWith(\"#\") || raw.startsWith(\"/\")) return null;\n  if (/^[A-Za-z][A-Za-z0-9+.-]*:/.test(raw)) return null;\n  const hash = raw.indexOf(\"#\");\n  const pathPart = hash === -1 ? raw : raw.slice(0, hash);\n  const fragment = hash === -1 ? \"\" : raw.slice(hash);\n  if (pathPart === \"\") return null;\n  const encoded = pathPart.includes(\"%\");\n  const was = resolve(route.from, decodePath(pathPart));\n  const will = resolve(route.retarget(was));\n  // The author's TEXT, read from the new place, still reaching the target —\n  // not two computed routes compared. A link that climbs above a moved\n  // directory and comes back down through its old name\n  // (`../../../services/payment-service/spec.md` from inside that service)\n  // normalises to the same route either side of the move, and comparing\n  // routes kept a spelling that names a directory the move just removed.\n  if (resolve(route.to, decodePath(pathPart)) === will) return null;\n  let rebased = relative(route.to, will).split(sep).join(\"/\");\n  // `relative` returns a bare name for a sibling, which markdown reads as a\n  // path relative to the file anyway — but `./` is what an author writes and\n  // what keeps the link distinguishable from a reference label.\n  if (rebased !== \"\" && !rebased.startsWith(\".\")) rebased = `./${rebased}`;\n  if (rebased === \"\") return null;\n  if (!angled && (encoded || rebased.includes(\" \"))) rebased = rebased.split(\" \").join(\"%20\");\n  const rewritten = rebased + fragment;\n  return angled ? `<${rewritten}>` : rewritten;\n}\n"]}

package/dist/core/mcp/argv.js

@@ -1,3 +1,80 @@
+/**
+ * The MCP inputSchema for one tool: a closed object, so a typo'd argument
+ * refuses instead of vanishing, with the required set and the positional order
+ * `toArgv` enforces declared beside it.
+ */
+export function toInputSchema(tool) {
+    const properties = {};
+    for (const positional of tool.positionals) {
+        properties[positional.property] = positional.variadic
+            ? { type: "array", items: { type: "string" }, description: positional.description }
+            : { type: "string", description: positional.description };
+    }
+    for (const flag of tool.flags) {
+        properties[flag.property] =
+            flag.kind === "boolean"
+                ? { type: "boolean", description: flag.description }
+                : flag.kind === "strings"
+                    ? { type: "array", items: { type: "string" }, description: flag.description }
+                    : { type: "string", description: flag.description };
+    }
+    const required = [
+        ...tool.positionals.filter((p) => p.required).map((p) => p.property),
+        ...tool.flags.filter((f) => f.required === true).map((f) => f.property),
+    ];
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        ...orderRule(tool),
+        additionalProperties: false,
+    };
+}
+/**
+ * The rule `positionalTokens` enforces, declared: a positional after an
+ * optional one needs it, because positionals reach argv by position and the
+ * later value would otherwise be read in the earlier one's slot. Without it a
+ * client that validated `{name: "smoke"}` for `loam_list` against the schema
+ * it was given passed, and was then refused `-32602` by the server.
+ *
+ * Read off the declaration order rather than spelled per tool, so a tool that
+ * gains a positional after an optional one is declared the day it is refused.
+ * Each later positional needs every earlier OPTIONAL one; an earlier required
+ * one is in `required` already.
+ *
+ * Two keywords, because presence means two things. A scalar that is present
+ * always yields a token, so presence is the whole condition and
+ * `dependentRequired` says exactly that. A variadic yields tokens only when it
+ * has members: an empty one moves nothing into anybody's slot, and
+ * `positionalTokens` serves it — `{args: []}` with no `workflow` is the
+ * workflow list. `dependentRequired` there would forbid a call the server
+ * answers, the same disagreement turned the other way, so the variadic's rule
+ * sits under `dependentSchemas`: once it is present, either the earlier ones
+ * are too or it is empty. `anyOf` rather than `if`/`then`, which says the same
+ * but puts a `then` key on an object, and a thenable literal is one `await`
+ * away from being called.
+ */
+function orderRule(tool) {
+    const dependentRequired = {};
+    const dependentSchemas = {};
+    const earlier = [];
+    for (const positional of tool.positionals) {
+        if (earlier.length > 0 && positional.variadic) {
+            dependentSchemas[positional.property] = {
+                anyOf: [{ required: [...earlier] }, { properties: { [positional.property]: { maxItems: 0 } } }],
+            };
+        }
+        else if (earlier.length > 0) {
+            dependentRequired[positional.property] = [...earlier];
+        }
+        if (!positional.required)
+            earlier.push(positional.property);
+    }
+    return {
+        ...(Object.keys(dependentRequired).length > 0 ? { dependentRequired } : {}),
+        ...(Object.keys(dependentSchemas).length > 0 ? { dependentSchemas } : {}),
+    };
+}
 /**
  * A string value that argv would read as a flag is refused before any command
  * sees it: {"target": "--type"} must not become a parsed option. Commander
@@ -30,13 +107,30 @@ function checkedStrings(property, value) {
     }
     return { ok: true, tokens };
 }
+/**
+ * The positionals, in declaration order — and refused when one would land in
+ * another's slot.
+ *
+ * A positional reaches argv by POSITION, so an optional one left out leaves no
+ * gap: whatever follows it moves up into its place. `loam_list` with `{name:
+ * "services"}` built `list services` and answered ok:true with the services
+ * listing, a wrong answer with nothing in it saying so; `loam_instructions`
+ * with `{args: [...]}` and no `workflow` read the first arg as the workflow.
+ * Refused here instead, as the invalid-params problem a missing REQUIRED
+ * positional already is, naming the slot the caller left empty. A later
+ * positional that yields no token — an empty variadic — moves nothing up, so
+ * it passes. `orderRule` above declares the same rule in the advertised
+ * schema; the two change together.
+ */
 function positionalTokens(tool, args) {
     const tokens = [];
+    let absent;
     for (const positional of tool.positionals) {
         const value = args[positional.property];
         if (value === undefined) {
             if (positional.required)
                 return { ok: false, problem: `required argument '${positional.property}' is missing` };
+            absent ??= positional.property;
             continue;
         }
         const checked = positional.variadic
@@ -44,6 +138,13 @@ function positionalTokens(tool, args) {
             : checkedString(positional.property, value);
         if (!checked.ok)
             return checked;
+        if (absent !== undefined && checked.tokens.length > 0) {
+            return {
+                ok: false,
+                problem: `argument '${positional.property}' requires '${absent}' — positionals are read in order, ` +
+                    `so without '${absent}' this value would be read as '${absent}'`,
+            };
+        }
         tokens.push(...checked.tokens);
     }
     return { ok: true, tokens };

package/dist/core/mcp/argv.js.map

@@ -1 +1 @@
-{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../../src/core/mcp/argv.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How one MCP tool call's JSON arguments become an argv the CLI already\n * trusts — the boundary where an argument value could otherwise smuggle a\n * flag. The tool TABLE (what the tools are) lives in `./tools.ts`; this\n * module owns the crossing.\n */\nimport type { McpTool } from \"./tools.js\";\n\n/** One checked step of argv construction: the tokens it yields, or the invalid-params problem. */\ntype Checked =\n  | { readonly ok: true; readonly tokens: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\nexport type ArgvOutcome =\n  | { readonly ok: true; readonly argv: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\n/**\n * A string value that argv would read as a flag is refused before any command\n * sees it: {\"target\": \"--type\"} must not become a parsed option. Commander\n * cannot make this distinction after the fact — by then the token IS a flag —\n * so the boundary is here, on every string that crosses, array members\n * included. No shell is ever involved, so this is the only smuggling path.\n */\nfunction smuggled(property: string, value: string): string | null {\n  return value.startsWith(\"-\")\n    ? `argument '${property}' value '${value}' begins with '-' — a value argv would read as a flag is refused`\n    : null;\n}\n\n/** One string value checked for type and smuggling. */\nfunction checkedString(property: string, value: unknown): Checked {\n  if (typeof value !== \"string\") return { ok: false, problem: `argument '${property}' must be a string` };\n  const bad = smuggled(property, value);\n  return bad === null ? { ok: true, tokens: [value] } : { ok: false, problem: bad };\n}\n\n/** An array value checked member by member — rebuilt, not cast, so the claim is earned. */\nfunction checkedStrings(property: string, value: unknown): Checked {\n  if (!Array.isArray(value)) return { ok: false, problem: `argument '${property}' must be an array of strings` };\n  const tokens: string[] = [];\n  for (const entry of value) {\n    const checked = checkedString(property, entry);\n    if (!checked.ok) return checked;\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\nfunction positionalTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  for (const positional of tool.positionals) {\n    const value = args[positional.property];\n    if (value === undefined) {\n      if (positional.required) return { ok: false, problem: `required argument '${positional.property}' is missing` };\n      continue;\n    }\n    const checked = positional.variadic\n      ? checkedStrings(positional.property, value)\n      : checkedString(positional.property, value);\n    if (!checked.ok) return checked;\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\nfunction flagTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  for (const flag of tool.flags) {\n    const value = args[flag.property];\n    if (value === undefined) {\n      // The same refusal absent required positionals get: the client learns\n      // \"-32602 missing argument\", not an invalid-option envelope after the\n      // command already refused.\n      if (flag.required === true) return { ok: false, problem: `required argument '${flag.property}' is missing` };\n      continue;\n    }\n    if (flag.kind === \"boolean\") {\n      if (typeof value !== \"boolean\") return { ok: false, problem: `argument '${flag.property}' must be a boolean` };\n      if (value) tokens.push(flag.flag);\n      continue;\n    }\n    const checked = flag.kind === \"strings\"\n      ? checkedStrings(flag.property, value)\n      : checkedString(flag.property, value);\n    if (!checked.ok) return checked;\n    // A repeatable flag repeats per value; a single-valued one appears once.\n    for (const token of checked.tokens) tokens.push(flag.flag, token);\n  }\n  return { ok: true, tokens };\n}\n\n/**\n * The argv for one tool call — or the invalid-params problem that stops it.\n * `--json` is always appended: the envelope is the tool-result contract, and\n * a client cannot opt out of it into the human rendering. Unknown argument\n * names refuse rather than vanish — the schema says additionalProperties\n * false, and a server that enforced that only in the schema would silently\n * drop the typo'd argument of any client that skipped validation.\n */\nexport function toArgv(tool: McpTool, args: Record<string, unknown>): ArgvOutcome {\n  const known = new Set([\n    ...tool.positionals.map((p) => p.property),\n    ...tool.flags.map((f) => f.property),\n  ]);\n  for (const property of Object.keys(args)) {\n    if (!known.has(property)) {\n      const allowed = known.size === 0 ? \"no arguments\" : [...known].join(\", \");\n      return { ok: false, problem: `unknown argument '${property}' for ${tool.name} — expected ${allowed}` };\n    }\n  }\n  const positionals = positionalTokens(tool, args);\n  if (!positionals.ok) return { ok: false, problem: positionals.problem };\n  const flags = flagTokens(tool, args);\n  if (!flags.ok) return { ok: false, problem: flags.problem };\n  return {\n    ok: true,\n    argv: [tool.command, ...positionals.tokens, ...flags.tokens, ...(tool.fixed ?? []), \"--json\"],\n  };\n}\n"]}
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../../../src/core/mcp/argv.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How one MCP tool call's JSON arguments become an argv the CLI already\n * trusts — the boundary where an argument value could otherwise smuggle a\n * flag. The tool TABLE (what the tools are) lives in `./tools.ts`; this\n * module owns the crossing, and the inputSchema that declares it: the schema\n * a client validates against and the argv builder that refuses what it\n * forbids are one contract written twice, so they sit in one module.\n */\nimport type { McpTool } from \"./tools.js\";\n\n/**\n * The MCP inputSchema for one tool: a closed object, so a typo'd argument\n * refuses instead of vanishing, with the required set and the positional order\n * `toArgv` enforces declared beside it.\n */\nexport function toInputSchema(tool: McpTool): Record<string, unknown> {\n  const properties: Record<string, unknown> = {};\n  for (const positional of tool.positionals) {\n    properties[positional.property] = positional.variadic\n      ? { type: \"array\", items: { type: \"string\" }, description: positional.description }\n      : { type: \"string\", description: positional.description };\n  }\n  for (const flag of tool.flags) {\n    properties[flag.property] =\n      flag.kind === \"boolean\"\n        ? { type: \"boolean\", description: flag.description }\n        : flag.kind === \"strings\"\n          ? { type: \"array\", items: { type: \"string\" }, description: flag.description }\n          : { type: \"string\", description: flag.description };\n  }\n  const required = [\n    ...tool.positionals.filter((p) => p.required).map((p) => p.property),\n    ...tool.flags.filter((f) => f.required === true).map((f) => f.property),\n  ];\n  return {\n    type: \"object\",\n    properties,\n    ...(required.length > 0 ? { required } : {}),\n    ...orderRule(tool),\n    additionalProperties: false,\n  };\n}\n\n/**\n * The rule `positionalTokens` enforces, declared: a positional after an\n * optional one needs it, because positionals reach argv by position and the\n * later value would otherwise be read in the earlier one's slot. Without it a\n * client that validated `{name: \"smoke\"}` for `loam_list` against the schema\n * it was given passed, and was then refused `-32602` by the server.\n *\n * Read off the declaration order rather than spelled per tool, so a tool that\n * gains a positional after an optional one is declared the day it is refused.\n * Each later positional needs every earlier OPTIONAL one; an earlier required\n * one is in `required` already.\n *\n * Two keywords, because presence means two things. A scalar that is present\n * always yields a token, so presence is the whole condition and\n * `dependentRequired` says exactly that. A variadic yields tokens only when it\n * has members: an empty one moves nothing into anybody's slot, and\n * `positionalTokens` serves it — `{args: []}` with no `workflow` is the\n * workflow list. `dependentRequired` there would forbid a call the server\n * answers, the same disagreement turned the other way, so the variadic's rule\n * sits under `dependentSchemas`: once it is present, either the earlier ones\n * are too or it is empty. `anyOf` rather than `if`/`then`, which says the same\n * but puts a `then` key on an object, and a thenable literal is one `await`\n * away from being called.\n */\nfunction orderRule(tool: McpTool): Record<string, unknown> {\n  const dependentRequired: Record<string, string[]> = {};\n  const dependentSchemas: Record<string, unknown> = {};\n  const earlier: string[] = [];\n  for (const positional of tool.positionals) {\n    if (earlier.length > 0 && positional.variadic) {\n      dependentSchemas[positional.property] = {\n        anyOf: [{ required: [...earlier] }, { properties: { [positional.property]: { maxItems: 0 } } }],\n      };\n    } else if (earlier.length > 0) {\n      dependentRequired[positional.property] = [...earlier];\n    }\n    if (!positional.required) earlier.push(positional.property);\n  }\n  return {\n    ...(Object.keys(dependentRequired).length > 0 ? { dependentRequired } : {}),\n    ...(Object.keys(dependentSchemas).length > 0 ? { dependentSchemas } : {}),\n  };\n}\n\n/** One checked step of argv construction: the tokens it yields, or the invalid-params problem. */\ntype Checked =\n  | { readonly ok: true; readonly tokens: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\nexport type ArgvOutcome =\n  | { readonly ok: true; readonly argv: readonly string[] }\n  | { readonly ok: false; readonly problem: string };\n\n/**\n * A string value that argv would read as a flag is refused before any command\n * sees it: {\"target\": \"--type\"} must not become a parsed option. Commander\n * cannot make this distinction after the fact — by then the token IS a flag —\n * so the boundary is here, on every string that crosses, array members\n * included. No shell is ever involved, so this is the only smuggling path.\n */\nfunction smuggled(property: string, value: string): string | null {\n  return value.startsWith(\"-\")\n    ? `argument '${property}' value '${value}' begins with '-' — a value argv would read as a flag is refused`\n    : null;\n}\n\n/** One string value checked for type and smuggling. */\nfunction checkedString(property: string, value: unknown): Checked {\n  if (typeof value !== \"string\") return { ok: false, problem: `argument '${property}' must be a string` };\n  const bad = smuggled(property, value);\n  return bad === null ? { ok: true, tokens: [value] } : { ok: false, problem: bad };\n}\n\n/** An array value checked member by member — rebuilt, not cast, so the claim is earned. */\nfunction checkedStrings(property: string, value: unknown): Checked {\n  if (!Array.isArray(value)) return { ok: false, problem: `argument '${property}' must be an array of strings` };\n  const tokens: string[] = [];\n  for (const entry of value) {\n    const checked = checkedString(property, entry);\n    if (!checked.ok) return checked;\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\n/**\n * The positionals, in declaration order — and refused when one would land in\n * another's slot.\n *\n * A positional reaches argv by POSITION, so an optional one left out leaves no\n * gap: whatever follows it moves up into its place. `loam_list` with `{name:\n * \"services\"}` built `list services` and answered ok:true with the services\n * listing, a wrong answer with nothing in it saying so; `loam_instructions`\n * with `{args: [...]}` and no `workflow` read the first arg as the workflow.\n * Refused here instead, as the invalid-params problem a missing REQUIRED\n * positional already is, naming the slot the caller left empty. A later\n * positional that yields no token — an empty variadic — moves nothing up, so\n * it passes. `orderRule` above declares the same rule in the advertised\n * schema; the two change together.\n */\nfunction positionalTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  let absent: string | undefined;\n  for (const positional of tool.positionals) {\n    const value = args[positional.property];\n    if (value === undefined) {\n      if (positional.required) return { ok: false, problem: `required argument '${positional.property}' is missing` };\n      absent ??= positional.property;\n      continue;\n    }\n    const checked = positional.variadic\n      ? checkedStrings(positional.property, value)\n      : checkedString(positional.property, value);\n    if (!checked.ok) return checked;\n    if (absent !== undefined && checked.tokens.length > 0) {\n      return {\n        ok: false,\n        problem:\n          `argument '${positional.property}' requires '${absent}' — positionals are read in order, ` +\n          `so without '${absent}' this value would be read as '${absent}'`,\n      };\n    }\n    tokens.push(...checked.tokens);\n  }\n  return { ok: true, tokens };\n}\n\nfunction flagTokens(tool: McpTool, args: Record<string, unknown>): Checked {\n  const tokens: string[] = [];\n  for (const flag of tool.flags) {\n    const value = args[flag.property];\n    if (value === undefined) {\n      // The same refusal absent required positionals get: the client learns\n      // \"-32602 missing argument\", not an invalid-option envelope after the\n      // command already refused.\n      if (flag.required === true) return { ok: false, problem: `required argument '${flag.property}' is missing` };\n      continue;\n    }\n    if (flag.kind === \"boolean\") {\n      if (typeof value !== \"boolean\") return { ok: false, problem: `argument '${flag.property}' must be a boolean` };\n      if (value) tokens.push(flag.flag);\n      continue;\n    }\n    const checked = flag.kind === \"strings\"\n      ? checkedStrings(flag.property, value)\n      : checkedString(flag.property, value);\n    if (!checked.ok) return checked;\n    // A repeatable flag repeats per value; a single-valued one appears once.\n    for (const token of checked.tokens) tokens.push(flag.flag, token);\n  }\n  return { ok: true, tokens };\n}\n\n/**\n * The argv for one tool call — or the invalid-params problem that stops it.\n * `--json` is always appended: the envelope is the tool-result contract, and\n * a client cannot opt out of it into the human rendering. Unknown argument\n * names refuse rather than vanish — the schema says additionalProperties\n * false, and a server that enforced that only in the schema would silently\n * drop the typo'd argument of any client that skipped validation.\n */\nexport function toArgv(tool: McpTool, args: Record<string, unknown>): ArgvOutcome {\n  const known = new Set([\n    ...tool.positionals.map((p) => p.property),\n    ...tool.flags.map((f) => f.property),\n  ]);\n  for (const property of Object.keys(args)) {\n    if (!known.has(property)) {\n      const allowed = known.size === 0 ? \"no arguments\" : [...known].join(\", \");\n      return { ok: false, problem: `unknown argument '${property}' for ${tool.name} — expected ${allowed}` };\n    }\n  }\n  const positionals = positionalTokens(tool, args);\n  if (!positionals.ok) return { ok: false, problem: positionals.problem };\n  const flags = flagTokens(tool, args);\n  if (!flags.ok) return { ok: false, problem: flags.problem };\n  return {\n    ok: true,\n    argv: [tool.command, ...positionals.tokens, ...flags.tokens, ...(tool.fixed ?? []), \"--json\"],\n  };\n}\n"]}

package/dist/core/mcp/author-tools.js

@@ -13,7 +13,7 @@ export const MCP_AUTHOR_TOOLS = [
         name: "loam_new",
         command: "new",
         description: "Scaffold a feature in the docs repo. Opt-in writer; refuses an existing feature. " +
-            "CLI equivalent: loam new <featureId> [--title <text>] [--touches <id>...] [--new-service <id>...] [--capability <id>...] --json",
+            "CLI equivalent: loam new <featureId> [--title <text>] [--touches <id>...] [--new-service <id>...] [--capability <id>...] [--modifies <Req-ID>...] --json",
         positionals: [
             { property: "featureId", required: true, variadic: false, description: "new feature id, e.g. FEAT-101" },
         ],
@@ -22,6 +22,7 @@ export const MCP_AUTHOR_TOOLS = [
             { property: "touches", flag: "--touches", kind: "strings", description: "existing services changed; repeatable" },
             { property: "newServices", flag: "--new-service", kind: "strings", description: "services introduced; repeatable" },
             { property: "capabilities", flag: "--capability", kind: "strings", description: "business capabilities changed; repeatable" },
+            { property: "modifies", flag: "--modifies", kind: "strings", description: "living Requirement-IDs of touched services this feature rewrites, scaffolded as pinned MODIFIED blocks; repeatable" },
         ],
         annotations: WRITE_ANNOTATIONS,
     },