@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/dist/commands/migrate-openspec/openspec/mapping.js.map

@@ -1 +1 @@
-{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/mapping.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The mapping document on the way in: YAML a human edited, graded into an\n * `OpenSpecMapping` or refused with the line to fix.\n *\n * Split from `./decisions.ts`, which is the same document on the way out — the\n * blank skeleton, the normalized record written beside a migration, and the\n * routing query. Reading is where every refusal lives and writing is where none\n * do, so the two halves have almost no vocabulary in common beyond the type.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { serviceIdProblem } from \"../../../core/kernel/ids/service.js\";\nimport { asRecord, dictionary } from \"../../../core/kernel/records.js\";\nimport { type OpenSpecMapping } from \"../../../core/openspec/model/mapping.js\";\nimport { message } from \"../../../core/staging/commit.js\";\nimport { OpenSpecCommandError } from \"./error.js\";\nimport { decodeSource } from \"./read.js\";\n\n/**\n * `Array.isArray` narrows an `unknown` to `any[]`, so the element check below it\n * proved nothing to tsc and the elements had to be asserted back to `string` at\n * the point of use. One predicate makes the narrowing carry the check.\n */\nfunction isStringArray(value: unknown): value is string[] {\n  return Array.isArray(value) && value.every((item) => typeof item === \"string\");\n}\n\nfunction stringList(value: unknown, label: string): string[] {\n  if (typeof value === \"string\") return value.trim() === \"\" ? [] : [value.trim()];\n  if (!isStringArray(value)) {\n    throw new OpenSpecCommandError(\"invalid-option\", `${label} must be a string or an array of service ids.`);\n  }\n  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];\n}\n\n/**\n * The service ids a mapping may name, checked against the ONE grammar.\n *\n * This used to carry its own copy of the rule — the same alphabet regex, the\n * `.`/`..` tests, the trailing dot and the Windows device names — which is how\n * the two spellings drifted apart to begin with: for a while migrate was the\n * STRICTER of the two, so the primary authoring path accepted ids a migration\n * refused. ids.ts owns the grammar now, so a mapping can only ever name a\n * `services/<id>/` the authoring commands can still address.\n *\n * The refusal keeps migrate's own shape — `OpenSpecCommandError` with\n * `invalid-option`, not an `Issue` — and `serviceIdProblem`'s label carries the\n * mapping key, so the message still points at the line of the YAML to edit.\n */\nfunction serviceList(value: unknown, label: string): string[] {\n  const services = stringList(value, label);\n  for (const service of services) {\n    const problem = serviceIdProblem(service, label);\n    if (problem !== null) throw new OpenSpecCommandError(\"invalid-option\", problem);\n  }\n  return services;\n}\n\nexport async function readMapping(path: string): Promise<OpenSpecMapping> {\n  let bytes: Buffer;\n  try {\n    bytes = await readFile(path);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"unknown-target\", `Cannot read OpenSpec mapping ${path}: ${message(error)}`);\n  }\n  // Decoded rather than assumed: a mapping saved as UTF-16 parses as YAML with\n  // no capabilities block, and the refusal would name a missing decision\n  // instead of the encoding that hid it.\n  const raw = decodeSource(bytes, path, \"OpenSpec mapping\");\n  let parsed: unknown;\n  try {\n    parsed = parseYaml(raw);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} is invalid YAML: ${message(error)}`);\n  }\n  const document = asRecord(parsed);\n  if (document === null || document.version !== 1) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must be a YAML mapping with version: 1.`);\n  }\n  const sourceNode = asRecord(document.source);\n  const source = sourceNode !== null\n    && typeof sourceNode.root === \"string\"\n    && typeof sourceNode.inventoryDigest === \"string\"\n    ? { root: sourceNode.root, inventoryDigest: sourceNode.inventoryDigest }\n    : null;\n  const capabilitiesNode = asRecord(document.capabilities);\n  if (capabilitiesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a capabilities mapping.`);\n  }\n  const capabilities = dictionary<OpenSpecMapping[\"capabilities\"][string]>();\n  for (const [capability, value] of Object.entries(capabilitiesNode)) {\n    const record = asRecord(value);\n    const services = serviceList(record?.services ?? value, `capabilities.${capability}.services`);\n    const requirementServices = dictionary<string[]>();\n    if (record?.requirementServices !== undefined) {\n      const allocations = asRecord(record.requirementServices);\n      if (allocations === null) {\n        throw new OpenSpecCommandError(\n          \"invalid-option\",\n          `capabilities.${capability}.requirementServices must be a mapping.`,\n        );\n      }\n      for (const [requirement, selected] of Object.entries(allocations)) {\n        requirementServices[requirement] = serviceList(\n          selected,\n          `capabilities.${capability}.requirementServices.${requirement}`,\n        );\n      }\n    }\n    capabilities[capability] = { services, requirementServices };\n  }\n\n  const changesNode = asRecord(document.changes);\n  if (changesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a changes mapping.`);\n  }\n  const changes = dictionary<OpenSpecMapping[\"changes\"][string]>();\n  for (const [change, value] of Object.entries(changesNode)) {\n    const record = asRecord(value);\n    if (record === null) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `changes.${change} must be a mapping with explicit feature and title fields.`,\n      );\n    }\n    const featureValue = record.feature;\n    if (featureValue !== null && typeof featureValue !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.feature must be a string or null.`);\n    }\n    if (typeof record.title !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.title must be a string.`);\n    }\n    changes[change] = {\n      feature: typeof featureValue === \"string\" && featureValue.trim() !== \"\" ? featureValue.trim() : null,\n      title: record.title,\n    };\n  }\n\n  const renames = dictionary<string>();\n  if (document.renames !== undefined) {\n    const renamesNode = asRecord(document.renames);\n    if (renamesNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} renames must be a mapping.`);\n    }\n    for (const [key, value] of Object.entries(renamesNode)) {\n      const record = asRecord(value);\n      const requirementId = record !== null && \"requirementId\" in record ? record.requirementId : value;\n      // A freshly generated skeleton deliberately uses null: it remains a\n      // needsIdentity decision rather than becoming a malformed mapping.\n      if (requirementId === null || requirementId === \"\") continue;\n      if (typeof requirementId !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `renames.${key}.requirementId must be a string or null.`);\n      }\n      renames[key] = requirementId.trim();\n    }\n  }\n  // Recorded as written. Naming the disposition union here only meant asserting\n  // an unreviewed string into it: `mapping.invalid-artifact-disposition` is what\n  // actually grades this value, and it has to see what the human typed to be\n  // able to name it back to them.\n  const artifacts = dictionary<string>();\n  if (document.artifacts !== undefined) {\n    const artifactsNode = asRecord(document.artifacts);\n    if (artifactsNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} artifacts must be a mapping.`);\n    }\n    for (const [artifactPath, value] of Object.entries(artifactsNode)) {\n      const record = asRecord(value);\n      const disposition = record !== null && \"disposition\" in record ? record.disposition : value;\n      if (disposition === null || disposition === \"\") continue;\n      if (typeof disposition !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `artifacts.${artifactPath}.disposition must be a string or null.`);\n      }\n      artifacts[artifactPath] = disposition;\n    }\n  }\n  return { source, capabilities, changes, renames, artifacts };\n}\n"]}
+{"version":3,"file":"mapping.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/mapping.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACtF,OAAO,EAAwB,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC1D,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,SAAS,UAAU,CAAC,KAAc,EAAE,KAAa;IAC/C,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAChF,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,GAAG,KAAK,+CAA+C,CAAC,CAAC;IAC5G,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,WAAW,CAAC,KAAc,EAAE,KAAa;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC1C,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACjD,IAAI,OAAO,KAAK,IAAI;YAAE,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,IAAI,KAAa,CAAC;IAClB,IAAI,CAAC;QACH,KAAK,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,gCAAgC,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC9G,CAAC;IACD,6EAA6E;IAC7E,uEAAuE;IACvE,uCAAuC;IACvC,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC;IAC1D,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,qBAAqB,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAClH,CAAC;IACD,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,OAAO,KAAK,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,0CAA0C,CAAC,CAAC;IACvH,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,UAAU,KAAK,IAAI;WAC7B,OAAO,UAAU,CAAC,IAAI,KAAK,QAAQ;WACnC,OAAO,UAAU,CAAC,eAAe,KAAK,QAAQ;QACjD,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,eAAe,EAAE,UAAU,CAAC,eAAe,EAAE;QACxE,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,gBAAgB,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;IACzD,IAAI,gBAAgB,KAAK,IAAI,EAAE,CAAC;QAC9B,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,uCAAuC,CAAC,CAAC;IACpH,CAAC;IACD,MAAM,YAAY,GAAG,UAAU,EAA2C,CAAC;IAC3E,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,MAAM,QAAQ,GAAG,WAAW,CAAC,MAAM,EAAE,QAAQ,IAAI,KAAK,EAAE,gBAAgB,UAAU,WAAW,CAAC,CAAC;QAC/F,MAAM,mBAAmB,GAAG,UAAU,EAAY,CAAC;QACnD,IAAI,MAAM,EAAE,mBAAmB,KAAK,SAAS,EAAE,CAAC;YAC9C,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;YACzD,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;gBACzB,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,EAChB,gBAAgB,UAAU,yCAAyC,CACpE,CAAC;YACJ,CAAC;YACD,KAAK,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;gBAClE,mBAAmB,CAAC,WAAW,CAAC,GAAG,WAAW,CAC5C,QAAQ,EACR,gBAAgB,UAAU,wBAAwB,WAAW,EAAE,CAChE,CAAC;YACJ,CAAC;QACH,CAAC;QACD,YAAY,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAC/D,CAAC;IAED,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/C,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,kCAAkC,CAAC,CAAC;IAC/G,CAAC;IACD,MAAM,OAAO,GAAG,UAAU,EAAsC,CAAC;IACjE,KAAK,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YACpB,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,EAChB,WAAW,MAAM,4DAA4D,CAC9E,CAAC;QACJ,CAAC;QACD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC;QACpC,IAAI,YAAY,KAAK,IAAI,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YAC9D,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,WAAW,MAAM,oCAAoC,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACrC,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,WAAW,MAAM,0BAA0B,CAAC,CAAC;QAChG,CAAC;QACD,OAAO,CAAC,MAAM,CAAC,GAAG;YAChB,OAAO,EAAE,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;YACpG,KAAK,EAAE,MAAM,CAAC,KAAK;SACpB,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,EAAU,CAAC;IACrC,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QACnC,MAAM,WAAW,GAAG,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QAC/C,IAAI,WAAW,KAAK,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,6BAA6B,CAAC,CAAC;QAC1G,CAAC;QACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC;YACvD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,aAAa,GAAG,MAAM,KAAK,IAAI,IAAI,eAAe,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC;YAClG,oEAAoE;YACpE,mEAAmE;YACnE,IAAI,aAAa,KAAK,IAAI,IAAI,aAAa,KAAK,EAAE;gBAAE,SAAS;YAC7D,IAAI,OAAO,aAAa,KAAK,QAAQ,EAAE,CAAC;gBACtC,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,WAAW,GAAG,0CAA0C,CAAC,CAAC;YAC7G,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QACtC,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,gCAAgC;IAChC,MAAM,SAAS,GAAG,UAAU,EAAU,CAAC;IACvC,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QACrC,MAAM,aAAa,GAAG,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;QACnD,IAAI,aAAa,KAAK,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,oBAAoB,IAAI,+BAA+B,CAAC,CAAC;QAC5G,CAAC;QACD,KAAK,MAAM,CAAC,YAAY,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YAClE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;YAC/B,MAAM,WAAW,GAAG,MAAM,KAAK,IAAI,IAAI,aAAa,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC;YAC5F,IAAI,WAAW,KAAK,IAAI,IAAI,WAAW,KAAK,EAAE;gBAAE,SAAS;YACzD,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACpC,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,aAAa,YAAY,wCAAwC,CAAC,CAAC;YACtH,CAAC;YACD,SAAS,CAAC,YAAY,CAAC,GAAG,WAAW,CAAC;QACxC,CAAC;IACH,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC","sourcesContent":["/**\n * The mapping document on the way in: YAML a human edited, graded into an\n * `OpenSpecMapping` or refused with the line to fix.\n *\n * Split from `./decisions.ts`, which is the same document on the way out — the\n * blank skeleton, the normalized record written beside a migration, and the\n * routing query. Reading is where every refusal lives and writing is where none\n * do, so the two halves have almost no vocabulary in common beyond the type.\n */\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYaml } from \"yaml\";\nimport { serviceIdProblem } from \"../../../core/kernel/ids/service.js\";\nimport { asRecord, dictionary, isStringArray } from \"../../../core/kernel/records.js\";\nimport { type OpenSpecMapping } from \"../../../core/openspec/model/mapping.js\";\nimport { message } from \"../../../core/staging/commit.js\";\nimport { OpenSpecCommandError } from \"./error.js\";\nimport { decodeSource } from \"./read.js\";\n\nfunction stringList(value: unknown, label: string): string[] {\n  if (typeof value === \"string\") return value.trim() === \"\" ? [] : [value.trim()];\n  if (!isStringArray(value)) {\n    throw new OpenSpecCommandError(\"invalid-option\", `${label} must be a string or an array of service ids.`);\n  }\n  return [...new Set(value.map((item) => item.trim()).filter(Boolean))];\n}\n\n/**\n * The service ids a mapping may name, checked against the ONE grammar.\n *\n * This used to carry its own copy of the rule — the same alphabet regex, the\n * `.`/`..` tests, the trailing dot and the Windows device names — which is how\n * the two spellings drifted apart to begin with: for a while migrate was the\n * STRICTER of the two, so the primary authoring path accepted ids a migration\n * refused. ids.ts owns the grammar now, so a mapping can only ever name a\n * `services/<id>/` the authoring commands can still address.\n *\n * The refusal keeps migrate's own shape — `OpenSpecCommandError` with\n * `invalid-option`, not an `Issue` — and `serviceIdProblem`'s label carries the\n * mapping key, so the message still points at the line of the YAML to edit.\n */\nfunction serviceList(value: unknown, label: string): string[] {\n  const services = stringList(value, label);\n  for (const service of services) {\n    const problem = serviceIdProblem(service, label);\n    if (problem !== null) throw new OpenSpecCommandError(\"invalid-option\", problem);\n  }\n  return services;\n}\n\nexport async function readMapping(path: string): Promise<OpenSpecMapping> {\n  let bytes: Buffer;\n  try {\n    bytes = await readFile(path);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"unknown-target\", `Cannot read OpenSpec mapping ${path}: ${message(error)}`);\n  }\n  // Decoded rather than assumed: a mapping saved as UTF-16 parses as YAML with\n  // no capabilities block, and the refusal would name a missing decision\n  // instead of the encoding that hid it.\n  const raw = decodeSource(bytes, path, \"OpenSpec mapping\");\n  let parsed: unknown;\n  try {\n    parsed = parseYaml(raw);\n  } catch (error) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} is invalid YAML: ${message(error)}`);\n  }\n  const document = asRecord(parsed);\n  if (document === null || document.version !== 1) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must be a YAML mapping with version: 1.`);\n  }\n  const sourceNode = asRecord(document.source);\n  const source = sourceNode !== null\n    && typeof sourceNode.root === \"string\"\n    && typeof sourceNode.inventoryDigest === \"string\"\n    ? { root: sourceNode.root, inventoryDigest: sourceNode.inventoryDigest }\n    : null;\n  const capabilitiesNode = asRecord(document.capabilities);\n  if (capabilitiesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a capabilities mapping.`);\n  }\n  const capabilities = dictionary<OpenSpecMapping[\"capabilities\"][string]>();\n  for (const [capability, value] of Object.entries(capabilitiesNode)) {\n    const record = asRecord(value);\n    const services = serviceList(record?.services ?? value, `capabilities.${capability}.services`);\n    const requirementServices = dictionary<string[]>();\n    if (record?.requirementServices !== undefined) {\n      const allocations = asRecord(record.requirementServices);\n      if (allocations === null) {\n        throw new OpenSpecCommandError(\n          \"invalid-option\",\n          `capabilities.${capability}.requirementServices must be a mapping.`,\n        );\n      }\n      for (const [requirement, selected] of Object.entries(allocations)) {\n        requirementServices[requirement] = serviceList(\n          selected,\n          `capabilities.${capability}.requirementServices.${requirement}`,\n        );\n      }\n    }\n    capabilities[capability] = { services, requirementServices };\n  }\n\n  const changesNode = asRecord(document.changes);\n  if (changesNode === null) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} must contain a changes mapping.`);\n  }\n  const changes = dictionary<OpenSpecMapping[\"changes\"][string]>();\n  for (const [change, value] of Object.entries(changesNode)) {\n    const record = asRecord(value);\n    if (record === null) {\n      throw new OpenSpecCommandError(\n        \"invalid-option\",\n        `changes.${change} must be a mapping with explicit feature and title fields.`,\n      );\n    }\n    const featureValue = record.feature;\n    if (featureValue !== null && typeof featureValue !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.feature must be a string or null.`);\n    }\n    if (typeof record.title !== \"string\") {\n      throw new OpenSpecCommandError(\"invalid-option\", `changes.${change}.title must be a string.`);\n    }\n    changes[change] = {\n      feature: typeof featureValue === \"string\" && featureValue.trim() !== \"\" ? featureValue.trim() : null,\n      title: record.title,\n    };\n  }\n\n  const renames = dictionary<string>();\n  if (document.renames !== undefined) {\n    const renamesNode = asRecord(document.renames);\n    if (renamesNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} renames must be a mapping.`);\n    }\n    for (const [key, value] of Object.entries(renamesNode)) {\n      const record = asRecord(value);\n      const requirementId = record !== null && \"requirementId\" in record ? record.requirementId : value;\n      // A freshly generated skeleton deliberately uses null: it remains a\n      // needsIdentity decision rather than becoming a malformed mapping.\n      if (requirementId === null || requirementId === \"\") continue;\n      if (typeof requirementId !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `renames.${key}.requirementId must be a string or null.`);\n      }\n      renames[key] = requirementId.trim();\n    }\n  }\n  // Recorded as written. Naming the disposition union here only meant asserting\n  // an unreviewed string into it: `mapping.invalid-artifact-disposition` is what\n  // actually grades this value, and it has to see what the human typed to be\n  // able to name it back to them.\n  const artifacts = dictionary<string>();\n  if (document.artifacts !== undefined) {\n    const artifactsNode = asRecord(document.artifacts);\n    if (artifactsNode === null) {\n      throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec mapping ${path} artifacts must be a mapping.`);\n    }\n    for (const [artifactPath, value] of Object.entries(artifactsNode)) {\n      const record = asRecord(value);\n      const disposition = record !== null && \"disposition\" in record ? record.disposition : value;\n      if (disposition === null || disposition === \"\") continue;\n      if (typeof disposition !== \"string\") {\n        throw new OpenSpecCommandError(\"invalid-option\", `artifacts.${artifactPath}.disposition must be a string or null.`);\n      }\n      artifacts[artifactPath] = disposition;\n    }\n  }\n  return { source, capabilities, changes, renames, artifacts };\n}\n"]}

