@sdd-method/author-cli 0.9.0 → 0.11.0

package/dist/author-program.js

@@ -47,6 +47,7 @@ export const AUTHOR_ONLY_SURFACE = [
     "context pull",
     "catalogue check",
     "migrate vocabulary",
+    "migrate intents",
 ];
 /** The full surface: verify's, plus the author's own. */
 export const AUTHOR_SURFACE = [...VERIFY_SURFACE, ...AUTHOR_ONLY_SURFACE];

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/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) });
                 }
             }
         }

package/dist/lib/catalogue/canonical-schema.yaml

@@ -7,7 +7,7 @@
 # Emitted by sdd-cli's YAML emitter with no line folding; the three header scalars are quoted for the
 # textual readers downstream. The one deliberate difference from the authored form is schema_status:
 # the authored form says canonical; a projection never does.
-schema_version: "4.2.0"
+schema_version: "5.0.0"
 schema_owner: "sdd-method"
 schema_status: "generated"
 enums:
@@ -620,6 +620,8 @@ enums:
       description: "In the living spec: shipped behaviour."
     - value: agreed
       description: Added by an open change whose agreement record is agreed; not yet shipped.
+    - value: retired
+      description: "Removed by an archived change's REMOVED delta: kept so its lineage shows the removal; no status."
     description: Where a catalogued requirement stands (M-ADR 0221 §4.4).
   requirement_change_kind:
     values:
@@ -633,7 +635,8 @@ enums:
     - value: ADDED
     - value: MODIFIED
     - value: RENAMED
-    description: How a change's delta treated a requirement that is current now (a removed requirement has no row).
+    - value: REMOVED
+    description: How a change's delta treated a requirement.
   requirement_status_value:
     values:
     - value: agreed
@@ -664,10 +667,33 @@ enums:
   work_order_status:
     values:
     - value: agreed
-      description: Agreed; the repository's work is not yet judged.
+      description: Agreed; the change has not yet archived on a passing judge.
     - value: completed
-      description: Marked completed by a passing judge.
+      description: "Completed: the change archived on a passing judge, after every repository merged its judged commit."
     description: A work order's status in its change's agreement record (M-ADR 0223 §4.2, §4.6).
+  feature_status:
+    values:
+    - value: active
+      description: The feature's behaviour is live or being built.
+    - value: retired
+      description: Its behaviour was retired by an archived change; kept so its retired requirements resolve.
+    description: A catalogued feature's status (M-ADR 0221 §4.5).
+  feature_kind:
+    values:
+    - value: feature
+      description: "A product or capability feature: the default."
+    - value: obligation
+      description: Behaviour every feature in a population depends on, owned as a feature of its own (M-ADR 0226, Proposed).
+    - value: journey
+      description: A user journey's joint behaviour, held in the behaviour store (M-ADR 0229 §4.2, option B; Proposed).
+    description: What a catalogued feature is (M-ADR 0226 and M-ADR 0229, both Proposed).
+  journey_requirement_basis:
+    values:
+    - value: tag
+      description: A @req tag in the journey's end-to-end test file (option A).
+    - value: citation
+      description: A citation in the journey feature's living spec (option B).
+    description: Where a journey's citation of a requirement was read (M-ADR 0229 §4.4, Proposed).
 catalogues:
   domains:
     primary_key: id
@@ -1454,7 +1480,7 @@ catalogues:
     - name: status
       type: string
       nullable: false
-      description: Default 'active'.
+      description: "Bound to feature_status: active, or retired when the feature spec says **Status:** retired (its behaviour retired by an archived change)."
     - name: source
       type: string
       nullable: false
@@ -1463,6 +1489,10 @@ catalogues:
       type: string
       nullable: true
       description: Optional adopter-owned lifecycle / migration marker. Free string at method level — the schema declares no enum and ships no controlled vocabulary. Adopters MAY declare a per-SDD `feature-runway-vocabulary.yaml` at their SDD root; when present, the canonical builder validates captured values against it and emits a `convention` finding for unknown values. Empty when the adopter does not track migration state. Comparability across SDDs requires ecosystem-level vocabulary alignment as an explicit pre-step. Added in schema 2.2.0.
+    - name: kind
+      type: string
+      nullable: false
+      description: "Bound to feature_kind: feature (the default), obligation (M-ADR 0226, Proposed) or journey (M-ADR 0229 §4.2, Proposed), from the feature spec's **Kind:** line."
     - name: source_sdd_id
       type: string
       nullable: true
@@ -1485,6 +1515,8 @@ catalogues:
       references: features.id
       nullable: true
     column_enums:
+      status: enums.feature_status
+      kind: enums.feature_kind
       source: enums.feature_source
       maturity: enums.artefact_maturity
   personas:
@@ -4188,7 +4220,7 @@ catalogues:
     - name: stage
       type: string
       nullable: false
-      description: "Bound to requirement_stage: living (in the living spec) or agreed (added by an open change whose agreement record is agreed)."
+      description: "Bound to requirement_stage: living (in the living spec), agreed (added by an open change whose agreement record is agreed) or retired (removed by an archived change)."
     - name: spec_path
       type: string
       nullable: false
