wingfoil 0.2.1

package/dist/core/registry.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerateOperations = enumerateOperations;
+exports.deriveVerb = deriveVerb;
+exports.computeParityDiff = computeParityDiff;
+/**
+ * Flatten `modules` into every declared operation, sorted deterministically by `(module.name,
+ * operation.name)` (REQ-SYS-07 — no unordered `Object.values`/iteration in a context-building
+ * path). Both `src/cli` and `src/mcp` register from this single enumerator, never from their own
+ * ad hoc traversal of `modules`/`Object.keys`.
+ */
+function enumerateOperations(modules) {
+    const out = [];
+    const sortedModules = [...modules].sort((a, b) => a.name.localeCompare(b.name));
+    for (const module of sortedModules) {
+        const operationNames = Object.keys(module.operations).sort();
+        for (const operationName of operationNames) {
+            const operation = module.operations[operationName];
+            if (operation)
+                out.push({ module, operation });
+        }
+    }
+    return out;
+}
+/** camelCase -> kebab-case (`"setTeam"` -> `"set-team"`), used by {@link deriveVerb}. */
+function camelToKebab(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}
+/**
+ * Derive an operation's CLI verb / MCP verb segment from its camelCase `{module}{Verb}` name
+ * (spec-006 §5), mechanically — this plus `mutates` is "the one place surface-routing logic
+ * lives" (§2): given `moduleName = "memory"` and `operationName = "memoryApprove"`, returns
+ * `"approve"`; a multi-word verb (`"workflowSetTeam"`) becomes kebab-case (`"set-team"`) so it
+ * renders as a single CLI token / Tool-name segment. Falls back to the full operation name,
+ * kebab-cased, when it does not start with the module's name — a config mistake the caller should
+ * catch earlier, but this function degrades rather than throwing, so a single bad registration
+ * cannot crash an adapter's entire registration pass.
+ */
+function deriveVerb(moduleName, operationName) {
+    // A "self-named" operation — its name is EXACTLY the module name (e.g. module `paths`, operation
+    // `paths`) — derives the empty string, not a verb: this is spec-008-cli-grammar §1's flat/no-verb
+    // command form (`wingfoil <noun> [args] [flags]`, e.g. `wingfoil paths [category]`), as opposed to
+    // the `<noun> <verb>` form every other operation today derives (`wingfoil dna show`). Both
+    // `src/cli/program.ts` and `src/mcp/registrar.ts` special-case an empty verb to skip the
+    // subcommand/URI-segment nesting they otherwise add (task-028-implement-paths-category).
+    if (operationName === moduleName)
+        return '';
+    const startsWithModule = operationName.startsWith(moduleName) && operationName.length > moduleName.length;
+    const suffix = startsWithModule ? operationName.slice(moduleName.length) : operationName;
+    const withLeadingLower = suffix.length > 0 ? suffix[0].toLowerCase() + suffix.slice(1) : suffix;
+    return camelToKebab(withLeadingLower);
+}
+/**
+ * Set-difference both ways between two enumerations of the same kind of key (e.g. `"noun verb"`
+ * CLI commands vs. the same keys' MCP Tool names, normalized to a common form by the caller) —
+ * the REQ-SYS-05 fit-criterion primitive: "reports 0 [operations] without a matching [counterpart]"
+ * in each direction. Both output lists are sorted, independent of input order (REQ-SYS-07).
+ */
+function computeParityDiff(a, b) {
+    const setA = new Set(a);
+    const setB = new Set(b);
+    const onlyInA = [...setA].filter((key) => !setB.has(key)).sort();
+    const onlyInB = [...setB].filter((key) => !setA.has(key)).sort();
+    return { onlyInA, onlyInB };
+}
+//# sourceMappingURL=registry.js.map

package/dist/core/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/core/registry.ts"],"names":[],"mappings":";;AAiGA,kDAWC;AAiBD,gCAYC;AAyFD,8CAMC;AA7ID;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,OAA8B;IAChE,MAAM,GAAG,GAA0B,EAAE,CAAC;IACtC,MAAM,aAAa,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAChF,KAAK,MAAM,MAAM,IAAI,aAAa,EAAE,CAAC;QACnC,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;QAC7D,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;YACnD,IAAI,SAAS;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yFAAyF;AACzF,SAAS,YAAY,CAAC,KAAa;IACjC,OAAO,KAAK,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AACpE,CAAC;AAED;;;;;;;;;GASG;AACH,SAAgB,UAAU,CAAC,UAAkB,EAAE,aAAqB;IAClE,iGAAiG;IACjG,kGAAkG;IAClG,mGAAmG;IACnG,2FAA2F;IAC3F,yFAAyF;IACzF,yFAAyF;IACzF,IAAI,aAAa,KAAK,UAAU;QAAE,OAAO,EAAE,CAAC;IAC5C,MAAM,gBAAgB,GAAG,aAAa,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;IAC1G,MAAM,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;IACzF,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjG,OAAO,YAAY,CAAC,gBAAgB,CAAC,CAAC;AACxC,CAAC;AAmFD;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,CAAoB,EAAE,CAAoB;IAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,IAAI,GAAG,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,MAAM,OAAO,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;AAC9B,CAAC"}

