@sdd-method/maintain-cli 0.10.0 → 0.12.0

package/dist/lib/behaviour-store/archive.js

@@ -204,4 +204,17 @@ export function surfaceMatches(entry, contractId, specPath) {
     const re = new RegExp(`(^|/)${e.split("*").map((p) => p.replace(/[.+?^${}()|[\]\\]/g, "\\$&")).join("[^/]*")}$`);
     return re.test(specPath.split("\\").join("/"));
 }
+/**
+ * The delta entries a work order's `implements` entry names (schema 5.0.0). `<feature>::<name>` names exactly one
+ * requirement. A bare name resolves only when one feature in the change has a requirement of that name; across
+ * two features it is ambiguous, and names none.
+ */
+export function resolveImplements(delta, entry) {
+    const q = /^(.+?)::(.+)$/.exec(entry);
+    if (q)
+        return { matches: delta.filter((d) => d.feature === q[1] && d.name === q[2]), ambiguous: [] };
+    const matches = delta.filter((d) => d.name === entry);
+    const features = [...new Set(matches.map((d) => d.feature))];
+    return features.length > 1 ? { matches: [], ambiguous: features } : { matches, ambiguous: [] };
+}
 //# sourceMappingURL=archive.js.map

package/dist/lib/catalogue/aggregate.js

@@ -40,6 +40,7 @@ import { buildCapabilitySpec } from "./builders/capability-spec.js";
 import { buildFeatureGrounding } from "./builders/feature-grounding.js";
 import { loadFeatureGroundingAliases } from "./feature-grounding-aliases-loader.js";
 import { buildFeatureContract } from "./builders/feature-contract.js";
+import { buildJourneyRequirement } from "./builders/journey-requirement.js";
 import { buildCapabilityEvent } from "./builders/event-edges.js";
 import { discoverVocabulary } from "./application-archetype/vocabulary.js";
 import { checkDataPlaneOverlayAtAggregation } from "./application-archetype/expectations.js";
@@ -342,6 +343,67 @@ export async function runCatalogueAggregate(inputs, write) {
             findings.add("coverage", `feature_repo: ${added} row(s) re-derived at aggregate tier for features that had NO anchor at member tier — evidence tokens naming a repo registered by another contributor resolve only against the merged repositories; already-anchored features are not widened (M-ADR 0198 §4.1 as amended; ${contributors.length} contributor doc trees scanned)`);
         }
     }