package/dist/commands/migrate-openspec/openspec/paths.js

@@ -2,7 +2,8 @@
  * The path arithmetic every write decision in this command rests on.
  *
  * Three rules, kept together because they answer one question in two
- * directions: is a path inside a tree it must stay out of (`contains`), what
+ * directions: is a path inside a tree it must stay out of (kernel's
+ * `isPathInside`, which this module used to restate as `contains`), what
  * tree is it really in once symlinks are resolved (`canonicalForCreate`), and
  * does a path claimed by the OpenSpec source stay inside the directory it was
  * listed under (`safeArtifactRelative`). `materialize/stage.ts` builds the
@@ -11,12 +12,8 @@
  */
 import { existsSync } from "node:fs";
 import { realpath } from "node:fs/promises";
-import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, resolve } from "node:path";
 import { OpenSpecCommandError } from "./error.js";
-export function contains(parent, candidate) {
-    const rel = relative(parent, candidate);
-    return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
-}
 /** Resolve symlinks in the nearest existing ancestor of a not-yet-created path. */
 export async function canonicalForCreate(path) {
     let cursor = path;

package/dist/commands/migrate-openspec/openspec/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,UAAU,QAAQ,CAAC,MAAc,EAAE,SAAiB;IACxD,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACxC,OAAO,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,GAAG,EAAE,CAAC,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AACzF,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,MAAM;YAAE,MAAM;QAC7B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjC,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,MAAc,EAAE,KAAa;IACtF,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,EAChB,GAAG,KAAK,oDAAoD,YAAY,GAAG,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/G,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,kDAAkD,YAAY,GAAG,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The path arithmetic every write decision in this command rests on.\n *\n * Three rules, kept together because they answer one question in two\n * directions: is a path inside a tree it must stay out of (`contains`), what\n * tree is it really in once symlinks are resolved (`canonicalForCreate`), and\n * does a path claimed by the OpenSpec source stay inside the directory it was\n * listed under (`safeArtifactRelative`). `materialize/stage.ts` builds the\n * staging refusals out of the first two; `openspec/decisions.ts` uses them to\n * keep a mapping skeleton out of the workspace it describes.\n */\nimport { existsSync } from \"node:fs\";\nimport { realpath } from \"node:fs/promises\";\nimport { basename, dirname, isAbsolute, relative, resolve, sep } from \"node:path\";\nimport { OpenSpecCommandError } from \"./error.js\";\n\nexport function contains(parent: string, candidate: string): boolean {\n  const rel = relative(parent, candidate);\n  return rel === \"\" || (!rel.startsWith(`..${sep}`) && rel !== \"..\" && !isAbsolute(rel));\n}\n\n/** Resolve symlinks in the nearest existing ancestor of a not-yet-created path. */\nexport async function canonicalForCreate(path: string): Promise<string> {\n  let cursor = path;\n  const suffix: string[] = [];\n  while (!existsSync(cursor)) {\n    const parent = dirname(cursor);\n    if (parent === cursor) break;\n    suffix.unshift(basename(cursor));\n    cursor = parent;\n  }\n  return resolve(await realpath(cursor), ...suffix);\n}\n\nexport function safeArtifactRelative(artifactPath: string, prefix: string, owner: string): string[] {\n  if (!artifactPath.startsWith(prefix)) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      `${owner} contains an artifact outside its own directory: ${artifactPath}.`,\n    );\n  }\n  const segments = artifactPath.slice(prefix.length).split(\"/\");\n  if (segments.length === 0 || segments.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec artifact has an unsafe relative path: ${artifactPath}.`);\n  }\n  return segments;\n}\n"]}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../../src/commands/migrate-openspec/openspec/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,mFAAmF;AACnF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAAY;IACnD,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC/B,IAAI,MAAM,KAAK,MAAM;YAAE,MAAM;QAC7B,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QACjC,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;IACD,OAAO,OAAO,CAAC,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,YAAoB,EAAE,MAAc,EAAE,KAAa;IACtF,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,EAChB,GAAG,KAAK,oDAAoD,YAAY,GAAG,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,EAAE,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QAC/G,MAAM,IAAI,oBAAoB,CAAC,gBAAgB,EAAE,kDAAkD,YAAY,GAAG,CAAC,CAAC;IACtH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC","sourcesContent":["/**\n * The path arithmetic every write decision in this command rests on.\n *\n * Three rules, kept together because they answer one question in two\n * directions: is a path inside a tree it must stay out of (kernel's\n * `isPathInside`, which this module used to restate as `contains`), what\n * tree is it really in once symlinks are resolved (`canonicalForCreate`), and\n * does a path claimed by the OpenSpec source stay inside the directory it was\n * listed under (`safeArtifactRelative`). `materialize/stage.ts` builds the\n * staging refusals out of the first two; `openspec/decisions.ts` uses them to\n * keep a mapping skeleton out of the workspace it describes.\n */\nimport { existsSync } from \"node:fs\";\nimport { realpath } from \"node:fs/promises\";\nimport { basename, dirname, resolve } from \"node:path\";\nimport { OpenSpecCommandError } from \"./error.js\";\n\n/** Resolve symlinks in the nearest existing ancestor of a not-yet-created path. */\nexport async function canonicalForCreate(path: string): Promise<string> {\n  let cursor = path;\n  const suffix: string[] = [];\n  while (!existsSync(cursor)) {\n    const parent = dirname(cursor);\n    if (parent === cursor) break;\n    suffix.unshift(basename(cursor));\n    cursor = parent;\n  }\n  return resolve(await realpath(cursor), ...suffix);\n}\n\nexport function safeArtifactRelative(artifactPath: string, prefix: string, owner: string): string[] {\n  if (!artifactPath.startsWith(prefix)) {\n    throw new OpenSpecCommandError(\n      \"invalid-option\",\n      `${owner} contains an artifact outside its own directory: ${artifactPath}.`,\n    );\n  }\n  const segments = artifactPath.slice(prefix.length).split(\"/\");\n  if (segments.length === 0 || segments.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) {\n    throw new OpenSpecCommandError(\"invalid-option\", `OpenSpec artifact has an unsafe relative path: ${artifactPath}.`);\n  }\n  return segments;\n}\n"]}