package/dist/core/relevance.d.ts

@@ -0,0 +1,86 @@
+import type { MemoryYaml } from '../memory/schema';
+/**
+ * Caps that keep an assembled context "bounded, not a full dump" (spec-012 §6) — the defaults match
+ * spec-012's own defaults verbatim: `maxDocs: 40`, `maxBytes: 262144` (256 KiB).
+ */
+export interface ContextLimits {
+    /** Maximum number of Memory documents included. */
+    readonly maxDocs: number;
+    /** Maximum total Memory-document body bytes (UTF-8) included. */
+    readonly maxBytes: number;
+}
+/** spec-012 §6's default {@link ContextLimits} (`maxDocs: 40`, `maxBytes: 262144` / 256 KiB). */
+export declare const DEFAULT_CONTEXT_LIMITS: ContextLimits;
+/**
+ * The active Memory element (usually a `task`) relevance is scored against — already resolved by the
+ * caller (spec-012 §3 stage 1, `resolve-element`, is a separate pipeline stage; this primitive is a
+ * pure `(state) -> selection` function and never reads the element document itself, per REQ-SYS-07).
+ */
+export interface RelevanceElementRef {
+    /** The element's `memory.yaml` type (e.g. `"task"`). */
+    readonly type: string;
+    /** The element's `id` frontmatter value. */
+    readonly id: string;
+    /** The element's already-parsed frontmatter (used to derive T1 links, T2 release scope, T3
+     * traceability keys, and T4 keyword/tag overlap — see {@link filterRelevantMemoryDocuments}). */
+    readonly frontmatter: Record<string, unknown>;
+}
+/** One Memory document selected as relevant, carrying the {@link ContextLimits}-bounding fields plus
+ * its computed spec-012 §6 tier `score` (exposed for callers that want to display/debug ranking). */
+export interface RelevantMemoryDocument {
+    readonly path: string;
+    readonly type?: string;
+    readonly id?: string;
+    readonly title?: string;
+    readonly status?: string;
+    readonly frontmatter: Record<string, unknown>;
+    readonly body: string;
+    /** `1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)` (spec-012 §6) — always `> 0` for an included doc. */
+    readonly score: number;
+}
+/** P5.3.3-relevance-filtering.feature's "Edge - no documents pass the relevance threshold" note,
+ * verbatim: `'a note "no relevant Memory found for task" is recorded'`. */
+export declare const NO_RELEVANT_MEMORY_NOTE = "no relevant Memory found for task";
+/**
+ * {@link filterRelevantMemoryDocuments}'s result: the bounded, ordered set of relevant documents, plus
+ * {@link NO_RELEVANT_MEMORY_NOTE} when — and only when — **nothing passed the relevance threshold**
+ * (mirrors `memorySearchFn`'s `message`-only-when-empty convention in `src/core/index.ts`).
+ *
+ * The note is keyed to the *scored* set, never to the *bounded* one: "no relevant Memory found for
+ * task" is a factual claim, and documents that scored as relevant but did not fit inside
+ * {@link ContextLimits} were found — they were merely not carried. In that case `documents` is empty
+ * and `note` is `undefined`, because the filter cannot honestly assert the stronger statement.
+ */
+export interface RelevantMemoryResult {
+    readonly documents: readonly RelevantMemoryDocument[];
+    readonly note?: string;
+}
+/**
+ * Rank and bound the Memory documents relevant to `element` (spec-012 §6, REQ-PERF-05). Deterministic
+ * end to end (REQ-SYS-07):
+ *
+ * 1. **Scan** every document `memoryYaml` declares under `root` ({@link listMemoryDocumentPaths}'s
+ *    already-sorted order, task-008) — no second directory walk.
+ * 2. **Exclude** the element's own document (never relevant to itself) and any document
+ *    {@link isExcludedFromContext} bars — `draft` plus the shared archived set `{deprecated,
+ *    superseded}` (`dl-028`; the archived half is the same predicate REQ-STATE-06 applies to default
+ *    `memory search`, the `draft` half is context-only).
+ * 3. **Score** each remaining document: `1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)` — T1 explicit
+ *    link, T2 same release scope, T3 shared traceability key, T4 keyword/tag overlap count
+ *    (spec-012 §6's exact formula). A document scoring `0` (no tier hit at all) is **not relevant**
+ *    and is dropped — this is the relevance threshold P5.3.3-relevance-filtering.feature's "Edge - no
+ *    documents pass the relevance threshold" scenario exercises.
+ * 4. **Order**: score DESC, then `type` ASC, then `id` ASC (falling back to `path` when a document has
+ *    no `id`) — a total, deterministic tie-break (spec-012 §6/REQ-SYS-07).
+ * 5. **Bound**: walk in that order, including documents until either `limits.maxDocs` or
+ *    `limits.maxBytes` (summed UTF-8 body bytes) would be exceeded, then **stop** — never skip a
+ *    lower-ranked document to fit under a cap while a higher-ranked one was excluded, and never
+ *    partially include a document (spec-012 §6's "deterministic truncation").
+ *
+ * Returns {@link NO_RELEVANT_MEMORY_NOTE} in `note` only when **step 3 left nothing** — i.e. no
+ * document passed the relevance threshold at all (P5.3.3's edge-case scenario, verbatim wording).
+ * When documents scored as relevant but step 5's caps admitted none of them, `documents` is empty and
+ * `note` is omitted: relevant Memory *was* found, so the note would assert something false.
+ */
+export declare function filterRelevantMemoryDocuments(root: string, memoryYaml: MemoryYaml, element: RelevanceElementRef, limits?: ContextLimits): RelevantMemoryResult;
+//# sourceMappingURL=relevance.d.ts.map

