@ybotok/loam 0.1.0-beta.2 → 0.2.0-alpha.1

package/dist/core/status/feature/feature.js

@@ -0,0 +1,207 @@
+/**
+ * One feature: the full report. `featureStatus` gathers what the shared gates
+ * say about a feature in flight — findings, the artifact table, the record,
+ * the dependency order — and rolls them up into the stage and the steps. The
+ * vocabulary it reports in lives in ../report.ts, whose header holds the rules
+ * this projection is held to.
+ */
+import { featureCoherence } from "../../coherence/coherence.js";
+import { invalidSpecServiceFindings, livingMergeConflicts, unknownDeltaServices, } from "../../coherence/living.js";
+import { analyzeDependencies } from "../../dependencies/dependencies.js";
+import { repoPath } from "../../envelope/json.js";
+import { FleetContext } from "../../fleet-context.js";
+import { featureProvenance } from "../../provenance/findings.js";
+import { featureSpecServices } from "../../repo/repo.js";
+import { enumeratedServices } from "../../repo/service-target.js";
+import { useCaseBlastRadius } from "../../usecases/touch.js";
+import { issueFinding } from "../../vocabulary/issue.js";
+import { contractOwners, contractsHeldElsewhere } from "../contracts.js";
+import { readInterruptedCommit } from "../interrupted.js";
+import { governedServices, scanDeltas } from "../scan.js";
+import { fullyVerified, verificationState } from "../verification.js";
+import { featureArtifacts } from "./artifacts.js";
+import { featureNext, unshippable } from "./next.js";
+import {} from "./state.js";
+/**
+ * Everything about one feature in flight. `service` narrows the per-service
+ * artifacts and the per-service steps; the feature's own `services` list stays
+ * complete either way, because a narrowed view that also hid which other
+ * services exist would read as a feature that touches exactly one.
+ */
+export async function featureStatus(docsDir, feature, opts = {}) {
+    const context = opts.context ?? new FleetContext();
+    const interrupted = await readInterruptedCommit(docsDir);
+    const services = await featureSpecServices(feature.dir, context);
+    const narrowed = opts.service;
+    const inView = narrowed === undefined ? services : services.filter((s) => s === narrowed);
+    const scans = feature.archived ? [] : await scanDeltas(docsDir, feature, services, context);
+    const read = await verificationState(docsDir, feature);
+    const verification = read.state;
+    // An archived feature is history: its delta is already folded into the living
+    // docs, so coherence would grade the change against a world that has absorbed
+    // it and report contradictions that are only the merge having happened. The
+    // same reason `list` never calls an archived record stale.
+    const findings = feature.archived ? [] : await featureFindings(docsDir, feature, scans, context);
+    // `verify.scenario-attested` rides in the same array an agent already parses,
+    // under verify's own code — a feature confirmed the short way has to be
+    // MARKED here, not merely absent from `stage: done`. It is a warning and it
+    // gates nothing, so `coherent` is untouched.
+    if (!feature.archived && read.notice !== null) {
+        findings.push({ severity: read.notice.severity, code: read.notice.code, message: read.notice.message });
+    }
+    const errors = findings.filter((f) => f.severity === "error");
+    const warnings = findings.filter((f) => f.severity === "warn").length;
+    // The union of the two gates, and the set every verdict below is drawn from.
+    const blocking = findings.filter(unshippable);
+    const governs = governedServices(scans);
+    // The whole feature is graded, then the view is narrowed — never the other
+    // way round. `--service` is a lens on the table and the steps; a rollup that
+    // moved with it would report a feature `ready` because the one service you
+    // asked about happens to be written, while three others have nothing.
+    const living = new Map((await enumeratedServices(docsDir, context)).map((s) => [s.id, s]));
+    const graded = featureArtifacts(docsDir, feature, services, {
+        blocking,
+        verification,
+        contracted: contractsHeldElsewhere(await contractOwners(docsDir, context), feature.id),
+        governs,
+        // Tolerant on purpose: status must keep answering in a docs repo whose
+        // services/ is broken or missing — an unenumerable fleet is doctor's
+        // diagnosis, and here it simply means every service reads as never-adopted.
+        living,
+        // Through the context's memo — the same walk `featureFindings` above and
+        // the coherence pass inside it already ran. An archived feature carries no
+        // delta to name, and the walk is one `existsSync` besides.
+        capabilities: (await context.featureCapabilityDeltas(feature.dir)).docs,
+    });
+    const artifacts = narrowed === undefined ? graded : graded.filter((a) => a.service === null || a.service === narrowed);
+    // The dependency index rather than the `*-pending` issue codes: those name the
+    // other feature in prose, and prose is not an API — dependencies.ts opens with
+    // exactly that argument. An archived feature waits on nothing; it landed.
+    const graph = feature.archived
+        ? null
+        : await analyzeDependencies(docsDir, feature.id, context);
+    const blockedBy = graph?.nodes.find((n) => n.id === feature.id)?.dependsOn ?? [];
+    // The flows the services in view are already hops of. The fleet set is the
+    // living services UNION the feature's own, so a service this feature
+    // introduces resolves to itself rather than to a container's title — and the
+    // load underneath gates itself, so a docs repo that declares no use case pays
+    // a readdir here rather than a LikeC4 workspace.
+    const useCases = await useCaseBlastRadius({
+        docsDir,
+        known: new Set([...living.keys(), ...services]),
+        services: new Set(inView),
+    });
+    return {
+        interrupted,
+        feature: {
+            id: feature.id,
+            dirName: feature.dirName,
+            path: repoPath(docsDir, feature.dir),
+            archived: feature.archived,
+            stage: featureStage({ feature, services, artifacts: graded, findings, blockedBy, verification, scans, interrupted }, blocking.length),
+            services,
+            blockedBy,
+        },
+        service: narrowed ?? null,
+        artifacts,
+        checks: {
+            ran: !feature.archived,
+            coherent: errors.length === 0,
+            errors: errors.length,
+            warnings,
+            gating: findings.filter((f) => f.gates === true).length,
+            issues: findings,
+        },
+        verification,
+        useCases,
+        next: featureNext({ feature, services: inView, artifacts, findings, blockedBy, verification, scans, interrupted }, opts.boundService),
+    };
+}
+/**
+ * Everything `loam validate --feature` and `loam archive` would say about this
+ * feature, in one list, through the very functions they call.
+ *
+ * Coherence alone was not it. `validate --feature` also runs `featureProvenance`
+ * over intent.md and the scenario-coverage check over every per-service delta,
+ * and both grade ERRORS — so a feature whose requirements carry no scenario at
+ * all read `coherent: true` here while `validate` exited 1 on the same tree.
+ * The coherence findings carry `gates` resolved, because archive's question is
+ * not severity's (issue.ts) and no consumer should re-derive it.
+ */
+async function featureFindings(docsDir, feature, scans, context) {
+    const issues = await featureCoherence({ docsDir, featureDir: feature.dir, featureId: feature.id, context });
+    const out = issues.map(issueFinding);
+    out.push(...(await featureProvenance(feature.dir, feature.id)).filter((f) => f.severity !== "ok"));
+    // The three refusals `archive` makes before its merge plan runs, from the
+    // same functions it calls: a per-service delta addressed to a service that
+    // exists nowhere, a specs/ directory whose NAME the id grammar refuses
+    // (that one is refused before archive plans anything — the name itself is
+    // the path it would become), and a LIVING document still holding git
+    // conflict markers. None are coherence issues — one is about a service id
+    // that means nothing, one about a name that can never be a path, one about
+    // a LIVING document nobody wrote — so they reach archive outside
+    // `featureCoherence`, and a projection that only inherited coherence
+    // printed "ship it" over all three. Errors: each is a refusal, and the rule
+    // this module is held to is one-directional.
+    out.push(...(await unknownDeltaServices(docsDir, feature.dir, feature.id, { context })));
+    out.push(...(await invalidSpecServiceFindings(feature.dir, context)));
+    // The capability half of the same scan: status may be redder than the gates
+    // and never greener, so a living capability document this feature's delta
+    // would rewrite has to be looked at here too. Through the context's memo —
+    // this function always has one — so the walk is shared with the coherence
+    // pass above rather than repeated.
+    const capabilityDeltas = await context.featureCapabilityDeltas(feature.dir);
+    out.push(...(await livingMergeConflicts(docsDir, await featureSpecServices(feature.dir, context), capabilityDeltas.docs.map((d) => d.id), context)));
+    for (const scan of scans) {
+        if (scan.bare.length === 0)
+            continue;
+        out.push({
+            severity: "error",
+            code: "requirements.missing-scenarios",
+            subject: scan.service,
+            message: `${scan.label}: ${scan.bare.length} requirement(s) without a scenario`,
+            details: scan.bare.map((r) => r.name),
+        });
+    }
+    return out;
+}
+/**
+ * The feature's own rollup, worst first. The order is the order the work has to
+ * happen in, so the winning branch is also the phase the feature is in:
+ * unwritten artifacts come before an ordering problem (you can author while
+ * another feature is still in flight), an ordering problem comes before this
+ * feature's own errors (fixing them may be pointless until the other one
+ * lands), and everything comes before the record — answers written over a
+ * broken feature are answers to questions that are about to change.
+ *
+ * The record is excluded from the `missing` branch on purpose. It is not
+ * something an author writes: it is the done-check's output, and counting its
+ * absence as unwritten work would report every correctly-authored feature as
+ * `missing` right up until somebody ran `loam verify` — which is the state
+ * `ready` exists to name, and which the fleet form already names correctly.
+ */
+function featureStage(state, blocking) {
+    const { feature, artifacts, services, blockedBy, verification, interrupted } = state;
+    // Ahead of `archived`, and ahead of everything else: a killed commit may be
+    // this very feature's, half-applied, so "it shipped" is a claim about files
+    // nobody has established the contents of. `blocked` is the honest word — the
+    // work is stalled on something that is not this feature's artifact — and it
+    // is what stops the projection printing `done` over a half-merged repo.
+    if (interrupted !== null)
+        return "blocked";
+    if (feature.archived)
+        return "done";
+    // A feature with no `specs/<service>/` changes nothing. There is no artifact
+    // row to be missing — the rows are per service — so the emptiness itself is
+    // the finding, and `next.touch-service` is the step.
+    if (services.length === 0)
+        return "missing";
+    if (artifacts.some((a) => a.id !== "verification" && a.status === "missing"))
+        return "missing";
+    if (blockedBy.length > 0)
+        return "blocked";
+    if (blocking > 0)
+        return "draft";
+    return fullyVerified(verification) ? "done" : "ready";
+}
+//# sourceMappingURL=feature.js.map