package/dist/commands/new/capability-template.js

@@ -0,0 +1,118 @@
+/**
+ * The capability delta `loam new --capability` scaffolds, and the id shape it
+ * offers.
+ *
+ * Split out of `./templates.ts` along the document-kind seam: the other five
+ * templates scaffold a feature's own files and one service's deltas, while this
+ * one is a delta against a fleet-level business document with its own altitude
+ * rules and its own id grammar (`REQUIREMENT_ID_RE`, which nothing else here
+ * reads). The sentinels stay single-sourced in `core/coherence/authoring/
+ * sentinels.ts`, so the move changes no string the placeholder gate matches on.
+ */
+import { REQUIREMENT_ID_RE } from "../../core/document/spec.js";
+import { CAPABILITY_REQUIREMENT_SENTINEL, CAPABILITY_SHALL_SENTINEL, GIVEN_SENTINEL, SCENARIO_SENTINEL, THEN_SENTINEL, WHEN_SENTINEL, } from "../../core/coherence/authoring/sentinels.js";
+/**
+ * The BUSINESS axis, scaffolded by `--capability`: a delta against the living
+ * `capabilities/<id>/spec.md`.
+ *
+ * Same idiom as the two spec templates in `./templates.ts`, for the same reason — the
+ * example lives INSIDE an HTML comment, indented past the line-anchored
+ * `## ADDED Requirements` / `### Requirement:` patterns core/document/parse.ts
+ * matches on — so the scaffold declares nothing until a person copies the block
+ * out. That is what lets a freshly scaffolded feature validate clean while
+ * still being refused by `loam archive` the moment the block is copied out and
+ * left unedited (`scaffold.placeholder`, which reads
+ * `features/<FEAT>/capabilities/` as well as `features/<FEAT>/specs/`).
+ *
+ * WHAT THE COMMENT TEACHES IS THE ALTITUDE, because that is the mistake this
+ * document invites. A capability requirement is a promise a customer could
+ * check; the four service-scoped lines (`Operations:`, `Covers:`, `Publishes:`,
+ * `Consumes:`) and the axis's own two (`Capability:`, `Realizes:`) are all
+ * ERRORS here — `capability.requirement-service-scoped` and
+ * `capability.requirement-inert-join` — and every one of them parses, so an
+ * author who is not told writes one and finds out at archive. `Requirement-ID:`
+ * is spelled as mandatory for the same reason: a capability document outlives
+ * every service that realizes it, so identity by heading is refused
+ * (`capability.requirement-unidentified`).
+ *
+ * No nested HTML comments, exactly as `specTemplate` (`./templates.ts`) states: an inner `-->`
+ * would end the outer comment early and re-expose the example to the parser.
+ */
+export function capabilityDeltaTemplate(featureId, capability) {
+    return `# ${capability} — capability delta for ${featureId}
+
+<!-- The business axis. This is a DELTA against the living
+     capabilities/${capability}/spec.md, not the document itself: sections are
+     ADDED / MODIFIED / REMOVED, delete the ones you do not need, and a MODIFIED
+     requirement carries its full new text rather than a diff. If the fleet has
+     no capabilities/${capability}/spec.md yet, this feature's archive creates it.
+
+     WHAT BELONGS HERE is a promise somebody outside the fleet could check —
+     'a refund reaches the customer's card within five days'. What does NOT is
+     the mechanism: \`Operations:\`, \`Covers:\`, \`Publishes:\` and \`Consumes:\`
+     all resolve against ONE service's own contract or model, so a requirement
+     carrying one is a service requirement filed at the wrong altitude and
+     \`loam validate\` says so. \`Capability:\` and \`Realizes:\` are refused here
+     too — they are the joins written on the SERVICE requirement that keeps this
+     promise, one directory over in specs/<svc>/spec.md, as
+     \`Realizes: ${capability}#<Requirement-ID>\`.
+
+     \`Requirement-ID:\` is mandatory on every requirement below. A capability
+     document outlives the services that realize it, so its requirements are
+     addressed by a stable id rather than by their heading — rewording a heading
+     would otherwise be a removal and an addition, and every \`Realizes:\` line
+     pointed at it would break in silence.
+
+     A MODIFIED or REMOVED requirement also needs a \`Based-On:\` pin quoting the
+     living text it rewrites, so two features touching one capability collide
+     loudly instead of overwriting each other. Run \`loam rebase ${featureId}\`
+     and the pins are written for you.
+
+     Copy the block below out of this comment, unindent it, and replace the TODO
+     and every <angle-bracket> fill-in — \`loam archive\` refuses the scaffold's
+     own wording (\`scaffold.placeholder\`):
+
+    ## ADDED Requirements
+
+    ### Requirement: ${CAPABILITY_REQUIREMENT_SENTINEL}
+    Requirement-ID: ${idHint(capability)}
+
+    The fleet SHALL ${CAPABILITY_SHALL_SENTINEL}.
+
+    #### Scenario: ${SCENARIO_SENTINEL}
+    - **Given** ${GIVEN_SENTINEL}
+    - **When** ${WHEN_SENTINEL}
+    - **Then** ${THEN_SENTINEL}
+-->
+`;
+}
+/**
+ * A plausible `Requirement-ID:` for a capability, offered as a shape rather than
+ * a name: `payments/refunds` -> `PAYMENTS-REFUNDS-1`.
+ *
+ * Deliberately NOT the feature id. A service requirement's scaffolded id is
+ * `<FEAT>.<svc>.requirement` because that requirement is created by, and lives
+ * and dies with, one feature; a capability requirement outlives every feature
+ * that touches it, so an id carrying the id of the feature that happened to
+ * introduce it is exactly the identity-by-accident this axis refuses. The
+ * suffix is `-1` and not a count of anything: it is a placeholder digit inside
+ * a placeholder id, and the author is being asked to name the promise.
+ *
+ * CHECKED AGAINST THE REAL GRAMMAR, never assumed to satisfy it. A capability id
+ * may begin with a digit (`3ds`, `2fa`, `1099-filing` — `dirNameHazard` allows an
+ * alphanumeric head) while `REQUIREMENT_ID_RE` demands a LETTER, so the obvious
+ * slug hands the author `3DS-1` and `loam validate` then refuses it with
+ * `delta.requirement-id-invalid` — the author refused for using the shape the
+ * scaffold offered. Length is the same class of failure at 128 characters. The
+ * fallback prefixes rather than truncates, because a truncated id is a plausible
+ * name that means something else.
+ */
+function idHint(capability) {
+    const slug = capability.toUpperCase().replace(/[^A-Z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    const candidate = `${slug}-1`;
+    if (REQUIREMENT_ID_RE.test(candidate))
+        return candidate;
+    const prefixed = `CAP-${candidate}`;
+    return REQUIREMENT_ID_RE.test(prefixed) ? prefixed : "CAP-1";
+}
+//# sourceMappingURL=capability-template.js.map

package/dist/commands/new/capability-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-template.js","sourceRoot":"","sources":["../../../src/commands/new/capability-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EACL,+BAA+B,EAC/B,yBAAyB,EACzB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,aAAa,GACd,MAAM,6CAA6C,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB,EAAE,UAAkB;IAC3E,OAAO,KAAK,UAAU,2BAA2B,SAAS;;;oBAGxC,UAAU;;;uBAGP,UAAU;;;;;;;;;;mBAUd,UAAU;;;;;;;;;;mEAUsC,SAAS;;;;;;;;;uBASrD,+BAA+B;sBAChC,MAAM,CAAC,UAAU,CAAC;;sBAElB,yBAAyB;;qBAE1B,iBAAiB;kBACpB,cAAc;iBACf,aAAa;iBACb,aAAa;;CAE7B,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,MAAM,CAAC,UAAkB;IAChC,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC1F,MAAM,SAAS,GAAG,GAAG,IAAI,IAAI,CAAC;IAC9B,IAAI,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,QAAQ,GAAG,OAAO,SAAS,EAAE,CAAC;IACpC,OAAO,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC;AAC/D,CAAC","sourcesContent":["/**\n * The capability delta `loam new --capability` scaffolds, and the id shape it\n * offers.\n *\n * Split out of `./templates.ts` along the document-kind seam: the other five\n * templates scaffold a feature's own files and one service's deltas, while this\n * one is a delta against a fleet-level business document with its own altitude\n * rules and its own id grammar (`REQUIREMENT_ID_RE`, which nothing else here\n * reads). The sentinels stay single-sourced in `core/coherence/authoring/\n * sentinels.ts`, so the move changes no string the placeholder gate matches on.\n */\nimport { REQUIREMENT_ID_RE } from \"../../core/document/spec.js\";\nimport {\n  CAPABILITY_REQUIREMENT_SENTINEL,\n  CAPABILITY_SHALL_SENTINEL,\n  GIVEN_SENTINEL,\n  SCENARIO_SENTINEL,\n  THEN_SENTINEL,\n  WHEN_SENTINEL,\n} from \"../../core/coherence/authoring/sentinels.js\";\n\n/**\n * The BUSINESS axis, scaffolded by `--capability`: a delta against the living\n * `capabilities/<id>/spec.md`.\n *\n * Same idiom as the two spec templates in `./templates.ts`, for the same reason — the\n * example lives INSIDE an HTML comment, indented past the line-anchored\n * `## ADDED Requirements` / `### Requirement:` patterns core/document/parse.ts\n * matches on — so the scaffold declares nothing until a person copies the block\n * out. That is what lets a freshly scaffolded feature validate clean while\n * still being refused by `loam archive` the moment the block is copied out and\n * left unedited (`scaffold.placeholder`, which reads\n * `features/<FEAT>/capabilities/` as well as `features/<FEAT>/specs/`).\n *\n * WHAT THE COMMENT TEACHES IS THE ALTITUDE, because that is the mistake this\n * document invites. A capability requirement is a promise a customer could\n * check; the four service-scoped lines (`Operations:`, `Covers:`, `Publishes:`,\n * `Consumes:`) and the axis's own two (`Capability:`, `Realizes:`) are all\n * ERRORS here — `capability.requirement-service-scoped` and\n * `capability.requirement-inert-join` — and every one of them parses, so an\n * author who is not told writes one and finds out at archive. `Requirement-ID:`\n * is spelled as mandatory for the same reason: a capability document outlives\n * every service that realizes it, so identity by heading is refused\n * (`capability.requirement-unidentified`).\n *\n * No nested HTML comments, exactly as `specTemplate` (`./templates.ts`) states: an inner `-->`\n * would end the outer comment early and re-expose the example to the parser.\n */\nexport function capabilityDeltaTemplate(featureId: string, capability: string): string {\n  return `# ${capability} — capability delta for ${featureId}\n\n<!-- The business axis. This is a DELTA against the living\n     capabilities/${capability}/spec.md, not the document itself: sections are\n     ADDED / MODIFIED / REMOVED, delete the ones you do not need, and a MODIFIED\n     requirement carries its full new text rather than a diff. If the fleet has\n     no capabilities/${capability}/spec.md yet, this feature's archive creates it.\n\n     WHAT BELONGS HERE is a promise somebody outside the fleet could check —\n     'a refund reaches the customer's card within five days'. What does NOT is\n     the mechanism: \\`Operations:\\`, \\`Covers:\\`, \\`Publishes:\\` and \\`Consumes:\\`\n     all resolve against ONE service's own contract or model, so a requirement\n     carrying one is a service requirement filed at the wrong altitude and\n     \\`loam validate\\` says so. \\`Capability:\\` and \\`Realizes:\\` are refused here\n     too — they are the joins written on the SERVICE requirement that keeps this\n     promise, one directory over in specs/<svc>/spec.md, as\n     \\`Realizes: ${capability}#<Requirement-ID>\\`.\n\n     \\`Requirement-ID:\\` is mandatory on every requirement below. A capability\n     document outlives the services that realize it, so its requirements are\n     addressed by a stable id rather than by their heading — rewording a heading\n     would otherwise be a removal and an addition, and every \\`Realizes:\\` line\n     pointed at it would break in silence.\n\n     A MODIFIED or REMOVED requirement also needs a \\`Based-On:\\` pin quoting the\n     living text it rewrites, so two features touching one capability collide\n     loudly instead of overwriting each other. Run \\`loam rebase ${featureId}\\`\n     and the pins are written for you.\n\n     Copy the block below out of this comment, unindent it, and replace the TODO\n     and every <angle-bracket> fill-in — \\`loam archive\\` refuses the scaffold's\n     own wording (\\`scaffold.placeholder\\`):\n\n    ## ADDED Requirements\n\n    ### Requirement: ${CAPABILITY_REQUIREMENT_SENTINEL}\n    Requirement-ID: ${idHint(capability)}\n\n    The fleet SHALL ${CAPABILITY_SHALL_SENTINEL}.\n\n    #### Scenario: ${SCENARIO_SENTINEL}\n    - **Given** ${GIVEN_SENTINEL}\n    - **When** ${WHEN_SENTINEL}\n    - **Then** ${THEN_SENTINEL}\n-->\n`;\n}\n\n/**\n * A plausible `Requirement-ID:` for a capability, offered as a shape rather than\n * a name: `payments/refunds` -> `PAYMENTS-REFUNDS-1`.\n *\n * Deliberately NOT the feature id. A service requirement's scaffolded id is\n * `<FEAT>.<svc>.requirement` because that requirement is created by, and lives\n * and dies with, one feature; a capability requirement outlives every feature\n * that touches it, so an id carrying the id of the feature that happened to\n * introduce it is exactly the identity-by-accident this axis refuses. The\n * suffix is `-1` and not a count of anything: it is a placeholder digit inside\n * a placeholder id, and the author is being asked to name the promise.\n *\n * CHECKED AGAINST THE REAL GRAMMAR, never assumed to satisfy it. A capability id\n * may begin with a digit (`3ds`, `2fa`, `1099-filing` — `dirNameHazard` allows an\n * alphanumeric head) while `REQUIREMENT_ID_RE` demands a LETTER, so the obvious\n * slug hands the author `3DS-1` and `loam validate` then refuses it with\n * `delta.requirement-id-invalid` — the author refused for using the shape the\n * scaffold offered. Length is the same class of failure at 128 characters. The\n * fallback prefixes rather than truncates, because a truncated id is a plausible\n * name that means something else.\n */\nfunction idHint(capability: string): string {\n  const slug = capability.toUpperCase().replace(/[^A-Z0-9]+/g, \"-\").replace(/^-+|-+$/g, \"\");\n  const candidate = `${slug}-1`;\n  if (REQUIREMENT_ID_RE.test(candidate)) return candidate;\n  const prefixed = `CAP-${candidate}`;\n  return REQUIREMENT_ID_RE.test(prefixed) ? prefixed : \"CAP-1\";\n}\n"]}