+    // M-ADR 0229 §4.4 (Proposed): journey_requirement re-derived over the merged rows. A journey is often catalogued
+    // in an application SDD and the requirements its steps cite in the platform's behaviour store, so neither member
+    // holds both join inputs; each reports the tag as external. Each contributor's tagged end-to-end files (its own
+    // manifest's journeys.test_paths) and its journey features' living specs are read again here against the MERGED
+    // features, requirements and journeys. Fills absences only (rederiveAppend). A tag naming another contributor's
+    // feature that the merged rows still do not resolve is reported here; everything the member build already reported
+    // (its own features' tags, its test paths, its files' journey tags and journey specs) is not repeated.
+    {
+        const contributors = [{ sddPath, sddId: rootManifest.sddId }];
+        for (const sib of aggManifest.siblings) {
+            if (sib.level === "organisation")
+                continue;
+            if (crossCheck.siblingProfiles.get(sib.sddId) === undefined)
+                continue;
+            contributors.push({ sddPath: sib.sddRoot, sddId: sib.sddId });
+        }
+        const merged = {
+            features: rowsByCatalogue.get("features") ?? [],
+            requirements: rowsByCatalogue.get("requirements") ?? [],
+            knownJourneyIds: new Set((rowsByCatalogue.get("user_journeys") ?? []).map((r) => String(r["id"]))),
+        };
+        const rederived = [];
+        const seen = new Set();
+        const unresolved = [];
+        for (const c of contributors) {
+            let testPaths = [];
+            try {
+                testPaths = (await loadSddManifest(c.sddPath, { cliVersion: CLI_VERSION })).journeys?.testPaths ?? [];
+            }
+            catch {
+                // the member's own build reports an unreadable manifest
+            }
+            const scratch = new FindingsLog();
+            // The contributor's own features: its member build already reported on tags naming them.
+            const reportedFeatureIds = new Set(merged.features.filter((f) => String(f["source_sdd_id"] ?? "") === c.sddId).map((f) => String(f["id"])));
+            for (const row of await buildJourneyRequirement({ sddPath: c.sddPath, findings: scratch, testPaths, reportedFeatureIds, ...merged })) {
+                const id = String(row["id"]);
+                if (seen.has(id))
+                    continue;
+                seen.add(id);
+                rederived.push({ ...row, source_sdd_id: c.sddId });
+            }
+            // Still external against the merged rows: unresolved. An orphan or divergence about another contributor's feature
+            // (a tag naming a platform requirement that does not exist, or that two of its requirements share) was invisible
+            // to the member build, so it is reported here.
+            for (const f of scratch.all()) {
+                if (f.category === "external")
+                    unresolved.push(`${c.sddId}: ${f.summary.replace(/; resolves at aggregation.*$/, "")}`);
+                else if (f.category === "orphan" || f.category === "divergence")
+                    unresolved.push(`${c.sddId}: ${f.summary}`);
+            }
+        }
+        const before = (rowsByCatalogue.get("journey_requirement") ?? []).length;
+        rederiveAppend(rowsByCatalogue, "journey_requirement", rederived);
+        const added = (rowsByCatalogue.get("journey_requirement") ?? []).length - before;
+        if (added > 0) {
+            findings.add("coverage", `journey_requirement: ${added} row(s) derived at aggregate tier, where a journey and the requirements it cites are catalogued in different SDDs (M-ADR 0229 §4.4, Proposed; ${contributors.length} contributor(s) read)`);
+        }
+        for (const u of unresolved)
+            findings.add("orphan", `journey_requirement: unresolved against the merged catalogue: ${u}`);
+    }
     const repoEdges = buildRepoEdges({
         findings,
         configs: [],

package/dist/lib/catalogue/build.js

@@ -35,6 +35,7 @@ import { buildDataItems, buildFeatureDemand, buildIntegrationSupply } from "./bu
 import { buildEvidenceTargetRepos } from "./builders/evidence-target-repo.js";
 import { buildRepoDependencies } from "./builders/repo-dependency.js";
 import { buildRequirements } from "./builders/requirements.js";
+import { buildJourneyRequirement } from "./builders/journey-requirement.js";
 import { buildDomains, buildProducts, buildApplicationDataPlaneBindings, buildApplicationDataPlaneDeviations, buildApplicationConformanceCoverage, buildImplementations, buildRepositories, buildServices, buildCapabilities, buildCapabilityService, buildCapabilityAdr, buildCapabilityFeature, buildCapabilityContract, buildAdrs, buildAdrSupersedes, buildFeatures, buildFeatureGroups, buildFeatureGrounding, buildCapabilitySpec, buildContracts, buildDeclaredExternalContracts, buildRepoEdges, deriveFeatureRepoFromServices, buildRepoCapabilityExemption, buildServiceCapabilityExemption, buildEvents, buildServiceEvent, buildCapabilityEvent, buildFeatureEvent, buildServiceContract, buildServiceContractConsumes, buildFeatureContract, buildDomainModels, buildCapabilityDomainModel, buildFeatureDomainModel, buildFeatureSubscriptionChannels, buildProductPlatformDependencies, buildGlossaryItems, backfillGlossaryRelations, buildGlossaryXref, buildC4Systems, buildC4Containers, buildC4Components, buildC4ExternalSystems, buildExternalSystemExemption, buildContainerDependency, reportEntryIdReferentCollisions, buildSystemExternalDependency, buildPersonaC4System, buildPersonaContainer, buildPersonas, buildQualityScores, buildScaffolds, buildScreens, buildUserJourneys, buildPersonaJourney, buildPersonaFeature, buildJourneyFeature, buildProductEdges, buildIntegrations, entitySlug, buildEntitiesFromManifest, buildEntitiesFromMermaid, buildServiceEntityFromTables, enrichEntityPersistenceKind, buildC4ContainerEntity, buildC4SystemEntity, } from "./builders/index.js";
 import { buildIntegrationComponents } from "./builders/integration-components.js";
 import { loadReverseProductQuality } from "./reverse-product-quality.js";
@@ -1163,6 +1164,7 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
             findings,
             knownFeatureIds: new Set((out.get("features") ?? []).map((row) => String(row["id"]))),
             knownRepoIds: knownRepoIdsFinal,
+            sddId: manifest.sddId,
         });
         out.set("requirements", r.requirements);
         out.set("requirement_lineage", r.lineage);
