@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/commands/tasks/render.js

@@ -0,0 +1,253 @@
+import { actionOf, groupOf } from "./actions.js";
+/**
+ * How many units one service shows in the WHOLE-feature view before the rest
+ * are elided behind its own lens. Under a lens nothing is elided: the lens IS
+ * the full listing, and pointing a person who already asked for one service at
+ * `--json` to see the rest of it sent them to the one view not written for them.
+ */
+const PER_SERVICE_LIMIT = 12;
+/** What each record state means for the list below it, in the words a reader acts on. */
+const RECORD_MEANING = {
+    absent: "no verification record yet, so nothing counts as done",
+    recorded: "the verification record answers this checklist; what it confirmed is off this list, bar attested scenarios",
+    stale: "the verification record answers an older question set, so it closes nothing until it is re-recorded",
+    unreadable: "the verification record could not be read, so it closes nothing",
+};
+/**
+ * What the stamps reading means, which turns on WHERE loam is standing.
+ *
+ * The stamps are read from this repository's generated suite and nobody else's
+ * (core/tasks/stamps.ts). So a scenario owned by another service reads
+ * `implement` whatever its own repository holds — the packet's honest answer,
+ * because nothing here looked — and the header says so whenever such a unit is
+ * on screen, or a person reads "implement" as "the test exists".
+ */
+function stampsMeaning(packet, view) {
+    if (packet.stamps === "unknown") {
+        return view.bound === undefined
+            ? "this is not a service repository bound with loam.json, so loam cannot see which tests were generated — " +
+                "run it in the service's repo to tell 'generate' from 'implement'"
+            : `this repository's generated suite (${view.bound}) could not be read — an unreadable directory, ` +
+                "or a gherkinDir outside the repository — so no scenario reads 'generate'";
+    }
+    const own = `from this repository's generated suite${view.bound === undefined ? "" : ` (${view.bound})`}`;
+    const elsewhere = [
+        ...new Set(packet.units.filter((unit) => unit.kind === "scenario.tested" && unit.subject !== view.bound).map((u) => u.subject)),
+    ];
+    if (elsewhere.length === 0)
+        return own;
+    const one = elsewhere.length === 1;
+    return (`${own}; ${elsewhere.join(", ")} ${one ? "keeps its tests in its own repository" : "keep their tests in their own repositories"}, ` +
+        `so ${one ? "its" : "their"} scenarios read 'implement' whatever is generated there — ` +
+        `run loam tasks in ${one ? "that repository" : "those repositories"}`);
+}
+/** Which slice of the feature this is, and how to get another. */
+function lensLine(packet, view) {
+    const lens = packet.service;
+    if (lens !== null && view.explicitLens)
+        return `lens: ${lens} — its units only, every one listed`;
+    if (lens !== null)
+        return `lens: ${lens} — this repository's service (loam.json); pass --service <id> for another`;
+    const among = packet.services.length === 0 ? "" : ` (${packet.services.join(", ")})`;
+    return view.bound === undefined
+        ? `view: the whole feature${among} — --service <id> narrows it to one service`
+        : `view: the whole feature${among} — this repository's service, ${view.bound}, is not one ${packet.feature} touches`;
+}
+/** The lines under the title both views share: what the record and the stamps MEAN, the lens, the blind spots. */
+function header(packet, view) {
+    console.log(`  record: ${packet.record} — ${RECORD_MEANING[packet.record]}`);
+    console.log(`  stamps: ${packet.stamps} — ${stampsMeaning(packet, view)}`);
+    console.log(`  ${lensLine(packet, view)}`);
+    // The blind spots straight after, and before any list: an empty packet over a
+    // document nobody could read is the one output an implementer must never take
+    // at face value, and a warning under fifty lines of units is one nobody reads.
+    for (const warning of blindSpots(packet))
+        console.log(`  ⚠ ${warning}`);
+}
+/** The step tag, padded so the actions line up: `[implement]` is the widest. */
+function tag(step) {
+    return `[${step}]`.padEnd("[implement]".length);
+}
+/** One row: the step, the action, the scenario's own line when it has one, and the id an agent hands on. */
+function row(unit, feature) {
+    const source = unit.source;
+    const line = source !== undefined && "scenario" in source && source.line !== undefined ? ` · line ${source.line}` : "";
+    return `      ${tag(unit.at)} ${actionOf(unit, feature)}${line} · ${unit.id}`;
+}
+/** Units filed under their heading, in the order the packet already sorted them — first appearance wins. */
+function grouped(units) {
+    const groups = new Map();
+    for (const unit of units) {
+        const group = groupOf(unit);
+        const existing = groups.get(group.key);
+        if (existing === undefined)
+            groups.set(group.key, { ...group, units: [unit] });
+        else
+            existing.units.push(unit);
+    }
+    return [...groups.values()];
+}
+/** `9 open`, plus the attested ones when there are any — those are listed, and are not work. */
+function tally(units) {
+    const attested = units.filter((unit) => unit.at === "attested").length;
+    return `${units.length - attested} open${attested === 0 ? "" : ` · ${attested} attested`}`;
+}
+/** The `--next` invocation for this packet's own slice — the flag carried only when the reader typed it. */
+function nextCommand(packet, view) {
+    const lens = view.explicitLens && packet.service !== null ? ` --service ${packet.service}` : "";
+    return `loam tasks ${packet.feature}${lens} --next`;
+}
+/**
+ * The frontier as a person reads it: the head's action first, then the ids.
+ * A bare list of ten hashes said what to do to nobody; the ids stay, because
+ * they are the order an orchestrator hands units out in.
+ */
+function frontierLines(packet, view) {
+    const headId = packet.frontier[0];
+    if (headId === undefined)
+        return [];
+    const head = packet.units.find((unit) => unit.id === headId);
+    const more = packet.frontierElided > 0 ? ` (+${packet.frontierElided} more open)` : "";
+    return [
+        head === undefined
+            ? `  next up: ${headId}`
+            : `  next up (${head.subject}): ${actionOf(head, packet.feature)} · ${headId}`,
+        `    ${nextCommand(packet, view)} prints it in full, with what closes it`,
+        `    frontier, the order to take open units in: ${packet.frontier.join(", ")}${more}`,
+    ];
+}
+export function renderPacket(packet, view) {
+    // Attested is the one count whose word misleads: it reads like "done", and
+    // it is the opposite — complete work resting on an assertion, still listed.
+    const attested = packet.counts.attested === 0 ? "" : " (confirmed on an agent's word, not a run — still listed)";
+    console.log(`${packet.feature} — ${packet.counts.open} open · ${packet.counts.done} done · ${packet.counts.attested} attested${attested}`);
+    header(packet, view);
+    console.log("");
+    if (packet.units.length === 0) {
+        console.log(packet.counts.attested > 0 || packet.counts.done > 0
+            ? "  Nothing open. Every unit is recorded confirmed, or attested and waiting on a run."
+            : "  Nothing open — this feature's delta, specs and contracts promise nothing yet.");
+    }
+    const capped = packet.service === null;
+    for (const subject of new Set(packet.units.map((unit) => unit.subject))) {
+        const units = packet.units.filter((unit) => unit.subject === subject);
+        const shown = capped ? units.slice(0, PER_SERVICE_LIMIT) : units;
+        console.log(`  ${subject} — ${tally(units)}`);
+        for (const group of grouped(shown)) {
+            console.log(`    ${group.heading}`);
+            for (const unit of group.units)
+                console.log(row(unit, packet.feature));
+        }
+        if (shown.length < units.length) {
+            console.log(`    +${units.length - shown.length} more — \`loam tasks ${packet.feature} --service ${subject}\` lists every one`);
+        }
+        console.log("");
+    }
+    for (const line of frontierLines(packet, view))
+        console.log(line);
+    for (const waiting of packet.waitingOn ?? []) {
+        console.log(`  waiting on ${waiting.subject}: ${waiting.claim} · ${waiting.id}, still open there`);
+    }
+    if (packet.units.length > 0) {
+        console.log("\n  [step] is where a unit waits: describe → generate → implement, or attested. " +
+            "`loam explain <word>` defines each of those, and frontier.");
+    }
+    console.log("\n  Review:");
+    for (const note of packet.review)
+        console.log(`    - ${note}`);
+}
+/**
+ * The leaf, in full. The follow-up command is literal rather than a shape to
+ * fill in, because the reader is usually a model cheap enough that "the
+ * appropriate verify invocation" is a guess it will get wrong.
+ */
+export function renderNext(packet, view) {
+    const unit = packet.units[0];
+    if (unit === undefined) {
+        console.log(`${packet.feature} — nothing open (${packet.counts.done} done · ${packet.counts.attested} attested)`);
+        header(packet, view);
+        return;
+    }
+    console.log(`${packet.feature} — next: ${unit.id}`);
+    console.log(`  ${actionOf(unit, packet.feature)}`);
+    // The lens only when the binding chose it: a reader who typed --service knows
+    // which slice this is, and one who did not would otherwise be handed another
+    // service's head with no word on why it is this one.
+    if (packet.service !== null && !view.explicitLens)
+        console.log(`  ${lensLine(packet, view)}`);
+    for (const warning of blindSpots(packet))
+        console.log(`  ⚠ ${warning}`);
+    const ungraded = ungradedScenario(packet, view, unit);
+    if (ungraded !== undefined)
+        console.log(`  ⚠ ${ungraded}`);
+    console.log("");
+    console.log(`  [${unit.at}] ${unit.kind}  [${unit.subject}]`);
+    console.log(`  ${unit.claim}`);
+    const source = unit.source;
+    if (source !== undefined) {
+        console.log(`  ${source.path}${source.line === undefined ? "" : `:${source.line}`}`);
+        // Verbatim, never reflowed: these are the bytes the scenario digest was
+        // taken over, and a test written from reworded criteria answers a claim
+        // nobody made.
+        if ("lines" in source)
+            for (const body of source.lines)
+                console.log(`    ${body}`);
+    }
+    if (unit.dependsOn.length > 0)
+        console.log(`  depends on: ${unit.dependsOn.join(", ")}`);
+    console.log(`\n  done: ${unit.done.check}`);
+    console.log(`\n  ${followUp(packet.feature, unit)}`);
+}
+/**
+ * The caveat a scenario at `implement` needs when nobody looked for its
+ * generated test: `implement` is also what a scenario reads when the stamps
+ * could not be read, or belong to another repository, and handing a worker
+ * "make it pass" for a test that was never generated sends them to write one by
+ * hand — the paraphrase the generated suite exists to prevent.
+ */
+function ungradedScenario(packet, view, unit) {
+    if (unit.kind !== "scenario.tested" || unit.at !== "implement")
+        return undefined;
+    if (packet.stamps === "read" && unit.subject === view.bound)
+        return undefined;
+    if (unit.subject === view.bound) {
+        return ("whether this scenario's test was generated is unknown — this repository's generated suite could not be read; " +
+            `if loam gherkin ${packet.feature} has not run here, run it first`);
+    }
+    return (`whether this scenario's test was generated is unknown here — its suite lives in ${unit.subject}'s repository; ` +
+        `run loam tasks there, or loam gherkin ${packet.feature} there first if it has not run`);
+}
+/**
+ * The command that closes this unit.
+ *
+ * A `describe` unit is the one arm that is NOT a `loam verify --record`: there
+ * is no claim to answer, because a requirement with no scenario asks no
+ * question — the work is writing the Given/When/Then into the file named above,
+ * and `loam validate --feature` is what grades that it landed. Pointing it at
+ * `--record` would invite an answer to a question the checklist does not carry.
+ */
+function followUp(feature, unit) {
+    if (unit.at === "describe")
+        return `loam validate --feature ${feature}`;
+    if (unit.at === "generate")
+        return `loam gherkin ${feature}`;
+    if (unit.kind === "scenario.tested") {
+        return `loam verify ${feature} --service ${unit.subject} --results report.json`;
+    }
+    return `loam verify ${feature} --record answers.json --service ${unit.subject}`;
+}
+/** What the packet could not look at — one sentence per document class. */
+function blindSpots(packet) {
+    const out = [];
+    if (packet.unreadable.architecture !== undefined) {
+        out.push(`delta.likec4 does not parse (${packet.unreadable.architecture}) — no c4.calls unit could be derived, ` +
+            "so this list is short because loam could not look, not because the work is done");
+    }
+    const contracts = packet.unreadable.contracts;
+    if (contracts !== undefined) {
+        out.push(`contract delta unreadable for ${contracts.join(", ")} — operations and messages are missing from this packet, ` +
+            "not absent from the feature");
+    }
+    return out;
+}
+//# sourceMappingURL=render.js.map