package/dist/commands/new/commit.js

@@ -11,34 +11,20 @@ import {} from "../../core/kernel/ids/dirs.js";
 import { resolveFeature } from "../../core/repo/repo.js";
 import { DocsRepoUnavailableError } from "../../core/repo/state.js";
 import { stageWrites } from "../../core/staging/commit.js";
-import { InterruptedCommitError } from "../../core/staging/interrupted.js";
-import { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from "../../core/staging/lock.js";
-import { recoverInterruptedCommit } from "../../core/staging/recovery/recover.js";
+import {} from "../../core/staging/interrupted.js";
+import { LOCK_WAIT_MS } from "../../core/staging/lock.js";
+import { openCommitWindow } from "../../core/staging/recovery/recover.js";
 import { commitStaged } from "../../core/staging/txn/transaction.js";
 import {} from "../../core/staging/writes.js";
 export async function commitScaffold(docsDir, featureId, writes) {
     // The commit window holds the docs lock: two `new`s for one id serialise
     // into a stable already-exists, and a predecessor's interrupted commit is
     // rolled forward (or refused) before this one stages anything.
-    let releaseLock;
+    const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);
+    if (!opened.ok)
+        return opened;
+    const { recovered } = opened;
     try {
-        releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);
-    }
-    catch (err) {
-        if (err instanceof DocsBusyError)
-            return { ok: false, code: "docs-busy", message: err.message };
-        throw err;
-    }
-    try {
-        let recovered;
-        try {
-            recovered = await recoverInterruptedCommit(docsDir);
-        }
-        catch (err) {
-            if (!(err instanceof InterruptedCommitError))
-                throw err;
-            return { ok: false, code: "commit-interrupted", message: err.message };
-        }
         // The one existence check, UNDER the lock and AFTER recovery: two racing
         // runs serialise on it, and a recovered half-scaffold has been completed
         // by the recovery above, so this refusal is truthful.
@@ -70,7 +56,7 @@ export async function commitScaffold(docsDir, featureId, writes) {
         return { ok: true, recovered };
     }
     finally {
-        await releaseLock();
+        await opened.release();
     }
 }
 //# sourceMappingURL=commit.js.map