package/dist/core/relevance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance.d.ts","sourceRoot":"","sources":["../../src/core/relevance.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAGnD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,iGAAiG;AACjG,eAAO,MAAM,sBAAsB,EAAE,aAAiD,CAAC;AAEvF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;qGACiG;IACjG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/C;AAED;qGACqG;AACrG,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;2EAC2E;AAC3E,eAAO,MAAM,uBAAuB,sCAAsC,CAAC;AAE3E;;;;;;;;;GASG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,sBAAsB,EAAE,CAAC;IACtD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAoID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,mBAAmB,EAC5B,MAAM,GAAE,aAAsC,GAC7C,oBAAoB,CAsDtB"}

package/dist/core/relevance.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_RELEVANT_MEMORY_NOTE = exports.DEFAULT_CONTEXT_LIMITS = void 0;
+exports.filterRelevantMemoryDocuments = filterRelevantMemoryDocuments;
+/**
+ * `relevance-filter` (task-035-bounded-context-relevance, REQ-PERF-05) —
+ * spec-012-context-loader-relevance-filtering §6's deterministic Memory-document selection unit:
+ * rank and bound the set of Memory documents relevant to an active element (usually a `task`), so an
+ * assembled agent context stays "curated, not full dump" (Product Brief) and satisfies REQ-PERF-05's
+ * Fit Criterion verbatim — "given 1,000 Memory documents of which K are relevant to the task, the
+ * assembled context contains exactly the K relevant (non-deprecated) documents and 0 others."
+ *
+ * This module implements ONLY spec-012 §6 (`relevance-filter`), one of the four cooperating units
+ * spec-012 defines (`dna-loader`, `directive-loader`, `relevance-filter`, `context-builder`) — the
+ * other three, and the canonical serialized envelope (§7), belong to
+ * task-037-role-task-scoped-context (REQ-STATE-05, the `context-builder`/envelope task). For the
+ * document scan itself it wraps, not reimplements, `src/memory/query.ts`'s scan primitives
+ * (task-008) — no second directory walk or frontmatter parser — and is placed in `src/core` per
+ * spec-012 §1 ("folded into the `core` module"). It is re-exported from `src/core`'s barrel, so
+ * `src/core` is the import surface for every consumer.
+ *
+ * **Exclusion set (`dl-028-archived-states-excluded-from-context`, `ready`).** Candidates are dropped
+ * when their `status` is archived — `{deprecated, superseded}`, via `src/memory/state-machine.ts`'s
+ * shared {@link isArchivedStatus} (the one predicate the default-search path, REQ-STATE-06, consumes
+ * too) — **or** `draft`. That `draft` clause is context-only and deliberately NOT mirrored into
+ * `memory search`: spec-012 §6 admits only "stable, decided and still-current content" into an
+ * execution context, whereas REQ-STATE-06 scopes default-search exclusion to archived content so a
+ * draft under active work stays findable. Two different sets, on purpose — see
+ * {@link DRAFT_STATUS}. dl-028 also dropped spec-012 §6's former `rejected` entry, a status
+ * `spec-001-memory-yaml-schema` removed from every type's machine.
+ *
+ * Determinism (REQ-SYS-07): no wall-clock, no randomness, no unordered map/set iteration in any
+ * output-affecting path. This function READS the live working tree under `root` — it is not pinned to
+ * a git revision, and `root`'s content is therefore part of its input, not a constant. What is
+ * guaranteed is *referential transparency over that observed state*: for one unchanged working tree,
+ * the selection and its order are a pure function of `(the Memory documents under root, memoryYaml,
+ * element, limits)`, so repeated calls return the identical array. See
+ * {@link filterRelevantMemoryDocuments}'s own doc comment for the exact ordering/bounding contract.
+ */
+const query_1 = require("../memory/query");
+const state_machine_1 = require("../memory/state-machine");
+/** spec-012 §6's default {@link ContextLimits} (`maxDocs: 40`, `maxBytes: 262144` / 256 KiB). */
+exports.DEFAULT_CONTEXT_LIMITS = { maxDocs: 40, maxBytes: 262144 };
+/** P5.3.3-relevance-filtering.feature's "Edge - no documents pass the relevance threshold" note,
+ * verbatim: `'a note "no relevant Memory found for task" is recorded'`. */
+exports.NO_RELEVANT_MEMORY_NOTE = 'no relevant Memory found for task';
+/**
+ * spec-012 §6's per-tier score weights, isolated as named constants so the scoring formula
+ * (`1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)`) reads as tiers, not magic numbers. Each weight is a
+ * strict order of magnitude above the next so any T(n) hit outranks every combination of lower tiers
+ * (a single doc can carry at most a handful of T4 overlaps, far below `TIER_3_TRACEABILITY = 10`).
+ */
+const TIER_1_EXPLICIT_LINK = 1000;
+const TIER_2_RELEASE_SCOPE = 100;
+const TIER_3_TRACEABILITY = 10;
+// T4 (keyword/tag overlap) contributes its raw overlap count, weight 1 — spec-012 §6.
+/** Frontmatter fields spec-012 §6 T1 treats as explicit links. Each may carry a single id or a list
+ * of them — see {@link asLinkIds} and `dl-045-absorbed-bug-back-reference`. */
+const LINK_FRONTMATTER_FIELDS = ['adr', 'spec', 'dl', 'bug'];
+/**
+ * `draft` — the one status excluded from an assembled context *beyond* the shared archived set.
+ * spec-012 §6 admits only "stable, decided and still-current content" into an execution context, so a
+ * draft — a document whose content is not yet submitted, let alone agreed — is dropped regardless of
+ * score. Kept as a named constant rather than folded into `isArchivedStatus` precisely because it is
+ * NOT archived: `memory search` must keep returning drafts (REQ-STATE-06 excludes archived content
+ * only), and collapsing the two sets would hide in-progress work from the search surface.
+ */
+const DRAFT_STATUS = 'draft';
+/**
+ * True when a candidate's `status` bars it from an assembled agent context (spec-012 §6): the shared
+ * archived set `{deprecated, superseded}` ({@link isArchivedStatus}, ratified by
+ * `dl-028-archived-states-excluded-from-context`) widened by {@link DRAFT_STATUS}.
+ * A document with no `status` frontmatter at all is not excluded — absence is not a decision.
+ */
+function isExcludedFromContext(status) {
+    return status === DRAFT_STATUS || (0, state_machine_1.isArchivedStatus)(status);
+}
+/** A traceability token: a feature id (`P5.3.3`, `P1.9`, ...) or a SARD requirement id
+ * (`REQ-PERF-05`, `REQ-SYS-07`, ...) — spec-012 §6 T3's "shared traceability keys". */
+const TRACEABILITY_PATTERN = /\bP\d+(?:\.\d+)+\b|\bREQ-[A-Z]+-\d+\b/g;
+/** Lowercase alphanumeric word tokens — spec-012 §6 T4's "title tokens". */
+const WORD_PATTERN = /[a-z0-9]+/g;
+function asString(value) {
+    return typeof value === 'string' ? value : undefined;
+}
+function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((entry) => typeof entry === 'string') : [];
+}
+/**
+ * Read a {@link LINK_FRONTMATTER_FIELDS} value as the list of ids it names, accepting BOTH a single
+ * string and an array of them.
+ *
+ * `dl-045-absorbed-bug-back-reference` made the task `bug:` field a list, so a bug absorbed into an
+ * existing task's Acceptance Criteria — rather than given its own fix task — keeps the back-reference
+ * `bug.sync_state` binds to. Reading these fields with a bare {@link asString} would have made that
+ * change **silently lossy**: `asString` returns `undefined` for an array, so an absorbed bug would
+ * stop scoring as a T1 explicit link and drop out of its own host task's assembled context, with no
+ * error to notice.
+ *
+ * Both shapes stay valid on purpose. Every fix task written before dl-045 carries a single id, and
+ * `adr`/`spec`/`dl` are unchanged by that decision — narrowing to arrays would break them all.
+ */
+function asLinkIds(value) {
+    const single = asString(value);
+    return single !== undefined ? [single] : asStringArray(value);
+}
+/** T1: the set of ids the element's frontmatter explicitly references (`adr`, `spec`, `dl`, `bug`,
+ * `depends_on`) — spec-012 §6. Insertion order follows {@link LINK_FRONTMATTER_FIELDS}'s fixed
+ * declaration order, then each field's own array order, then `depends_on`'s (REQ-SYS-07: no
+ * unordered iteration). */
+function collectLinkedIds(frontmatter) {
+    const ids = new Set();
+    for (const field of LINK_FRONTMATTER_FIELDS) {
+        for (const value of asLinkIds(frontmatter[field])) {
+            if (value.length > 0)
+                ids.add(value);
+        }
+    }
+    for (const dependency of asStringArray(frontmatter.depends_on))
+        ids.add(dependency);
+    return ids;
+}
+/** T3: the set of `P*`/`REQ-*` traceability tokens found across every string-valued frontmatter field
+ * (`ref`, `tags`, ...) and, when supplied, the document body — spec-012 §6. */
+function collectTraceabilityKeys(frontmatter, body) {
+    const keys = new Set();
+    const scan = (text) => {
+        for (const match of text.matchAll(TRACEABILITY_PATTERN))
+            keys.add(match[0]);
+    };
+    for (const value of Object.values(frontmatter)) {
+        if (typeof value === 'string')
+            scan(value);
+        else if (Array.isArray(value))
+            for (const entry of value)
+                if (typeof entry === 'string')
+                    scan(entry);
+    }
+    if (body !== undefined)
+        scan(body);
+    return keys;
+}
+/** T4: the element/document's keyword set — its `tags:` entries plus its title's lowercase word
+ * tokens — spec-012 §6 ("docs whose tags: or title tokens intersect the element's tags/title
+ * tokens"). */
+function collectKeywords(frontmatter) {
+    const keywords = new Set();
+    for (const tag of asStringArray(frontmatter.tags))
+        keywords.add(tag.toLowerCase());
+    const title = asString(frontmatter.title);
+    if (title !== undefined)
+        for (const word of title.toLowerCase().match(WORD_PATTERN) ?? [])
+            keywords.add(word);
+    return keywords;
+}
+function intersectionSize(a, b) {
+    let count = 0;
+    for (const value of a)
+        if (b.has(value))
+            count += 1;
+    return count;
+}
+function hasIntersection(a, b) {
+    for (const value of a)
+        if (b.has(value))
+            return true;
+    return false;
+}
+/** T2: is `documentPath` under the element's release scope? True when the element declares a
+ * `release` and either the candidate document's own `release:` frontmatter matches it exactly, or its
+ * path contains that release as a path segment (covers release-line-scoped docs whose own frontmatter
+ * has no `release` field) — spec-012 §6 ("docs under the element's release / release-line path"). */
+function isSameReleaseScope(elementRelease, documentPath, documentFrontmatter) {
+    if (elementRelease === undefined)
+        return false;
+    return documentPath.includes(`/${elementRelease}/`) || asString(documentFrontmatter.release) === elementRelease;
+}
+/**
+ * Rank and bound the Memory documents relevant to `element` (spec-012 §6, REQ-PERF-05). Deterministic
+ * end to end (REQ-SYS-07):
+ *
+ * 1. **Scan** every document `memoryYaml` declares under `root` ({@link listMemoryDocumentPaths}'s
+ *    already-sorted order, task-008) — no second directory walk.
+ * 2. **Exclude** the element's own document (never relevant to itself) and any document
+ *    {@link isExcludedFromContext} bars — `draft` plus the shared archived set `{deprecated,
+ *    superseded}` (`dl-028`; the archived half is the same predicate REQ-STATE-06 applies to default
+ *    `memory search`, the `draft` half is context-only).
+ * 3. **Score** each remaining document: `1000*T1 + 100*T2 + 10*T3 + overlapCount(T4)` — T1 explicit
+ *    link, T2 same release scope, T3 shared traceability key, T4 keyword/tag overlap count
+ *    (spec-012 §6's exact formula). A document scoring `0` (no tier hit at all) is **not relevant**
+ *    and is dropped — this is the relevance threshold P5.3.3-relevance-filtering.feature's "Edge - no
+ *    documents pass the relevance threshold" scenario exercises.
+ * 4. **Order**: score DESC, then `type` ASC, then `id` ASC (falling back to `path` when a document has
+ *    no `id`) — a total, deterministic tie-break (spec-012 §6/REQ-SYS-07).
+ * 5. **Bound**: walk in that order, including documents until either `limits.maxDocs` or
+ *    `limits.maxBytes` (summed UTF-8 body bytes) would be exceeded, then **stop** — never skip a
+ *    lower-ranked document to fit under a cap while a higher-ranked one was excluded, and never
+ *    partially include a document (spec-012 §6's "deterministic truncation").
+ *
+ * Returns {@link NO_RELEVANT_MEMORY_NOTE} in `note` only when **step 3 left nothing** — i.e. no
+ * document passed the relevance threshold at all (P5.3.3's edge-case scenario, verbatim wording).
+ * When documents scored as relevant but step 5's caps admitted none of them, `documents` is empty and
+ * `note` is omitted: relevant Memory *was* found, so the note would assert something false.
+ */
+function filterRelevantMemoryDocuments(root, memoryYaml, element, limits = exports.DEFAULT_CONTEXT_LIMITS) {
+    const linkedIds = collectLinkedIds(element.frontmatter);
+    const elementRelease = asString(element.frontmatter.release);
+    const elementTraceability = collectTraceabilityKeys(element.frontmatter);
+    const elementKeywords = collectKeywords(element.frontmatter);
+    const scored = [];
+    for (const path of (0, query_1.listMemoryDocumentPaths)(root, memoryYaml)) {
+        const { frontmatter, body } = (0, query_1.loadMemoryDocumentSummary)(root, path);
+        const type = asString(frontmatter.type);
+        const id = asString(frontmatter.id);
+        const status = asString(frontmatter.status);
+        if (isExcludedFromContext(status))
+            continue;
+        if (type === element.type && id === element.id)
+            continue;
+        const t1 = id !== undefined && linkedIds.has(id);
+        const t2 = isSameReleaseScope(elementRelease, path, frontmatter);
+        const t3 = hasIntersection(elementTraceability, collectTraceabilityKeys(frontmatter, body));
+        const t4OverlapCount = intersectionSize(elementKeywords, collectKeywords(frontmatter));
+        const score = (t1 ? TIER_1_EXPLICIT_LINK : 0) +
+            (t2 ? TIER_2_RELEASE_SCOPE : 0) +
+            (t3 ? TIER_3_TRACEABILITY : 0) +
+            t4OverlapCount;
+        if (score <= 0)
+            continue;
+        scored.push({ path, type, id, title: asString(frontmatter.title), status, frontmatter, body, score });
+    }
+    scored.sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        const typeA = a.type ?? '';
+        const typeB = b.type ?? '';
+        if (typeA !== typeB)
+            return typeA < typeB ? -1 : 1;
+        const idA = a.id ?? a.path;
+        const idB = b.id ?? b.path;
+        return idA < idB ? -1 : idA > idB ? 1 : 0;
+    });
+    const documents = [];
+    let totalBytes = 0;
+    for (const doc of scored) {
+        if (documents.length >= limits.maxDocs)
+            break;
+        const docBytes = Buffer.byteLength(doc.body, 'utf-8');
+        if (totalBytes + docBytes > limits.maxBytes)
+            break;
+        documents.push(doc);
+        totalBytes += docBytes;
+    }
+    // The note is keyed to `scored`, NOT to `documents`: an empty `documents` with a non-empty `scored`
+    // means relevant Memory existed and was bounded out, which the note must not claim away.
+    return scored.length === 0 ? { documents, note: exports.NO_RELEVANT_MEMORY_NOTE } : { documents };
+}
+//# sourceMappingURL=relevance.js.map