package/dist/commands/tasks/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/commands/tasks/render.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The terminal view of a work packet.\n *\n * Two shapes for two readers. The whole packet is a person's orientation — how\n * much is open, filed under which service and which requirement, what each unit\n * asks them to DO, and which unit leads — so every row is an action rather than\n * the claim it answers, and the requirement's file is printed once over its\n * scenarios rather than on each of them. `--next` is the opposite: a single\n * leaf, printed in full, including the scenario's Given/When/Then VERBATIM,\n * because that text is the acceptance criterion and the exact words the digest\n * was taken over. Paraphrasing it into a summary is the one thing the digest\n * chain exists to prevent.\n *\n * Every row keeps its unit id. The id is what an agent hands `loam verify`, and\n * a view that dropped it to read better would turn the human listing into one\n * nobody can act on without a second, `--json`, run.\n *\n * Every `loam …` line printed here parses against the real CLI —\n * `test/agent-commands-runnable.test.ts` is the consumer, and an instruction\n * loam prints that does not parse is a defect rather than a typo.\n */\nimport type { WorkPacket } from \"../../core/tasks/packet.js\";\nimport type { RecordState } from \"../../core/tasks/record.js\";\nimport type { TaskStep, TaskUnit } from \"../../core/tasks/unit.js\";\nimport { actionOf, groupOf, type UnitGroup } from \"./actions.js\";\n\n/** What the command knows and the packet does not: where the lens came from, and which repository this is. */\nexport interface TasksView {\n  /** True when `--service` named the lens; false when it came from the binding, or there is none. */\n  explicitLens: boolean;\n  /** loam.json's `service` — set only when standing in a service repository. */\n  bound: string | undefined;\n}\n\n/**\n * How many units one service shows in the WHOLE-feature view before the rest\n * are elided behind its own lens. Under a lens nothing is elided: the lens IS\n * the full listing, and pointing a person who already asked for one service at\n * `--json` to see the rest of it sent them to the one view not written for them.\n */\nconst PER_SERVICE_LIMIT = 12;\n\n/** What each record state means for the list below it, in the words a reader acts on. */\nconst RECORD_MEANING: Record<RecordState, string> = {\n  absent: \"no verification record yet, so nothing counts as done\",\n  recorded: \"the verification record answers this checklist; what it confirmed is off this list, bar attested scenarios\",\n  stale: \"the verification record answers an older question set, so it closes nothing until it is re-recorded\",\n  unreadable: \"the verification record could not be read, so it closes nothing\",\n};\n\n/**\n * What the stamps reading means, which turns on WHERE loam is standing.\n *\n * The stamps are read from this repository's generated suite and nobody else's\n * (core/tasks/stamps.ts). So a scenario owned by another service reads\n * `implement` whatever its own repository holds — the packet's honest answer,\n * because nothing here looked — and the header says so whenever such a unit is\n * on screen, or a person reads \"implement\" as \"the test exists\".\n */\nfunction stampsMeaning(packet: WorkPacket, view: TasksView): string {\n  if (packet.stamps === \"unknown\") {\n    return view.bound === undefined\n      ? \"this is not a service repository bound with loam.json, so loam cannot see which tests were generated — \" +\n          \"run it in the service's repo to tell 'generate' from 'implement'\"\n      : `this repository's generated suite (${view.bound}) could not be read — an unreadable directory, ` +\n          \"or a gherkinDir outside the repository — so no scenario reads 'generate'\";\n  }\n  const own = `from this repository's generated suite${view.bound === undefined ? \"\" : ` (${view.bound})`}`;\n  const elsewhere = [\n    ...new Set(packet.units.filter((unit) => unit.kind === \"scenario.tested\" && unit.subject !== view.bound).map((u) => u.subject)),\n  ];\n  if (elsewhere.length === 0) return own;\n  const one = elsewhere.length === 1;\n  return (\n    `${own}; ${elsewhere.join(\", \")} ${one ? \"keeps its tests in its own repository\" : \"keep their tests in their own repositories\"}, ` +\n    `so ${one ? \"its\" : \"their\"} scenarios read 'implement' whatever is generated there — ` +\n    `run loam tasks in ${one ? \"that repository\" : \"those repositories\"}`\n  );\n}\n\n/** Which slice of the feature this is, and how to get another. */\nfunction lensLine(packet: WorkPacket, view: TasksView): string {\n  const lens = packet.service;\n  if (lens !== null && view.explicitLens) return `lens: ${lens} — its units only, every one listed`;\n  if (lens !== null) return `lens: ${lens} — this repository's service (loam.json); pass --service <id> for another`;\n  const among = packet.services.length === 0 ? \"\" : ` (${packet.services.join(\", \")})`;\n  return view.bound === undefined\n    ? `view: the whole feature${among} — --service <id> narrows it to one service`\n    : `view: the whole feature${among} — this repository's service, ${view.bound}, is not one ${packet.feature} touches`;\n}\n\n/** The lines under the title both views share: what the record and the stamps MEAN, the lens, the blind spots. */\nfunction header(packet: WorkPacket, view: TasksView): void {\n  console.log(`  record: ${packet.record} — ${RECORD_MEANING[packet.record]}`);\n  console.log(`  stamps: ${packet.stamps} — ${stampsMeaning(packet, view)}`);\n  console.log(`  ${lensLine(packet, view)}`);\n  // The blind spots straight after, and before any list: an empty packet over a\n  // document nobody could read is the one output an implementer must never take\n  // at face value, and a warning under fifty lines of units is one nobody reads.\n  for (const warning of blindSpots(packet)) console.log(`  ⚠ ${warning}`);\n}\n\n/** The step tag, padded so the actions line up: `[implement]` is the widest. */\nfunction tag(step: TaskStep): string {\n  return `[${step}]`.padEnd(\"[implement]\".length);\n}\n\n/** One row: the step, the action, the scenario's own line when it has one, and the id an agent hands on. */\nfunction row(unit: TaskUnit, feature: string): string {\n  const source = unit.source;\n  const line = source !== undefined && \"scenario\" in source && source.line !== undefined ? ` · line ${source.line}` : \"\";\n  return `      ${tag(unit.at)} ${actionOf(unit, feature)}${line} · ${unit.id}`;\n}\n\n/** Units filed under their heading, in the order the packet already sorted them — first appearance wins. */\nfunction grouped(units: readonly TaskUnit[]): Array<UnitGroup & { units: TaskUnit[] }> {\n  const groups = new Map<string, UnitGroup & { units: TaskUnit[] }>();\n  for (const unit of units) {\n    const group = groupOf(unit);\n    const existing = groups.get(group.key);\n    if (existing === undefined) groups.set(group.key, { ...group, units: [unit] });\n    else existing.units.push(unit);\n  }\n  return [...groups.values()];\n}\n\n/** `9 open`, plus the attested ones when there are any — those are listed, and are not work. */\nfunction tally(units: readonly TaskUnit[]): string {\n  const attested = units.filter((unit) => unit.at === \"attested\").length;\n  return `${units.length - attested} open${attested === 0 ? \"\" : ` · ${attested} attested`}`;\n}\n\n/** The `--next` invocation for this packet's own slice — the flag carried only when the reader typed it. */\nfunction nextCommand(packet: WorkPacket, view: TasksView): string {\n  const lens = view.explicitLens && packet.service !== null ? ` --service ${packet.service}` : \"\";\n  return `loam tasks ${packet.feature}${lens} --next`;\n}\n\n/**\n * The frontier as a person reads it: the head's action first, then the ids.\n * A bare list of ten hashes said what to do to nobody; the ids stay, because\n * they are the order an orchestrator hands units out in.\n */\nfunction frontierLines(packet: WorkPacket, view: TasksView): string[] {\n  const headId = packet.frontier[0];\n  if (headId === undefined) return [];\n  const head = packet.units.find((unit) => unit.id === headId);\n  const more = packet.frontierElided > 0 ? ` (+${packet.frontierElided} more open)` : \"\";\n  return [\n    head === undefined\n      ? `  next up: ${headId}`\n      : `  next up (${head.subject}): ${actionOf(head, packet.feature)} · ${headId}`,\n    `    ${nextCommand(packet, view)} prints it in full, with what closes it`,\n    `    frontier, the order to take open units in: ${packet.frontier.join(\", \")}${more}`,\n  ];\n}\n\nexport function renderPacket(packet: WorkPacket, view: TasksView): void {\n  // Attested is the one count whose word misleads: it reads like \"done\", and\n  // it is the opposite — complete work resting on an assertion, still listed.\n  const attested = packet.counts.attested === 0 ? \"\" : \" (confirmed on an agent's word, not a run — still listed)\";\n  console.log(\n    `${packet.feature} — ${packet.counts.open} open · ${packet.counts.done} done · ${packet.counts.attested} attested${attested}`,\n  );\n  header(packet, view);\n  console.log(\"\");\n\n  if (packet.units.length === 0) {\n    console.log(\n      packet.counts.attested > 0 || packet.counts.done > 0\n        ? \"  Nothing open. Every unit is recorded confirmed, or attested and waiting on a run.\"\n        : \"  Nothing open — this feature's delta, specs and contracts promise nothing yet.\",\n    );\n  }\n  const capped = packet.service === null;\n  for (const subject of new Set(packet.units.map((unit) => unit.subject))) {\n    const units = packet.units.filter((unit) => unit.subject === subject);\n    const shown = capped ? units.slice(0, PER_SERVICE_LIMIT) : units;\n    console.log(`  ${subject} — ${tally(units)}`);\n    for (const group of grouped(shown)) {\n      console.log(`    ${group.heading}`);\n      for (const unit of group.units) console.log(row(unit, packet.feature));\n    }\n    if (shown.length < units.length) {\n      console.log(\n        `    +${units.length - shown.length} more — \\`loam tasks ${packet.feature} --service ${subject}\\` lists every one`,\n      );\n    }\n    console.log(\"\");\n  }\n\n  for (const line of frontierLines(packet, view)) console.log(line);\n  for (const waiting of packet.waitingOn ?? []) {\n    console.log(`  waiting on ${waiting.subject}: ${waiting.claim} · ${waiting.id}, still open there`);\n  }\n  if (packet.units.length > 0) {\n    console.log(\n      \"\\n  [step] is where a unit waits: describe → generate → implement, or attested. \" +\n        \"`loam explain <word>` defines each of those, and frontier.\",\n    );\n  }\n  console.log(\"\\n  Review:\");\n  for (const note of packet.review) console.log(`    - ${note}`);\n}\n\n/**\n * The leaf, in full. The follow-up command is literal rather than a shape to\n * fill in, because the reader is usually a model cheap enough that \"the\n * appropriate verify invocation\" is a guess it will get wrong.\n */\nexport function renderNext(packet: WorkPacket, view: TasksView): void {\n  const unit = packet.units[0];\n  if (unit === undefined) {\n    console.log(`${packet.feature} — nothing open (${packet.counts.done} done · ${packet.counts.attested} attested)`);\n    header(packet, view);\n    return;\n  }\n  console.log(`${packet.feature} — next: ${unit.id}`);\n  console.log(`  ${actionOf(unit, packet.feature)}`);\n  // The lens only when the binding chose it: a reader who typed --service knows\n  // which slice this is, and one who did not would otherwise be handed another\n  // service's head with no word on why it is this one.\n  if (packet.service !== null && !view.explicitLens) console.log(`  ${lensLine(packet, view)}`);\n  for (const warning of blindSpots(packet)) console.log(`  ⚠ ${warning}`);\n  const ungraded = ungradedScenario(packet, view, unit);\n  if (ungraded !== undefined) console.log(`  ⚠ ${ungraded}`);\n  console.log(\"\");\n  console.log(`  [${unit.at}] ${unit.kind}  [${unit.subject}]`);\n  console.log(`  ${unit.claim}`);\n  const source = unit.source;\n  if (source !== undefined) {\n    console.log(`  ${source.path}${source.line === undefined ? \"\" : `:${source.line}`}`);\n    // Verbatim, never reflowed: these are the bytes the scenario digest was\n    // taken over, and a test written from reworded criteria answers a claim\n    // nobody made.\n    if (\"lines\" in source) for (const body of source.lines) console.log(`    ${body}`);\n  }\n  if (unit.dependsOn.length > 0) console.log(`  depends on: ${unit.dependsOn.join(\", \")}`);\n  console.log(`\\n  done: ${unit.done.check}`);\n  console.log(`\\n  ${followUp(packet.feature, unit)}`);\n}\n\n/**\n * The caveat a scenario at `implement` needs when nobody looked for its\n * generated test: `implement` is also what a scenario reads when the stamps\n * could not be read, or belong to another repository, and handing a worker\n * \"make it pass\" for a test that was never generated sends them to write one by\n * hand — the paraphrase the generated suite exists to prevent.\n */\nfunction ungradedScenario(packet: WorkPacket, view: TasksView, unit: TaskUnit): string | undefined {\n  if (unit.kind !== \"scenario.tested\" || unit.at !== \"implement\") return undefined;\n  if (packet.stamps === \"read\" && unit.subject === view.bound) return undefined;\n  if (unit.subject === view.bound) {\n    return (\n      \"whether this scenario's test was generated is unknown — this repository's generated suite could not be read; \" +\n      `if loam gherkin ${packet.feature} has not run here, run it first`\n    );\n  }\n  return (\n    `whether this scenario's test was generated is unknown here — its suite lives in ${unit.subject}'s repository; ` +\n    `run loam tasks there, or loam gherkin ${packet.feature} there first if it has not run`\n  );\n}\n\n/**\n * The command that closes this unit.\n *\n * A `describe` unit is the one arm that is NOT a `loam verify --record`: there\n * is no claim to answer, because a requirement with no scenario asks no\n * question — the work is writing the Given/When/Then into the file named above,\n * and `loam validate --feature` is what grades that it landed. Pointing it at\n * `--record` would invite an answer to a question the checklist does not carry.\n */\nfunction followUp(feature: string, unit: TaskUnit): string {\n  if (unit.at === \"describe\") return `loam validate --feature ${feature}`;\n  if (unit.at === \"generate\") return `loam gherkin ${feature}`;\n  if (unit.kind === \"scenario.tested\") {\n    return `loam verify ${feature} --service ${unit.subject} --results report.json`;\n  }\n  return `loam verify ${feature} --record answers.json --service ${unit.subject}`;\n}\n\n/** What the packet could not look at — one sentence per document class. */\nfunction blindSpots(packet: WorkPacket): string[] {\n  const out: string[] = [];\n  if (packet.unreadable.architecture !== undefined) {\n    out.push(\n      `delta.likec4 does not parse (${packet.unreadable.architecture}) — no c4.calls unit could be derived, ` +\n        \"so this list is short because loam could not look, not because the work is done\",\n    );\n  }\n  const contracts = packet.unreadable.contracts;\n  if (contracts !== undefined) {\n    out.push(\n      `contract delta unreadable for ${contracts.join(\", \")} — operations and messages are missing from this packet, ` +\n        \"not absent from the feature\",\n    );\n  }\n  return out;\n}\n"]}