@@ -4225,7 +4257,7 @@ catalogues:
     - name: change_id
       type: string
       nullable: false
-      description: The archived change's directory name (its archive date prefix included); a changes.id.
+      description: "The archived change's id: <sdd_id>::<archive directory> (its archive date prefix included); a changes.id."
     - name: change_kind
       type: string
       nullable: false
@@ -4233,7 +4265,7 @@ catalogues:
     - name: operation
       type: string
       nullable: false
-      description: "Bound to requirement_operation: how the change's delta treated the requirement."
+      description: "Bound to requirement_operation: how the change's delta treated the requirement; REMOVED retires it."
     - name: archived_on
       type: string
       nullable: false
@@ -4278,7 +4310,7 @@ catalogues:
     - name: basis
       type: string
       nullable: false
-      description: "The change that produced the status: the open change's or the archived change's directory name."
+      description: "The change that produced the status: its changes.id, <sdd_id>::<directory>."
     - name: source_sdd_id
       type: string
       nullable: true
@@ -4287,7 +4319,7 @@ catalogues:
       type: string
       nullable: true
       description: The platform SDD the row belongs to (stamped at aggregation).
-    description: "Edge: a requirement's status in a repository that implements it (M-ADR 0221 §4.5; M-ADR 0223 §4.7). Derived, never authored: agreed from an open agreed change's work orders, declared-shipped from an archived change's PASS verdict and its work orders, observed from a baseline's evidence. The latest event in archive order wins."
+    description: "Edge: a requirement's status in a repository that implements it (M-ADR 0221 §4.5; M-ADR 0223 §4.7). Derived, never authored: agreed from an open agreed change's work orders, declared-shipped from an archived change's PASS verdict and its work orders, observed from a baseline's evidence. The latest event in archive order wins. Limitation: a requirement and repository hold one status. An agreed open change's status replaces the evidence about the revision that is live until the change archives, and evidence is not bound to the requirement revision it concerns."
     foreign_keys:
     - column: requirement_id
       references: requirements.id
@@ -4303,7 +4335,7 @@ catalogues:
     - name: id
       type: string
       nullable: false
-      description: "The change's directory name: the open change's name, or the archived change's directory (its archive date prefix included). requirement_lineage.change_id references it."
+      description: "<sdd_id>::<directory>: the SDD the store belongs to and the change's directory name there, the open change's name or the archived change's directory (its archive date prefix included). A change name is its store's own, so the SDD is part of its identity: two SDDs' changes of one name are two changes. requirement_lineage.change_id references it."
     - name: name
       type: string
       nullable: false
@@ -4354,7 +4386,7 @@ catalogues:
     - name: status
       type: string
       nullable: false
-      description: "Bound to work_order_status: the record's status for the work order; a judge PASS marks it completed (M-ADR 0223 §4.6)."
+      description: "Bound to work_order_status: the record's status for the work order; the change archiving on a judge PASS marks it completed (M-ADR 0223 §4.6)."
     - name: source_sdd_id
       type: string
       nullable: true
@@ -4379,11 +4411,11 @@ catalogues:
     - name: id
       type: string
       nullable: false
-      description: "<change_name>__<work_item_id>: keyed by the change's undated name, so the row is the same before and after archive."
+      description: "<sdd_id>::<change_name>__<work_item_id>: keyed by the SDD and the change's undated name, so the row is the same before and after archive."
     - name: change_id
       type: string
       nullable: false
-      description: "The change as it stands now: its open name, or its archive directory."
+      description: "The change as it stands now (a changes.id): <sdd_id>:: with its open name or its archive directory."
     - name: change_name
       type: string
       nullable: false
@@ -4405,3 +4437,38 @@ catalogues:
     - column: change_id
       references: changes.id
       nullable: false
+  journey_requirement:
+    primary_key: id
+    columns:
+    - name: id
+      type: string
+      nullable: false
+      description: <journey_id>__<requirement_id>.
+    - name: journey_id
+      type: string
+      nullable: false
+    - name: requirement_id
+      type: string
+      nullable: false
+    - name: basis
+      type: string
+      nullable: false
+      description: "Bound to journey_requirement_basis: where the citation was read."
+    - name: source_sdd_id
+      type: string
+      nullable: true
+      description: Originating SDD (stamped at aggregation; empty in a per-SDD build).
+    - name: platform_sdd_id
+      type: string
+      nullable: true
+      description: The platform SDD the row belongs to (stamped at aggregation).
+    description: "Edge: a requirement a user journey cites for one of its steps (M-ADR 0229 §4.4, Proposed). Derived, never authored: from the @req tags in the journey's end-to-end test file, or from the citations in its journey feature's living spec. A journey with no row is untraced."
+    foreign_keys:
+    - column: journey_id
+      references: user_journeys.id
+      nullable: false
+    - column: requirement_id
+      references: requirements.id
+      nullable: false
+    column_enums:
+      basis: enums.journey_requirement_basis