package/dist/core/status/feature/feature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature.js","sourceRoot":"","sources":["../../../../src/core/status/feature/feature.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One feature: the full report. `featureStatus` gathers what the shared gates\n * say about a feature in flight — findings, the artifact table, the record,\n * the dependency order — and rolls them up into the stage and the steps. The\n * vocabulary it reports in lives in ../report.ts, whose header holds the rules\n * this projection is held to.\n */\nimport { featureCoherence } from \"../../coherence/coherence.js\";\nimport {\n  invalidSpecServiceFindings,\n  livingMergeConflicts,\n  unknownDeltaServices,\n} from \"../../coherence/living.js\";\nimport { analyzeDependencies } from \"../../dependencies/dependencies.js\";\nimport { repoPath } from \"../../envelope/json.js\";\nimport { FleetContext } from \"../../fleet-context.js\";\nimport { featureProvenance } from \"../../provenance/findings.js\";\nimport type { FeatureEntry } from \"../../repo/entries.js\";\nimport { featureSpecServices } from \"../../repo/repo.js\";\nimport { enumeratedServices } from \"../../repo/service-target.js\";\nimport { useCaseBlastRadius } from \"../../usecases/touch.js\";\nimport { issueFinding, type Issue } from \"../../vocabulary/issue.js\";\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { contractOwners, contractsHeldElsewhere } from \"../contracts.js\";\nimport { readInterruptedCommit } from \"../interrupted.js\";\nimport type { ArtifactStatus, FeatureStatusReport } from \"../report.js\";\nimport { governedServices, scanDeltas, type DeltaScan } from \"../scan.js\";\nimport { fullyVerified, verificationState } from \"../verification.js\";\nimport { featureArtifacts } from \"./artifacts.js\";\nimport { featureNext, unshippable } from \"./next.js\";\nimport { type FeatureState } from \"./state.js\";\nimport type { DocsDir } from \"../../kernel/ids/dirs.js\";\n\n/**\n * Everything about one feature in flight. `service` narrows the per-service\n * artifacts and the per-service steps; the feature's own `services` list stays\n * complete either way, because a narrowed view that also hid which other\n * services exist would read as a feature that touches exactly one.\n */\nexport async function featureStatus(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  opts: { service?: string; boundService?: string; context?: FleetContext } = {},\n): Promise<FeatureStatusReport> {\n  const context = opts.context ?? new FleetContext();\n  const interrupted = await readInterruptedCommit(docsDir);\n  const services = await featureSpecServices(feature.dir, context);\n  const narrowed = opts.service;\n  const inView = narrowed === undefined ? services : services.filter((s) => s === narrowed);\n\n  const scans = feature.archived ? [] : await scanDeltas(docsDir, feature, services, context);\n  const read = await verificationState(docsDir, feature);\n  const verification = read.state;\n  // An archived feature is history: its delta is already folded into the living\n  // docs, so coherence would grade the change against a world that has absorbed\n  // it and report contradictions that are only the merge having happened. The\n  // same reason `list` never calls an archived record stale.\n  const findings = feature.archived ? [] : await featureFindings(docsDir, feature, scans, context);\n  // `verify.scenario-attested` rides in the same array an agent already parses,\n  // under verify's own code — a feature confirmed the short way has to be\n  // MARKED here, not merely absent from `stage: done`. It is a warning and it\n  // gates nothing, so `coherent` is untouched.\n  if (!feature.archived && read.notice !== null) {\n    findings.push({ severity: read.notice.severity, code: read.notice.code, message: read.notice.message });\n  }\n  const errors = findings.filter((f) => f.severity === \"error\");\n  const warnings = findings.filter((f) => f.severity === \"warn\").length;\n  // The union of the two gates, and the set every verdict below is drawn from.\n  const blocking = findings.filter(unshippable);\n\n  const governs = governedServices(scans);\n  // The whole feature is graded, then the view is narrowed — never the other\n  // way round. `--service` is a lens on the table and the steps; a rollup that\n  // moved with it would report a feature `ready` because the one service you\n  // asked about happens to be written, while three others have nothing.\n  const living = new Map((await enumeratedServices(docsDir, context)).map((s) => [s.id, s]));\n  const graded = featureArtifacts(docsDir, feature, services, {\n    blocking,\n    verification,\n    contracted: contractsHeldElsewhere(await contractOwners(docsDir, context), feature.id),\n    governs,\n    // Tolerant on purpose: status must keep answering in a docs repo whose\n    // services/ is broken or missing — an unenumerable fleet is doctor's\n    // diagnosis, and here it simply means every service reads as never-adopted.\n    living,\n    // Through the context's memo — the same walk `featureFindings` above and\n    // the coherence pass inside it already ran. An archived feature carries no\n    // delta to name, and the walk is one `existsSync` besides.\n    capabilities: (await context.featureCapabilityDeltas(feature.dir)).docs,\n  });\n  const artifacts =\n    narrowed === undefined ? graded : graded.filter((a) => a.service === null || a.service === narrowed);\n\n  // The dependency index rather than the `*-pending` issue codes: those name the\n  // other feature in prose, and prose is not an API — dependencies.ts opens with\n  // exactly that argument. An archived feature waits on nothing; it landed.\n  const graph = feature.archived\n    ? null\n    : await analyzeDependencies(docsDir, feature.id, context);\n  const blockedBy = graph?.nodes.find((n) => n.id === feature.id)?.dependsOn ?? [];\n\n  // The flows the services in view are already hops of. The fleet set is the\n  // living services UNION the feature's own, so a service this feature\n  // introduces resolves to itself rather than to a container's title — and the\n  // load underneath gates itself, so a docs repo that declares no use case pays\n  // a readdir here rather than a LikeC4 workspace.\n  const useCases = await useCaseBlastRadius({\n    docsDir,\n    known: new Set([...living.keys(), ...services]),\n    services: new Set(inView),\n  });\n\n  return {\n    interrupted,\n    feature: {\n      id: feature.id,\n      dirName: feature.dirName,\n      path: repoPath(docsDir, feature.dir),\n      archived: feature.archived,\n      stage: featureStage(\n        { feature, services, artifacts: graded, findings, blockedBy, verification, scans, interrupted },\n        blocking.length,\n      ),\n      services,\n      blockedBy,\n    },\n    service: narrowed ?? null,\n    artifacts,\n    checks: {\n      ran: !feature.archived,\n      coherent: errors.length === 0,\n      errors: errors.length,\n      warnings,\n      gating: findings.filter((f) => f.gates === true).length,\n      issues: findings,\n    },\n    verification,\n    useCases,\n    next: featureNext(\n      { feature, services: inView, artifacts, findings, blockedBy, verification, scans, interrupted },\n      opts.boundService,\n    ),\n  };\n}\n\n/**\n * Everything `loam validate --feature` and `loam archive` would say about this\n * feature, in one list, through the very functions they call.\n *\n * Coherence alone was not it. `validate --feature` also runs `featureProvenance`\n * over intent.md and the scenario-coverage check over every per-service delta,\n * and both grade ERRORS — so a feature whose requirements carry no scenario at\n * all read `coherent: true` here while `validate` exited 1 on the same tree.\n * The coherence findings carry `gates` resolved, because archive's question is\n * not severity's (issue.ts) and no consumer should re-derive it.\n */\nasync function featureFindings(\n  docsDir: DocsDir,\n  feature: FeatureEntry,\n  scans: DeltaScan[],\n  context: FleetContext,\n): Promise<Finding[]> {\n  const issues: Issue[] = await featureCoherence({ docsDir, featureDir: feature.dir, featureId: feature.id, context });\n  const out: Finding[] = issues.map(issueFinding);\n  out.push(...(await featureProvenance(feature.dir, feature.id)).filter((f) => f.severity !== \"ok\"));\n  // The three refusals `archive` makes before its merge plan runs, from the\n  // same functions it calls: a per-service delta addressed to a service that\n  // exists nowhere, a specs/ directory whose NAME the id grammar refuses\n  // (that one is refused before archive plans anything — the name itself is\n  // the path it would become), and a LIVING document still holding git\n  // conflict markers. None are coherence issues — one is about a service id\n  // that means nothing, one about a name that can never be a path, one about\n  // a LIVING document nobody wrote — so they reach archive outside\n  // `featureCoherence`, and a projection that only inherited coherence\n  // printed \"ship it\" over all three. Errors: each is a refusal, and the rule\n  // this module is held to is one-directional.\n  out.push(...(await unknownDeltaServices(docsDir, feature.dir, feature.id, { context })));\n  out.push(...(await invalidSpecServiceFindings(feature.dir, context)));\n  // The capability half of the same scan: status may be redder than the gates\n  // and never greener, so a living capability document this feature's delta\n  // would rewrite has to be looked at here too. Through the context's memo —\n  // this function always has one — so the walk is shared with the coherence\n  // pass above rather than repeated.\n  const capabilityDeltas = await context.featureCapabilityDeltas(feature.dir);\n  out.push(\n    ...(await livingMergeConflicts(docsDir, await featureSpecServices(feature.dir, context), capabilityDeltas.docs.map((d) => d.id), context)),\n  );\n  for (const scan of scans) {\n    if (scan.bare.length === 0) continue;\n    out.push({\n      severity: \"error\",\n      code: \"requirements.missing-scenarios\",\n      subject: scan.service,\n      message: `${scan.label}: ${scan.bare.length} requirement(s) without a scenario`,\n      details: scan.bare.map((r) => r.name),\n    });\n  }\n  return out;\n}\n\n/**\n * The feature's own rollup, worst first. The order is the order the work has to\n * happen in, so the winning branch is also the phase the feature is in:\n * unwritten artifacts come before an ordering problem (you can author while\n * another feature is still in flight), an ordering problem comes before this\n * feature's own errors (fixing them may be pointless until the other one\n * lands), and everything comes before the record — answers written over a\n * broken feature are answers to questions that are about to change.\n *\n * The record is excluded from the `missing` branch on purpose. It is not\n * something an author writes: it is the done-check's output, and counting its\n * absence as unwritten work would report every correctly-authored feature as\n * `missing` right up until somebody ran `loam verify` — which is the state\n * `ready` exists to name, and which the fleet form already names correctly.\n */\nfunction featureStage(state: FeatureState, blocking: number): ArtifactStatus {\n  const { feature, artifacts, services, blockedBy, verification, interrupted } = state;\n  // Ahead of `archived`, and ahead of everything else: a killed commit may be\n  // this very feature's, half-applied, so \"it shipped\" is a claim about files\n  // nobody has established the contents of. `blocked` is the honest word — the\n  // work is stalled on something that is not this feature's artifact — and it\n  // is what stops the projection printing `done` over a half-merged repo.\n  if (interrupted !== null) return \"blocked\";\n  if (feature.archived) return \"done\";\n  // A feature with no `specs/<service>/` changes nothing. There is no artifact\n  // row to be missing — the rows are per service — so the emptiness itself is\n  // the finding, and `next.touch-service` is the step.\n  if (services.length === 0) return \"missing\";\n  if (artifacts.some((a) => a.id !== \"verification\" && a.status === \"missing\")) return \"missing\";\n  if (blockedBy.length > 0) return \"blocked\";\n  if (blocking > 0) return \"draft\";\n  return fullyVerified(verification) ? \"done\" : \"ready\";\n}\n"]}

