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

package/dist/commands/tasks/actions.js

@@ -0,0 +1,107 @@
+/** The scenario's own name, when the packet found the words the claim was minted from. */
+function scenarioOf(unit) {
+    const source = unit.source;
+    return source !== undefined && "scenario" in source ? source.scenario : undefined;
+}
+/**
+ * A scenario action, with the claim appended when the name is missing. A
+ * scenario unit has no source only when the digest belt in core/tasks/packet.ts
+ * refused somebody else's words — rare, and then "make it pass" alone would be
+ * an instruction about nothing in particular.
+ */
+function aboutScenario(unit, phrase) {
+    const name = scenarioOf(unit);
+    return name === undefined ? `${phrase("it")}: ${unit.claim}` : phrase(`scenario '${name}'`);
+}
+/** `sends` or `receives`, out of the claim's prose — display only, see the header. */
+const DIRECTION = / declares it (sends|receives) message /;
+/** The provider at the end of `<from> calls '<op>' on <to>` — display only, see the header. */
+const CALLEE = / on (\S+)$/;
+/** What a unit waiting at `implement` asks for, by kind. */
+function implementAction(unit) {
+    switch (unit.kind) {
+        case "scenario.tested":
+            return aboutScenario(unit, (what) => `make ${what} pass, then record the run`);
+        case "api.exposes":
+            // Named because its channel is the unusual one: its done check asks for
+            // a contract-test report (`--contract-results`), not a cucumber run.
+            return unit.operation === undefined
+                ? unit.claim
+                : `expose operation '${unit.operation}' (contract-test evidence closes it)`;
+        case "event.declares": {
+            const direction = DIRECTION.exec(unit.claim)?.[1];
+            if (unit.token === undefined || direction === undefined)
+                return unit.claim;
+            return `${direction === "sends" ? "send" : "receive"} message '${unit.token}'`;
+        }
+        case "c4.calls": {
+            const callee = CALLEE.exec(unit.claim)?.[1];
+            if (unit.token === undefined || callee === undefined)
+                return unit.claim;
+            return `call '${unit.token}' on ${callee}`;
+        }
+        case "service.exists":
+            return `create service '${unit.subject}'`;
+        default:
+            // A kind added to the vocabulary after this was written still prints
+            // something true rather than nothing.
+            return unit.claim;
+    }
+}
+/**
+ * The unit as an action. `feature` is spelled into the one arm that names a
+ * command, because a reader handed "run the generator" with no id has to go and
+ * find out which feature they are looking at.
+ */
+export function actionOf(unit, feature) {
+    switch (unit.at) {
+        case "describe":
+            return unit.source === undefined
+                ? unit.claim
+                : `write the scenarios for requirement '${unit.source.requirement}' — at least one Given/When/Then, in the docs repo`;
+        case "generate":
+            return aboutScenario(unit, (what) => `generate the test for ${what} (loam gherkin ${feature})`);
+        case "attested":
+            return aboutScenario(unit, (what) => `re-answer ${what} from a test run — it rests on an agent's word`);
+        case "implement":
+            return implementAction(unit);
+        default: {
+            const unreachable = unit.at;
+            return unreachable;
+        }
+    }
+}
+/** The kinds a contract delta promises — openapi.yaml and asyncapi.yaml. */
+const CONTRACT_KINDS = new Set(["api.exposes", "event.declares"]);
+/** The kinds delta.likec4 promises — a service drawn, an edge between two. */
+const ARCHITECTURE_KINDS = new Set(["service.exists", "c4.calls"]);
+/**
+ * The heading a unit is filed under inside its service.
+ *
+ * A requirement's units sit under the requirement, which is where a person
+ * opens the file — and the path is printed ONCE there rather than on every
+ * row, which is most of what made the old view unreadable. The key carries the
+ * path as well as the requirement: one name may legitimately appear on both
+ * axes (`spec.md` and `arch.spec.md`), and those are two requirements.
+ *
+ * A describe unit's line IS the requirement heading's, so it rides on the
+ * heading; a scenario's line is its own and is printed on its row.
+ */
+export function groupOf(unit) {
+    if (CONTRACT_KINDS.has(unit.kind))
+        return { key: "contract", heading: "contract — operations and messages" };
+    if (ARCHITECTURE_KINDS.has(unit.kind))
+        return { key: "architecture", heading: "architecture — delta.likec4" };
+    const source = unit.source;
+    if (source === undefined) {
+        return { key: "unplaced", heading: "scenarios loam could not match to their words — each row quotes its claim" };
+    }
+    const label = source.path.endsWith("arch.spec.md") ? "arch requirement" : "requirement";
+    const id = source.requirementId === undefined ? "" : ` [${source.requirementId}]`;
+    const line = unit.at === "describe" && source.line !== undefined ? `:${source.line}` : "";
+    return {
+        key: ["requirement", source.path, source.requirementId ?? "", source.requirement].join("\0"),
+        heading: `${label} '${source.requirement}'${id} — ${source.path}${line}`,
+    };
+}
+//# sourceMappingURL=actions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../../../src/commands/tasks/actions.ts"],"names":[],"mappings":"AAsBA,0FAA0F;AAC1F,SAAS,UAAU,CAAC,IAAc;IAChC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,OAAO,MAAM,KAAK,SAAS,IAAI,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AACpF,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CAAC,IAAc,EAAE,MAAgC;IACrE,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;AAC9F,CAAC;AAED,sFAAsF;AACtF,MAAM,SAAS,GAAG,wCAAwC,CAAC;AAE3D,+FAA+F;AAC/F,MAAM,MAAM,GAAG,YAAY,CAAC;AAE5B,4DAA4D;AAC5D,SAAS,eAAe,CAAC,IAAc;IACrC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,iBAAiB;YACpB,OAAO,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,IAAI,4BAA4B,CAAC,CAAC;QACjF,KAAK,aAAa;YAChB,wEAAwE;YACxE,qEAAqE;YACrE,OAAO,IAAI,CAAC,SAAS,KAAK,SAAS;gBACjC,CAAC,CAAC,IAAI,CAAC,KAAK;gBACZ,CAAC,CAAC,qBAAqB,IAAI,CAAC,SAAS,sCAAsC,CAAC;QAChF,KAAK,gBAAgB,EAAE,CAAC;YACtB,MAAM,SAAS,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAClD,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,SAAS,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC;YAC3E,OAAO,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,aAAa,IAAI,CAAC,KAAK,GAAG,CAAC;QACjF,CAAC;QACD,KAAK,UAAU,EAAE,CAAC;YAChB,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAC5C,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC,KAAK,CAAC;YACxE,OAAO,SAAS,IAAI,CAAC,KAAK,QAAQ,MAAM,EAAE,CAAC;QAC7C,CAAC;QACD,KAAK,gBAAgB;YACnB,OAAO,mBAAmB,IAAI,CAAC,OAAO,GAAG,CAAC;QAC5C;YACE,qEAAqE;YACrE,sCAAsC;YACtC,OAAO,IAAI,CAAC,KAAK,CAAC;IACtB,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAc,EAAE,OAAe;IACtD,QAAQ,IAAI,CAAC,EAAE,EAAE,CAAC;QAChB,KAAK,UAAU;YACb,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS;gBAC9B,CAAC,CAAC,IAAI,CAAC,KAAK;gBACZ,CAAC,CAAC,wCAAwC,IAAI,CAAC,MAAM,CAAC,WAAW,oDAAoD,CAAC;QAC1H,KAAK,UAAU;YACb,OAAO,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,yBAAyB,IAAI,kBAAkB,OAAO,GAAG,CAAC,CAAC;QAClG,KAAK,UAAU;YACb,OAAO,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,aAAa,IAAI,gDAAgD,CAAC,CAAC;QAC1G,KAAK,WAAW;YACd,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;QAC/B,SAAS,CAAC;YACR,MAAM,WAAW,GAAU,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,cAAc,GAAwB,IAAI,GAAG,CAAC,CAAC,aAAa,EAAE,gBAAgB,CAAC,CAAC,CAAC;AAEvF,8EAA8E;AAC9E,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC,CAAC,gBAAgB,EAAE,UAAU,CAAC,CAAC,CAAC;AAQxF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,OAAO,CAAC,IAAc;IACpC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,oCAAoC,EAAE,CAAC;IAC7G,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC;IAC9G,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,OAAO,EAAE,2EAA2E,EAAE,CAAC;IACnH,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC;IACxF,MAAM,EAAE,GAAG,MAAM,CAAC,aAAa,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,aAAa,GAAG,CAAC;IAClF,MAAM,IAAI,GAAG,IAAI,CAAC,EAAE,KAAK,UAAU,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1F,OAAO;QACL,GAAG,EAAE,CAAC,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAC5F,OAAO,EAAE,GAAG,KAAK,KAAK,MAAM,CAAC,WAAW,IAAI,EAAE,MAAM,MAAM,CAAC,IAAI,GAAG,IAAI,EAAE;KACzE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * A unit said as something a person does, and the heading it is filed under.\n *\n * The packet's `claim` is the QUESTION `loam verify` asks — \"scenario 'X' of\n * requirement 'Y' (svc) is covered by a test\" — and a list of questions reads as\n * a claim ledger rather than a to-do list: the step a unit waits at used to be a\n * bracketed tag in front of a sentence that never changed with it. Here the step\n * and the kind together pick the verb, so a unit at `generate` says \"generate\n * the test\" and the same scenario at `implement` says \"make it pass\". The claim\n * stays on the payload and in `--next`, verbatim; this is a rendering, and\n * nothing ever reads it back.\n *\n * Two facts the phrasing wants live only in the claim's prose — which way an\n * event.declares message goes, and which service a c4.calls edge lands on:\n * `featureChecklist` (core/verify/checklist.ts) spells both into the sentence\n * and carries neither as a field. They are read out of the prose for DISPLAY\n * only, and a reworded claim falls back to the claim itself, which is always\n * true: no join key, count or verdict comes from here, which is the line\n * `Claim.operation`'s docblock draws against parsing claim prose.\n */\nimport type { TaskUnit } from \"../../core/tasks/unit.js\";\n\n/** The scenario's own name, when the packet found the words the claim was minted from. */\nfunction scenarioOf(unit: TaskUnit): string | undefined {\n  const source = unit.source;\n  return source !== undefined && \"scenario\" in source ? source.scenario : undefined;\n}\n\n/**\n * A scenario action, with the claim appended when the name is missing. A\n * scenario unit has no source only when the digest belt in core/tasks/packet.ts\n * refused somebody else's words — rare, and then \"make it pass\" alone would be\n * an instruction about nothing in particular.\n */\nfunction aboutScenario(unit: TaskUnit, phrase: (what: string) => string): string {\n  const name = scenarioOf(unit);\n  return name === undefined ? `${phrase(\"it\")}: ${unit.claim}` : phrase(`scenario '${name}'`);\n}\n\n/** `sends` or `receives`, out of the claim's prose — display only, see the header. */\nconst DIRECTION = / declares it (sends|receives) message /;\n\n/** The provider at the end of `<from> calls '<op>' on <to>` — display only, see the header. */\nconst CALLEE = / on (\\S+)$/;\n\n/** What a unit waiting at `implement` asks for, by kind. */\nfunction implementAction(unit: TaskUnit): string {\n  switch (unit.kind) {\n    case \"scenario.tested\":\n      return aboutScenario(unit, (what) => `make ${what} pass, then record the run`);\n    case \"api.exposes\":\n      // Named because its channel is the unusual one: its done check asks for\n      // a contract-test report (`--contract-results`), not a cucumber run.\n      return unit.operation === undefined\n        ? unit.claim\n        : `expose operation '${unit.operation}' (contract-test evidence closes it)`;\n    case \"event.declares\": {\n      const direction = DIRECTION.exec(unit.claim)?.[1];\n      if (unit.token === undefined || direction === undefined) return unit.claim;\n      return `${direction === \"sends\" ? \"send\" : \"receive\"} message '${unit.token}'`;\n    }\n    case \"c4.calls\": {\n      const callee = CALLEE.exec(unit.claim)?.[1];\n      if (unit.token === undefined || callee === undefined) return unit.claim;\n      return `call '${unit.token}' on ${callee}`;\n    }\n    case \"service.exists\":\n      return `create service '${unit.subject}'`;\n    default:\n      // A kind added to the vocabulary after this was written still prints\n      // something true rather than nothing.\n      return unit.claim;\n  }\n}\n\n/**\n * The unit as an action. `feature` is spelled into the one arm that names a\n * command, because a reader handed \"run the generator\" with no id has to go and\n * find out which feature they are looking at.\n */\nexport function actionOf(unit: TaskUnit, feature: string): string {\n  switch (unit.at) {\n    case \"describe\":\n      return unit.source === undefined\n        ? unit.claim\n        : `write the scenarios for requirement '${unit.source.requirement}' — at least one Given/When/Then, in the docs repo`;\n    case \"generate\":\n      return aboutScenario(unit, (what) => `generate the test for ${what} (loam gherkin ${feature})`);\n    case \"attested\":\n      return aboutScenario(unit, (what) => `re-answer ${what} from a test run — it rests on an agent's word`);\n    case \"implement\":\n      return implementAction(unit);\n    default: {\n      const unreachable: never = unit.at;\n      return unreachable;\n    }\n  }\n}\n\n/** The kinds a contract delta promises — openapi.yaml and asyncapi.yaml. */\nconst CONTRACT_KINDS: ReadonlySet<string> = new Set([\"api.exposes\", \"event.declares\"]);\n\n/** The kinds delta.likec4 promises — a service drawn, an edge between two. */\nconst ARCHITECTURE_KINDS: ReadonlySet<string> = new Set([\"service.exists\", \"c4.calls\"]);\n\nexport interface UnitGroup {\n  /** What makes two units one group: the same document and the same requirement in it. */\n  key: string;\n  heading: string;\n}\n\n/**\n * The heading a unit is filed under inside its service.\n *\n * A requirement's units sit under the requirement, which is where a person\n * opens the file — and the path is printed ONCE there rather than on every\n * row, which is most of what made the old view unreadable. The key carries the\n * path as well as the requirement: one name may legitimately appear on both\n * axes (`spec.md` and `arch.spec.md`), and those are two requirements.\n *\n * A describe unit's line IS the requirement heading's, so it rides on the\n * heading; a scenario's line is its own and is printed on its row.\n */\nexport function groupOf(unit: TaskUnit): UnitGroup {\n  if (CONTRACT_KINDS.has(unit.kind)) return { key: \"contract\", heading: \"contract — operations and messages\" };\n  if (ARCHITECTURE_KINDS.has(unit.kind)) return { key: \"architecture\", heading: \"architecture — delta.likec4\" };\n  const source = unit.source;\n  if (source === undefined) {\n    return { key: \"unplaced\", heading: \"scenarios loam could not match to their words — each row quotes its claim\" };\n  }\n  const label = source.path.endsWith(\"arch.spec.md\") ? \"arch requirement\" : \"requirement\";\n  const id = source.requirementId === undefined ? \"\" : ` [${source.requirementId}]`;\n  const line = unit.at === \"describe\" && source.line !== undefined ? `:${source.line}` : \"\";\n  return {\n    key: [\"requirement\", source.path, source.requirementId ?? \"\", source.requirement].join(\"\\0\"),\n    heading: `${label} '${source.requirement}'${id} — ${source.path}${line}`,\n  };\n}\n"]}

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"]}