package/dist/commands/new/commit.js.map

@@ -1 +1 @@
-{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/new/commit.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The scaffold's commit window: lock, recover, the one existence check, the\n * exclusive-create transaction. Split from new.ts on the same seam vouch's\n * commitStamp and gherkin's commitEmission sit on — everything in here holds\n * the docs lock, nothing outside it does — and, as there, the split keeps the\n * window's extent visible in the code shape. This module prints nothing; the\n * caller renders every arm.\n */\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { type DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { resolveFeature } from \"../../core/repo/repo.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery, InterruptedCommitError } from \"../../core/staging/interrupted.js\";\nimport { acquireDocsLockWaiting, DocsBusyError, LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { recoverInterruptedCommit } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\n\nexport type ScaffoldCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | {\n      ok: false;\n      code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\";\n      message: string;\n    }\n  /** The feature exists — found by the under-lock check, or by losing the create race. */\n  | { ok: false; code: \"already-exists\"; existing: FeatureEntry | null; recovered: CommitRecovery | null }\n  /**\n   * The docs repo went away between the command's gate and the locked read.\n   * Deliberately NOT a `code:` arm: the caller renders it through the shared\n   * docs-repo reporter, and the codes-drift collector reads every `code:`\n   * literal as a stable emission — which this discriminant is not.\n   */\n  | { ok: false; repoGone: DocsRepoUnavailableError };\n\nexport async function commitScaffold(\n  docsDir: DocsDir,\n  featureId: string,\n  writes: PlannedWrite[],\n): Promise<ScaffoldCommit> {\n  // The commit window holds the docs lock: two `new`s for one id serialise\n  // into a stable already-exists, and a predecessor's interrupted commit is\n  // rolled forward (or refused) before this one stages anything.\n  let releaseLock: () => Promise<void>;\n  try {\n    releaseLock = await acquireDocsLockWaiting(docsDir, LOCK_WAIT_MS);\n  } catch (err) {\n    if (err instanceof DocsBusyError) return { ok: false, code: \"docs-busy\", message: err.message };\n    throw err;\n  }\n  try {\n    let recovered: CommitRecovery | null;\n    try {\n      recovered = await recoverInterruptedCommit(docsDir);\n    } catch (err) {\n      if (!(err instanceof InterruptedCommitError)) throw err;\n      return { ok: false, code: \"commit-interrupted\", message: err.message };\n    }\n    // The one existence check, UNDER the lock and AFTER recovery: two racing\n    // runs serialise on it, and a recovered half-scaffold has been completed\n    // by the recovery above, so this refusal is truthful.\n    let existing: FeatureEntry | null;\n    try {\n      existing = await resolveFeature(docsDir, featureId, \"include\");\n    } catch (err) {\n      // The command's gate already refused both broken states, so reaching\n      // here means the docs repo went away between that check and this read.\n      // Same breach, same two codes — the alternative is a stack trace under\n      // `internal` that names neither.\n      if (!(err instanceof DocsRepoUnavailableError)) throw err;\n      return { ok: false, repoGone: err };\n    }\n    if (existing) return { ok: false, code: \"already-exists\", existing, recovered };\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"new\", rerun: `loam new ${featureId}`, target: featureId },\n      staged,\n      \"scaffolded\",\n    );\n    if (!committed.ok) {\n      // A lost exclusive-create race IS the feature existing: the other `new`\n      // won, and this refusal is the same stable answer the check above gives\n      // when it sees the winner first.\n      return committed.raced\n        ? { ok: false, code: \"already-exists\", existing: null, recovered }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await releaseLock();\n  }\n}\n"]}
+{"version":3,"file":"commit.js","sourceRoot":"","sources":["../../../src/commands/new/commit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAqB,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAgB,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAC3D,OAAO,EAAuB,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAqB,MAAM,8BAA8B,CAAC;AAmBjE,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAgB,EAChB,SAAiB,EACjB,MAAsB;IAEtB,yEAAyE;IACzE,0EAA0E;IAC1E,+DAA+D;IAC/D,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAC7D,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,MAAM,CAAC;IAC9B,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAC7B,IAAI,CAAC;QACH,yEAAyE;QACzE,yEAAyE;QACzE,sDAAsD;QACtD,IAAI,QAA6B,CAAC;QAClC,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC;QACjE,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,qEAAqE;YACrE,uEAAuE;YACvE,uEAAuE;YACvE,iCAAiC;YACjC,IAAI,CAAC,CAAC,GAAG,YAAY,wBAAwB,CAAC;gBAAE,MAAM,GAAG,CAAC;YAC1D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC;QACtC,CAAC;QACD,IAAI,QAAQ;YAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;QAChF,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,MAAM,YAAY,CAClC,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,SAAS,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EACpF,MAAM,EACN,YAAY,CACb,CAAC;QACF,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC;YAClB,wEAAwE;YACxE,wEAAwE;YACxE,iCAAiC;YACjC,OAAO,SAAS,CAAC,KAAK;gBACpB,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE;gBAClE,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,OAAO,EAAE,CAAC;QACtE,CAAC;QACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IACjC,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,OAAO,EAAE,CAAC;IACzB,CAAC;AACH,CAAC","sourcesContent":["/**\n * The scaffold's commit window: lock, recover, the one existence check, the\n * exclusive-create transaction. Split from new.ts on the same seam vouch's\n * commitStamp and gherkin's commitEmission sit on — everything in here holds\n * the docs lock, nothing outside it does — and, as there, the split keeps the\n * window's extent visible in the code shape. This module prints nothing; the\n * caller renders every arm.\n */\nimport { type FeatureEntry } from \"../../core/repo/entries.js\";\nimport { type DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { resolveFeature } from \"../../core/repo/repo.js\";\nimport { DocsRepoUnavailableError } from \"../../core/repo/state.js\";\nimport { stageWrites } from \"../../core/staging/commit.js\";\nimport { type CommitRecovery } from \"../../core/staging/interrupted.js\";\nimport { LOCK_WAIT_MS } from \"../../core/staging/lock.js\";\nimport { openCommitWindow } from \"../../core/staging/recovery/recover.js\";\nimport { commitStaged } from \"../../core/staging/txn/transaction.js\";\nimport { type PlannedWrite } from \"../../core/staging/writes.js\";\n\nexport type ScaffoldCommit =\n  | { ok: true; recovered: CommitRecovery | null }\n  | {\n      ok: false;\n      code: \"docs-busy\" | \"commit-interrupted\" | \"merge-failed\" | \"rollback-incomplete\";\n      message: string;\n    }\n  /** The feature exists — found by the under-lock check, or by losing the create race. */\n  | { ok: false; code: \"already-exists\"; existing: FeatureEntry | null; recovered: CommitRecovery | null }\n  /**\n   * The docs repo went away between the command's gate and the locked read.\n   * Deliberately NOT a `code:` arm: the caller renders it through the shared\n   * docs-repo reporter, and the codes-drift collector reads every `code:`\n   * literal as a stable emission — which this discriminant is not.\n   */\n  | { ok: false; repoGone: DocsRepoUnavailableError };\n\nexport async function commitScaffold(\n  docsDir: DocsDir,\n  featureId: string,\n  writes: PlannedWrite[],\n): Promise<ScaffoldCommit> {\n  // The commit window holds the docs lock: two `new`s for one id serialise\n  // into a stable already-exists, and a predecessor's interrupted commit is\n  // rolled forward (or refused) before this one stages anything.\n  const opened = await openCommitWindow(docsDir, LOCK_WAIT_MS);\n  if (!opened.ok) return opened;\n  const { recovered } = opened;\n  try {\n    // The one existence check, UNDER the lock and AFTER recovery: two racing\n    // runs serialise on it, and a recovered half-scaffold has been completed\n    // by the recovery above, so this refusal is truthful.\n    let existing: FeatureEntry | null;\n    try {\n      existing = await resolveFeature(docsDir, featureId, \"include\");\n    } catch (err) {\n      // The command's gate already refused both broken states, so reaching\n      // here means the docs repo went away between that check and this read.\n      // Same breach, same two codes — the alternative is a stack trace under\n      // `internal` that names neither.\n      if (!(err instanceof DocsRepoUnavailableError)) throw err;\n      return { ok: false, repoGone: err };\n    }\n    if (existing) return { ok: false, code: \"already-exists\", existing, recovered };\n    const staged = await stageWrites(writes);\n    const committed = await commitStaged(\n      { root: docsDir, command: \"new\", rerun: `loam new ${featureId}`, target: featureId },\n      staged,\n      \"scaffolded\",\n    );\n    if (!committed.ok) {\n      // A lost exclusive-create race IS the feature existing: the other `new`\n      // won, and this refusal is the same stable answer the check above gives\n      // when it sees the winner first.\n      return committed.raced\n        ? { ok: false, code: \"already-exists\", existing: null, recovered }\n        : { ok: false, code: committed.code, message: committed.message };\n    }\n    return { ok: true, recovered };\n  } finally {\n    await opened.release();\n  }\n}\n"]}

package/dist/commands/new/modifies.js

@@ -0,0 +1,206 @@
+/**
+ * `loam new --modifies <Req-ID>`: the small-change lane's one hand step,
+ * done by the scaffold.
+ *
+ * A change that rewrites a requirement the fleet already has used to cost a
+ * hand copy and a second command: the scaffold offered only the ADDED example
+ * inside its comment, so the author copied the living requirement into a
+ * `## MODIFIED Requirements` section by hand — most of a small delta is that
+ * copy — and then ran `loam rebase` to pin it. This module does both at
+ * scaffold time: it finds each named requirement in the living specs of the
+ * services the feature touches and writes it, UNCOMMENTED, under a MODIFIED
+ * heading with its `Based-On:` pin already set.
+ *
+ * THE PIN IS REBASE'S PIN, not a second rule for one. `requirementDigest` of
+ * the living requirement, selected by its `Requirement-ID:` exactly as
+ * `selectLiving` (commands/rebase/plan.ts) selects one, and written where
+ * `serializeRequirements` puts it — under the id line, where `pinEdit` inserts
+ * it too. So a scaffold followed by `loam rebase` reports every pin
+ * `unchanged`, and a living requirement that moves between this scaffold and
+ * the archive is `delta.baseline-stale`, exactly as if the author had copied
+ * and pinned it by hand at this moment. The gate is the same gate; only the
+ * typing went away.
+ *
+ * WHY THE BLOCK SHIPS LIVE, when every other template example ships inside a
+ * comment. Those examples are placeholder text nobody wrote, and a live one
+ * once archived a literal TODO into the living spec — so they declare nothing
+ * until a person copies them out. This block is the opposite: it is the
+ * fleet's own current text, and the one honest state for it to be in is the
+ * state archive would merge. Left unedited it merges as no change to the
+ * living wording, which is why the comment above it says to edit in place.
+ *
+ * ADDRESSED BY `Requirement-ID:` ONLY. A requirement without that line is
+ * addressed by its heading everywhere else, but a heading is free text with
+ * spaces in it and no grammar a flag value can be checked against; offering it
+ * here would teach identity-by-heading on the one path built to be typed.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repoPath } from "../../core/envelope/json.js";
+import { NotUtf8DocumentError } from "../../core/kernel/document-bytes.js";
+import { parseRequirements, readRequirementsDocument } from "../../core/document/parse.js";
+import { REQUIREMENT_ID_RE, requirementDigest, serializeRequirements, withoutBaseline, } from "../../core/document/spec.js";
+import { compareIds, nearestIds } from "../../core/repo/entries.js";
+import { SPEC_AXES, servicePathsAt } from "../../core/repo/paths.js";
+import { enumeratedServices } from "../../core/repo/service-target.js";
+import { archSpecTemplate, specTemplate } from "./templates.js";
+/** Every identified requirement in one service's living spec files, one entry per (axis, requirement). */
+async function livingRequirements(docsDir, entry) {
+    const paths = servicePathsAt(entry.dir);
+    const found = [];
+    for (const axis of SPEC_AXES) {
+        const path = paths[axis.key];
+        if (!existsSync(path))
+            continue;
+        for (const r of parseRequirements(await readRequirementsDocument(path))) {
+            if (r.id === undefined)
+                continue;
+            // The pin is taken over the requirement WITHOUT any baseline it carries —
+            // a living document should hold none (archive strips them), and one that
+            // does must not end up with two `Based-On:` lines in the scaffold.
+            const living = withoutBaseline(r);
+            found.push({
+                id: r.id,
+                service: entry.id,
+                axis,
+                living: repoPath(docsDir, path),
+                requirement: { ...living, basedOn: requirementDigest(living) },
+            });
+        }
+    }
+    return found;
+}
+/**
+ * Which services OUTSIDE the touched set carry the id — read only on the
+ * refusal path, where a fleet-wide walk is paid once by a run that is about to
+ * stop anyway. The commonest way to miss is to name the right requirement and
+ * the wrong (or no) `--touches`, and the useful refusal names the service.
+ * An undecodable document there is skipped: this is a hint, not a grade.
+ */
+async function carriersElsewhere(docsDir, id, skip) {
+    const carriers = [];
+    for (const entry of await enumeratedServices(docsDir)) {
+        if (skip.has(entry.id))
+            continue;
+        try {
+            if ((await livingRequirements(docsDir, entry)).some((t) => t.id === id))
+                carriers.push(entry.id);
+        }
+        catch (err) {
+            if (!(err instanceof NotUtf8DocumentError))
+                throw err;
+        }
+    }
+    return carriers.sort(compareIds);
+}
+function unknownMessage(id, touched, known) {
+    const where = touched.length === 0
+        ? "this feature touches no service — name the one that owns it with --touches"
+        : `it names no requirement in the living specs of ${touched.map((s) => `'${s}'`).join(", ")}`;
+    const near = nearestIds(id, [...known]);
+    return (`--modifies '${id}': ${where}.` +
+        (near.length === 0 ? "" : ` Did you mean ${near.map((n) => `'${n}'`).join(" or ")}?`) +
+        " A requirement is addressed by its `Requirement-ID:` line; one without that line cannot be named here.");
+}
+/**
+ * Resolve every `--modifies` id against the living specs of the touched
+ * services, before anything is written. In flag order, each id once.
+ */
+export async function planModifies(docsDir, touched, ids) {
+    for (const id of ids) {
+        if (!REQUIREMENT_ID_RE.test(id)) {
+            return {
+                ok: false,
+                code: "invalid-option",
+                message: `--modifies '${id}' is not a Requirement-ID — it takes the value of a living requirement's \`Requirement-ID:\` line, not its heading.`,
+            };
+        }
+    }
+    const scope = new Set(touched);
+    let living = [];
+    try {
+        for (const entry of await enumeratedServices(docsDir)) {
+            if (scope.has(entry.id))
+                living = living.concat(await livingRequirements(docsDir, entry));
+        }
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8DocumentError))
+            throw err;
+        // A pin is a claim about text somebody read, and over a document loam could
+        // not decode it would be a digest of mojibake — `loam rebase` refuses the
+        // same document under the same code, and so does this, before any write.
+        return { ok: false, code: "merge-failed", message: `--modifies cannot copy from a living spec loam cannot read — nothing was scaffolded: ${err.message}` };
+    }
+    const targets = [];
+    for (const id of new Set(ids)) {
+        const hits = living.filter((t) => t.id === id);
+        if (hits.length === 1) {
+            targets.push(hits[0]);
+            continue;
+        }
+        if (hits.length > 1) {
+            // A Requirement-ID is unique inside ONE document, so two touched
+            // documents may both carry it (and a document that repeats one is its
+            // own finding, `delta.living-duplicate-requirement`). Picking one would
+            // be loam guessing which requirement the author means to rewrite.
+            return {
+                ok: false,
+                code: "invalid-option",
+                message: `--modifies '${id}' is a Requirement-ID in more than one living document this feature touches ` +
+                    `(${[...new Set(hits.map((t) => t.living))].join(", ")}), and an id is unique only inside its own document. ` +
+                    "Touch only the service whose requirement changes, and write the other service's delta by hand.",
+            };
+        }
+        const elsewhere = await carriersElsewhere(docsDir, id, scope);
+        const known = [...new Set(living.map((t) => t.id))];
+        return {
+            ok: false,
+            code: "unknown-target",
+            message: elsewhere.length > 0
+                ? `--modifies '${id}' is a requirement of ${elsewhere.map((s) => `'${s}'`).join(", ")}, which this feature does not touch — add --touches ${elsewhere[0]}.`
+                : unknownMessage(id, touched, known),
+        };
+    }
+    return { ok: true, targets };
+}
+/**
+ * The MODIFIED section one delta file carries, appended after the template's
+ * own comment. The guidance sits ABOVE the H2 on purpose: below it, before the
+ * first `### Requirement:`, it would be section prose of the very section the
+ * merge reads, and no comment there is worth that question.
+ */
+export function modifiedSection(featureId, targets) {
+    return `
+<!-- Each requirement below is the LIVING text, copied by \`loam new\` for an id you
+     named and pinned (Based-On:) to the version you are rewriting — the pin
+     \`loam rebase ${featureId}\` would write, so there is nothing to rebase unless the
+     living text moves first.
+     Edit it in place: a MODIFIED carries its full new text, and archive replaces the
+     living requirement with exactly what is here — left as copied, it changes nothing.
+     Keep the Requirement-ID: and Based-On: lines as they are. -->
+
+## MODIFIED Requirements
+
+${serializeRequirements(targets.map((t) => t.requirement))}`;
+}
+/**
+ * The delta files `--modifies` writes or extends, keyed as `new` keys its
+ * plan (relative to the feature directory). A business-axis target lands in
+ * the `spec.md` the touched service already gets; an architecture-axis target
+ * gets the `arch.spec.md` template a touched service is otherwise not handed,
+ * because the requirement it rewrites lives there.
+ */
+export function modifiedFiles(featureId, targets, planned) {
+    const out = {};
+    for (const t of targets) {
+        const rel = join("specs", t.service, t.axis.file);
+        if (rel in out)
+            continue;
+        const mine = targets.filter((other) => other.service === t.service && other.axis.key === t.axis.key);
+        const base = planned[rel] ?? (t.axis.key === "spec" ? specTemplate(featureId, t.service) : archSpecTemplate(featureId, t.service));
+        out[rel] = base + modifiedSection(featureId, mine);
+    }
+    return out;
+}
+//# sourceMappingURL=modifies.js.map