package/dist/core/status/feature/next.js

@@ -0,0 +1,150 @@
+import { recoverStep } from "../interrupted.js";
+import { testStep, verifyStep } from "../verification.js";
+import {} from "./state.js";
+/**
+ * Would either gate refuse this? Severity answers `validate`'s question and
+ * `gates` answers archive's; a finding that fails EITHER is one an author has
+ * work to do about, and collapsing them to `severity === "error"` is how
+ * `status` came to print "ship it" beside a warning archive exits 1 on.
+ */
+export function unshippable(f) {
+    return f.severity === "error" || f.gates === true;
+}
+/** Codes whose one fix is `loam rebase`: a pin nobody ever wrote, on any of the three axes. */
+const UNPINNED = new Set(["delta.baseline-missing", "openapi.baseline-missing", "asyncapi.baseline-missing"]);
+export function featureNext(state, boundService) {
+    const { feature, services, artifacts, findings, blockedBy, verification, scans, interrupted } = state;
+    const id = feature.id;
+    // Before the archived shortcut: the interrupted commit may be this feature's
+    // own, and "it shipped" is not a thing to tell somebody whose living docs are
+    // half-written.
+    const first = interrupted === null ? [] : [recoverStep(interrupted)];
+    if (feature.archived) {
+        return [
+            ...first,
+            {
+                code: "next.archived",
+                statement: `${id} is archived — it shipped, and its delta is already folded into the living docs.`,
+                command: `loam show ${id} --json`,
+            },
+        ];
+    }
+    const steps = [...first];
+    const owed = (kind, service) => artifacts.find((a) => a.id === kind && a.status === "missing" && (service === undefined || a.service === service));
+    const intent = owed("intent");
+    if (intent !== undefined) {
+        steps.push({
+            code: "next.author-intent",
+            statement: `Write ${intent.path} — what ${id} is for, in prose, before anything is derived from it.`,
+            command: `loam validate ${id} --json`,
+            artifact: "intent",
+            path: intent.path,
+        });
+    }
+    if (services.length === 0) {
+        steps.push({
+            code: "next.touch-service",
+            statement: `${id} carries no per-service delta — add specs/<service>/spec.md for every service it changes.`,
+            command: "loam list services --json",
+        });
+    }
+    for (const svc of services) {
+        const spec = owed("spec", svc);
+        if (spec !== undefined) {
+            steps.push({
+                code: "next.author-spec",
+                statement: `Write ${spec.path} — the ADDED/MODIFIED/REMOVED requirements ${id} makes to ${svc}, each with a scenario.`,
+                command: `loam delta ${id} --service ${svc} --json`,
+                artifact: "spec",
+                service: svc,
+                path: spec.path,
+            });
+        }
+        const api = owed("openapi", svc);
+        if (api !== undefined) {
+            steps.push({
+                code: "next.author-openapi",
+                // Not "the service is not in the living docs": a service adopted
+                // without a contract is the commoner case, and that wording sent a
+                // reader looking for a directory that was right there. And not "the
+                // operations it governs" either — this step also fires for a service
+                // the feature INTRODUCES, where owesContract asks nothing about
+                // operations and the delta may tag none, so naming them promised the
+                // author a list they would go looking for and not find.
+                statement: `Write ${api.path} — nothing gives ${svc} a living openapi.yaml, so this feature is the only thing that can write down its API surface.`,
+                command: `loam delta ${id} --service ${svc} --json`,
+                artifact: "openapi",
+                service: svc,
+                path: api.path,
+            });
+        }
+    }
+    // A requirement with no scenario yields no generated .feature and no
+    // scenario.tested claim: a promise that reaches neither the suite nor the
+    // done-check, and that nothing downstream will ever mention again. One entry
+    // per service rather than per requirement — a delta with forty bare
+    // requirements would otherwise BE the payload (validate caps its details for
+    // the same reason).
+    for (const gap of scans) {
+        if (gap.bare.length === 0 || !services.includes(gap.service))
+            continue;
+        steps.push({
+            code: "next.author-scenarios",
+            statement: `${gap.bare.length} requirement(s) in ${gap.service}'s delta have no '#### Scenario:' ` +
+                `(starting with '${gap.bare[0].name}') — they generate no test and no verify claim.`,
+            command: `loam delta ${id} --service ${gap.service} --json`,
+            artifact: "spec",
+            service: gap.service,
+            path: gap.path,
+        });
+    }
+    if (findings.some((f) => UNPINNED.has(f.code))) {
+        steps.push({
+            code: "next.rebase",
+            statement: `${id} carries requirements or operations with no baseline pin — until they have one the merge cannot tell what it EDITS from what it merely quotes.`,
+            command: `loam rebase ${id}`,
+        });
+    }
+    if (blockedBy.length > 0) {
+        steps.push({
+            code: "next.archive-first",
+            statement: `${id} builds on ${blockedBy.join(", ")}, which ${blockedBy.length === 1 ? "has" : "have"} to archive first.`,
+            command: `loam dependencies ${id} --json`,
+        });
+    }
+    // Everything either gate refuses on, not just the errors: a warning marked
+    // `gates: true` stops archive exactly as hard, and leaving it out of the
+    // steps was the other half of leaving it out of the stage.
+    const blocking = findings.filter(unshippable);
+    if (blocking.length > 0) {
+        const gating = blocking.filter((f) => f.gates === true && f.severity !== "error").length;
+        steps.push({
+            code: "next.fix-coherence",
+            statement: `${id} has ${blocking.length} finding(s) that stop it, starting with ${blocking[0].code}` +
+                (gating > 0
+                    ? ` — ${gating} of them ${gating === 1 ? "is a warning that GATES" : "are warnings that GATE"} archive, ` +
+                        "which `validate` grades valid, so its exit code alone will not show you why archive refuses."
+                    : " — the axes disagree, and archive refuses."),
+            command: `loam validate ${id} --json`,
+        });
+    }
+    // The implementation half of the forward flow, which next[] never named at
+    // all: an agent read "author the spec" and then "record the verification",
+    // with nothing in between saying where a test comes from — so the only way
+    // left to answer a scenario claim was its own word, through `--record`.
+    steps.push(...testStep(id, verification, { services, scans, boundService }));
+    steps.push(...verifyStep(id, verification, { artifacts, services, boundService }));
+    // Always last, and always present: a feature whose every artifact holds and
+    // whose record is complete still has one thing left to do, and an empty
+    // `next[]` would leave a caller unable to tell "finished" from "this command
+    // had nothing to say".
+    steps.push({
+        code: "next.archive",
+        statement: steps.length === 0
+            ? `${id} is authored, coherent and verified — ship it.`
+            : `${id} ships once everything above is done; the dry run writes nothing and lists every file the merge would touch.`,
+        command: `loam archive ${id} --dry-run --json`,
+    });
+    return steps;
+}
+//# sourceMappingURL=next.js.map