package/dist/core/relevance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relevance.js","sourceRoot":"","sources":["../../src/core/relevance.ts"],"names":[],"mappings":"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"}

package/dist/core/require-reason.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Return the `--reason` value out of a `CoreFn`'s parsed `options` (the `ParamsContext.options`
+ * value-bearing seam, `../core/registry.ts` — the same one `memoryAddFn` reads `--type`/`--title`/
+ * `--tags` from), normalized to the form the commit trailer records; or throw a `UsageError` (exit 2)
+ * when it is absent (`options` itself undefined, or present without a `reason` key) or cannot be
+ * recorded. Call this BEFORE any registry/document lookup in a mutating `CoreFn` so a refused
+ * `--reason` makes no change.
+ *
+ * Returning the NORMALIZED text rather than the raw argument is what keeps the commit trailer and
+ * `memory reject`'s `rejection_reason` frontmatter field (`spec-010` — the one verb that writes the
+ * reason twice) carrying byte-identical text: the rule is applied once, here, not at each sink.
+ */
+export declare function requireReason(options: Readonly<Record<string, string>> | undefined): string;
+/**
+ * The same, for a verb whose `--reason` is OPTIONAL — `memory deprecate` (`dl-027` option (a)):
+ * `undefined` when none was given (the verb then exits `0` and commits a subject-only message), the
+ * normalized text when one was.
+ *
+ * A reason that is *declared but empty* is a usage error here too, exactly as on the approval gates
+ * (dl-067 S2, ratified). `buildOptionValues` (`src/cli/program.ts`) keeps any `typeof value ===
+ * 'string'` precisely so a core op can tell "not given" from "given empty"; honouring that
+ * distinction means refusing the empty one, not silently discarding it. This changes a merged verb's
+ * behaviour — nothing pinned the old one, and the old one was bug-042 F2 on the verb where it bites
+ * hardest, `deprecate` having no `Approver:` line of its own to lose.
+ */
+export declare function optionalReason(options: Readonly<Record<string, string>> | undefined): string | undefined;
+//# sourceMappingURL=require-reason.d.ts.map