package/dist/commands/tasks/tasks.js

@@ -0,0 +1,119 @@
+import { configOrRefuse, emitJson, fail } from "../../core/envelope/json.js";
+import { InvalidIdError, assertServiceId } from "../../core/kernel/ids/service.js";
+import { livingServices } from "../../core/projection/arch-slice.js";
+import { nearestIds } from "../../core/repo/entries.js";
+import { missingFeatureMessage, resolveFeature } from "../../core/repo/repo.js";
+import { workPacket } from "../../core/tasks/packet.js";
+import { renderNext, renderPacket } from "./render.js";
+export function registerTasks(program) {
+    program
+        .command("tasks")
+        .argument("<featureId>", "feature id, e.g. FEAT-101")
+        .description("What is still open on a feature, at which step, and what closes each unit — read-only")
+        .option("--service <id>", "narrow the packet to the units one service owns (a lens: no binding needed)")
+        .option("--next", "the frontier head alone — the single leaf to hand to a worker")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (featureId, opts) => {
+        const json = opts.json === true;
+        const config = await configOrRefuse(json);
+        if (config === null)
+            return;
+        // The id grammar first, and on the RAW argument, exactly as `loam delta`
+        // does: `--service ../../etc` reaches `featureSpecPaths` and reads from
+        // outside the feature directory. One grammar for the whole tool.
+        if (opts.service !== undefined) {
+            try {
+                assertServiceId(opts.service, "--service");
+            }
+            catch (err) {
+                if (!(err instanceof InvalidIdError))
+                    throw err;
+                fail(json, "invalid-option", err.message);
+                return;
+            }
+        }
+        // "exclude", so an ARCHIVED feature gets the shared missing-feature
+        // message rather than a packet. This is refusal by honesty: archive merges
+        // a feature's operations into the living contracts, so a re-derived
+        // checklist over an archived feature mismatches BY CONSTRUCTION — every
+        // api.exposes claim it once made now reads as already-living and is never
+        // minted. A packet over that is not a short list, it is an invented one.
+        // `loam verify <id>` still reads the frozen record, and the message says so.
+        const feature = await resolveFeature(config.docsDir, featureId, "exclude");
+        if (!feature) {
+            fail(json, "unknown-target", await missingFeatureMessage(config.docsDir, featureId));
+            return;
+        }
+        // Only the flag's lens is passed. Without one, the packet narrows itself to
+        // the bound service when the feature touches it (`lensOf` in
+        // core/tasks/packet.ts says why, and why it is decided there), and
+        // `packet.service` is what reports the lens actually applied.
+        const lens = opts.service ?? null;
+        const packet = await workPacket({
+            docsDir: config.docsDir,
+            feature,
+            lens,
+            // `config.root`, never the cwd: loam.json discovery walks upward, and a
+            // run from `src/deep/` must read the same generated suite as one from
+            // the root. The same reasoning `loam gherkin` records for its writes.
+            binding: {
+                repoDir: config.root ?? process.cwd(),
+                ...(config.service === undefined ? {} : { service: config.service }),
+                ...(config.gherkinDir === undefined ? {} : { gherkinDir: config.gherkinDir }),
+            },
+        });
+        // The lens is checked AFTER the derivation, and on the packet's own
+        // service list, because that list is the feature's claim subjects — which
+        // includes a service the C4 delta introduces and no `specs/` directory
+        // names. Checking first would need a second LikeC4 parse of the same
+        // delta to learn the same answer. A typo must never be indistinguishable
+        // from a finished service: `--service paymnt-service` produces a
+        // perfectly plausible EMPTY packet, and an agent reads that as "nothing
+        // to do here". Only an EXPLICIT lens is checked: the bound service is
+        // applied only when the packet already lists it, so it cannot be a typo.
+        if (lens !== null && !packet.services.includes(lens)) {
+            const living = await livingServices(config.docsDir);
+            if (!living.includes(lens)) {
+                const near = nearestIds(lens, [...new Set([...packet.services, ...living])]);
+                fail(json, "unknown-target", `No service '${lens}': it is neither a services/${lens}/ in the docs repo nor a service ${feature.id} touches` +
+                    (packet.services.length === 0 ? "" : ` (${packet.services.join(", ")})`) +
+                    (near.length === 0 ? "." : ` — did you mean ${near.map((n) => `'${n}'`).join(" or ")}?`));
+                return;
+            }
+        }
+        // A feeder that could not be read empties the packet, and an agent
+        // consuming this as a task list reads an empty packet as "nothing to do":
+        // the vacuously-green pattern `loam delta` guards against on the same
+        // three documents. The payload stays as informative as ever and `ok`
+        // stays true under --json — the command ran — and the exit code is what
+        // stops a pipeline from building on it. Set BEFORE the format fork: the
+        // guard is about the documents, not about how they are rendered.
+        const blind = Object.keys(packet.unreadable).length > 0;
+        if (blind)
+            process.exitCode = 1;
+        const shown = opts.next === true ? leaf(packet) : packet;
+        if (json) {
+            emitJson({ command: "tasks", ...shown });
+            return;
+        }
+        const view = { explicitLens: opts.service !== undefined, bound: config.service };
+        if (opts.next === true)
+            renderNext(shown, view);
+        else
+            renderPacket(shown, view);
+    });
+}
+/**
+ * The leaf packet: the same payload with `units` narrowed to the frontier head.
+ *
+ * Everything else is left whole on purpose — the counts, the frontier and the
+ * review notes are the context that stops a cheap model handed one unit from
+ * believing it is the whole job. An empty `units` when nothing is open is the
+ * honest answer and not an error: the feature's open work is done, or the
+ * record says why the packet cannot see it.
+ */
+function leaf(packet) {
+    const head = packet.frontier[0];
+    return { ...packet, units: packet.units.filter((unit) => unit.id === head) };
+}
+//# sourceMappingURL=tasks.js.map