package/dist/commands/new/modifies.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modifies.js","sourceRoot":"","sources":["../../../src/commands/new/modifies.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam new --modifies <Req-ID>`: the small-change lane's one hand step,\n * done by the scaffold.\n *\n * A change that rewrites a requirement the fleet already has used to cost a\n * hand copy and a second command: the scaffold offered only the ADDED example\n * inside its comment, so the author copied the living requirement into a\n * `## MODIFIED Requirements` section by hand — most of a small delta is that\n * copy — and then ran `loam rebase` to pin it. This module does both at\n * scaffold time: it finds each named requirement in the living specs of the\n * services the feature touches and writes it, UNCOMMENTED, under a MODIFIED\n * heading with its `Based-On:` pin already set.\n *\n * THE PIN IS REBASE'S PIN, not a second rule for one. `requirementDigest` of\n * the living requirement, selected by its `Requirement-ID:` exactly as\n * `selectLiving` (commands/rebase/plan.ts) selects one, and written where\n * `serializeRequirements` puts it — under the id line, where `pinEdit` inserts\n * it too. So a scaffold followed by `loam rebase` reports every pin\n * `unchanged`, and a living requirement that moves between this scaffold and\n * the archive is `delta.baseline-stale`, exactly as if the author had copied\n * and pinned it by hand at this moment. The gate is the same gate; only the\n * typing went away.\n *\n * WHY THE BLOCK SHIPS LIVE, when every other template example ships inside a\n * comment. Those examples are placeholder text nobody wrote, and a live one\n * once archived a literal TODO into the living spec — so they declare nothing\n * until a person copies them out. This block is the opposite: it is the\n * fleet's own current text, and the one honest state for it to be in is the\n * state archive would merge. Left unedited it merges as no change to the\n * living wording, which is why the comment above it says to edit in place.\n *\n * ADDRESSED BY `Requirement-ID:` ONLY. A requirement without that line is\n * addressed by its heading everywhere else, but a heading is free text with\n * spaces in it and no grammar a flag value can be checked against; offering it\n * here would teach identity-by-heading on the one path built to be typed.\n */\nimport { existsSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { repoPath } from \"../../core/envelope/json.js\";\nimport { NotUtf8DocumentError } from \"../../core/kernel/document-bytes.js\";\nimport { parseRequirements, readRequirementsDocument } from \"../../core/document/parse.js\";\nimport {\n  REQUIREMENT_ID_RE,\n  requirementDigest,\n  serializeRequirements,\n  withoutBaseline,\n  type Requirement,\n} from \"../../core/document/spec.js\";\nimport { compareIds, nearestIds, type ServiceEntry } from \"../../core/repo/entries.js\";\nimport { SPEC_AXES, servicePathsAt, type SpecAxis } from \"../../core/repo/paths.js\";\nimport { enumeratedServices } from \"../../core/repo/service-target.js\";\nimport type { DocsDir } from \"../../core/kernel/ids/dirs.js\";\nimport { archSpecTemplate, specTemplate } from \"./templates.js\";\n\n/** One living requirement `--modifies` named, where it lives, and the pin it is scaffolded with. */\nexport interface ModifiedTarget {\n  readonly id: string;\n  readonly service: string;\n  readonly axis: SpecAxis;\n  /** The living document it was copied from, repo-relative — what a message names. */\n  readonly living: string;\n  /** The living requirement, its pin set — the block the delta carries. */\n  readonly requirement: Requirement;\n}\n\nexport type ModifiesPlan =\n  | { readonly ok: true; readonly targets: readonly ModifiedTarget[] }\n  | { readonly ok: false; readonly code: \"invalid-option\" | \"unknown-target\" | \"merge-failed\"; readonly message: string };\n\n/** Every identified requirement in one service's living spec files, one entry per (axis, requirement). */\nasync function livingRequirements(docsDir: DocsDir, entry: ServiceEntry): Promise<ModifiedTarget[]> {\n  const paths = servicePathsAt(entry.dir);\n  const found: ModifiedTarget[] = [];\n  for (const axis of SPEC_AXES) {\n    const path = paths[axis.key];\n    if (!existsSync(path)) continue;\n    for (const r of parseRequirements(await readRequirementsDocument(path))) {\n      if (r.id === undefined) continue;\n      // The pin is taken over the requirement WITHOUT any baseline it carries —\n      // a living document should hold none (archive strips them), and one that\n      // does must not end up with two `Based-On:` lines in the scaffold.\n      const living = withoutBaseline(r);\n      found.push({\n        id: r.id,\n        service: entry.id,\n        axis,\n        living: repoPath(docsDir, path),\n        requirement: { ...living, basedOn: requirementDigest(living) },\n      });\n    }\n  }\n  return found;\n}\n\n/**\n * Which services OUTSIDE the touched set carry the id — read only on the\n * refusal path, where a fleet-wide walk is paid once by a run that is about to\n * stop anyway. The commonest way to miss is to name the right requirement and\n * the wrong (or no) `--touches`, and the useful refusal names the service.\n * An undecodable document there is skipped: this is a hint, not a grade.\n */\nasync function carriersElsewhere(docsDir: DocsDir, id: string, skip: ReadonlySet<string>): Promise<string[]> {\n  const carriers: string[] = [];\n  for (const entry of await enumeratedServices(docsDir)) {\n    if (skip.has(entry.id)) continue;\n    try {\n      if ((await livingRequirements(docsDir, entry)).some((t) => t.id === id)) carriers.push(entry.id);\n    } catch (err) {\n      if (!(err instanceof NotUtf8DocumentError)) throw err;\n    }\n  }\n  return carriers.sort(compareIds);\n}\n\nfunction unknownMessage(id: string, touched: readonly string[], known: readonly string[]): string {\n  const where = touched.length === 0\n    ? \"this feature touches no service — name the one that owns it with --touches\"\n    : `it names no requirement in the living specs of ${touched.map((s) => `'${s}'`).join(\", \")}`;\n  const near = nearestIds(id, [...known]);\n  return (\n    `--modifies '${id}': ${where}.` +\n    (near.length === 0 ? \"\" : ` Did you mean ${near.map((n) => `'${n}'`).join(\" or \")}?`) +\n    \" A requirement is addressed by its `Requirement-ID:` line; one without that line cannot be named here.\"\n  );\n}\n\n/**\n * Resolve every `--modifies` id against the living specs of the touched\n * services, before anything is written. In flag order, each id once.\n */\nexport async function planModifies(\n  docsDir: DocsDir,\n  touched: readonly string[],\n  ids: readonly string[],\n): Promise<ModifiesPlan> {\n  for (const id of ids) {\n    if (!REQUIREMENT_ID_RE.test(id)) {\n      return {\n        ok: false,\n        code: \"invalid-option\",\n        message: `--modifies '${id}' is not a Requirement-ID — it takes the value of a living requirement's \\`Requirement-ID:\\` line, not its heading.`,\n      };\n    }\n  }\n  const scope = new Set(touched);\n  let living: ModifiedTarget[] = [];\n  try {\n    for (const entry of await enumeratedServices(docsDir)) {\n      if (scope.has(entry.id)) living = living.concat(await livingRequirements(docsDir, entry));\n    }\n  } catch (err) {\n    if (!(err instanceof NotUtf8DocumentError)) throw err;\n    // A pin is a claim about text somebody read, and over a document loam could\n    // not decode it would be a digest of mojibake — `loam rebase` refuses the\n    // same document under the same code, and so does this, before any write.\n    return { ok: false, code: \"merge-failed\", message: `--modifies cannot copy from a living spec loam cannot read — nothing was scaffolded: ${err.message}` };\n  }\n  const targets: ModifiedTarget[] = [];\n  for (const id of new Set(ids)) {\n    const hits = living.filter((t) => t.id === id);\n    if (hits.length === 1) {\n      targets.push(hits[0]!);\n      continue;\n    }\n    if (hits.length > 1) {\n      // A Requirement-ID is unique inside ONE document, so two touched\n      // documents may both carry it (and a document that repeats one is its\n      // own finding, `delta.living-duplicate-requirement`). Picking one would\n      // be loam guessing which requirement the author means to rewrite.\n      return {\n        ok: false,\n        code: \"invalid-option\",\n        message:\n          `--modifies '${id}' is a Requirement-ID in more than one living document this feature touches ` +\n          `(${[...new Set(hits.map((t) => t.living))].join(\", \")}), and an id is unique only inside its own document. ` +\n          \"Touch only the service whose requirement changes, and write the other service's delta by hand.\",\n      };\n    }\n    const elsewhere = await carriersElsewhere(docsDir, id, scope);\n    const known = [...new Set(living.map((t) => t.id))];\n    return {\n      ok: false,\n      code: \"unknown-target\",\n      message: elsewhere.length > 0\n        ? `--modifies '${id}' is a requirement of ${elsewhere.map((s) => `'${s}'`).join(\", \")}, which this feature does not touch — add --touches ${elsewhere[0]}.`\n        : unknownMessage(id, touched, known),\n    };\n  }\n  return { ok: true, targets };\n}\n\n/**\n * The MODIFIED section one delta file carries, appended after the template's\n * own comment. The guidance sits ABOVE the H2 on purpose: below it, before the\n * first `### Requirement:`, it would be section prose of the very section the\n * merge reads, and no comment there is worth that question.\n */\nexport function modifiedSection(featureId: string, targets: readonly ModifiedTarget[]): string {\n  return `\n<!-- Each requirement below is the LIVING text, copied by \\`loam new\\` for an id you\n     named and pinned (Based-On:) to the version you are rewriting — the pin\n     \\`loam rebase ${featureId}\\` would write, so there is nothing to rebase unless the\n     living text moves first.\n     Edit it in place: a MODIFIED carries its full new text, and archive replaces the\n     living requirement with exactly what is here — left as copied, it changes nothing.\n     Keep the Requirement-ID: and Based-On: lines as they are. -->\n\n## MODIFIED Requirements\n\n${serializeRequirements(targets.map((t) => t.requirement))}`;\n}\n\n/**\n * The delta files `--modifies` writes or extends, keyed as `new` keys its\n * plan (relative to the feature directory). A business-axis target lands in\n * the `spec.md` the touched service already gets; an architecture-axis target\n * gets the `arch.spec.md` template a touched service is otherwise not handed,\n * because the requirement it rewrites lives there.\n */\nexport function modifiedFiles(\n  featureId: string,\n  targets: readonly ModifiedTarget[],\n  planned: Readonly<Record<string, string>>,\n): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const t of targets) {\n    const rel = join(\"specs\", t.service, t.axis.file);\n    if (rel in out) continue;\n    const mine = targets.filter((other) => other.service === t.service && other.axis.key === t.axis.key);\n    const base = planned[rel] ?? (t.axis.key === \"spec\" ? specTemplate(featureId, t.service) : archSpecTemplate(featureId, t.service));\n    out[rel] = base + modifiedSection(featureId, mine);\n  }\n  return out;\n}\n"]}