package/dist/core/require-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-reason.d.ts","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":"AA2DA;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,CAM3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAGxG"}

package/dist/core/require-reason.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireReason = requireReason;
+exports.optionalReason = optionalReason;
+/**
+ * `--reason` mandatory-argument pre-flight check (REQ-SEC-04 — task-041-mandatory-reason-on-verbs).
+ *
+ * Decisions must be explainable in the audit trail: `memory approve` (P1.7) and `memory reject`
+ * (P1.8) both record an approver/rejecter identity, an ISO-8601 timestamp, and a reason in the
+ * resulting git commit body (P1.7/P1.8 BDD "the git commit records the approver identity, timestamp,
+ * and reason"). The reason text can only be recorded if the caller supplied one, so both operations
+ * refuse before any read/write when `--reason` is omitted — the argument-validation step every
+ * mutating `CoreFn` already performs inline for its own required options (e.g. `memoryAddFn`'s
+ * `--type`/`--title` checks, task-020), factored out here once both approve and reject need the
+ * identical check (this task is their shared prerequisite, per its own Implementation Notes).
+ *
+ * This mirrors `requireGitIdentity`'s (`./git-identity.ts`, REQ-SEC-01, task-014) role and calling
+ * convention: a mutating `CoreFn` calls it first, before any registry lookup or file access, so an
+ * omitted `--reason` makes no change (REQ-SEC-04's fit criterion). Unlike `requireGitIdentity` (an
+ * ambient precondition, not tied to a CLI argument, returning a `CoreResult.error` mapped to exit 1)
+ * this is an ARGUMENT-shape problem — spec-005-cli-command-contract §1's "missing required argument"
+ * case — so, matching `memoryAddFn`'s own `--type`/`--title` checks and `dnaSetFn`'s invalid-key-path
+ * check, it `throw`s a `UsageError` (exit **2**, `./exit-code.ts`'s `exitCodeForThrow`) rather than
+ * returning a `CoreResult`.
+ *
+ * `memory deprecate` (P1.9, task-048) deliberately does NOT call {@link requireReason}:
+ * `spec-008-cli-grammar.md` §2 marks `--reason` optional "elsewhere (e.g. `memory deprecate`)", and
+ * `P1.9-memory-deprecate.feature` has no "missing reason" error scenario (unlike P1.7/P1.8). Since
+ * `task-072` it calls {@link optionalReason} instead of reading `options?.reason` raw.
+ *
+ * `task-072-fix-reason-trailer-contract` (`dl-067-reason-trailer-contract`, fixing `bug-042`) widens
+ * both checks from "was a reason given?" to "can this reason be RECORDED?". Those turned out to be
+ * different questions: `--reason ""` *was* given, was accepted at exit `0`, and left a bare `Reason:`
+ * that made `wingfoil memory history` report an approval gate crossed by nobody, for no reason. The
+ * shape rule itself is not decided here — it lives once, in `src/memory/commit-message.ts`, beside the
+ * formatter that writes the trailer and consumed by the reader in `src/memory/audit.ts` (dl-067
+ * clause 5). This module only maps a defect onto the CLI's usage-error exit code.
+ */
+const commit_message_1 = require("../memory/commit-message");
+const usage_error_1 = require("./usage-error");
+/** Exact refusal message required by REQ-SEC-04's fit criterion (spec-008-cli-grammar §2's ground-truth wording) — do not reword. */
+const MISSING_REASON_ERROR = 'missing required argument: --reason';
+/**
+ * The given reason in its declared normal form, or a `UsageError` (exit 2) naming the defect that
+ * makes it unrecordable — blank, carrying a reserved trailer line, or ending in one
+ * (`reasonDefect`, `src/memory/commit-message.ts`).
+ *
+ * The message is deliberately NOT {@link MISSING_REASON_ERROR}: that string answers the *omitted*
+ * case, and `spec-008-cli-grammar` §2 plus the `P1.7`/`P1.8` BDD features quote it verbatim for that
+ * case alone, so reusing it would make those scenarios ambiguous about which failure they pin
+ * (dl-067 S1).
+ */
+function recordableReason(reason) {
+    const defect = (0, commit_message_1.reasonDefect)(reason);
+    if (defect !== null) {
+        throw new usage_error_1.UsageError((0, commit_message_1.reasonDefectMessage)(defect));
+    }
+    return (0, commit_message_1.normalizeReason)(reason);
+}
+/**
+ * Return the `--reason` value out of a `CoreFn`'s parsed `options` (the `ParamsContext.options`
+ * value-bearing seam, `../core/registry.ts` — the same one `memoryAddFn` reads `--type`/`--title`/
+ * `--tags` from), normalized to the form the commit trailer records; or throw a `UsageError` (exit 2)
+ * when it is absent (`options` itself undefined, or present without a `reason` key) or cannot be
+ * recorded. Call this BEFORE any registry/document lookup in a mutating `CoreFn` so a refused
+ * `--reason` makes no change.
+ *
+ * Returning the NORMALIZED text rather than the raw argument is what keeps the commit trailer and
+ * `memory reject`'s `rejection_reason` frontmatter field (`spec-010` — the one verb that writes the
+ * reason twice) carrying byte-identical text: the rule is applied once, here, not at each sink.
+ */
+function requireReason(options) {
+    const reason = options?.reason;
+    if (reason === undefined) {
+        throw new usage_error_1.UsageError(MISSING_REASON_ERROR);
+    }
+    return recordableReason(reason);
+}
+/**
+ * The same, for a verb whose `--reason` is OPTIONAL — `memory deprecate` (`dl-027` option (a)):
+ * `undefined` when none was given (the verb then exits `0` and commits a subject-only message), the
+ * normalized text when one was.
+ *
+ * A reason that is *declared but empty* is a usage error here too, exactly as on the approval gates
+ * (dl-067 S2, ratified). `buildOptionValues` (`src/cli/program.ts`) keeps any `typeof value ===
+ * 'string'` precisely so a core op can tell "not given" from "given empty"; honouring that
+ * distinction means refusing the empty one, not silently discarding it. This changes a merged verb's
+ * behaviour — nothing pinned the old one, and the old one was bug-042 F2 on the verb where it bites
+ * hardest, `deprecate` having no `Approver:` line of its own to lose.
+ */
+function optionalReason(options) {
+    const reason = options?.reason;
+    return reason === undefined ? undefined : recordableReason(reason);
+}
+//# sourceMappingURL=require-reason.js.map