package/dist/core/status/feature/next.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"next.js","sourceRoot":"","sources":["../../../../src/core/status/feature/next.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `next[]` — one feature.\n *\n * The payload's reason to exist. Each entry carries a stable `code` to branch\n * on, one sentence a person can read, and the literal command to run — ordered,\n * first entry first. `command` is the loam invocation that carries the step\n * forward: the one that does the work where loam does it (`rebase`, `archive`),\n * and the one that states or grades the work where the author does it (`delta`,\n * `validate`, `verify`). It is never a command that would write the artifact\n * behind the author's back — loam does not author.\n *\n * `next` is never empty. A feature with nothing outstanding still has a next\n * step (ship it), and a repository with nothing outstanding still has one (keep\n * the fleet green) — an empty array would be indistinguishable from a bug in\n * the caller's own parsing.\n */\nimport type { Finding } from \"../../vocabulary/report.js\";\nimport { recoverStep } from \"../interrupted.js\";\nimport type { ArtifactId, ArtifactState, NextStep } from \"../report.js\";\nimport { testStep, verifyStep } from \"../verification.js\";\nimport { type FeatureState } from \"./state.js\";\n\n/**\n * Would either gate refuse this? Severity answers `validate`'s question and\n * `gates` answers archive's; a finding that fails EITHER is one an author has\n * work to do about, and collapsing them to `severity === \"error\"` is how\n * `status` came to print \"ship it\" beside a warning archive exits 1 on.\n */\nexport function unshippable(f: Finding): boolean {\n  return f.severity === \"error\" || f.gates === true;\n}\n\n/** Codes whose one fix is `loam rebase`: a pin nobody ever wrote, on any of the three axes. */\nconst UNPINNED = new Set([\"delta.baseline-missing\", \"openapi.baseline-missing\", \"asyncapi.baseline-missing\"]);\n\nexport function featureNext(state: FeatureState, boundService: string | undefined): NextStep[] {\n  const { feature, services, artifacts, findings, blockedBy, verification, scans, interrupted } = state;\n  const id = feature.id;\n  // Before the archived shortcut: the interrupted commit may be this feature's\n  // own, and \"it shipped\" is not a thing to tell somebody whose living docs are\n  // half-written.\n  const first = interrupted === null ? [] : [recoverStep(interrupted)];\n  if (feature.archived) {\n    return [\n      ...first,\n      {\n        code: \"next.archived\",\n        statement: `${id} is archived — it shipped, and its delta is already folded into the living docs.`,\n        command: `loam show ${id} --json`,\n      },\n    ];\n  }\n\n  const steps: NextStep[] = [...first];\n  const owed = (kind: ArtifactId, service?: string): ArtifactState | undefined =>\n    artifacts.find(\n      (a) => a.id === kind && a.status === \"missing\" && (service === undefined || a.service === service),\n    );\n\n  const intent = owed(\"intent\");\n  if (intent !== undefined) {\n    steps.push({\n      code: \"next.author-intent\",\n      statement: `Write ${intent.path} — what ${id} is for, in prose, before anything is derived from it.`,\n      command: `loam validate ${id} --json`,\n      artifact: \"intent\",\n      path: intent.path,\n    });\n  }\n\n  if (services.length === 0) {\n    steps.push({\n      code: \"next.touch-service\",\n      statement: `${id} carries no per-service delta — add specs/<service>/spec.md for every service it changes.`,\n      command: \"loam list services --json\",\n    });\n  }\n\n  for (const svc of services) {\n    const spec = owed(\"spec\", svc);\n    if (spec !== undefined) {\n      steps.push({\n        code: \"next.author-spec\",\n        statement: `Write ${spec.path} — the ADDED/MODIFIED/REMOVED requirements ${id} makes to ${svc}, each with a scenario.`,\n        command: `loam delta ${id} --service ${svc} --json`,\n        artifact: \"spec\",\n        service: svc,\n        path: spec.path,\n      });\n    }\n    const api = owed(\"openapi\", svc);\n    if (api !== undefined) {\n      steps.push({\n        code: \"next.author-openapi\",\n        // Not \"the service is not in the living docs\": a service adopted\n        // without a contract is the commoner case, and that wording sent a\n        // reader looking for a directory that was right there. And not \"the\n        // operations it governs\" either — this step also fires for a service\n        // the feature INTRODUCES, where owesContract asks nothing about\n        // operations and the delta may tag none, so naming them promised the\n        // author a list they would go looking for and not find.\n        statement: `Write ${api.path} — nothing gives ${svc} a living openapi.yaml, so this feature is the only thing that can write down its API surface.`,\n        command: `loam delta ${id} --service ${svc} --json`,\n        artifact: \"openapi\",\n        service: svc,\n        path: api.path,\n      });\n    }\n  }\n\n  // A requirement with no scenario yields no generated .feature and no\n  // scenario.tested claim: a promise that reaches neither the suite nor the\n  // done-check, and that nothing downstream will ever mention again. One entry\n  // per service rather than per requirement — a delta with forty bare\n  // requirements would otherwise BE the payload (validate caps its details for\n  // the same reason).\n  for (const gap of scans) {\n    if (gap.bare.length === 0 || !services.includes(gap.service)) continue;\n    steps.push({\n      code: \"next.author-scenarios\",\n      statement:\n        `${gap.bare.length} requirement(s) in ${gap.service}'s delta have no '#### Scenario:' ` +\n        `(starting with '${gap.bare[0]!.name}') — they generate no test and no verify claim.`,\n      command: `loam delta ${id} --service ${gap.service} --json`,\n      artifact: \"spec\",\n      service: gap.service,\n      path: gap.path,\n    });\n  }\n\n  if (findings.some((f) => UNPINNED.has(f.code))) {\n    steps.push({\n      code: \"next.rebase\",\n      statement: `${id} carries requirements or operations with no baseline pin — until they have one the merge cannot tell what it EDITS from what it merely quotes.`,\n      command: `loam rebase ${id}`,\n    });\n  }\n\n  if (blockedBy.length > 0) {\n    steps.push({\n      code: \"next.archive-first\",\n      statement: `${id} builds on ${blockedBy.join(\", \")}, which ${blockedBy.length === 1 ? \"has\" : \"have\"} to archive first.`,\n      command: `loam dependencies ${id} --json`,\n    });\n  }\n\n  // Everything either gate refuses on, not just the errors: a warning marked\n  // `gates: true` stops archive exactly as hard, and leaving it out of the\n  // steps was the other half of leaving it out of the stage.\n  const blocking = findings.filter(unshippable);\n  if (blocking.length > 0) {\n    const gating = blocking.filter((f) => f.gates === true && f.severity !== \"error\").length;\n    steps.push({\n      code: \"next.fix-coherence\",\n      statement:\n        `${id} has ${blocking.length} finding(s) that stop it, starting with ${blocking[0]!.code}` +\n        (gating > 0\n          ? ` — ${gating} of them ${gating === 1 ? \"is a warning that GATES\" : \"are warnings that GATE\"} archive, ` +\n            \"which `validate` grades valid, so its exit code alone will not show you why archive refuses.\"\n          : \" — the axes disagree, and archive refuses.\"),\n      command: `loam validate ${id} --json`,\n    });\n  }\n\n  // The implementation half of the forward flow, which next[] never named at\n  // all: an agent read \"author the spec\" and then \"record the verification\",\n  // with nothing in between saying where a test comes from — so the only way\n  // left to answer a scenario claim was its own word, through `--record`.\n  steps.push(...testStep(id, verification, { services, scans, boundService }));\n  steps.push(...verifyStep(id, verification, { artifacts, services, boundService }));\n\n  // Always last, and always present: a feature whose every artifact holds and\n  // whose record is complete still has one thing left to do, and an empty\n  // `next[]` would leave a caller unable to tell \"finished\" from \"this command\n  // had nothing to say\".\n  steps.push({\n    code: \"next.archive\",\n    statement:\n      steps.length === 0\n        ? `${id} is authored, coherent and verified — ship it.`\n        : `${id} ships once everything above is done; the dry run writes nothing and lists every file the merge would touch.`,\n    command: `loam archive ${id} --dry-run --json`,\n  });\n  return steps;\n}\n"]}