package/dist/commands/tasks/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../../../src/commands/tasks/tasks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `loam tasks` — the third rendering of one ledger, and a pure read.\n *\n * `loam verify` answers \"answered by whom\". `loam status` answers \"which\n * artifact is at which rung\". This answers the question an implementer actually\n * holds: what is still open, at which step, and what closes it. Nothing is\n * written, nothing is cached, and there is no state that says a unit is\n * finished — done is \"the unit no longer appears\", so the list cannot be\n * falsified by editing a checkbox. Everything in it re-derives from the tree, so\n * an orchestrator can ask again and compare rather than trusting a report.\n *\n * THE DOCS-REPO GATE IS DELIBERATELY ABSENT, following `loam delta` rather than\n * `loam verify`. This command is delta's sibling — a projection of ONE feature's\n * own documents — and its first act is `resolveFeature`, whose enumeration\n * carries the docs-repo precondition itself. Adding `docsRepoReady(json, …,\n * \"services\")` here would also refuse a features-only docs repo that `delta`\n * reads perfectly well today, which would be a new gate wearing the clothes of a\n * new command.\n */\nimport type { Command } from \"commander\";\nimport { configOrRefuse, emitJson, fail } from \"../../core/envelope/json.js\";\nimport { InvalidIdError, assertServiceId } from \"../../core/kernel/ids/service.js\";\nimport { livingServices } from \"../../core/projection/arch-slice.js\";\nimport { nearestIds } from \"../../core/repo/entries.js\";\nimport { missingFeatureMessage, resolveFeature } from \"../../core/repo/repo.js\";\nimport { workPacket, type WorkPacket } from \"../../core/tasks/packet.js\";\nimport { renderNext, renderPacket } from \"./render.js\";\n\ninterface TasksOptions {\n  service?: string;\n  next?: boolean;\n  json?: boolean;\n}\n\nexport function registerTasks(program: Command): void {\n  program\n    .command(\"tasks\")\n    .argument(\"<featureId>\", \"feature id, e.g. FEAT-101\")\n    .description(\"What is still open on a feature, at which step, and what closes each unit — read-only\")\n    .option(\"--service <id>\", \"narrow the packet to the units one service owns (a lens: no binding needed)\")\n    .option(\"--next\", \"the frontier head alone — the single leaf to hand to a worker\")\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (featureId: string, opts: TasksOptions) => {\n      const json = opts.json === true;\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n\n      // The id grammar first, and on the RAW argument, exactly as `loam delta`\n      // does: `--service ../../etc` reaches `featureSpecPaths` and reads from\n      // outside the feature directory. One grammar for the whole tool.\n      if (opts.service !== undefined) {\n        try {\n          assertServiceId(opts.service, \"--service\");\n        } catch (err) {\n          if (!(err instanceof InvalidIdError)) throw err;\n          fail(json, \"invalid-option\", err.message);\n          return;\n        }\n      }\n\n      // \"exclude\", so an ARCHIVED feature gets the shared missing-feature\n      // message rather than a packet. This is refusal by honesty: archive merges\n      // a feature's operations into the living contracts, so a re-derived\n      // checklist over an archived feature mismatches BY CONSTRUCTION — every\n      // api.exposes claim it once made now reads as already-living and is never\n      // minted. A packet over that is not a short list, it is an invented one.\n      // `loam verify <id>` still reads the frozen record, and the message says so.\n      const feature = await resolveFeature(config.docsDir, featureId, \"exclude\");\n      if (!feature) {\n        fail(json, \"unknown-target\", await missingFeatureMessage(config.docsDir, featureId));\n        return;\n      }\n\n      // Only the flag's lens is passed. Without one, the packet narrows itself to\n      // the bound service when the feature touches it (`lensOf` in\n      // core/tasks/packet.ts says why, and why it is decided there), and\n      // `packet.service` is what reports the lens actually applied.\n      const lens = opts.service ?? null;\n      const packet = await workPacket({\n        docsDir: config.docsDir,\n        feature,\n        lens,\n        // `config.root`, never the cwd: loam.json discovery walks upward, and a\n        // run from `src/deep/` must read the same generated suite as one from\n        // the root. The same reasoning `loam gherkin` records for its writes.\n        binding: {\n          repoDir: config.root ?? process.cwd(),\n          ...(config.service === undefined ? {} : { service: config.service }),\n          ...(config.gherkinDir === undefined ? {} : { gherkinDir: config.gherkinDir }),\n        },\n      });\n\n      // The lens is checked AFTER the derivation, and on the packet's own\n      // service list, because that list is the feature's claim subjects — which\n      // includes a service the C4 delta introduces and no `specs/` directory\n      // names. Checking first would need a second LikeC4 parse of the same\n      // delta to learn the same answer. A typo must never be indistinguishable\n      // from a finished service: `--service paymnt-service` produces a\n      // perfectly plausible EMPTY packet, and an agent reads that as \"nothing\n      // to do here\". Only an EXPLICIT lens is checked: the bound service is\n      // applied only when the packet already lists it, so it cannot be a typo.\n      if (lens !== null && !packet.services.includes(lens)) {\n        const living = await livingServices(config.docsDir);\n        if (!living.includes(lens)) {\n          const near = nearestIds(lens, [...new Set([...packet.services, ...living])]);\n          fail(\n            json,\n            \"unknown-target\",\n            `No service '${lens}': it is neither a services/${lens}/ in the docs repo nor a service ${feature.id} touches` +\n              (packet.services.length === 0 ? \"\" : ` (${packet.services.join(\", \")})`) +\n              (near.length === 0 ? \".\" : ` — did you mean ${near.map((n) => `'${n}'`).join(\" or \")}?`),\n          );\n          return;\n        }\n      }\n\n      // A feeder that could not be read empties the packet, and an agent\n      // consuming this as a task list reads an empty packet as \"nothing to do\":\n      // the vacuously-green pattern `loam delta` guards against on the same\n      // three documents. The payload stays as informative as ever and `ok`\n      // stays true under --json — the command ran — and the exit code is what\n      // stops a pipeline from building on it. Set BEFORE the format fork: the\n      // guard is about the documents, not about how they are rendered.\n      const blind = Object.keys(packet.unreadable).length > 0;\n      if (blind) process.exitCode = 1;\n\n      const shown = opts.next === true ? leaf(packet) : packet;\n      if (json) {\n        emitJson({ command: \"tasks\", ...shown });\n        return;\n      }\n      const view = { explicitLens: opts.service !== undefined, bound: config.service };\n      if (opts.next === true) renderNext(shown, view);\n      else renderPacket(shown, view);\n    });\n}\n\n/**\n * The leaf packet: the same payload with `units` narrowed to the frontier head.\n *\n * Everything else is left whole on purpose — the counts, the frontier and the\n * review notes are the context that stops a cheap model handed one unit from\n * believing it is the whole job. An empty `units` when nothing is open is the\n * honest answer and not an error: the feature's open work is done, or the\n * record says why the packet cannot see it.\n */\nfunction leaf(packet: WorkPacket): WorkPacket {\n  const head = packet.frontier[0];\n  return { ...packet, units: packet.units.filter((unit) => unit.id === head) };\n}\n"]}