package/dist/core/require-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-reason.js","sourceRoot":"","sources":["../../src/core/require-reason.ts"],"names":[],"mappings":";;AAuEA,sCAMC;AAcD,wCAGC;AA9FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,6DAA8F;AAE9F,+CAA2C;AAE3C,qIAAqI;AACrI,MAAM,oBAAoB,GAAG,qCAAqC,CAAC;AAEnE;;;;;;;;;GASG;AACH,SAAS,gBAAgB,CAAC,MAAc;IACtC,MAAM,MAAM,GAAG,IAAA,6BAAY,EAAC,MAAM,CAAC,CAAC;IACpC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,IAAI,wBAAU,CAAC,IAAA,oCAAmB,EAAC,MAAM,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAA,gCAAe,EAAC,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,aAAa,CAAC,OAAqD;IACjF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,wBAAU,CAAC,oBAAoB,CAAC,CAAC;IAC7C,CAAC;IACD,OAAO,gBAAgB,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,SAAgB,cAAc,CAAC,OAAqD;IAClF,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;IAC/B,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;AACrE,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Core result & error shapes (spec-006-core-domain-api §2 — "Function shape").
+ *
+ * Every core function returns `Promise<CoreResult<T>>`, a discriminated union — never a thrown
+ * error for *expected* domain failures (illegal state transition, missing element, schema
+ * violation). That is what lets `src/cli`'s exit-code/stderr rendering and `src/mcp`'s Tool
+ * `isError`/Resource-read-failure response be driven off the very same value, rather than each
+ * surface independently deciding what counts as a failure and how to report it.
+ */
+/** The fixed `CoreError.code` enumeration (spec-006 §2, verbatim). */
+export type CoreErrorCode = 'NOT_FOUND' | 'INVALID_TRANSITION' | 'VALIDATION' | 'CONFLICT' | 'IO';
+/**
+ * An expected domain failure carried by a failed {@link CoreResult} (spec-006 §2): a fixed
+ * {@link CoreErrorCode}, a human-readable `message`, and optional structured `details`. The single
+ * shape both surfaces map to an exit code / MCP error response.
+ */
+export interface CoreError {
+    readonly code: CoreErrorCode;
+    readonly message: string;
+    readonly details?: Record<string, unknown>;
+}
+/**
+ * The discriminated-union return of every {@link CoreFn} (spec-006 §2): `ok: true` with the operation's
+ * `value` (and, for a mutation, the `commit` it produced), or `ok: false` with a {@link CoreError}.
+ * Expected domain failures travel here, never as a thrown exception.
+ */
+export type CoreResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly commit?: {
+        readonly sha: string;
+        readonly message: string;
+    };
+} | {
+    readonly ok: false;
+    readonly error: CoreError;
+};
+/** Build a success {@link CoreResult}, optionally carrying the git commit the operation produced. */
+export declare function coreOk<T>(value: T, commit?: {
+    sha: string;
+    message: string;
+}): CoreResult<T>;
+/** Build a failure {@link CoreResult} from a {@link CoreError}. */
+export declare function coreErr<T = never>(error: CoreError): CoreResult<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtD,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAE5F;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}