package/dist/core/status/feature/state.js

@@ -0,0 +1,21 @@
+/**
+ * One feature, fully graded — the record every question in this package asks
+ * about.
+ *
+ * It exists because eight functions took the same seven or nine values in
+ * hand-kept order: a feature, its services, its artifacts, its findings, its
+ * verification, its scans, what it is blocked by, and whether a commit was
+ * interrupted. Positional, `services` and `blockedBy` are both `string[]` and
+ * transposing them compiles.
+ *
+ * Note what is NOT in here: the `--service` lens. The whole feature is graded
+ * and the view is narrowed afterwards, never the other way round — a rollup
+ * that moved with the lens would report a feature `ready` because the one
+ * service you asked about happens to be written, while three others have
+ * nothing.
+ */
+import {} from "../../repo/entries.js";
+import {} from "../../vocabulary/report.js";
+import {} from "../scan.js";
+import {} from "../report.js";
+//# sourceMappingURL=state.js.map

package/dist/core/status/feature/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/core/status/feature/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EAAqB,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAgB,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAkB,MAAM,YAAY,CAAC;AAC5C,OAAO,EAIN,MAAM,cAAc,CAAC","sourcesContent":["/**\n * One feature, fully graded — the record every question in this package asks\n * about.\n *\n * It exists because eight functions took the same seven or nine values in\n * hand-kept order: a feature, its services, its artifacts, its findings, its\n * verification, its scans, what it is blocked by, and whether a commit was\n * interrupted. Positional, `services` and `blockedBy` are both `string[]` and\n * transposing them compiles.\n *\n * Note what is NOT in here: the `--service` lens. The whole feature is graded\n * and the view is narrowed afterwards, never the other way round — a rollup\n * that moved with the lens would report a feature `ready` because the one\n * service you asked about happens to be written, while three others have\n * nothing.\n */\nimport { type FeatureEntry } from \"../../repo/entries.js\";\nimport { type Finding } from \"../../vocabulary/report.js\";\nimport { type DeltaScan } from \"../scan.js\";\nimport {\n  type ArtifactState,\n  type InterruptedCommit,\n  type VerificationState,\n} from \"../report.js\";\n\nexport interface FeatureState {\n  feature: FeatureEntry;\n  /** Every service the feature touches — not the narrowed view. */\n  services: string[];\n  artifacts: ArtifactState[];\n  findings: Finding[];\n  /** Features that have to archive before this one can. */\n  blockedBy: string[];\n  verification: VerificationState;\n  scans: DeltaScan[];\n  interrupted: InterruptedCommit | null;\n}\n"]}