@@ -1170,6 +1172,16 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
         out.set("changes", r.changes);
         out.set("change_work_order", r.workOrders);
         out.set("change_work_item", r.workItems);
+        // M-ADR 0229 §4.4 (Proposed): the requirements each journey cites, from its tagged end-to-end files or its
+        // journey feature's living spec.
+        out.set("journey_requirement", await buildJourneyRequirement({
+            sddPath,
+            findings,
+            testPaths: manifest.journeys?.testPaths ?? [],
+            features: out.get("features") ?? [],
+            requirements: r.requirements,
+            knownJourneyIds: new Set((out.get("user_journeys") ?? []).map((row) => String(row["id"]))),
+        }));
     }
     // 15. C4 systems + containers + components (L1 + L2 + L3). The L3 walker
     // is the forward-method authoring path reading

package/dist/lib/catalogue/builders/capability-spec.js

@@ -133,6 +133,7 @@ export async function buildCapabilitySpec(inputs) {
                     status: "active",
                     source: "capability-spec",
                     runway: "",
+                    kind: "feature",
                     source_sdd_id: "",
                 });
             }

package/dist/lib/catalogue/builders/feature-grounding.js

@@ -153,6 +153,7 @@ export async function buildFeatureGrounding(inputs) {
                     status: "active",
                     source: "feature-grounding",
                     runway: "",
+                    kind: "feature",
                     source_sdd_id: "",
                 });
                 const cfId = `${capabilityId}__${featureId}`;

package/dist/lib/catalogue/builders/features.js

@@ -89,9 +89,10 @@ export async function buildFeatures(inputs) {
             parent_feature_id: "",
             description,
             maturity: "",
-            status: "active",
+            status: featureStatus(text),
             source: "feature-spec",
             runway: "",
+            kind: featureKind(text),
             source_sdd_id: "",
         });
         idByPath.set(relPath, id);
@@ -123,9 +124,10 @@ export async function buildFeatures(inputs) {
                 parent_feature_id: "",
                 description,
                 maturity: "",
-                status: "active",
+                status: featureStatus(text),
                 source: "feature-spec",
                 runway: "",
+                kind: featureKind(text),
                 source_sdd_id: "",
             });
             idByPath.set(relPath, id);
@@ -145,6 +147,24 @@ export async function buildFeatures(inputs) {
     }
     return { rows, idByPath, idBySlug };
 }
+/**
+ * A feature spec's catalogue status: `retired` when the spec says `**Status:** retired` (its behaviour retired by
+ * an archived change, the feature kept in the catalogue so its retired requirements still resolve), else
+ * `active`. A retired feature stays where it is; it does not have to move to withdrawn/ first.
+ */
+export function featureStatus(text) {
+    const m = /^\*\*Status:\*\*\s*([A-Za-z-]+)/m.exec(text) ?? /^>.*\bStatus:\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() === "retired" ? "retired" : "active";
+}
+/**
+ * A feature spec's kind (schema 4.4.0): the value of its `**Kind:**` line, lower-cased, else `feature`. An
+ * obligation (M-ADR 0226, Proposed) and a journey feature (M-ADR 0229 §4.2, Proposed) say so; any other value is written as given, so
+ * the catalogue's vocabulary gate names the spec rather than a default hiding the mistake.
+ */
+export function featureKind(text) {
+    const m = /^\*\*Kind:\*\*\s*([A-Za-z-]+)/m.exec(text);
+    return m?.[1]?.toLowerCase() ?? "feature";
+}
 async function emitBulletRows(ctx) {
     const featureTreePath = await findFeatureTreeFile(ctx.sddPath);
     if (!featureTreePath)
@@ -188,6 +208,7 @@ async function emitBulletRows(ctx) {
             status: "active",
             source: "feature-tree",
             runway: ev.runway,
+            kind: "feature",
             source_sdd_id: "",
         });
         if (!ctx.idBySlug.has(ev.slug))