package/dist/commands/unarchive/manifest.js

@@ -0,0 +1,176 @@
+/**
+ * The snapshot manifest, validated before a single byte is written back.
+ *
+ * `unarchive` says "I put your docs back", and that sentence must never be
+ * sayable over a pre-image edited in the archived feature directory since. Each
+ * entry carries the digest of what archive WROTE and the digest of what will be
+ * RESTORED, and this is where both are checked — version, timestamp, feature
+ * name, duplicate paths and all — so the restore below it can assume the file
+ * describes the archive it claims to.
+ */
+import { existsSync, lstatSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { repoPath } from "../../core/envelope/json.js";
+import { resolveInside, resolvePortableFileInside } from "../../core/kernel/path-safety.js";
+import { isRecord } from "../../core/kernel/records.js";
+import { isReadableSnapshotVersion, keysServiceRows, preImageRel, SNAPSHOT_DIR, SNAPSHOT_MANIFEST, } from "../../core/staging/snapshot/manifest.js";
+/**
+ * The snapshot manifest, or null when there is nothing this command can honour —
+ * absent, unreadable, or a layout version it would have to guess at. All three are
+ * the same answer to the caller: this feature cannot be unarchived automatically.
+ */
+export async function readManifest(request) {
+    const { featureDir, docsDir, featureId, dirName } = request;
+    try {
+        const path = resolveInside(featureDir, join(SNAPSHOT_DIR, SNAPSHOT_MANIFEST), "snapshot manifest path");
+        if (!existsSync(path))
+            return null;
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (!isRecord(parsed))
+            return null;
+        // Version 4 is what archive writes; versions 3 and 2 are read forever under
+        // their own rules — 3 keyed but storing pre-images under their living
+        // names, 2 by literal path — because snapshots an older loam wrote already
+        // sit in archived features and travel with them across loam upgrades.
+        // Version 1 stays refused: it records nothing about its restore source.
+        const version = parsed.version;
+        if (!isReadableSnapshotVersion(version))
+            return null;
+        if (parsed.feature !== featureId || parsed.dirName !== dirName)
+            return null;
+        if (typeof parsed.archivedAt !== "string" || !isCanonicalIsoDate(parsed.archivedAt))
+            return null;
+        if (!Array.isArray(parsed.files))
+            return null;
+        const seen = new Set();
+        // Where the archived feature sits, as the rows spell paths (`repoPath`).
+        const featureRel = repoPath(docsDir, featureDir);
+        const files = [];
+        for (const raw of parsed.files) {
+            if (!isRecord(raw))
+                return null;
+            if (typeof raw.path !== "string" || typeof raw.existed !== "boolean")
+                return null;
+            if (typeof raw.after !== "string" || !/^[0-9a-f]{64}$/.test(raw.after))
+                return null;
+            // A manifest that claims a pre-image must say what it should hash to, and
+            // one that claims none must not. Either way it is a shape question, so it
+            // is answered here with the rest of them; whether the bytes MATCH is a
+            // different answer with its own code (`snapshot-corrupt`).
+            if (raw.existed ? typeof raw.before !== "string" || !/^[0-9a-f]{64}$/.test(raw.before) : raw.before !== null) {
+                return null;
+            }
+            const before = raw.existed ? raw.before : null;
+            if (seen.has(raw.path))
+                return null;
+            seen.add(raw.path);
+            // The keyed shape rule (versions 3 and 4), exact in both directions: a
+            // `services/` row carries its (service, artifact) key — that key is what
+            // version 3 introduced, and a row without one is not a manifest this
+            // loam wrote — while a row anywhere else carries none, because nothing
+            // outside `services/` moves. Version-2 rows never carry the fields and
+            // are not asked to.
+            const key = readServiceKey(version, raw);
+            if (key === undefined)
+                return null;
+            // Where the file lives NOW. A re-keyed row resolves through the current
+            // enumeration — the whole point of the bump: the bytes land wherever the
+            // service lives today, not where it lived on the day of the archive. An
+            // id the enumeration does not answer falls back to the literal path
+            // (an absent service restores as a create, exactly as before).
+            let targetRel = raw.path;
+            if (key !== null) {
+                const current = request.serviceDirOf(key.service);
+                if (current !== null)
+                    targetRel = `${current}/${key.artifact}`;
+            }
+            // The realpath test stays on this side, and it is not negotiable: this
+            // path is WRITTEN through. A symlink that leaves the repo is
+            // indistinguishable, lexically, from a service directory the operator
+            // mounted on purpose — `escape/owned.txt` and `services/<svc>/spec.md`
+            // are both "inside docsDir" until something resolves them — so the only
+            // check that can refuse the first is the one that also refuses the
+            // second. Restoring is the write; `staging.ts` only reads and compares a
+            // digest, which is why its resolution of this same field can be lexical
+            // and this one cannot.
+            //
+            // A row of the feature's OWN documents — the ones archive relinked for
+            // its move, recorded inside `features/archive/<FEAT>/` — is held to the
+            // same test with the feature directory as the root, which is where its
+            // pre-image below is anchored too: that directory is the thing this
+            // command restores and moves back. Anchored at the docs root instead, a
+            // feature mounted by symlink from outside the repo — a layout every walk
+            // follows — resolved outside it and was refused as `snapshot-missing`,
+            // over rows inside the very directory being restored. A row that leaves
+            // the feature is still refused.
+            const inFeature = raw.path.startsWith(`${featureRel}/`) ? raw.path.slice(featureRel.length + 1) : null;
+            const target = inFeature === null
+                ? resolvePortableFileInside(docsDir, targetRel, `snapshot path '${raw.path}'`)
+                : resolvePortableFileInside(featureDir, inFeature, `snapshot path '${raw.path}'`);
+            let snapshot = null;
+            // Where THIS manifest's layout stores the pre-image — suffixed from
+            // version 4 on, under the living name before it (`preImageRel`).
+            const snapshotRel = `${SNAPSHOT_DIR}/files/${preImageRel(version, raw.path)}`;
+            if (raw.existed) {
+                // Resolve from the feature directory, which always exists. The `files/`
+                // directory legitimately does not exist when every archive write was a
+                // creation; anchoring here permits that case while still inspecting an
+                // existing `files` component for symlink escape.
+                snapshot = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);
+                // Archive writes plain files. A missing pre-image or a symlink (even an
+                // internally-contained one) is not the byte snapshot this manifest
+                // claims, so refuse before any destination is staged.
+                if (!existsSync(snapshot) || !lstatSync(snapshot).isFile())
+                    return null;
+            }
+            else {
+                const unexpected = resolvePortableFileInside(featureDir, snapshotRel, `snapshot pre-image '${raw.path}'`);
+                if (existsSync(unexpected))
+                    return null;
+            }
+            files.push({ path: raw.path, existed: raw.existed, after: raw.after, before, target, snapshot });
+        }
+        return {
+            // The version as WRITTEN, not as preferred: a caller looking at a
+            // validated manifest deserves to know which rules it was read under.
+            version,
+            feature: featureId,
+            dirName,
+            archivedAt: parsed.archivedAt,
+            files,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The (service, artifact) key of one manifest row, under its version's shape
+ * rule. Three answers: the key; null when the row legitimately carries none (a
+ * non-`services/` row, or any version-2 row — the key postdates version 2);
+ * undefined when the row breaks the rule and the manifest must be refused
+ * whole, because a half-keyed or wrongly-keyed row is not a record this loam
+ * wrote and nothing can say what else in the file to distrust.
+ */
+function readServiceKey(version, raw) {
+    if (!keysServiceRows(version))
+        return null;
+    const under = typeof raw.path === "string" && raw.path.startsWith("services/");
+    if (!under)
+        return raw.service === undefined && raw.artifact === undefined ? null : undefined;
+    // The id is a lookup key into the enumeration and the artifact is joined
+    // under the resolved directory, so the id must be a single path segment; the
+    // artifact's own containment is `resolvePortableFileInside`'s question.
+    if (typeof raw.service !== "string" || raw.service.length === 0 || raw.service.includes("/"))
+        return undefined;
+    if (typeof raw.artifact !== "string" || raw.artifact.length === 0)
+        return undefined;
+    return { service: raw.service, artifact: raw.artifact };
+}
+export function isCanonicalIsoDate(value) {
+    const millis = Date.parse(value);
+    return Number.isFinite(millis) && new Date(millis).toISOString() === value;
+}
+/** Remove `dir` and each empty ancestor, stopping short of `stopAt`. Best effort. */
+//# sourceMappingURL=manifest.js.map