@ybotok/loam 0.0.0 → 0.1.0-beta.1

package/dist/commands/validate.js

@@ -0,0 +1,1609 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { cpus } from "node:os";
+import { join } from "node:path";
+import { agentsStaleFinding } from "../core/agents-stamp.js";
+import { loadConfig } from "../core/config.js";
+import { listField, readFrontmatter } from "../core/frontmatter.js";
+import { emitJson, fail, reportNoConfig } from "../core/json.js";
+import { elementService, loadFile, serviceOf, serviceResolver, } from "../core/likec4.js";
+import { DocsRepoUnavailableError, docsRepoState, featurePaths, featureSpecPaths, featureSpecServices, landscapePath as landscapeFile, listFeatures, listServices, missingFeatureMessage, resolveFeature, serviceIdFindings, servicePaths, } from "../core/repo.js";
+import { countSeverity, reportValid, targetJson, targetValid, } from "../core/report.js";
+import { parseRequirements, requirementIdProblems, requirementsMissingScenarios, steplessFindings, } from "../core/spec.js";
+import { readOpenapi } from "../core/openapi.js";
+import { featureCoherence } from "../core/coherence.js";
+import { gatesArchive } from "../core/issue.js";
+import { emptySourcesMessage, expandSourceFiles, featureProvenance, missingSources, patternSources, serviceProvenance, unsafeSources, } from "../core/provenance.js";
+import { closeIds, coversCandidates, coversEdge, coversElement, entryResolves, parseCoversEntry, } from "../core/arch.js";
+import { gherkinFindings } from "../core/gherkin.js";
+import { readHealth } from "../core/health.js";
+import { LOAM_VERSION } from "../core/version.js";
+import { FleetContext, documentConflictFinding, landscapeConflictFinding, } from "../core/fleet-context.js";
+/**
+ * The refusal every READ command owes a `docsDir` that is not a docs repo.
+ *
+ * It is not a formality. `validate --all` and `list` used to answer a docsDir
+ * that does not exist with a green report over zero services, which is the one
+ * output a fleet gate must never produce: "nothing is wrong" and "I could not
+ * look" are opposite facts, and in CI the first one merges. The two codes are
+ * kept apart because the fixes point in different directions — a wrong path in
+ * loam.json versus a docs repo that was never cloned or scaffolded — exactly
+ * the way `no-config` and `config-invalid` are kept apart.
+ *
+ * "Zero services" stays reachable, and only from a REAL docs repo whose
+ * `services/` is empty: that is a legitimate state (before the first
+ * `loam adopt`) and it must keep exiting 0.
+ *
+ * `need` says how much of a docs repo this particular run has to have. A run
+ * that only reads features genuinely does not need `services/` — repo.ts takes
+ * the same position for `listFeatures` — and refusing there would turn one
+ * diagnosis into two contradictory ones. A run that enumerates services needs
+ * the directory that IS the list of services.
+ *
+ * It lives in validate.ts because validate is the fleet gate this doctrine is
+ * about; `list` and `show` import it rather than growing two more copies that
+ * could drift into three different sentences for one fact.
+ */
+export function docsRepoReady(json, docsDir, need) {
+    const state = docsRepoState(docsDir);
+    if (state.kind === "ok" || (state.kind === "no-services" && need === "docs"))
+        return true;
+    if (state.kind === "missing") {
+        fail(json, "docs-missing", `The configured docs repo does not exist: ${state.path}. ` +
+            "Fix `docsDir` in loam.json, clone the docs repo there, " +
+            "or run `loam init --docs <dir> --create` to make a new one.");
+        return false;
+    }
+    fail(json, "services-missing", `${state.path} is not a docs repo — it has no services/ directory. ` +
+        "Point `docsDir` in loam.json at the shared docs repo, " +
+        "or run `loam init --docs <dir> --create` to make one.");
+    return false;
+}
+/**
+ * The same refusal, reached the other way: `listServices`/`listFeatures` throw
+ * `DocsRepoUnavailableError` when the repo goes away mid-run (or when a caller
+ * reaches enumeration without passing the gate above). Mapping it back onto the
+ * same two codes keeps one breach spelled one way, instead of surfacing as the
+ * `internal` catch-all in cli.ts.
+ */
+export function reportDocsRepoError(json, err) {
+    fail(json, err.state.kind === "missing" ? "docs-missing" : "services-missing", err.message);
+}
+export function registerValidate(program) {
+    program
+        .command("validate")
+        .argument("[target]", "service or feature id (a feature wins when both match; --service/--feature force the reading)")
+        .description("Validate a service (C4 + requirement coverage) or a feature (delta + coverage)")
+        .option("--service <id>", "service to validate (defaults to the configured service)")
+        .option("--feature <id>", "validate a feature delta instead of a service")
+        .option("--all", "validate every service and every active feature")
+        .option("--strict", "exit 1 on any warning too — a per-invocation CI lever; the report and --json payload do not change")
+        .option("--errors-only", "print only errors and warnings — a rendering lever; the --json payload does not change")
+        .option("--json", "emit the machine contract instead of the human view")
+        .action(async (target, opts) => {
+        const json = opts.json === true;
+        if (target !== undefined && (opts.all || opts.service || opts.feature)) {
+            fail(json, "invalid-option", `'${target}' already names the target; drop --all/--service/--feature.`);
+            return;
+        }
+        if (opts.all && (opts.service || opts.feature)) {
+            fail(json, "invalid-option", "--all validates everything; drop --service/--feature.");
+            return;
+        }
+        // Two targets is no target: silently validating only the feature taught
+        // callers that --service had been honoured when it had been dropped.
+        if (opts.service && opts.feature) {
+            fail(json, "invalid-option", "--service and --feature name different targets; pass one or the other.");
+            return;
+        }
+        const config = await loadConfig();
+        if (!config) {
+            reportNoConfig(json);
+            return;
+        }
+        const { docsDir } = config;
+        // Before anything is enumerated: a docsDir that is not a docs repo must
+        // refuse, not report an empty fleet. See docsRepoReady. `--feature` is the
+        // one mode that never enumerates services, so it asks for less.
+        if (!docsRepoReady(json, docsDir, opts.feature ? "docs" : "services"))
+            return;
+        // One invocation, one filesystem snapshot. Nothing is global: a later
+        // command gets a fresh index and therefore cannot observe stale files.
+        const fleet = new FleetContext();
+        // `sources` are paths into a service's own repository, so they only mean
+        // something when loam is standing in that repository — which is exactly
+        // what loam.json's `service` records.
+        const repoOf = (service) => config.service === service ? process.cwd() : undefined;
+        const targets = [];
+        /** What the positional argument turned out to name, for the JSON payload. */
+        let resolvedKind;
+        try {
+            if (opts.all) {
+                // Parse the living landscape ONCE for the whole run: loadFile spins up
+                // a fresh LikeC4 workspace per call, and paying that per service makes
+                // the fleet's main CI command O(services) re-parses of the same file.
+                const lp = landscapeFile(docsDir);
+                const land = existsSync(lp) ? await fleet.loadLikeC4(lp) : null;
+                // The fleet-level cross-check first: it frames everything below it, and a
+                // service nobody drew is worth knowing before its own findings scroll past.
+                targets.push(await validateLandscape(docsDir, land, fleet));
+                const landscape = targets[0];
+                // The agent contract check, --all only: AGENTS.md is written once and
+                // never refreshed (the ownership contract), so the one thing the
+                // docs-repo-wide mode owes it is detection — a stamp older than the
+                // binary means agents are branching on tables the binary no longer
+                // honours. It grades the repo, not any service, so it rides on the
+                // landscape target.
+                const agentsPath = join(docsDir, "AGENTS.md");
+                const agents = agentsStaleFinding(existsSync(agentsPath) ? await readFile(agentsPath, "utf8") : null, LOAM_VERSION);
+                if (agents !== null)
+                    landscape.findings.push(agents);
+                targets.push(...(await inOrder(await listServices(docsDir, fleet), (svc) => guarded({ kind: "service", id: svc.id }, () => validateService({
+                    docsDir,
+                    service: svc.id,
+                    repoDir: repoOf(svc.id),
+                    preloaded: land,
+                    gherkinDir: config.gherkinDir,
+                    fleet,
+                    landscapeReported: true,
+                })))));
+                targets.push(...(await inOrder(await listFeatures(docsDir, {}, fleet), (feat) => guarded({ kind: "feature", id: feat.id }, () => validateFeature(docsDir, feat, land, fleet)))));
+            }
+            else if (opts.feature) {
+                const feature = await resolveFeature(docsDir, opts.feature, "exclude", fleet);
+                if (!feature) {
+                    fail(json, "unknown-target", await missingFeatureMessage(docsDir, opts.feature, fleet));
+                    return;
+                }
+                targets.push(await guarded({ kind: "feature", id: feature.id }, () => validateFeature(docsDir, feature, undefined, fleet)));
+            }
+            else if (target !== undefined) {
+                // The positional reads the way `show` reads one: try the feature first
+                // (ids like FEAT-101 are distinctive, service names are arbitrary), then
+                // the service. --service/--feature stay as the explicit spellings for a
+                // name that could be both — and when both readings exist, the run says
+                // so out loud instead of silently taking one (`target.ambiguous`).
+                const feature = await resolveFeature(docsDir, target, "exclude", fleet);
+                const isService = (await listServices(docsDir, fleet)).some((s) => s.id === target);
+                if (feature) {
+                    resolvedKind = "feature";
+                    const report = await guarded({ kind: "feature", id: feature.id }, () => validateFeature(docsDir, feature, undefined, fleet));
+                    if (isService)
+                        report.findings.unshift(ambiguousTarget(target, "feature"));
+                    targets.push(report);
+                }
+                else {
+                    // Neither reading exists. An archived feature is its own diagnosis
+                    // ("already archived", not "no such thing"); anything else reads as a
+                    // service, so the did-you-mean hints in service.unknown fire.
+                    if (!isService && (await resolveFeature(docsDir, target, "only", fleet)) !== null) {
+                        fail(json, "unknown-target", await missingFeatureMessage(docsDir, target, fleet));
+                        return;
+                    }
+                    resolvedKind = "service";
+                    targets.push(await guarded({ kind: "service", id: target }, () => validateService({
+                        docsDir,
+                        service: target,
+                        repoDir: repoOf(target),
+                        gherkinDir: config.gherkinDir,
+                        fleet,
+                    })));
+                }
+            }
+            else {
+                const service = opts.service ?? config.service;
+                if (!service) {
+                    fail(json, "invalid-option", "No service. Pass --service <id> or set it in loam.json.");
+                    return;
+                }
+                targets.push(await guarded({ kind: "service", id: service }, () => validateService({
+                    docsDir,
+                    service,
+                    repoDir: repoOf(service),
+                    gherkinDir: config.gherkinDir,
+                    fleet,
+                })));
+            }
+        }
+        catch (err) {
+            // The docs repo went away between the gate above and the enumeration.
+            if (err instanceof DocsRepoUnavailableError) {
+                reportDocsRepoError(json, err);
+                return;
+            }
+            // An IO failure that `guarded` could not localise to one target — it
+            // happened in the ENUMERATION, which reads every living spec's
+            // frontmatter to build the service list. There is no partial report to
+            // give: without the list, no service was checked, including the ones
+            // that are fine. Say which file, and refuse; the one thing that must
+            // not happen is a stack trace on stdout's sibling stream and an
+            // `internal` envelope that names nothing.
+            const path = err.path;
+            if (path === undefined)
+                throw err;
+            fail(json, "repository-unavailable", `${path} could not be read, so the service list itself is unknown and nothing was validated. ${err instanceof Error ? err.message : String(err)}`);
+            return;
+        }
+        // Counted off the findings rather than alongside them, so the rollup line
+        // and the per-service findings can never disagree about how many services
+        // this run could not check.
+        //
+        // Counted by SUBJECT, not by finding: a service whose spec.md and
+        // arch.spec.md both name `sources` raises two findings — each document
+        // has its own list and its own answer — but it is one service nobody
+        // here can check, and "2 services' sources" over a fleet of one is a
+        // number that sends the reader looking for a service that does not exist.
+        const unverifiable = new Set(targets.flatMap((t) => t.findings.filter((f) => f.code === UNVERIFIABLE).map((f) => f.subject ?? t.id))).size;
+        const valid = reportValid(targets);
+        const capped = targets.map(capDetails);
+        if (json) {
+            emitJson({
+                valid,
+                summary: summary(targets),
+                ...(resolvedKind === undefined ? {} : { resolvedKind }),
+                // Emitted in every mode now that it is derived per service: a
+                // single-service run knows exactly as much about its own blind spot
+                // as `--all` knows about the fleet's.
+                sourcesUnverifiableFromHere: unverifiable,
+                targets: capped.map(targetJson),
+            });
+        }
+        else {
+            renderText(capped, opts.all === true, unverifiable, opts.errorsOnly === true);
+        }
+        // --strict is a per-invocation CI lever: it fails the run on any error or
+        // warning (ok-severity confirmations never trip it — virtually every
+        // clean target emits some), and changes nothing else — `valid` keeps meaning "no
+        // errors" in text and JSON alike, so two pipelines reading the same repo
+        // may grade the same report differently and both are telling the truth.
+        const strictFailed = opts.strict === true &&
+            countSeverity(targets, "error") + countSeverity(targets, "warn") > 0;
+        if (!valid || strictFailed)
+            process.exitCode = 1;
+    });
+}
+/**
+ * How many targets `--all` may have in flight at once.
+ *
+ * Capped as well as scaled: each in-flight target holds a whole LikeC4/Langium
+ * workspace, so a 64-core box would open sixty-four of them at once and buy
+ * memory pressure rather than throughput (peak RSS on an 80-service fleet:
+ * 385 MB serial, ~500 MB pooled).
+ *
+ * Do not quote a speedup for this. The measured cost of `--all` is CPU inside
+ * the Langium parse, which one thread cannot divide however the loop is
+ * shaped; what the pool overlaps is the I/O half — the spec, contract and
+ * health reads around each parse. On an 80-service fleet it measures as a wash
+ * (11–13 s either way, on a box that was itself loaded). The number that moves
+ * this command is workspaces per run, not awaits per loop.
+ */
+const TARGET_CONCURRENCY = Math.max(1, Math.min(cpus().length, 8));
+/**
+ * Run `work` over `items` with a bounded number in flight, returning the
+ * results in INPUT order.
+ *
+ * The order is the contract, not an accident: the text report and the `--json`
+ * envelope are diffed between runs and between machines, so a concurrent run
+ * has to be byte-identical to the serial one for the same input. That is why
+ * results are written by index — nothing is appended as it finishes, and a slow
+ * service cannot reorder the fleet around it.
+ */
+async function inOrder(items, work) {
+    const out = [];
+    let next = 0;
+    const workers = Math.min(TARGET_CONCURRENCY, items.length);
+    await Promise.all(Array.from({ length: workers }, async () => {
+        for (let i = next++; i < items.length; i = next++)
+            out[i] = await work(items[i]);
+    }));
+    return out;
+}
+function summary(targets) {
+    return {
+        services: targets.filter((t) => t.kind === "service").length,
+        features: targets.filter((t) => t.kind === "feature").length,
+        errors: countSeverity(targets, "error"),
+        warnings: countSeverity(targets, "warn"),
+    };
+}
+/** The one code the rollup line counts; spelled once so the two cannot drift. */
+const UNVERIFIABLE = "sources.unverifiable-from-here";
+/**
+ * How many `details` lines any one finding may print before the rest are
+ * summarised away.
+ *
+ * A finding's details are evidence, not a log: LikeC4 reports one syntax error
+ * as dozens of cascading diagnostics, and a fleet-sized repo multiplies that by
+ * every target that mentions the file. The report is read by a person scrolling
+ * a CI log and by an agent with a context window, and neither of them is helped
+ * by the four-hundredth copy. The cap is applied to the JSON payload too, on
+ * purpose: `--json` is the interface an agent pipes, and an unbounded array is
+ * the same denial-of-attention there, just machine-readable.
+ */
+const DETAIL_LIMIT = 10;
+/** Truncate every finding's details, marking what was dropped so nothing looks complete when it is not. */
+function capDetails(t) {
+    return {
+        ...t,
+        findings: t.findings.map((f) => {
+            const details = f.details ?? [];
+            if (details.length <= DETAIL_LIMIT)
+                return f;
+            return {
+                ...f,
+                details: [...details.slice(0, DETAIL_LIMIT), `… (+${details.length - DETAIL_LIMIT} more)`],
+            };
+        }),
+    };
+}
+/**
+ * One target's checks, with an IO exception turned into a finding ON that
+ * target instead of aborting the run.
+ *
+ * A fleet gate that dies on the first unreadable file reports nothing about the
+ * other ninety-nine services — one bad permission bit, one file that is a
+ * dangling symlink, and CI's answer to "how is the fleet" becomes a stack
+ * trace. The failure is real and it is an error, so the run still exits 1; what
+ * changes is that everything else is still graded, and the finding names the
+ * service and the path instead of arriving as the `internal` catch-all.
+ */
+async function guarded(target, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        // A docs repo that vanished mid-run is not one target's problem — it is the
+        // whole run's, and the action's own catch reports it.
+        if (err instanceof DocsRepoUnavailableError)
+            throw err;
+        const path = err.path;
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            kind: target.kind,
+            id: target.id,
+            findings: [
+                {
+                    severity: "error",
+                    code: target.kind === "service" ? "service.unreadable" : "feature.unreadable",
+                    subject: target.id,
+                    message: `${target.id}: ${path === undefined ? "an artifact" : path} could not be read — ` +
+                        `nothing about this ${target.kind} was checked. ${reason}`,
+                },
+            ],
+        };
+    }
+}
+/**
+ * `target.ambiguous` — the positional named a service AND a feature. The tie is
+ * still broken the way it always was (the feature wins), because changing which
+ * one is picked would silently re-target every script that relies on it; what
+ * is new is that the run says which reading it took and how to force the other.
+ */
+function ambiguousTarget(arg, chosen) {
+    const other = chosen === "feature" ? "service" : "feature";
+    return {
+        severity: "warn",
+        code: "target.ambiguous",
+        subject: arg,
+        message: `'${arg}' names both a service and a feature — validated as the ${chosen}. ` +
+            `Pass --${other} ${arg} for the other reading.`,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Checks — every one produces findings, none of them print            */
+/* ------------------------------------------------------------------ */
+/** C4 kinds that model people. A person is never a service directory. */
+const ACTOR_KINDS = new Set(["person", "actor", "user"]);
+/** Tag marking an element as somebody else's system — undocumented on purpose. */
+const EXTERNAL_TAG = "external";
+/**
+ * The fleet cross-check: `services/` and the landscape both claim to name the
+ * fleet, and nothing used to compare them. A directory nobody drew and an element
+ * with nothing behind it were equally invisible.
+ *
+ * The two directions are graded differently because the evidence differs. A
+ * directory that exists is a fact, so a landscape missing it is an error — every
+ * view derived from that landscape is then incomplete. An element with no
+ * directory may legitimately be someone else's system, so it warns, and
+ * `#external` says "deliberately not ours" and silences it. An explicit
+ * `metadata { service '<id>' }` naming nothing is an error either way: a binding
+ * is a claim about this repo, not a guess at one.
+ *
+ * An ABSENT landscape is a finding, not a skipped check. It used to return null
+ * — no target, no findings, and a fleet gate that went green over a docs repo
+ * with no fleet map at all, which is the single artifact every derived view and
+ * every spine check is computed from. It is graded by what its absence proves:
+ * with services in `services/` it is an ERROR (a fleet that exists is undrawn),
+ * with none it is a WARNING (a docs repo before its first adopt legitimately
+ * has nothing to draw, but the file still belongs there — `loam init` scaffolds
+ * it, and a repo missing it will silently accept never getting one).
+ *
+ * `preloaded` is the already-parsed landscape under --all — the same doc every
+ * service check gets.
+ */
+async function validateLandscape(docsDir, preloaded, fleet) {
+    const path = landscapeFile(docsDir);
+    const findings = [];
+    const report = { kind: "landscape", id: "landscape", findings };
+    // The SET of service directories is this target's other subject, so it is
+    // graded before the map is even opened: `service.id-invalid` is a fact about
+    // `services/` that holds whether or not a landscape exists or parses, and
+    // both of those return early below. Emitted here and nowhere else — the
+    // enumeration is what makes the id a question, and one finding per fleet is
+    // what the rename fixes.
+    const entries = await listServices(docsDir, fleet);
+    findings.push(...serviceIdFindings(entries));
+    if (!existsSync(path)) {
+        const count = entries.length;
+        findings.push({
+            severity: count > 0 ? "error" : "warn",
+            code: "landscape.missing",
+            message: `landscape: architecture/landscape.likec4 does not exist — ` +
+                (count > 0
+                    ? `${count} service(s) are adopted and nothing draws the fleet. `
+                    : "nothing draws the fleet. ") +
+                "It is the one map every derived view and the C4↔API spine are computed from: " +
+                "write a `specification { element softwareSystem }` + `model { … }` document there " +
+                "with one element per services/<id>/, bound with `metadata { service '<id>' }`.",
+        });
+        return report;
+    }
+    // Conflict markers before the parse — `loam doctor`'s order, and for its
+    // reason: the markers are the cause and the parse errors are the cascade.
+    // Nothing may be concluded from a file that is two halves of two different
+    // maps, least of all that a service nobody drew is unmodelled, so this
+    // returns the way `landscape.invalid` does. An error, gating by the default
+    // rule and deliberately not carrying `gates` — that field is coherence's,
+    // and the archive gate has to ask this question itself (it does not yet).
+    // Read plainly rather than through FleetContext: this target runs outside
+    // `guarded`, and a document refused for its encoding would surface here as
+    // the whole run's `repository-unavailable` instead of one finding.
+    const conflict = landscapeConflictFinding("architecture/landscape.likec4", await readFile(path, "utf8"));
+    if (conflict !== null) {
+        findings.push(conflict);
+        return report;
+    }
+    const land = preloaded ?? (fleet === undefined ? await loadFile(path) : await fleet.loadLikeC4(path));
+    if (land.errors.length > 0) {
+        // Nothing may be concluded from a document that did not parse — in particular
+        // not that every service is unmodelled.
+        findings.push({
+            severity: "error",
+            code: "landscape.invalid",
+            message: `landscape: architecture/landscape.likec4 has ${land.errors.length} error(s) — cross-check with services/ impossible`,
+            details: land.errors.map(errorText),
+        });
+        return report;
+    }
+    const services = new Set(entries.map((s) => s.id));
+    // Depth is not a fact about a service. This used to keep only top-level
+    // elements (`!e.id.includes(".")`), which ordinary C4 breaks the moment it
+    // groups services under a parent: every nested element was thrown away, so a
+    // bound service read as unmodelled — an ERROR, on every service in the fleet
+    // — and a binding written one level down was never checked at all. The tree
+    // is walked instead, the way `serviceResolver` walks it for edges: a binding
+    // wins at any depth, then a title naming a real services/<id>/, and what sits
+    // INSIDE one of those is that service's container, not a service of its own.
+    const byId = new Map(land.elements.map((e) => [e.id, e]));
+    /** Declared ancestors of an element, nearest first. */
+    const ancestorsOf = (e) => {
+        const out = [];
+        for (let dot = e.id.lastIndexOf("."); dot !== -1; dot = e.id.lastIndexOf(".", dot - 1)) {
+            const parent = byId.get(e.id.slice(0, dot));
+            if (parent !== undefined)
+                out.push(parent);
+        }
+        return out;
+    };
+    const standsForService = (e) => e.service !== undefined || services.has(e.title);
+    /** Service-LEVEL elements: everything not drawn inside something that is already a service. */
+    const drawn = land.elements.filter((e) => !ancestorsOf(e).some(standsForService));
+    // Which services the landscape models, answered by the same resolver every
+    // edge join uses — so "modelled" here and "inbound edge" in the spine check
+    // can never disagree about what an element stands for.
+    const landSvcOf = serviceResolver(land.elements, services);
+    const modelled = new Set(land.elements.map((e) => landSvcOf(e.id)));
+    // Two boxes standing for one service directory. Every join in loam is
+    // `element -> service`, computed by picking the FIRST element that resolves —
+    // so with two of them, which one wins is readdir order, and the edges of the
+    // loser are attributed to a service they do not belong to. Silent until now,
+    // and unfixable by staring at either element on its own.
+    const perService = new Map();
+    for (const e of drawn) {
+        if (e.tags.includes(EXTERNAL_TAG))
+            continue;
+        const id = elementService(e);
+        perService.set(id, [...(perService.get(id) ?? []), e]);
+    }
+    for (const [id, elems] of perService) {
+        if (elems.length < 2)
+            continue;
+        // A collision only matters where it decides something: a real directory to
+        // attribute to, or a binding somebody wrote down on purpose.
+        if (!services.has(id) && !elems.some((e) => e.service !== undefined))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "landscape.binding-duplicate",
+            subject: id,
+            message: `landscape: ${elems.length} elements resolve to service '${id}' (${elems.map((e) => e.id).join(", ")}) — every element→service join picks one of them arbitrarily, so the others' edges are filed under a service that does not own them; keep one element per services/<id>/`,
+        });
+    }
+    for (const id of services) {
+        if (modelled.has(id))
+            continue;
+        findings.push({
+            severity: "error",
+            code: "landscape.service-unmodelled",
+            subject: id,
+            message: `landscape: services/${id}/ exists but nothing in architecture/landscape.likec4 models it — add an element, or bind one with metadata { service '${id}' }`,
+        });
+    }
+    // A binding is a claim about this repo wherever it is written — including
+    // inside another element, which the old top-level filter never looked at, so
+    // a typo one level down bound an edge to a service that does not exist and
+    // nothing said so. Every element with a binding answers for it, at any depth.
+    for (const e of land.elements) {
+        if (e.tags.includes(EXTERNAL_TAG) || e.service === undefined)
+            continue;
+        if (services.has(e.service))
+            continue;
+        findings.push({
+            severity: "error",
+            code: "landscape.binding-unknown",
+            subject: e.service,
+            message: `landscape: '${e.title}' binds to service '${e.service}', but services/${e.service}/ does not exist`,
+        });
+    }
+    for (const e of drawn) {
+        if (e.tags.includes(EXTERNAL_TAG))
+            continue;
+        if (e.service !== undefined)
+            continue; // graded by the binding pass above
+        if (ACTOR_KINDS.has(e.kind.toLowerCase()))
+            continue;
+        if (services.has(e.title))
+            continue;
+        // An element that CONTAINS a service is a grouping — a domain, a boundary,
+        // an enterprise — not a service nobody adopted. There is nothing to bind on
+        // it and nothing to tag #external, so asking for either would be a warning
+        // with no correct fix; the services under it answer for themselves.
+        if (land.elements.some((c) => c.id.startsWith(`${e.id}.`) && standsForService(c)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "landscape.service-undocumented",
+            subject: e.title,
+            message: `landscape: '${e.title}' has no services/${e.title}/ — bind it with metadata { service '<id>' }, or tag it #${EXTERNAL_TAG} if it is not ours`,
+        });
+    }
+    if (findings.length === 0) {
+        findings.push({
+            severity: "ok",
+            code: "landscape.matched",
+            message: `landscape: ${services.size} service(s) modelled — architecture/landscape.likec4 and services/ agree`,
+        });
+    }
+    return report;
+}
+async function validateService(check) {
+    const { docsDir, service, repoDir, preloaded, gherkinDir, fleet } = check;
+    const findings = [];
+    const report = { kind: "service", id: service, findings };
+    const paths = servicePaths(docsDir, service);
+    // A directory that does not exist is a different fact from a directory with
+    // everything missing: validating a typo must say "typo", not "unadopted".
+    if (!existsSync(paths.dir)) {
+        const close = closeIds(service, (await listServices(docsDir, fleet)).map((s) => s.id));
+        findings.push({
+            severity: "error",
+            code: "service.unknown",
+            message: `No service directory at ${paths.dir}.` +
+                (close.length > 0
+                    ? ` Did you mean: ${close.join(", ")}?`
+                    : " `loam list services` shows what exists."),
+            text: { marker: false },
+        });
+        return report;
+    }
+    // C4 model. Its absence is an error — this is where `adopt` comes in — but it
+    // must NOT silence the rest of the gate stack: `loam archive` of a feature
+    // introducing a new service creates exactly this state (spec.md, arch.spec.md,
+    // openapi.yaml, no model.likec4), and an early return here suspended arch
+    // coverage, health.uncovered, provenance (content_digest included) and the
+    // gherkin staleness chain for the very services vouch had just promised them
+    // to. So the finding is emitted and the walk CONTINUES; only the checks that
+    // read the model itself are guarded.
+    const hasModel = existsSync(paths.model);
+    let elements = [];
+    let relationships = [];
+    if (!hasModel) {
+        findings.push({
+            severity: "error",
+            code: "service.no-model",
+            message: `No C4 model at ${paths.model}. Run \`loam adopt\` for '${service}' first.`,
+            text: { marker: false },
+        });
+    }
+    else {
+        const model = fleet === undefined ? await loadFile(paths.model) : await fleet.loadLikeC4(paths.model);
+        elements = model.elements;
+        relationships = model.relationships;
+        if (model.errors.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "c4.invalid",
+                message: `${service}: C4 model has ${model.errors.length} error(s)`,
+                details: model.errors.map(errorText),
+            });
+        }
+        else {
+            findings.push({
+                severity: "ok",
+                code: "c4.valid",
+                message: `${service}: C4 model valid (${elements.length} elements · ${relationships.length} relationships)`,
+            });
+        }
+    }
+    // The living landscape, parsed at most once per run: under --all the caller
+    // hands in the doc it already loaded, single-service runs load on demand. It
+    // serves two checks below — the no-openapi grace and the spine.
+    const land = preloaded ??
+        (existsSync(landscapeFile(docsDir))
+            ? fleet === undefined
+                ? await loadFile(landscapeFile(docsDir))
+                : await fleet.loadLikeC4(landscapeFile(docsDir))
+            : null);
+    // Which service directories actually exist — the positive evidence
+    // `serviceOf` needs to resolve an edge drawn into a modelled CONTAINER
+    // (`paymentService.api`) back to the service that owns it. Without it every
+    // such edge resolves to the container's own title, i.e. to a service nobody
+    // has ever adopted, and drops out of the spine unnoticed.
+    const known = new Set((await listServices(docsDir, fleet)).map((s) => s.id));
+    // Requirement coverage.
+    let reqs = [];
+    if (existsSync(paths.spec)) {
+        const specText = fleet === undefined ? await readFile(paths.spec, "utf8") : await fleet.readText(paths.spec);
+        reqs = fleet === undefined ? parseRequirements(specText) : await fleet.readRequirements(paths.spec);
+        // Conflict markers first, because they say that nothing below this line is
+        // anyone's text. An error, gating by the default rule and deliberately
+        // without `gates`: that field is coherence's (issue.ts) and archive does
+        // not read validate's findings, so claiming it here would be a promise
+        // about a gate that is not wired. What makes it an error rather than a
+        // warning is what the next merge does — `loam archive` rewrites the
+        // requirements section of this very file and takes whichever marker lines
+        // fall inside it, turning a conflict anyone can see into a document nobody
+        // can tell is wrong.
+        const conflict = documentConflictFinding(`${service}: spec.md`, service, specText);
+        if (conflict !== null)
+            findings.push(conflict);
+        // A living spec with no `### Requirement:` block at all is the baseline
+        // `loam adopt` scaffolds and nobody ever filled in. "requirements covered
+        // (0 requirements, all with scenarios)" is true of it and says the opposite
+        // of what a reader needs: every cross-axis check downstream — API
+        // governance, the Operations: spine, gherkin generation — is vacuous here,
+        // and the green tick is what let a whole fleet score `sourced` over empty
+        // files.
+        if (reqs.length === 0) {
+            findings.push({
+                severity: "warn",
+                code: "spec.no-requirements",
+                subject: service,
+                message: `${service}: spec.md holds no '### Requirement:' blocks — every requirement-driven check below is vacuous, and nothing here can go out of date because nothing is written down`,
+            });
+        }
+        else {
+            findings.push(coverageFinding(`${service}: requirements`, reqs));
+        }
+        // The other half of the coverage question, and an error for the same
+        // reason the first half is: the whole claim of coverage is that a
+        // requirement has a scenario something can RUN. A heading with no steps
+        // satisfies the count and tests nothing — cucumber runs it vacuously green
+        // and `loam verify --results` can never confirm it — so a fleet gate that
+        // called it covered was certifying the absence of a test.
+        findings.push(...steplessFindings(`${service}: requirements`, service, reqs));
+        findings.push(...duplicateRequirementFindings(reqs, `${service}: spec.md`, service));
+        findings.push(...requirementIdFindings(reqs, `${service}: spec.md`, service));
+        findings.push(...repeatedListLineFindings(reqs, `${service}: spec.md`, service));
+    }
+    else {
+        findings.push({
+            severity: "warn",
+            code: "service.no-spec",
+            message: `No living spec at ${paths.spec} — requirement coverage and API governance are unchecked`,
+        });
+    }
+    // API coverage: every operation in openapi.yaml is governed by a requirement.
+    const api = await readOpenapi(paths.openapi, fleet);
+    const removeMarkers = api.ops.filter((o) => o.remove);
+    const liveOps = api.ops.filter((o) => !o.remove);
+    const ops = liveOps.map((o) => o.id);
+    const deprecatedOps = new Set(liveOps.filter((o) => o.deprecated).map((o) => o.id));
+    // The living landscape's element→service resolver, container-aware and
+    // memoized. Every question below that asks "does this edge point at me?"
+    // asks it through this one function, so the no-openapi grace and the spine
+    // check can never disagree about which edges are inbound.
+    const landSvcOf = land === null ? null : serviceResolver(land.elements, known);
+    // Inbound calls the landscape can PROVE: op-linked edges whose target
+    // resolves to this service. Null when the landscape proves nothing at all
+    // (absent, or it did not parse) — which is not the same fact as "nobody
+    // calls me", and the two must not be graded alike.
+    const inboundOps = land === null || land.errors.length > 0
+        ? null
+        : land.relationships.filter((r) => r.op !== undefined && landSvcOf(r.target) === service);
+    // The other half of the evidence a contract is owed: the living spec's own
+    // `Operations:` lines. A requirement on its way out governs nothing.
+    const governedOps = reqs.filter((r) => r.kind !== "REMOVED").flatMap((r) => r.operations);
+    /** No contract to read: deleted, renamed, or never written. */
+    const contractMissing = !existsSync(paths.openapi);
+    if (contractMissing) {
+        // A contract that is gone is not a reason to stop grading the API axis —
+        // it IS the axis's answer, and every check below used to live inside the
+        // file-exists branch, so deleting or misspelling the file turned the whole
+        // axis (including the documented `spec-api.op-undefined`) green.
+        //
+        // What decides the severity is whether anything already written down is
+        // holding a join into it: a living `Operations:` line, or an op-linked
+        // landscape edge. With one of those, the absence breaks a link somebody
+        // authored — an error. With neither, this is a service that legitimately
+        // has no HTTP surface (a worker nobody calls), and a fleet mid-rollout
+        // must not go red for it — a warning, or, when the landscape PROVES nobody
+        // calls it, the documented silence.
+        //
+        // One finding, not one per dangling link: the fix is a single file, and
+        // the links it strands ride along as details.
+        const dangling = [...new Set([...governedOps, ...(inboundOps ?? []).map((r) => r.op)])].sort();
+        if (dangling.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "service.no-openapi",
+                subject: service,
+                message: `No OpenAPI contract at ${paths.openapi}, and ${dangling.length} operation link(s) already point into it — ` +
+                    `every requirement and landscape edge naming one of them resolves to nothing until the file is back`,
+                details: dangling,
+            });
+        }
+        else if (inboundOps === null) {
+            findings.push({
+                severity: "warn",
+                code: "service.no-openapi",
+                message: `No OpenAPI contract at ${paths.openapi} — API coverage and the landscape spine are unchecked`,
+            });
+        }
+    }
+    else if (api.unreadable) {
+        // A contract that EXISTS but does not read is a broken source of truth, not
+        // an empty one: swallowing it into zero operations used to grade every
+        // inbound landscape edge `spine.op-undefined` — a false diagnosis pointing
+        // at the landscape when the truth was this file. So the file is the error,
+        // and every check that reads the contract (api.*, the spine's op
+        // resolution) is suspended below, the landscape.invalid discipline.
+        findings.push({
+            severity: "error",
+            code: "openapi.invalid",
+            message: `${service}: openapi.yaml does not parse — API coverage and the landscape spine are unchecked`,
+            ...(api.error === undefined ? {} : { details: [api.error] }),
+        });
+    }
+    else {
+        if (removeMarkers.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "openapi.remove-marker-living",
+                message: `${service}: living openapi.yaml contains ${removeMarkers.length} x-loam-remove marker(s) (${removeMarkers.map((op) => op.id).join(", ")}) — removal markers are valid only in feature deltas`,
+            });
+        }
+        // The same marker written at PATH level, beside the methods. `readOpenapi`
+        // is keyed by (path, method), which is precisely why the check above cannot
+        // see this one and precisely how one reached a living contract in the first
+        // place: it addresses no operation, so it retired nothing, and it stayed
+        // invisible afterwards. Error, like its method-level sibling — a
+        // feature-only key published to every consumer of the fleet, and one that
+        // keeps the empty-path cleanup from ever firing. Same code as the archive
+        // plan's: one breach, one name, wherever it is found.
+        for (const removed of api.pathLevelRemovals) {
+            findings.push({
+                severity: "error",
+                code: "openapi.remove-marker-path-level",
+                subject: service,
+                message: `${service}: living openapi.yaml carries x-loam-remove at PATH level on '${removed}' — ` +
+                    `a removal marker names ONE operation, so beside the methods it retires nothing and is not a contract key either, ` +
+                    `and no id-keyed check can see it. Delete it from the living contract; retire an operation through a feature delta whose marker sits inside the operation.`,
+            });
+        }
+        // Two slots claiming one operationId in a LIVING contract. `readOpenapi`
+        // has computed this since the merge needed it, and only the feature path
+        // (coherence) ever read it — so the ambiguity was reachable only when some
+        // unrelated feature happened to carry a delta for this service, and the
+        // fleet gate that actually runs in CI was blind to it. Same code and same
+        // sentence as the feature-scope check: one breach, one name.
+        for (const id of api.duplicateIds) {
+            const slots = api.ops.filter((op) => op.id === id).map((op) => `${op.method} ${op.path}`);
+            findings.push({
+                severity: "warn",
+                code: "openapi.duplicate-operationid",
+                subject: service,
+                message: `${service}: the living OpenAPI defines operationId '${id}' at ${slots.join(" and ")} — every join on the id (a requirement's Operations: line, an edge's metadata { op }, a removal marker) picks one of those slots arbitrarily`,
+            });
+        }
+        const defined = new Set(ops);
+        // `Operations:` on a LIVING requirement, resolved against this service's own
+        // contract. Nothing did this before: the same spine is checked inside a
+        // feature delta (coherence's spec-api.op-undefined) and then never again, so
+        // a typo that shipped, or an operation later renamed out of openapi.yaml,
+        // left a living requirement governing an operation that does not exist —
+        // green forever, and every downstream join through that id silently empty.
+        // Same code and severity as the feature-scope check on purpose: one breach,
+        // one name, wherever it is found.
+        for (const r of reqs) {
+            if (r.kind === "REMOVED")
+                continue;
+            for (const op of r.operations) {
+                if (defined.has(op))
+                    continue;
+                const close = closeIds(op, ops);
+                findings.push({
+                    severity: "error",
+                    code: "spec-api.op-undefined",
+                    subject: service,
+                    message: `${service}: requirement '${r.name}' governs '${op}', not defined in ${service}'s OpenAPI` +
+                        (close.length > 0 ? `. Did you mean: ${close.join(", ")}?` : ""),
+                });
+            }
+        }
+        if (ops.length > 0) {
+            const governed = new Set(reqs.flatMap((r) => r.operations));
+            const orphans = ops.filter((op) => !governed.has(op));
+            if (orphans.length === 0) {
+                findings.push({
+                    severity: "ok",
+                    code: "api.covered",
+                    message: `${service}: API covered (${ops.length} operation(s) governed by requirements)`,
+                });
+            }
+            else {
+                findings.push({
+                    severity: "warn",
+                    code: "api.ungoverned",
+                    message: `${service}: ${orphans.length} operation(s) not governed by any requirement — ${orphans.join(", ")}`,
+                });
+            }
+            // The migration-debt case: requirements exist, the API exists, and no
+            // `Operations:` line ties them — every cross-axis check above and in
+            // feature mode is vacuously green. Once per service, not per operation;
+            // with zero requirements the spec (or its absence) is the finding instead.
+            if (reqs.length > 0 && reqs.every((r) => r.operations.length === 0)) {
+                findings.push({
+                    severity: "warn",
+                    code: "api.ops-unlinked",
+                    message: `${service}: openapi.yaml defines ${ops.length} operation(s) but no requirement links any — the API axis is unchecked for this service`,
+                });
+            }
+            // Lifecycle: a requirement whose `Operations:` list resolves ONLY to
+            // deprecated operations governs behaviour the contract is retiring.
+            // Deprecation is the documented first step of removing an op; the explicit
+            // feature marker is the final step. Until that delta archives, the op stays
+            // live, so the fix is migration or a coordinated retirement. Ops the contract does not define at all
+            // prove nothing here and are left to spec-api.op-undefined above.
+            for (const r of reqs) {
+                const resolved = r.operations.filter((op) => defined.has(op));
+                if (resolved.length === 0 || !resolved.every((op) => deprecatedOps.has(op)))
+                    continue;
+                findings.push({
+                    severity: "warn",
+                    code: "api.requirement-deprecated",
+                    message: `${service}: requirement '${r.name}' governs only deprecated operation(s) (${resolved.join(", ")}) — the behaviour it describes is on its way out; migrate it to the replacement operation, or retire it`,
+                });
+            }
+        }
+    }
+    // Landscape spine: cross-system edges calling THIS service must resolve to a real
+    // operation in its OpenAPI — the C4↔API contract, checked in the living landscape,
+    // not only in feature mode. Catches dangling / de-linked op edges.
+    if (land !== null) {
+        if (land.errors.length > 0) {
+            // A living landscape that does not parse disables the C4↔API spine check —
+            // that is a broken source of truth, not a skippable detail.
+            //
+            // The parser's own output is attached ONCE per run, and not here when the
+            // run has a landscape target to carry it. One syntax error in one file
+            // becomes N copies of a dozen cascading diagnostics on a fleet of N
+            // services — the report stops being readable at exactly the moment
+            // somebody needs to read it, and the fix is one file either way.
+            findings.push({
+                severity: "error",
+                code: "spine.landscape-invalid",
+                subject: service,
+                message: `${service}: landscape.likec4 has ${land.errors.length} error(s) — spine check impossible` +
+                    (check.landscapeReported === true
+                        ? "; the parser output is reported once, on the landscape target"
+                        : ""),
+                ...(check.landscapeReported === true ? {} : { details: land.errors.map(errorText) }),
+            });
+        }
+        else {
+            // Which element IS this service is the binding's call, then a title that
+            // names a real services/<id>/, and an edge into a modelled container
+            // counts as an edge into its service — matching the exact id alone meant a
+            // container edge left the spine without a word.
+            const svcOf = landSvcOf;
+            const opset = new Set(ops);
+            let checked = 0;
+            let broken = 0;
+            for (const r of land.relationships) {
+                if (svcOf(r.target) !== service)
+                    continue;
+                if (r.op !== undefined) {
+                    // A contract that cannot be read — broken, or not there at all —
+                    // proves nothing about this edge, neither broken nor resolved.
+                    // Grading the edges against an empty operation set turned ONE root
+                    // cause (the file) into one `spine.op-undefined` per inbound edge, so
+                    // a service with twelve consumers reported twelve landscape defects
+                    // and never named the file. `openapi.invalid` / `service.no-openapi`
+                    // already did; only op-link-missing (which never reads the contract)
+                    // stays live, and `checked` stays 0 so no false spine.resolved is
+                    // claimed either.
+                    if (api.unreadable || contractMissing)
+                        continue;
+                    checked += 1;
+                    if (!opset.has(r.op)) {
+                        broken += 1;
+                        findings.push({
+                            severity: "error",
+                            code: "spine.op-undefined",
+                            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', not defined in ${service}'s OpenAPI`,
+                        });
+                    }
+                    else if (deprecatedOps.has(r.op)) {
+                        // The contract holds — the op is defined — but it is marked
+                        // `deprecated: true`: the consumer is standing on a contract being
+                        // retired, and should be migrating off it. Warn per inbound edge;
+                        // a deprecated op nobody calls raises no spine finding at all.
+                        findings.push({
+                            severity: "warn",
+                            code: "spine.op-deprecated",
+                            message: `${service}: landscape edge ${svcOf(r.source)} → ${service} calls '${r.op}', which ${service}'s OpenAPI marks deprecated — the consumer should migrate off it`,
+                        });
+                    }
+                }
+                else if ((r.title ?? "").toLowerCase().startsWith("call")) {
+                    findings.push({
+                        severity: "warn",
+                        code: "spine.op-link-missing",
+                        message: `${service}: landscape edge ${svcOf(r.source)} → ${service} ("${r.title}") has no operation link (metadata { op })`,
+                    });
+                }
+            }
+            if (broken === 0 && checked > 0) {
+                findings.push({
+                    severity: "ok",
+                    code: "spine.resolved",
+                    message: `${service}: landscape spine (${checked} inbound call(s) resolve to OpenAPI)`,
+                });
+            }
+        }
+    }
+    // The architecture spec axis — the obligations a business spec never carries
+    // (the transactional outbox, retries, metrics, alerts). arch.spec.md is
+    // optional and its ABSENCE is not a finding (partial adoption is supported);
+    // what exists must hold together: every requirement needs a scenario, every
+    // `Covers:` entry must resolve (covers.unknown), and every alert/SLI that
+    // health.yaml declares wants a covering requirement (health.uncovered) — the
+    // moment health.yaml stops being inert. Warnings, never gates: `--strict` is
+    // the CI escalation.
+    const health = await readHealth(paths.health);
+    const archText = existsSync(paths.archSpec)
+        ? fleet === undefined
+            ? await readFile(paths.archSpec, "utf8")
+            : await fleet.readText(paths.archSpec)
+        : null;
+    const archReqs = archText === null
+        ? []
+        : fleet === undefined
+            ? parseRequirements(archText)
+            : await fleet.readRequirements(paths.archSpec);
+    if (archText !== null) {
+        // The arch axis is advisory in what it ASKS for (covers.unknown,
+        // health.uncovered are warnings) but not in whether the file is readable:
+        // both breaches below are about the document itself, and they are graded
+        // exactly as they are on the business axis — one file, one rule.
+        const conflict = documentConflictFinding(`${service}: arch.spec.md`, service, archText);
+        if (conflict !== null)
+            findings.push(conflict);
+        findings.push(coverageFinding(`${service}: arch requirements`, archReqs));
+        findings.push(...steplessFindings(`${service}: arch requirements`, service, archReqs));
+        findings.push(...duplicateRequirementFindings(archReqs, `${service}: arch.spec.md`, service));
+        findings.push(...requirementIdFindings(archReqs, `${service}: arch.spec.md`, service));
+        findings.push(...repeatedListLineFindings(archReqs, `${service}: arch.spec.md`, service));
+    }
+    // A health.yaml that exists but does not read is reported once, and the
+    // checks that read it go quiet BOTH ways: its ids are unknown, so no
+    // health.uncovered obligation exists (the empty id set below is already
+    // silent), and no `Covers: alert:/sli:` entry may be graded a typo against
+    // ids nobody could read (coversUnknownFindings mutes on the flag). A warn,
+    // not an error: the axis it feeds is advisory end to end.
+    if (health.unreadable) {
+        findings.push({
+            severity: "warn",
+            code: "health.invalid",
+            subject: service,
+            message: `${service}: health.yaml does not parse — alert/SLI ids are unreadable, so Covers: alert:/sli: entries and health coverage are unchecked`,
+            ...(health.error === undefined ? {} : { details: [health.error] }),
+        });
+    }
+    const landParses = land !== null && land.errors.length === 0 ? land : null;
+    const scope = {
+        elements: [...elements, ...(landParses?.elements ?? [])],
+        relationships: [...relationships, ...(landParses?.relationships ?? [])],
+        health: health.ids,
+    };
+    findings.push(...coversUnknownFindings(archReqs, `${service}: arch.spec.md`, service, scope, health.unreadable));
+    const activeCovers = coversEntries(archReqs);
+    for (const { form, ids } of [
+        { form: "alert", ids: health.ids.alerts },
+        { form: "sli", ids: health.ids.slis },
+    ]) {
+        for (const id of ids) {
+            if (activeCovers.some((e) => e.form === form && e.id === id))
+                continue;
+            findings.push({
+                severity: "warn",
+                code: "health.uncovered",
+                subject: service,
+                message: `${service}: health.yaml declares ${form === "alert" ? "alert" : "SLI"} '${id}' but no arch.spec.md requirement covers it — write one with 'Covers: ${form}:${id}', or the signal ships with nothing testing it`,
+            });
+        }
+    }
+    // Provenance last: who vouched for this, and what code it was written from.
+    findings.push(...(await serviceProvenance(docsDir, service, { repoDir })));
+    findings.push(...(await sourceScopeFindings(docsDir, service, repoDir)));
+    // The generated-gherkin freshness chain, service-repo-scoped like sources.*:
+    // it needs the repo (the suite lives there), and it stays quiet until
+    // <gherkinDir>/loam/ exists — a service that never generated has not opted in.
+    findings.push(...(await gherkinFindings({ docsDir, service, repoDir, gherkinDir, fleet })));
+    return report;
+}
+/** The parsed Covers entries of every requirement that will live (REMOVED covers nothing). */
+function coversEntries(reqs) {
+    return reqs.filter((r) => r.kind !== "REMOVED").flatMap((r) => r.covers.map(parseCoversEntry));
+}
+/**
+ * `spec.duplicate-requirement` — two `### Requirement:` blocks with one name in
+ * one LIVING document. Nothing else catches it, and the merge algebra
+ * (applyRequirementDelta) matches by name and edits only the FIRST match: a
+ * later archive rewrites one copy and the other survives as a stale snapshot
+ * of whatever the requirement used to say. Per file on purpose — spec.md and
+ * arch.spec.md are separate requirement namespaces (their merges never cross
+ * files), so one name appearing in both is legal and unflagged.
+ */
+function duplicateRequirementFindings(reqs, where, subject) {
+    const counts = new Map();
+    for (const r of reqs)
+        counts.set(r.name, (counts.get(r.name) ?? 0) + 1);
+    return [...counts]
+        .filter(([, n]) => n > 1)
+        .map(([name, n]) => ({
+        severity: "error",
+        code: "spec.duplicate-requirement",
+        subject,
+        message: `${where}: requirement '${name}' is defined ${n} times — a merge edits only the first, every other copy lives on stale; keep exactly one`,
+    }));
+}
+/** Stable IDs are optional, but once authored they must select exactly one requirement. */
+function requirementIdFindings(reqs, where, subject) {
+    return requirementIdProblems(reqs).map((problem) => {
+        if (problem.kind === "invalid") {
+            return {
+                severity: "error",
+                code: "spec.requirement-id-invalid",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' has invalid Requirement-ID '${problem.value}' — use 1-128 characters matching [A-Za-z][A-Za-z0-9._-]*`,
+            };
+        }
+        if (problem.kind === "repeated") {
+            return {
+                severity: "error",
+                code: "spec.requirement-id-repeated",
+                subject,
+                message: `${where}: requirement '${problem.requirement}' declares Requirement-ID ${problem.values.length} times — identity must be declared exactly once`,
+            };
+        }
+        return {
+            severity: "error",
+            code: "spec.requirement-id-duplicate",
+            subject,
+            message: `${where}: Requirement-ID '${problem.id}' is shared by ${problem.requirements.map((name) => `'${name}'`).join(", ")} — one ID may identify only one requirement`,
+        };
+    });
+}
+/**
+ * The two list lines of the requirement grammar, exactly as core/spec.ts spells
+ * them (mirrored here, not exported from there, because the parser's grammar is
+ * its own; a drift shows up as this check counting differently than the parser
+ * assigns). A SECOND matching line in one requirement body REPLACES the first —
+ * assignment, not append, the documented keep-last quirk — so the author's
+ * "long list in two lines" pattern silently loses its first line.
+ */
+const OPERATIONS_LINE_RE = /^\s*Operations?:\s*(.+?)\s*$/i;
+const COVERS_LINE_RE = /^\s*Covers?:\s*(.+?)\s*$/i;
+/**
+ * `spec.repeated-operations` / `spec.repeated-covers` — warn on the silent
+ * loss, keep the keep-last semantics (changing them would re-read every spec
+ * in the fleet). Scenario bodies never count: the parser only assigns from the
+ * requirement's own body lines, and `Requirement.text` is exactly those.
+ * REMOVED requirements are exempt the way coversEntries exempts them — content
+ * on its way out obliges nothing.
+ */
+function repeatedListLineFindings(reqs, where, subject) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const { re, label, code } of [
+            { re: OPERATIONS_LINE_RE, label: "Operations:", code: "spec.repeated-operations" },
+            { re: COVERS_LINE_RE, label: "Covers:", code: "spec.repeated-covers" },
+        ]) {
+            const n = r.text.filter((line) => re.test(line)).length;
+            if (n < 2)
+                continue;
+            out.push({
+                severity: "warn",
+                code,
+                subject,
+                message: `${where}: requirement '${r.name}' has ${n} '${label}' lines — the last REPLACES the others (assignment, not append), the earlier list is silently lost; merge them into one comma-separated line`,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * `covers.unknown` — the typo guard on the Covers: line. Warn, not error: the
+ * axis is advisory end to end, and a wrong id already costs its author the
+ * coverage they wrote the line for. The hint offers only real ids (closeIds's
+ * rule), and says where resolution looked when there is nothing close.
+ * `healthUnreadable` mutes the alert:/sli: forms only: against a health.yaml
+ * nobody could read, "did you mean" is a false diagnosis of a typo —
+ * health.invalid (emitted by the service target) is the honest one.
+ */
+function coversUnknownFindings(reqs, where, subject, scope, healthUnreadable = false) {
+    const out = [];
+    for (const r of reqs) {
+        if (r.kind === "REMOVED")
+            continue;
+        for (const raw of r.covers) {
+            const entry = parseCoversEntry(raw);
+            if (healthUnreadable && (entry.form === "alert" || entry.form === "sli"))
+                continue;
+            if (entryResolves(entry, scope))
+                continue;
+            const close = coversCandidates(entry, scope);
+            out.push({
+                severity: "warn",
+                code: "covers.unknown",
+                subject,
+                message: `${where}: requirement '${r.name}' — Covers: '${raw}' resolves to nothing` +
+                    (close.length > 0
+                        ? `. Did you mean: ${close.join(", ")}?`
+                        : " in the model, the landscape or health.yaml"),
+            });
+        }
+    }
+    return out;
+}
+async function validateFeature(docsDir, feature, preloadedLand, fleet) {
+    const findings = [];
+    const featureDir = feature.dir;
+    const featureId = feature.id;
+    // delta.likec4 parse + collect tagged edges. The loaded doc is kept and
+    // handed to featureCoherence below — loading it is a Langium workspace spin,
+    // and paying it twice per feature was the dominant cost of `validate --all`.
+    let taggedEls = [];
+    let taggedRels = [];
+    let elements = [];
+    let deltaRels = [];
+    let deltaDoc;
+    const deltaPath = featurePaths(featureDir).delta;
+    if (existsSync(deltaPath)) {
+        const res = fleet === undefined ? await loadFile(deltaPath) : await fleet.loadLikeC4(deltaPath);
+        deltaDoc = res;
+        if (res.errors.length > 0) {
+            findings.push({
+                severity: "error",
+                code: "delta.invalid",
+                message: `delta.likec4 has ${res.errors.length} error(s)`,
+                details: res.errors.map(errorText),
+            });
+        }
+        else {
+            elements = res.elements;
+            deltaRels = res.relationships;
+            taggedEls = res.elements.filter((e) => e.tags.includes(featureId));
+            taggedRels = res.relationships.filter((r) => r.tags.includes(featureId));
+            findings.push({
+                severity: "ok",
+                code: "delta.valid",
+                message: `delta.likec4 valid (${res.elements.length} elements · ${res.relationships.length} relationships)`,
+            });
+        }
+    }
+    findings.push(...(await featureProvenance(featureDir, featureId)));
+    // Who this feature is allowed to address. `specs/<svc>/` is what the archive
+    // materialises `services/<svc>/` from, and nothing used to ask whether that
+    // name means anything: one wrong character in `--touches` passed
+    // `validate --all` with zero errors, and archive then created the phantom
+    // directory. A delta may legitimately name a service that does not exist yet
+    // — but only one it INTRODUCES itself, in its own tagged C4. A delta that did
+    // not parse proves neither (`delta.invalid` is that finding), so the question
+    // is suspended there rather than answered by guessing.
+    //
+    // `services/<svc>/` is asked for directly rather than through the
+    // enumeration: `validate --feature` is allowed to run in a docs repo with no
+    // services/ at all (repo.ts takes the same position), where enumerating is a
+    // refusal, not an answer.
+    const featureServices = await featureSpecServices(featureDir, fleet);
+    const introduces = new Set(taggedEls.map(elementService));
+    const deltaReadable = deltaDoc === undefined || deltaDoc.errors.length === 0;
+    const unknownServices = deltaReadable
+        ? featureServices.filter((svc) => !existsSync(servicePaths(docsDir, svc).dir) && !introduces.has(svc))
+        : [];
+    // The near-miss hint, on the same rule `service.unknown` uses — a typo is
+    // only diagnosable against the ids that DO exist.
+    const closeTo = unknownServices.length > 0 && docsRepoState(docsDir).kind === "ok"
+        ? (await listServices(docsDir, fleet)).map((s) => s.id)
+        : [];
+    for (const svc of unknownServices) {
+        const close = closeIds(svc, closeTo);
+        findings.push({
+            severity: "error",
+            code: "delta.service-unknown",
+            subject: svc,
+            message: `specs/${svc}/ addresses a service that does not exist: there is no services/${svc}/ and this feature's ` +
+                `delta.likec4 does not introduce one — archiving would create it out of the typo.` +
+                (close.length > 0 ? ` Did you mean: ${close.join(", ")}?` : " `loam list services` shows what exists."),
+        });
+    }
+    // Requirement coverage across every per-service delta — the business spec and
+    // the arch spec through the same check — and collect scenario text.
+    let scenarioText = "";
+    const archDeltas = [];
+    for (const svc of featureServices) {
+        const p = featureSpecPaths(featureDir, svc);
+        if (existsSync(p.spec)) {
+            const raw = fleet === undefined ? await readFile(p.spec, "utf8") : await fleet.readText(p.spec);
+            scenarioText += "\n" + raw.toLowerCase();
+            const reqs = fleet === undefined ? parseRequirements(raw) : await fleet.readRequirements(p.spec);
+            // Both document-level breaches carry into the living spec through the
+            // merge, so a delta is graded for them exactly as a living document is:
+            // conflict markers merge as prose under someone's requirement, and a
+            // stepless scenario merges as a requirement the coverage rule calls
+            // covered forever after.
+            const conflict = documentConflictFinding(`${svc}: spec.md`, svc, raw);
+            if (conflict !== null)
+                findings.push(conflict);
+            findings.push({ ...coverageFinding(`${svc}: requirements`, reqs), subject: svc });
+            findings.push(...steplessFindings(`${svc}: requirements`, svc, reqs));
+            // The keep-last quirk loses lines in a delta exactly as in a living spec
+            // — and a delta's lost Operations: line then merges into the living one.
+            findings.push(...repeatedListLineFindings(reqs, `${svc}: spec.md`, svc));
+        }
+        if (existsSync(p.archSpec)) {
+            const raw = fleet === undefined ? await readFile(p.archSpec, "utf8") : await fleet.readText(p.archSpec);
+            scenarioText += "\n" + raw.toLowerCase();
+            const reqs = fleet === undefined ? parseRequirements(raw) : await fleet.readRequirements(p.archSpec);
+            archDeltas.push({ service: svc, reqs });
+            const conflict = documentConflictFinding(`${svc}: arch.spec.md`, svc, raw);
+            if (conflict !== null)
+                findings.push(conflict);
+            findings.push({ ...coverageFinding(`${svc}: arch requirements`, reqs), subject: svc });
+            findings.push(...steplessFindings(`${svc}: arch requirements`, svc, reqs));
+            findings.push(...repeatedListLineFindings(reqs, `${svc}: arch.spec.md`, svc));
+        }
+    }
+    // Arch-edge coverage (heuristic, warn-only): each new tagged edge should be named by a scenario.
+    for (const r of taggedRels) {
+        const target = serviceOf(elements, r.target);
+        const covered = edgeCovered(target, r.title, scenarioText);
+        findings.push({
+            severity: covered ? "ok" : "warn",
+            code: covered ? "archedge.covered" : "archedge.uncovered",
+            subject: target,
+            message: `${serviceOf(elements, r.source)} → ${target}  "${r.title ?? ""}"${covered ? "" : "  — no scenario names it"}`,
+            text: { indent: 4, header: "arch-edge coverage (heuristic):" },
+        });
+    }
+    // The architecture spec axis, feature scope — the mechanical counterpart of
+    // the heuristic above. Every NEW tagged element and edge in the delta wants a
+    // `Covers:` line in one of the feature's arch.spec.md deltas (c4.uncovered):
+    // this is where agent-built code cuts its corners — the outbox, the retries,
+    // the alerts — because no business scenario was ever going to mention them.
+    // Grouping-only elements follow the landscape checks' exemptions (person
+    // kinds, #external). Warnings, never archive gates; `--strict` escalates.
+    //
+    // Only requirements the archive will MERGE grant coverage here. In a delta,
+    // BASE means "the living state, quoted": it merges nothing, emits no
+    // .feature, and yields no scenario.tested claim — so a Covers: line under a
+    // plain `## Requirements` quote is an obligation that ships nowhere, and
+    // counting it silenced c4.uncovered for free. (The service-scope pass keeps
+    // the unfiltered call: a LIVING spec is legitimately all BASE.)
+    const activeCovers = archDeltas.flatMap(({ reqs }) => coversEntries(reqs.filter((r) => r.kind === "ADDED" || r.kind === "MODIFIED")));
+    // What the living landscape ALREADY holds. A delta has to re-declare the
+    // elements its new edges attach to, and authors tag those re-declarations
+    // along with everything else — so a requirements-only feature that touches an
+    // existing service was told to write `Covers:` lines for architecture it is
+    // not adding. c4.uncovered is an obligation on NEW architecture; an element
+    // the living landscape already resolves is not new, whatever the tag says.
+    // Loaded lazily: a delta with nothing tagged never pays for the parse.
+    let living = preloadedLand;
+    const livingLandscape = async () => {
+        if (living === undefined) {
+            const lp = landscapeFile(docsDir);
+            living = existsSync(lp)
+                ? fleet === undefined
+                    ? await loadFile(lp)
+                    : await fleet.loadLikeC4(lp)
+                : null;
+        }
+        return living;
+    };
+    const alreadyLiving = async () => {
+        if (taggedEls.length === 0 && taggedRels.length === 0)
+            return null;
+        const doc = await livingLandscape();
+        return doc !== null && doc.errors.length === 0 ? doc : null;
+    };
+    const base = await alreadyLiving();
+    const baseSvcOf = base === null ? null : serviceResolver(base.elements);
+    const baseIds = new Set(base?.elements.map((e) => e.id) ?? []);
+    const baseServices = new Set((base?.elements ?? []).map(elementService));
+    // How a service→service pair is keyed, spelled ONCE. The two sides used to
+    // join with different separators — a NUL where the set was built, a space
+    // where it was queried — so the exemption never matched anything, and every
+    // edge a delta re-declares verbatim (which it must, to attach anything to
+    // it) was reported as new architecture nobody covers. The join is structural
+    // rather than a separator character: the last one was a NUL, and a raw NUL in
+    // a template literal makes the source read as binary to `file` and invisible
+    // to `grep` — which is how a one-character mismatch survived review.
+    const edgeKey = (source, target) => JSON.stringify([source, target]);
+    const baseEdges = new Set((base?.relationships ?? []).map((r) => edgeKey(baseSvcOf(r.source), baseSvcOf(r.target))));
+    for (const e of taggedEls) {
+        if (ACTOR_KINDS.has(e.kind.toLowerCase()) || e.tags.includes(EXTERNAL_TAG))
+            continue;
+        if (baseIds.has(e.id) || baseServices.has(elementService(e)))
+            continue;
+        if (activeCovers.some((c) => coversElement(c, e)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: elementService(e),
+            message: `delta adds '${e.title}' (${e.id}) but no arch requirement covers it — add 'Covers: ${e.id}' to a specs/<svc>/arch.spec.md delta, or its architectural obligations ship unchecked`,
+        });
+    }
+    for (const r of taggedRels) {
+        if (baseEdges.has(edgeKey(serviceOf(elements, r.source), serviceOf(elements, r.target))))
+            continue;
+        if (activeCovers.some((c) => coversEdge(c, r, elements)))
+            continue;
+        findings.push({
+            severity: "warn",
+            code: "c4.uncovered",
+            subject: serviceOf(elements, r.target),
+            message: `delta adds edge ${serviceOf(elements, r.source)} → ${serviceOf(elements, r.target)} ("${r.title ?? ""}") but no arch requirement covers it — add 'Covers: ${r.source} -> ${r.target}' to a specs/<svc>/arch.spec.md delta`,
+        });
+    }
+    // covers.unknown, feature scope. Resolution looks at the delta itself, the
+    // living landscape, the service's own model and its health.yaml — a delta's
+    // arch requirement may cover an element it adds, one that already exists, or
+    // an alert the service declares. The landscape and each model are loaded
+    // lazily, and only when an entry fails against what is already in hand: the
+    // clean path never pays for a workspace spin.
+    if (archDeltas.some(({ reqs }) => coversEntries(reqs).length > 0)) {
+        const land = await livingLandscape();
+        const landParses = land !== null && land.errors.length === 0 ? land : null;
+        const baseElements = [...elements, ...(landParses?.elements ?? [])];
+        const baseRels = [...deltaRels, ...(landParses?.relationships ?? [])];
+        for (const { service: svc, reqs } of archDeltas) {
+            // An unreadable living health.yaml mutes the alert:/sli: entries here
+            // exactly as in service scope — the health.invalid finding itself
+            // belongs to the service target, which owns the file's diagnosis.
+            const health = await readHealth(servicePaths(docsDir, svc).health);
+            let scope = { elements: baseElements, relationships: baseRels, health: health.ids };
+            const unresolved = coversUnknownFindings(reqs, `${svc}: arch.spec.md`, svc, scope, health.unreadable);
+            if (unresolved.length > 0) {
+                const modelPath = servicePaths(docsDir, svc).model;
+                const model = existsSync(modelPath)
+                    ? fleet === undefined
+                        ? await loadFile(modelPath)
+                        : await fleet.loadLikeC4(modelPath)
+                    : null;
+                if (model !== null && model.errors.length === 0) {
+                    scope = {
+                        elements: [...baseElements, ...model.elements],
+                        relationships: [...baseRels, ...model.relationships],
+                        health: health.ids,
+                    };
+                }
+                findings.push(...coversUnknownFindings(reqs, `${svc}: arch.spec.md`, svc, scope, health.unreadable));
+            }
+        }
+    }
+    // Coherence — cross-axis consistency (C4 ↔ requirements ↔ OpenAPI).
+    const issues = await featureCoherence(docsDir, featureDir, featureId, deltaDoc, fleet);
+    if (issues.length === 0) {
+        findings.push({
+            severity: "ok",
+            code: "coherence.ok",
+            message: "coherence: ✓ C4 · requirements · OpenAPI agree",
+            text: { indent: 2, marker: false },
+        });
+    }
+    else {
+        for (const i of issues) {
+            findings.push({
+                severity: i.severity,
+                code: i.code,
+                gates: gatesArchive(i),
+                ...(i.subject === undefined ? {} : { subject: i.subject }),
+                message: i.message,
+                text: { indent: 4, header: "coherence:" },
+            });
+        }
+    }
+    return { kind: "feature", id: featureId, findings };
+}
+function coverageFinding(label, reqs) {
+    const missing = requirementsMissingScenarios(reqs);
+    if (missing.length === 0) {
+        return {
+            severity: "ok",
+            code: "requirements.covered",
+            message: `${label} covered (${reqs.length} requirement${reqs.length === 1 ? "" : "s"}, all with scenarios)`,
+        };
+    }
+    return {
+        severity: "error",
+        code: "requirements.missing-scenarios",
+        message: `${label}: ${missing.length} requirement(s) without a scenario`,
+        details: missing.map((r) => r.name),
+        text: { detailPrefix: "- " },
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Text renderer                                                       */
+/* ------------------------------------------------------------------ */
+const MARKER = { ok: "✓", warn: "⚠", error: "✗" };
+/**
+ * `--errors-only` is a RENDERING lever, the way `--strict` is an exit-code
+ * lever: neither changes the report, and the `--json` payload is unaffected by
+ * both. On a fleet of a hundred services the clean run prints several hundred
+ * `ok` confirmations, and the two warnings that matter are somewhere inside it;
+ * anyone reading a CI log wants the exceptions, and anyone auditing wants all
+ * of it. Both are available, from the same run, and neither is the default.
+ */
+function renderText(targets, all, unverifiable, errorsOnly) {
+    for (const t of targets) {
+        const shown = errorsOnly ? t.findings.filter((f) => f.severity !== "ok") : t.findings;
+        if (shown.length === 0)
+            continue;
+        // A feature announces itself; a service's findings already carry its name.
+        if (t.kind === "feature")
+            console.log(t.id);
+        let header;
+        for (const f of shown) {
+            const hint = f.text ?? {};
+            if (hint.header && hint.header !== header) {
+                header = hint.header;
+                console.log(`  ${header}`);
+            }
+            // The whole report goes to stdout, in document order. Splitting errors
+            // onto stderr meant a piped stdout silently lost them from the middle of
+            // the report and 2>&1 could reorder it; the exit code carries failure,
+            // and stderr stays reserved for refusals (the fail() path).
+            const marker = hint.marker === false ? "" : `${MARKER[f.severity]} `;
+            console.log(`${" ".repeat(hint.indent ?? 0)}${marker}${f.message}`);
+            for (const d of f.details ?? [])
+                console.log(`    ${hint.detailPrefix ?? ""}${d}`);
+        }
+    }
+    if (!all) {
+        // Without the --all footer there would be nothing at all to print for a
+        // clean single target under --errors-only — and silence is the one output
+        // that must never mean "checked, fine".
+        if (errorsOnly && targets.every((t) => t.findings.every((f) => f.severity === "ok"))) {
+            console.log(`${targets.map((t) => t.id).join(", ")}: no errors or warnings`);
+        }
+        return;
+    }
+    const s = summary(targets);
+    const plural = (n, noun) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+    console.log(`\n${plural(s.services, "service")}, ${plural(s.features, "feature")} — ` +
+        `${plural(s.errors, "error")}, ${plural(s.warnings, "warning")}`);
+    // One line for the whole fleet, never one per service: honest about the blind
+    // spot without drowning the report in a hundred copies of it.
+    if (unverifiable > 0) {
+        const whose = unverifiable === 1 ? "1 service's" : `${unverifiable} services'`;
+        console.log(`⚠ sources.unverifiable-from-here: ${whose} sources can only be checked from their own repos`);
+    }
+}
+/* ------------------------------------------------------------------ */
+/**
+ * The two things a `sources` list can be that `serviceProvenance` cannot say.
+ *
+ * `sources.unverifiable-from-here` — the spec names sources and loam is NOT in
+ * that service's repository, so every sources check (existence, digest,
+ * staleness) is skipped. serviceProvenance returns an empty list in that case
+ * and the silence read as "checked and fine". It used to be counted only under
+ * `--all` and printed as one rollup line, which meant `validate --service X`
+ * run from the docs repo — the single most common way anyone looks at one
+ * service — reported nothing at all about its own blind spot. Severity `ok`,
+ * deliberately: nothing is WRONG with the docs, the check simply cannot run
+ * here, and grading it a warning would make a correctly-adopted fleet
+ * permanently yellow and `--strict` permanently red in the docs repo's CI.
+ *
+ * `sources.empty` — the paths exist, and expand to no files at all: an empty
+ * directory, or a tree the repository itself ignores. A digest over nothing
+ * never changes, so the stamp would read as current forever. `loam vouch`
+ * already refuses to stamp it; until now `validate` said nothing, so an author
+ * got a green run followed by a refusal, two commands contradicting each other
+ * about one document. The sentence comes from `emptySourcesMessage`, the same
+ * definition vouch refuses with, under the label vouch uses.
+ */
+async function sourceScopeFindings(docsDir, service, repoDir) {
+    const paths = servicePaths(docsDir, service);
+    const out = [];
+    for (const { path, file } of [
+        { path: paths.spec, file: "spec.md" },
+        { path: paths.archSpec, file: "arch.spec.md" },
+    ]) {
+        if (!existsSync(path))
+            continue;
+        const sources = listField(await readFrontmatter(path), "sources");
+        if (sources.length === 0)
+            continue;
+        // vouch's own labelling: a bare service id for spec.md, qualified for the
+        // arch axis. The refusal and the finding must be the same sentence.
+        const label = file === "spec.md" ? service : `${service}: ${file}`;
+        if (repoDir === undefined) {
+            out.push({
+                severity: "ok",
+                code: UNVERIFIABLE,
+                subject: service,
+                message: `${label}: ${sources.length} source(s) declared, but this is not ${service}'s repository — nothing here can resolve them. Run \`loam validate --service ${service}\` from inside it.`,
+            });
+            continue;
+        }
+        // Every other shape of broken list is serviceProvenance's to grade, and
+        // grading them twice would send an author fixing one thing from two
+        // findings. "Covers no files" is only meaningful once the paths are real.
+        if (patternSources(sources).length > 0 ||
+            unsafeSources(repoDir, sources).length > 0 ||
+            missingSources(repoDir, sources).length > 0) {
+            continue;
+        }
+        const expansion = await expandSourceFiles(repoDir, sources, label);
+        if (expansion.files.length > 0)
+            continue;
+        out.push({
+            severity: "warn",
+            code: "sources.empty",
+            subject: service,
+            message: expansion.empty ?? emptySourcesMessage(label, sources),
+        });
+    }
+    return out;
+}
+/** Heuristic: an edge is "covered" if a scenario names the target or a keyword from the edge title. */
+function edgeCovered(target, title, scenarioText) {
+    if (scenarioText.includes(target.toLowerCase()))
+        return true;
+    for (const token of (title ?? "").split(/[^A-Za-z0-9]+/)) {
+        if (token.length >= 5 && scenarioText.includes(token.toLowerCase()))
+            return true;
+    }
+    return false;
+}
+function errorText(e) {
+    return typeof e.line === "number" ? `L${e.line}: ${e.message}` : e.message;
+}
+export { targetValid };
+//# sourceMappingURL=validate.js.map