package/dist/lib/catalogue/builders/journey-requirement.js

@@ -0,0 +1,144 @@
+// journey_requirement: the requirements a user journey cites for its steps (M-ADR 0229 §4.4, Proposed; schema 4.4.0).
+//
+// Derived, never authored, from either master (§4.2):
+//   tag       option A: the end-to-end `.feature` files under the manifest's `journeys.test_paths`. A file tagged
+//             `@journey:<journey-id>` cites every `@req:<feature-id>/<requirement-slug>` tag it carries.
+//   citation  option B: the living spec (openspec/specs/<feature-id>/spec.md) of a feature of kind journey names its
+//             journey with the same `@journey:<journey-id>` tag and cites each step's requirement with `@req:`.
+// One tag grammar for both, so the derivation needs only the files and the catalogue's rows. Both are read whenever
+// present, so an estate moving from A to B shows both while it moves.
+//
+// A requirement tag cannot carry spaces, so it names the requirement by slug: its name lower-cased, each run of
+// anything but a-z and 0-9 turned into one hyphen. A tag resolves when exactly one requirement of that feature,
+// living or agreed (not retired), has that slug; a tag naming a retired requirement names none, so it is a finding. A tag that resolves to none or to several, a file with two journey tags, or a test
+// path that does not exist is a finding and produces no row, so no foreign key dangles. A tag naming a feature or a
+// journey this catalogue does not hold is reported as external: journeys are often catalogued in application SDDs
+// and requirements in the platform's store, so the row is derived at aggregation, where both are merged
+// (catalogue aggregate re-runs this builder over each contributor). A journey with no row is untraced, which the
+// journey-impact check reports.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative } from "node:path";
+const REQ_TAG = /@req:([a-z0-9][a-z0-9-]*)\/([a-z0-9][a-z0-9-]*)/g;
+const JOURNEY_TAG = /@journey:([a-z0-9][a-z0-9-]*)/g;
+/** "Order shipped (REST)" -> "order-shipped-rest". */
+export function requirementSlug(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+async function featureFiles(dir) {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (e.name === "node_modules" || e.name.startsWith("."))
+            continue;
+        const p = join(dir, e.name);
+        if (e.isDirectory())
+            out.push(...(await featureFiles(p)));
+        else if (e.isFile() && e.name.endsWith(".feature"))
+            out.push(p);
+    }
+    return out.sort();
+}
+export async function buildJourneyRequirement(inputs) {
+    // At aggregation the member builds have already reported every finding about their own files and features.
+    const atAggregate = inputs.reportedFeatureIds !== undefined;
+    const { sddPath, findings } = inputs;
+    const bySlug = new Map();
+    for (const r of inputs.requirements) {
+        if (String(r["stage"] ?? "") === "retired")
+            continue; // a journey step cannot rely on behaviour that has been removed
+        const key = `${String(r["feature_id"])}/${requirementSlug(String(r["name"]))}`;
+        const ids = bySlug.get(key) ?? [];
+        if (!ids.includes(String(r["id"])))
+            ids.push(String(r["id"]));
+        bySlug.set(key, ids);
+    }
+    const rows = new Map();
+    const knownFeatures = new Set(inputs.features.map((f) => String(f["id"])));
+    const cite = (journeyId, text, where, basis) => {
+        for (const m of text.matchAll(REQ_TAG)) {
+            const quiet = atAggregate && inputs.reportedFeatureIds.has(m[1]);
+            if (!knownFeatures.has(m[1])) {
+                findings.add("external", `${where}: @req:${m[1]}/${m[2]} names a feature this catalogue does not hold; resolves at aggregation (M-ADR 0229 §4.4, Proposed)`);
+                continue;
+            }
+            const ids = bySlug.get(`${m[1]}/${m[2]}`) ?? [];
+            if (ids.length !== 1) {
+                if (!quiet)
+                    findings.add("orphan", `${where}: @req:${m[1]}/${m[2]} ${ids.length === 0 ? "names no requirement of that feature" : `matches ${ids.length} requirements of that feature`}; no journey_requirement row (M-ADR 0229 §4.4, Proposed)`);
+                continue;
+            }
+            const id = `${journeyId}__${ids[0]}`;
+            if (!rows.has(id))
+                rows.set(id, { id, journey_id: journeyId, requirement_id: ids[0], basis, source_sdd_id: "", platform_sdd_id: "" });
+        }
+    };
+    // Option A: tagged end-to-end files.
+    for (const rel of inputs.testPaths) {
+        const dir = join(sddPath, rel);
+        const exists = await stat(dir).then((s) => s.isDirectory(), () => false);
+        if (!exists) {
+            if (!atAggregate)
+                findings.add("orphan", `.sdd/sdd-manifest.yaml: journeys.test_paths names ${rel}, which is not a directory in this SDD`);
+            continue;
+        }
+        for (const file of await featureFiles(dir)) {
+            const where = relative(sddPath, file);
+            const text = await readFile(file, "utf8");
+            const journeys = [...new Set([...text.matchAll(JOURNEY_TAG)].map((m) => m[1]))];
+            if (journeys.length === 0)
+                continue;
+            if (journeys.length > 1) {
+                if (!atAggregate)
+                    findings.add("divergence", `${where}: tagged with ${journeys.length} journeys (${journeys.join(", ")}); one file is one journey's master (M-ADR 0229 §4.2, Proposed)`);
+                continue;
+            }
+            const journeyId = journeys[0];
+            if (!inputs.knownJourneyIds.has(journeyId)) {
+                findings.add("external", `${where}: @journey:${journeyId} is not a user journey this catalogue holds; resolves at aggregation`);
+                continue;
+            }
+            cite(journeyId, text, where, "tag");
+        }
+    }
+    // Option B: journey features in the store, each naming its journey in its living spec.
+    const kindById = new Map(inputs.features.map((f) => [String(f["id"]), String(f["kind"] ?? "")]));
+    let specDirs = [];
+    try {
+        specDirs = (await readdir(join(sddPath, "openspec", "specs"), { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        // no store here
+    }
+    for (const featureId of specDirs) {
+        if (kindById.get(featureId) !== "journey")
+            continue;
+        const where = join("openspec", "specs", featureId, "spec.md");
+        let spec;
+        try {
+            spec = await readFile(join(sddPath, where), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const journeys = [...new Set([...spec.matchAll(JOURNEY_TAG)].map((m) => m[1]))];
+        if (journeys.length !== 1) {
+            if (!atAggregate)
+                findings.add(journeys.length === 0 ? "orphan" : "divergence", `${where}: a journey feature's living spec ${journeys.length === 0 ? "names no journey (@journey:<journey-id>)" : `names ${journeys.length} journeys`}; one journey feature masters one journey (M-ADR 0229 §4.2, Proposed)`);
+            continue;
+        }
+        const journeyId = journeys[0];
+        if (!inputs.knownJourneyIds.has(journeyId)) {
+            findings.add("external", `${where}: @journey:${journeyId} is not a user journey this catalogue holds; resolves at aggregation`);
+            continue;
+        }
+        cite(journeyId, spec, where, "citation");
+    }
+    return [...rows.values()].sort((a, b) => String(a["id"]).localeCompare(String(b["id"])));
+}
+//# sourceMappingURL=journey-requirement.js.map

package/dist/lib/catalogue/builders/requirements.js

@@ -7,9 +7,12 @@
 //   requirements        one row per `### Requirement:` in a living spec (stage living), keyed by the spec's
 //                       directory name, which is the catalogue feature id; plus one per requirement an open,
 //                       agreed change ADDS (stage agreed).
-//   requirement_lineage each archived change, in archive order, whose delta ADDED, MODIFIED or RENAMED a
-//                       requirement that is current now, under any name a later RENAMED gave it. A change carrying
+//   requirement_lineage each archived change, in archive order, whose delta ADDED, MODIFIED, RENAMED or REMOVED a
+//                       requirement, under any name a later RENAMED gave it. A change carrying
 //                       baseline-evidence.md is a baseline. Statuses follow renames the same way.
+//                       A requirement REMOVED by an archived change and not in a living spec now is kept in
+//                       requirements as stage retired (schema 4.3.0), so its lineage ends in the REMOVED row;
+//                       it carries no status.
 //   changes             each change in the store, open or archived (M-ADR 0223 §4.2): its directory name, its
 //                       undated name, kind, status (archived, or its agreement record's) and verdict.
 //   change_work_order   per (change, repository): the record's work order, agreed or completed.
@@ -26,8 +29,8 @@
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { observedIn, orderArchives, parseRequirements, renamePairs } from "../../behaviour-store/archive.js";
-export { observedIn, parseRequirements };
+import { observedIn, orderArchives, parseRequirements, renamePairs, resolveImplements } from "../../behaviour-store/archive.js";
+export { observedIn, parseRequirements, resolveImplements };
 const STORE = "openspec";
 const AGREEMENTS = join("docs", "agreements");
 async function isDir(p) {
@@ -125,6 +128,7 @@ export function parseWorkItems(proposal) {
 const rel = (sddPath, p) => p.slice(sddPath.length + 1).split("\\").join("/");
 export async function buildRequirements(inputs) {
     const { sddPath, findings } = inputs;
+    const scoped = (change) => `${inputs.sddId}::${change}`;
     const empty = { requirements: [], lineage: [], status: [], changes: [], workOrders: [], workItems: [] };
     const store = join(sddPath, STORE);
     if (!(await isDir(store)))
@@ -159,8 +163,9 @@ export async function buildRequirements(inputs) {
     const workOrders = [];
     const workItems = [];
     // The change itself, its work orders and its work items (M-ADR 0223 §4.2).
-    const recordChange = async (id, name, kind, status, archivedOn, changeDir, record) => {
+    const recordChange = async (localId, name, kind, status, archivedOn, changeDir, record) => {
         const verdict = record?.verdict?.result === "PASS" || record?.verdict?.result === "FAIL" ? record.verdict.result : "";
+        const id = scoped(localId);
         changes.push({ id, name, change_kind: kind, status, archived_on: archivedOn, verdict, source_sdd_id: "", platform_sdd_id: "" });
         for (const wo of record?.work_orders ?? []) {
             if (!wo.repo)
@@ -174,7 +179,7 @@ export async function buildRequirements(inputs) {
         }
         const proposal = await readText(join(changeDir, "proposal.md"));
         for (const item of proposal === null ? [] : parseWorkItems(proposal)) {
-            workItems.push({ id: `${name}__${item}`, change_id: id, change_name: name, work_item_id: item, source_sdd_id: "", platform_sdd_id: "" });
+            workItems.push({ id: `${scoped(name)}__${item}`, change_id: id, change_name: name, work_item_id: item, source_sdd_id: "", platform_sdd_id: "" });
         }
     };
     const pushEvent = (e) => {
@@ -182,7 +187,8 @@ export async function buildRequirements(inputs) {
             unknownRepos.add(e.repo);
             return;
         }
-        if (requirements.has(e.requirementId))
+        // A retired requirement has no status: it is not where any repository's behaviour is.
+        if (requirements.has(e.requirementId) && requirements.get(e.requirementId)["stage"] !== "retired")
             events.push(e);
     };
     // 2. Archived changes, in archive order. A requirement is named as it was when each change archived, so its
@@ -201,9 +207,13 @@ export async function buildRequirements(inputs) {
         await recordChange(dir, change, kind, "archived", archivedOn, changeDir, await agreementRecord(sddPath, change));
         const delta = await deltaOf(changeDir);
         for (const d of delta) {
-            if (d.operation === "REMOVED")
-                continue;
-            archived.push({ index, feature: d.feature, name: d.name, lineage: { change_id: dir, change_kind: kind, operation: d.operation, archived_on: archivedOn, source_sdd_id: "", platform_sdd_id: "" } });
+            archived.push({
+                index,
+                feature: d.feature,
+                name: d.name,
+                lineage: { change_id: scoped(dir), change_kind: kind, operation: d.operation, archived_on: archivedOn, source_sdd_id: "", platform_sdd_id: "" },
+                ...(d.operation === "REMOVED" ? { removedIn: rel(sddPath, d.file) } : {}),
+            });
         }
         if (evidence !== null) {
             const repos = observedIn(evidence);
@@ -213,7 +223,7 @@ export async function buildRequirements(inputs) {
             for (const repo of repos)
                 for (const d of delta)
                     if (d.operation !== "REMOVED")
-                        archived.push({ index, feature: d.feature, name: d.name, event: { repo, status: "observed", basis: dir } });
+                        archived.push({ index, feature: d.feature, name: d.name, event: { repo, status: "observed", basis: scoped(dir) } });
             continue;
         }
         const record = await agreementRecord(sddPath, change);
@@ -223,12 +233,16 @@ export async function buildRequirements(inputs) {
             if (!wo.repo)
                 continue;
             for (const name of wo.implements ?? []) {
-                const match = delta.filter((d) => d.name === name && d.operation !== "REMOVED");
-                if (match.length === 0) {
+                const { matches, ambiguous } = resolveImplements(delta.filter((d) => d.operation !== "REMOVED"), name);
+                const match = matches;
+                if (ambiguous.length > 0) {
+                    findings.add("divergence", `${AGREEMENTS}/${change}.yaml: work order for ${wo.repo} implements "${name}", a name ${ambiguous.length} features in the change share (${ambiguous.join(", ")}); qualify it as <feature>::<name>. No status is derived from it`);
+                }
+                else if (match.length === 0) {
                     findings.add("convention", `${AGREEMENTS}/${change}.yaml: work order for ${wo.repo} implements "${name}", which the change's delta does not name`);
                 }
                 for (const d of match)
-                    archived.push({ index, feature: d.feature, name: d.name, event: { repo: wo.repo, status: "declared-shipped", basis: dir } });
+                    archived.push({ index, feature: d.feature, name: d.name, event: { repo: wo.repo, status: "declared-shipped", basis: scoped(dir) } });
             }
         }
     }
@@ -240,6 +254,15 @@ export async function buildRequirements(inputs) {
                     n = r.to;
         return `${feature}::${n}`;
     };
+    // A requirement removed and not living now is retired: kept, so its lineage can end in the removal.
+    for (const a of archived) {
+        if (!a.removedIn)
+            continue;
+        const id = current(a.feature, a.name, a.index);
+        if (requirements.has(id) || !known(a.feature))
+            continue;
+        requirements.set(id, { id, feature_id: a.feature, name: id.slice(a.feature.length + 2), stage: "retired", spec_path: a.removedIn, scenario_count: 0, source_sdd_id: "", platform_sdd_id: "" });
+    }
     // One lineage row per (requirement, change): a change that renames and modifies a requirement records MODIFIED,
     // the behaviour change, and its delta still shows the rename.
     const lineageById = new Map();
@@ -278,8 +301,12 @@ export async function buildRequirements(inputs) {
             if (!wo.repo)
                 continue;
             for (const name of wo.implements ?? []) {
-                for (const d of delta.filter((x) => x.name === name && x.operation !== "REMOVED")) {
-                    pushEvent({ requirementId: `${d.feature}::${d.name}`, repo: wo.repo, status: "agreed", basis: dir });
+                const { matches, ambiguous } = resolveImplements(delta.filter((x) => x.operation !== "REMOVED"), name);
+                if (ambiguous.length > 0) {
+                    findings.add("divergence", `${AGREEMENTS}/${dir}.yaml: work order for ${wo.repo} implements "${name}", a name ${ambiguous.length} features in the change share (${ambiguous.join(", ")}); qualify it as <feature>::<name>. No status is derived from it`);
+                }
+                for (const d of matches) {
+                    pushEvent({ requirementId: `${d.feature}::${d.name}`, repo: wo.repo, status: "agreed", basis: scoped(dir) });
                 }
             }
         }