wingfoil 0.2.1

package/dist/core/builtin-integrity.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyBuiltinTemplates = verifyBuiltinTemplates;
+/**
+ * Built-in template schema check (task-044-builtin-template-integrity, REQ-SEC-10 "Schema checks on
+ * built-in templates"): "Built-in directive and workflow templates are schema-checked before
+ * installation during `init`... A corrupted or schema-invalid built-in template aborts `init` before
+ * writing partial assets, with a message naming the failing template"
+ * (docs/02_requirements/03_sard/05_security-compliance.md).
+ *
+ * SCOPE, per `dl-031-req-sec-10-integrity-depth` (`ready`), which retitled the requirement: schema
+ * validation IS the REQ-SEC-10 contract. There is deliberately NO digest and NO manifest here — the
+ * threat the requirement's rationale names is accidental corruption (truncated file, bad merge), not
+ * post-install tampering; a manifest shipped inside the same package is no control against an
+ * adversary who can rewrite a template; and a content hash would add a line-ending / encoding /
+ * ordering determinism surface against REQ-SYS-07. Distribution-channel assurance lives in `adr-009`
+ * / `spec-015` (npm provenance) instead. Do not "strengthen" this module with hashing.
+ *
+ * A cross-pillar concern by construction — checking a directive source needs the Directives pillar's
+ * `DirectiveFrontmatter` schema, checking a workflow source needs the Workflow pillar's `Workflow`
+ * schema — so, per `src/core/loaders.ts`'s own precedent ("Cross-file concerns ... need the caller to
+ * have actually loaded the referenced files ... live in the loader, not [a pillar] schema module"),
+ * this lives in `core`, not in either pillar module or in `storage` (which only carries the raw
+ * {@link BuiltinTemplateSource} shape — see `src/storage/templates.ts`). Reuses the exact same
+ * two-pass validation primitives (`parseYaml`, `runValidation`) every pillar loader already uses, so a
+ * built-in source is checked against precisely the same schema its custom counterpart would be loaded
+ * with — no bespoke re-implementation of YAML/frontmatter parsing.
+ *
+ * `verifyBuiltinTemplates` is a pure function of its input list (REQ-SYS-07: no wall-clock, no
+ * randomness) — the same corrupted input always yields the same failure, and callers may pass a
+ * fixture list in tests via {@link BuiltinTemplateSource} without touching disk.
+ */
+const schema_1 = require("../directives/schema");
+const storage_1 = require("../storage");
+const validation_1 = require("../validation");
+const schema_2 = require("../workflow/schema");
+/**
+ * `true` iff `source.content` parses as a `.md` document with a frontmatter block that validates
+ * against `DirectiveFrontmatter` (the same schema `core/loaders.ts`'s `loadDirectives` runs custom
+ * directive files through). Any parse or schema failure — missing frontmatter, unparsable YAML, a
+ * missing required field — is "corrupted" for REQ-SEC-10's purposes; the exact cause is not surfaced
+ * (the fit criterion only requires naming *which* template failed, not why).
+ */
+function isValidDirectiveSource(source) {
+    const frontmatterText = (0, storage_1.extractFrontmatter)(source.content);
+    if (frontmatterText === null)
+        return false;
+    try {
+        const data = (0, validation_1.parseYaml)(frontmatterText, source.name);
+        (0, validation_1.runValidation)(schema_1.DirectiveFrontmatter, data, source.name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `true` iff `source.content` parses as YAML and validates against the `Workflow` schema (the same
+ * schema `core/loaders.ts`'s `loadWorkflowsYaml` runs every included workflow file through).
+ */
+function isValidWorkflowSource(source) {
+    try {
+        const data = (0, validation_1.parseYaml)(source.content, source.name);
+        (0, validation_1.runValidation)(schema_2.Workflow, data, source.name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Per-kind schema-check policy: the `isValid` predicate to apply and the exact REQ-SEC-10 abort-message
+ * builder to use when it fails. Keyed by {@link BuiltinTemplateKind} so each kind's validator and its
+ * BDD wording live together and `verifyBuiltinTemplates` branches on `kind` exactly once. The message
+ * strings are verbatim BDD contracts — P3.8 "Error - a built-in template fails its integrity check"
+ * and P4.17 "Error - a built-in workflow template is structurally invalid" — do not reword.
+ *
+ * Declared as an EXHAUSTIVE `Record` so widening {@link BuiltinTemplateKind} is a compile error until
+ * the new kind gets a policy; look it up only through {@link policyFor}, never by bare indexing.
+ */
+const INTEGRITY_POLICY = {
+    directive: {
+        isValid: isValidDirectiveSource,
+        message: (name) => `built-in directive template integrity check failed: ${name}`,
+    },
+    workflow: {
+        isValid: isValidWorkflowSource,
+        message: (name) => `built-in workflow template invalid: ${name}`,
+    },
+};
+/**
+ * The REQ-SEC-10 message for a source whose `kind` has no policy — the fail-closed branch. Not a BDD
+ * contract string (the P3.8/P4.17 scenarios only cover the two known kinds), but it obeys the fit
+ * criterion's one requirement of every abort message: it NAMES the failing template. The offending
+ * `kind` is echoed so the operator can see what arrived.
+ */
+function unknownKindMessage(name, kind) {
+    return `built-in template integrity check failed: ${name} (unrecognized kind "${kind}")`;
+}
+/**
+ * The policy for `kind`, or `undefined` when there is none.
+ *
+ * `INTEGRITY_POLICY[kind]` on its own is FAIL-OPEN at runtime: TypeScript types the result as always
+ * present, but a `kind` outside the union — reachable through a cast, a JS caller, a JSON boundary, or
+ * a future disk-derived source list — yields `undefined` (or, for `constructor`/`toString`/`__proto__`,
+ * an inherited `Object.prototype` member), and the call on it throws a `TypeError`. That throw escapes
+ * `initWingfoilProject`, whose guard-5 call sits outside its `try`/`catch`, as an uncaught exception
+ * instead of the `VALIDATION` CoreResult / exit 1 REQ-SEC-10 demands. `hasOwnProperty` keeps inherited
+ * members out, so an unrecognized kind resolves to `undefined` and the caller fails it closed.
+ */
+function policyFor(kind) {
+    return Object.prototype.hasOwnProperty.call(INTEGRITY_POLICY, kind) ? INTEGRITY_POLICY[kind] : undefined;
+}
+/**
+ * Schema-check every `sources` entry, in list order (REQ-SYS-07: deterministic, no unordered
+ * iteration), and return the FIRST one that fails — or `null` when every source is valid (including
+ * the trivial, always-passing case of an empty list, which is what `src/storage/templates.ts`'s
+ * `builtinTemplateSources` derives from the P1.1 minimal skeleton, whose built-in directory holds only
+ * a `.gitkeep`; `templateScaffold` yields the six P3.8 built-in directives since
+ * `task-057-builtin-directive-templates`).
+ *
+ * FAILS CLOSED on an unrecognized `kind`: a source whose kind has no {@link INTEGRITY_POLICY} entry is
+ * reported as a failure ({@link unknownKindMessage}) rather than skipped or thrown on — it cannot be
+ * checked, so it must not be installed.
+ *
+ * Callers — `initWingfoilProject` AND `initWingfoilStorage`, both in `src/core/init.ts`; every
+ * `initStorage` write path there is one — MUST run this before writing any file: REQ-SEC-10's fit
+ * criterion requires the abort to happen "before writing partial assets". This function itself never
+ * writes or reads from disk, so calling it before the scaffold write is sufficient to satisfy that
+ * ordering.
+ */
+function verifyBuiltinTemplates(sources) {
+    for (const source of sources) {
+        const policy = policyFor(source.kind);
+        if (policy === undefined) {
+            return {
+                name: source.name,
+                kind: source.kind,
+                message: unknownKindMessage(source.name, String(source.kind)),
+            };
+        }
+        if (!policy.isValid(source)) {
+            return { name: source.name, kind: source.kind, message: policy.message(source.name) };
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=builtin-integrity.js.map

package/dist/core/builtin-integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-integrity.js","sourceRoot":"","sources":["../../src/core/builtin-integrity.ts"],"names":[],"mappings":";;AAsJA,wDAiBC;AAvKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,iDAA4D;AAC5D,wCAAsG;AACtG,8CAAyD;AACzD,+CAA8C;AAe9C;;;;;;GAMG;AACH,SAAS,sBAAsB,CAAC,MAA6B;IAC3D,MAAM,eAAe,GAAG,IAAA,4BAAkB,EAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3D,IAAI,eAAe,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAA,sBAAS,EAAC,eAAe,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACrD,IAAA,0BAAa,EAAC,6BAAoB,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACvD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,MAA6B;IAC1D,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAA,sBAAS,EAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACpD,IAAA,0BAAa,EAAC,iBAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3C,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAQD;;;;;;;;;GASG;AACH,MAAM,gBAAgB,GAA2D;IAC/E,SAAS,EAAE;QACT,OAAO,EAAE,sBAAsB;QAC/B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,uDAAuD,IAAI,EAAE;KACjF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,qBAAqB;QAC9B,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,uCAAuC,IAAI,EAAE;KACjE;CACF,CAAC;AAEF;;;;;GAKG;AACH,SAAS,kBAAkB,CAAC,IAAY,EAAE,IAAY;IACpD,OAAO,6CAA6C,IAAI,wBAAwB,IAAI,IAAI,CAAC;AAC3F,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,SAAS,CAAC,IAAyB;IAC1C,OAAO,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3G,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,SAAgB,sBAAsB,CACpC,OAAyC;IAEzC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,OAAO;gBACL,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;aAC9D,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACxF,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/confinement.d.ts

@@ -0,0 +1,57 @@
+import { type CoreResult } from './types';
+/**
+ * Refuse, before anything on disk changes, a target whose **real** path lies outside the project
+ * root.
+ *
+ * Resolution is the point. A prefix check over `relativePath` cannot see this: the path this bug is
+ * about — `.wingfoil/directives/custom/legacy-rule.md` under a `custom` that is a symlink to another
+ * directory — is inside the project in every segment and outside it on the filesystem. So the check
+ * resolves first and compares afterwards.
+ *
+ * Returns a `VALIDATION` `CoreResult.error`, which `exitCodeForError` maps to exit **1**: a
+ * well-formed invocation refused on the state of the repository, never the `2` that
+ * `spec-005-cli-command-contract` §1 reserves for a malformed one. The message names both spellings
+ * of the path — the one the operator typed against and the one it really resolves to — because the
+ * two differing is the entire finding, and it deliberately carries no child-process text
+ * (`bug-071`/`bug-093`).
+ *
+ * **What it answers, and what it does not.** This decides where the path *leads*: the target's
+ * parent is real-resolved and its own name is kept, which is right for a deletion and insufficient
+ * for a write ({@link resolveRealPathInRoot}'s own doc, `bug-120`). A caller that is about to
+ * **write** asks {@link requireConfinedWriteTarget} instead, which adds the second question this one
+ * does not ask.
+ *
+ * @param root - Project root.
+ * @param relativePath - Root-relative POSIX path of the file the operation is about to touch.
+ * @param action - The verb for the refusal's first clause, e.g. `'remove'` → `cannot remove '<path>'`
+ *   (P3.3's own message shape, shared with `requireCustomAsset`).
+ */
+export declare function requireConfinedTarget(root: string, relativePath: string, action: string): CoreResult<void>;
+/**
+ * {@link requireConfinedTarget} plus the question a **write** has to ask and a delete must not: the
+ * target's own name may not be a symbolic link (task-106,
+ * `bug-120-a-symlinked-document-leaf-is-followed-by-the-write`).
+ *
+ * `unlinkSync` acts on a link; `writeFileSync` follows it. So the parent-resolved, leaf-unresolved
+ * shape that makes a symlinked directive file removable (`bug-044`'s benign case) lets a write land
+ * wherever the link points — measured on the four Memory transition verbs, which rewrote a linked
+ * document *outside the project root* and then failed with git's own text (`bug-120` D2). The
+ * asymmetry is therefore read per verb, which is `dl-086`'s ground and is argued there rather than
+ * here: resolve the parent everywhere, refuse a symlinked leaf where the syscall would follow it.
+ *
+ * Order matters and is the confinement one first: a path that leaves the project is reported as
+ * leaving the project, whatever its leaf is, so the operator reads the boundary finding and not a
+ * narrower one that happens to fire first. Both refusals are `VALIDATION` → exit `1`, and the
+ * symlink sentence is {@link symlinkTargetRefusal}, shared verbatim with the `StorageError`
+ * `memory add` raises through `resolveConfinedMemoryPath`, so the two surfaces cannot drift.
+ *
+ * The TOCTOU window between this check and the write is real and is not closable on a path-based
+ * API — Node's `fs` exposes no `O_NOFOLLOW` (see {@link targetIsSymlink}). This turns a routine,
+ * self-inflicted loss into a refusal; it is not an adversarial defence.
+ *
+ * @param root - Project root.
+ * @param relativePath - Root-relative POSIX path of the file the operation is about to write.
+ * @param action - The verb for the refusal's first clause, e.g. `'write'` → `cannot write '<path>'`.
+ */
+export declare function requireConfinedWriteTarget(root: string, relativePath: string, action: string): CoreResult<void>;
+//# sourceMappingURL=confinement.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"confinement.d.ts","sourceRoot":"","sources":["../../src/core/confinement.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,UAAU,CAAC,IAAI,CAAC,CAUlB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,UAAU,CAAC,IAAI,CAAC,CAKlB"}

package/dist/core/confinement.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireConfinedTarget = requireConfinedTarget;
+exports.requireConfinedWriteTarget = requireConfinedWriteTarget;
+/**
+ * Project-root confinement as a mutating-op **pre-flight** (REQ-SEC-06 —
+ * `task-102`, `bug-044-symlinked-directives-custom-escapes-confinement`; extended to the write
+ * paths' own question by `task-106`, `bug-120`).
+ *
+ * The boundary is decided once, in `src/storage/confinement.ts`; this is the thin layer that turns
+ * that answer into the `CoreResult` a core operation returns, exactly as `requireGitIdentity`
+ * (REQ-SEC-01) and `requireCustomAsset` (REQ-SEC-07) do for their own rules. It lives in `src/core`
+ * for their reason too: the rule crosscuts pillars, and the CLI and MCP surfaces must enforce it
+ * identically because they run the same function (REQ-SYS-05).
+ *
+ * Two entry points, because a delete and a write do not ask the same thing:
+ * {@link requireConfinedTarget} for an operation whose syscall acts on a link (`unlinkSync`), and
+ * {@link requireConfinedWriteTarget} for one whose syscall follows it (`writeFileSync`).
+ *
+ * **Why a pre-flight and not a check at the write.** `bug-044`'s whole defect is order. The shipped
+ * `directive remove` unlinked the outside file and only then failed, on `git add`, with a raw
+ * `execFileSync` message — so the operator lost a file, got git's text instead of a mapped refusal,
+ * and no commit recorded any of it. A check that runs after the deletion reports a loss it could
+ * have prevented; the refusal has to land before the filesystem is touched at all.
+ *
+ * **Baseline.** This guard resolves against the **working tree**, not `HEAD`, and that is deliberate
+ * — a departure from the `command-baseline` directive's read half, argued (as that directive
+ * requires) in `task-102`'s Execution Notes and in the decision-log filed from them, never settled
+ * here. The one-line reason: what this predicts is where `unlinkSync` — or, on the write path,
+ * `writeFileSync` — will land, and both follow the symlinks that are on disk, not the ones a commit
+ * records.
+ */
+const node_path_1 = require("node:path");
+const confinement_1 = require("../storage/confinement");
+const types_1 = require("./types");
+/**
+ * Refuse, before anything on disk changes, a target whose **real** path lies outside the project
+ * root.
+ *
+ * Resolution is the point. A prefix check over `relativePath` cannot see this: the path this bug is
+ * about — `.wingfoil/directives/custom/legacy-rule.md` under a `custom` that is a symlink to another
+ * directory — is inside the project in every segment and outside it on the filesystem. So the check
+ * resolves first and compares afterwards.
+ *
+ * Returns a `VALIDATION` `CoreResult.error`, which `exitCodeForError` maps to exit **1**: a
+ * well-formed invocation refused on the state of the repository, never the `2` that
+ * `spec-005-cli-command-contract` §1 reserves for a malformed one. The message names both spellings
+ * of the path — the one the operator typed against and the one it really resolves to — because the
+ * two differing is the entire finding, and it deliberately carries no child-process text
+ * (`bug-071`/`bug-093`).
+ *
+ * **What it answers, and what it does not.** This decides where the path *leads*: the target's
+ * parent is real-resolved and its own name is kept, which is right for a deletion and insufficient
+ * for a write ({@link resolveRealPathInRoot}'s own doc, `bug-120`). A caller that is about to
+ * **write** asks {@link requireConfinedWriteTarget} instead, which adds the second question this one
+ * does not ask.
+ *
+ * @param root - Project root.
+ * @param relativePath - Root-relative POSIX path of the file the operation is about to touch.
+ * @param action - The verb for the refusal's first clause, e.g. `'remove'` → `cannot remove '<path>'`
+ *   (P3.3's own message shape, shared with `requireCustomAsset`).
+ */
+function requireConfinedTarget(root, relativePath, action) {
+    const resolved = (0, confinement_1.resolveRealPathInRoot)(root, relativePath);
+    if (resolved.within)
+        return (0, types_1.coreOk)(undefined);
+    return (0, types_1.coreErr)({
+        code: 'VALIDATION',
+        message: `cannot ${action} '${relativePath}': it resolves to '${resolved.real}', outside the project root. ` +
+            'Nothing has been written or deleted — this check runs before the operation touches the filesystem; ' +
+            'check whether a directory on the way to it is a symlink.',
+    });
+}
+/**
+ * {@link requireConfinedTarget} plus the question a **write** has to ask and a delete must not: the
+ * target's own name may not be a symbolic link (task-106,
+ * `bug-120-a-symlinked-document-leaf-is-followed-by-the-write`).
+ *
+ * `unlinkSync` acts on a link; `writeFileSync` follows it. So the parent-resolved, leaf-unresolved
+ * shape that makes a symlinked directive file removable (`bug-044`'s benign case) lets a write land
+ * wherever the link points — measured on the four Memory transition verbs, which rewrote a linked
+ * document *outside the project root* and then failed with git's own text (`bug-120` D2). The
+ * asymmetry is therefore read per verb, which is `dl-086`'s ground and is argued there rather than
+ * here: resolve the parent everywhere, refuse a symlinked leaf where the syscall would follow it.
+ *
+ * Order matters and is the confinement one first: a path that leaves the project is reported as
+ * leaving the project, whatever its leaf is, so the operator reads the boundary finding and not a
+ * narrower one that happens to fire first. Both refusals are `VALIDATION` → exit `1`, and the
+ * symlink sentence is {@link symlinkTargetRefusal}, shared verbatim with the `StorageError`
+ * `memory add` raises through `resolveConfinedMemoryPath`, so the two surfaces cannot drift.
+ *
+ * The TOCTOU window between this check and the write is real and is not closable on a path-based
+ * API — Node's `fs` exposes no `O_NOFOLLOW` (see {@link targetIsSymlink}). This turns a routine,
+ * self-inflicted loss into a refusal; it is not an adversarial defence.
+ *
+ * @param root - Project root.
+ * @param relativePath - Root-relative POSIX path of the file the operation is about to write.
+ * @param action - The verb for the refusal's first clause, e.g. `'write'` → `cannot write '<path>'`.
+ */
+function requireConfinedWriteTarget(root, relativePath, action) {
+    const confined = requireConfinedTarget(root, relativePath, action);
+    if (!confined.ok)
+        return confined;
+    if (!(0, confinement_1.targetIsSymlink)((0, node_path_1.join)(root, relativePath)))
+        return (0, types_1.coreOk)(undefined);
+    return (0, types_1.coreErr)({ code: 'VALIDATION', message: (0, confinement_1.symlinkTargetRefusal)(action, relativePath) });
+}
+//# sourceMappingURL=confinement.js.map

package/dist/core/confinement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confinement.js","sourceRoot":"","sources":["../../src/core/confinement.ts"],"names":[],"mappings":";;AA6DA,sDAcC;AA4BD,gEASC;AAhHD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,yCAAiC;AAEjC,wDAAsG;AAEtG,mCAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,SAAgB,qBAAqB,CACnC,IAAY,EACZ,YAAoB,EACpB,MAAc;IAEd,MAAM,QAAQ,GAAG,IAAA,mCAAqB,EAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC3D,IAAI,QAAQ,CAAC,MAAM;QAAE,OAAO,IAAA,cAAM,EAAO,SAAS,CAAC,CAAC;IACpD,OAAO,IAAA,eAAO,EAAC;QACb,IAAI,EAAE,YAAY;QAClB,OAAO,EACL,UAAU,MAAM,KAAK,YAAY,sBAAsB,QAAQ,CAAC,IAAI,+BAA+B;YACnG,qGAAqG;YACrG,0DAA0D;KAC7D,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,0BAA0B,CACxC,IAAY,EACZ,YAAoB,EACpB,MAAc;IAEd,MAAM,QAAQ,GAAG,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,CAAC,QAAQ,CAAC,EAAE;QAAE,OAAO,QAAQ,CAAC;IAClC,IAAI,CAAC,IAAA,6BAAe,EAAC,IAAA,gBAAI,EAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAAE,OAAO,IAAA,cAAM,EAAO,SAAS,CAAC,CAAC;IAC/E,OAAO,IAAA,eAAO,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,IAAA,kCAAoB,EAAC,MAAM,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AAC9F,CAAC"}

package/dist/core/context.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Agent execution context assembly (task-037-role-task-scoped-context, REQ-STATE-05) — the
+ * `directive-loader` + a minimal `context-builder` slice of
+ * `spec-012-context-loader-relevance-filtering` (§1 "placement & responsibilities", §5 "Directive
+ * resolution"). Satisfies REQ-STATE-05's Fit Criterion, verbatim: "The assembled context object
+ * exposes separate `dna`, `memory`, `directives` sections; it contains 100% of the role's assigned
+ * directives and 0 directives of other roles."
+ *
+ * **Archived elements are excluded** (REQ-STATE-06, the `{deprecated, superseded}` set ratified by
+ * `dl-028-archived-states-excluded-from-context`): {@link assembleExecutionContext} drops a resolved
+ * element whose `status` is archived, through the shared `isArchivedStatus` primitive rather than any
+ * local notion of "archived". This closed `bug-010-deprecated-reaches-agent-context` — which this
+ * header previously recorded as an open gap — together with the `wingfoil://memory/{type}` collection
+ * Resource, the other surface that bug covered (`task-069-fix-archived-excluded-from-agent-context`).
+ *
+ * Still deliberately NOT the full spec-012 pipeline: no `ContextRequest`/`stateRef` pinning, no tiered
+ * (T1–T4) Memory relevance ranking, no bounding caps, and no canonical byte-for-byte Markdown
+ * serialization (§7). Those are split across sibling Wave-1 v0.2 tasks
+ * (task-035-bounded-context-relevance REQ-PERF-05, task-038-deprecated-excluded-from-context
+ * REQ-STATE-06) and v0.3 (`REQ-SYS-07`, `REQ-PERF-01`, `REQ-STATE-09`, the real `agent execute`
+ * CLI/MCP surface) — see this task's Execution Notes for the full scope decision. This module wraps
+ * only existing, already-shipped primitives: `loadDirectives`/`loadRolesYaml` (`./loaders`),
+ * `findMemoryDocumentByTypeAndId` and `isArchivedStatus` (`../memory`, task-011/task-035) — no
+ * scan/parse logic and no second status predicate is reimplemented here.
+ */
+import { type MemoryDocumentSummary } from '../memory';
+import type { MemoryYaml } from '../memory/schema';
+import type { RolesYaml } from '../directives/schema';
+import type { DnaYaml } from '../dna/schema';
+import type { DirectiveFile } from './loaders';
+/**
+ * The outcome of {@link resolveRoleDirectives}: the resolved directive files **and** any operator
+ * diagnostics produced while resolving them.
+ *
+ * `warnings` is returned rather than written to `stderr` (or to a logger) on purpose: this is a
+ * context-building path, where REQ-SYS-07 requires the output to be a pure function of the inputs.
+ * A returned array keeps the diagnostic deterministic, unit-testable without capturing process
+ * streams, and free for the eventual CLI/MCP surface (`task-055-auto-load-directives-by-role`) to
+ * render however that surface renders warnings.
+ */
+export interface RoleDirectiveResolution {
+    /** Deduplicated by directive id and sorted ascending by id — see {@link resolveRoleDirectives}. */
+    readonly directives: readonly DirectiveFile[];
+    /** Operator diagnostics, in a fixed order. Empty when the role's bindings are unremarkable. */
+    readonly warnings: readonly string[];
+}
+/**
+ * The outcome of {@link selectDirectivesById}: one winning file per directive id, and one shadow
+ * warning per id that more than one file defines.
+ */
+export interface DirectiveSelection {
+    /** Winning file per directive id, keyed and iterated in ascending id order. */
+    readonly byId: ReadonlyMap<string, DirectiveFile>;
+    /** `directive '<id>' defined in <path>, <path>; using <winner>` — one per shadowed id, ascending by id. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Deduplicate `directiveFiles` by `frontmatter.id` — the one place WingFoil decides which of several
+ * same-id directive files is in force. Both {@link resolveRoleDirectives} (context assembly) and the
+ * `directives list` payload (`./directives-list.ts`, `dl-042-directives-list-output-contract` A) call
+ * this, so the rule the listing *reports* is the rule context assembly *applies*.
+ *
+ * - Precedence: `custom/` wins over `built-in/`, then smallest path (see `compareDirectivePrecedence`).
+ * - A shadowed file is **reported, never silently dropped** (dl-037 B.1): one warning per shadowed id,
+ *   naming every file that defines it (in precedence-independent path order) and the winner.
+ * - `ids`, when given, restricts selection (and warnings) to those directive ids.
+ */
+export declare function selectDirectivesById(directiveFiles: readonly DirectiveFile[], ids?: ReadonlySet<string>): DirectiveSelection;
+/**
+ * Resolve the directives bound to `role` — its own `roles.yaml` `assignments[role]` entries plus every
+ * `global` directive — per `spec-012-context-loader-relevance-filtering` §5 and
+ * `dl-029-role-with-no-directive-assignments` (`ready`, option (c)).
+ *
+ * Behaviour, point by point:
+ *
+ * - **Globals are unconditional** (spec-012 §5). Every role gets them, including a role with no
+ *   bindings of its own — globals exist precisely so that no role can be configured out of
+ *   `security-secrets` (dl-029, Rationale).
+ * - **A role that contributes no assignments of its own** — absent from `assignments`, or bound to an
+ *   explicitly empty list — resolves to exactly the globals **and** produces the warning
+ *   `no directives assigned to role '<role>'`. This is dl-029's ratified hybrid, and it is the
+ *   behaviour the edge scenario of `p3-directives/P3.6-auto-load-by-role.feature` specifies
+ *   ("the agent context contains only the global directives" + that warning). Never an error.
+ *   Role-name lookup reads **own** properties only, so a role named after an `Object.prototype`
+ *   member (`toString`, `constructor`, …) is treated as unbound like any other unknown role.
+ * - **Deduplicated by directive id, `custom/` winning over `built-in/`** (spec-012 §5, dl-037 A.1),
+ *   through the shared {@link selectDirectivesById}; each shadowed id the role is bound to adds a
+ *   warning naming the files and the winner (dl-037 B.1).
+ * - **A dangling binding is reported** — an id bound to the role (own assignment or global) with no
+ *   file in `directiveFiles` adds `directive '<id>' bound to role '<role>' has no directive file`
+ *   (`dl-042-directives-list-output-contract` D). It is still not an error: the rest resolves.
+ * - **Sorted ascending by directive id** (spec-012 §5: "never rely on `roles.yaml` listing order or
+ *   file-system enumeration order", REQ-SYS-07).
+ * - `warnings` has a fixed order: the no-assignments warning, then dangling ids ascending, then
+ *   shadowed ids ascending.
+ *
+ * This is REQ-STATE-05's Fit Criterion made concrete: for any two distinct roles with disjoint
+ * `assignments`, the resolved sets are disjoint too (100% of one role's directives, 0% of the other's).
+ */
+export declare function resolveRoleDirectives(directiveFiles: readonly DirectiveFile[], rolesYaml: RolesYaml, role: string): RoleDirectiveResolution;
+/** The active Memory element an execution context is scoped to (spec-012 §2 `ContextRequest.element`,
+ * narrowed here to just `type`/`id` — this task does not implement the full `ContextRequest` shape). */
+export interface ExecutionContextElement {
+    readonly type: string;
+    readonly id: string;
+}
+/**
+ * The assembled execution context (REQ-STATE-05 Fit Criterion, P5.4.4 "a context object containing
+ * distinct DNA, Memory, and Directives sections", "each section is individually addressable"): three
+ * plain, independently-readable properties — `context.dna`, `context.memory`,
+ * `context.directives` — never merged into one flat structure.
+ */
+export interface ExecutionContext {
+    /** The full parsed `dna.yaml` (P5.4.4: DNA section — this task does not sub-select DNA sections by
+     * scope, unlike spec-012 §4's full `dna-loader`; that selection logic is out of this task's scope). */
+    readonly dna: DnaYaml;
+    /** This role's assigned directives + global, resolved by {@link resolveRoleDirectives}. */
+    readonly directives: readonly DirectiveFile[];
+    /** Memory relevant to `element` — today, exactly the element's own document (0 or 1 entries), and
+     * empty when that document is archived (REQ-STATE-06; see {@link assembleExecutionContext}); the
+     * full T1–T4 tiered relevance expansion is task-035/038/v0.3's scope (see the module doc comment). */
+    readonly memory: readonly MemoryDocumentSummary[];
+    /** Operator diagnostics gathered during assembly — currently only
+     * {@link RoleDirectiveResolution.warnings}: no-assignments (dl-029), dangling binding (dl-042 D),
+     * shadowed directive (dl-037 B.1). Diagnostics *about* the context, not content
+     * *of* it: spec-012 §7's canonical envelope has no warnings section, so this never enters the
+     * serialized payload. */
+    readonly warnings: readonly string[];
+}
+/** Inputs to {@link assembleExecutionContext} — every pillar's config, already loaded by its own
+ * loader (`./loaders.ts`), plus the `role`/`element` the context is being assembled for. Nothing here
+ * reads the filesystem itself beyond resolving `element` via `findMemoryDocumentByTypeAndId`. */
+export interface ExecutionContextInputs {
+    /** Project root the Memory element lookup resolves against (same root the pillar loaders were
+     * called with). */
+    readonly root: string;
+    readonly dna: DnaYaml;
+    readonly memoryYaml: MemoryYaml;
+    readonly directiveFiles: readonly DirectiveFile[];
+    readonly rolesYaml: RolesYaml;
+    readonly role: string;
+    readonly element: ExecutionContextElement;
+}
+/**
+ * Assemble a role- and task-scoped {@link ExecutionContext} (REQ-STATE-05) from already-loaded pillar
+ * config. Given the same inputs and unchanged on-disk Memory content, the output is deep-equal across
+ * calls: the function itself introduces no wall-clock, randomness, or unordered iteration
+ * (REQ-SYS-07's discipline, applied to this narrower slice per REQ-STATE-05's own rationale "crisp,
+ * low-noise context; determinism"), and `directives` is totally ordered by
+ * {@link resolveRoleDirectives}.
+ *
+ * `memory` resolves `element` via `findMemoryDocumentByTypeAndId`
+ * (`task-011-mcp-resources-read-only`). Two properties of that primitive are inherited here and are
+ * worth stating plainly:
+ *
+ * - It is **not** a single addressed read. It walks the Memory document paths derived from
+ *   `memoryYaml` in sorted order and YAML-parses each document's frontmatter until one matches
+ *   `element.type`/`element.id`, so cost grows with the size of the Memory tree (bounding that is
+ *   `task-035-bounded-context-relevance`'s REQ-PERF-05 scope, not this task's).
+ * - It therefore **can throw**. An `element` that matches nothing yields an empty `memory` array
+ *   rather than an error — an unresolvable element is the caller's concern to surface — but a
+ *   `ValidationError` (`E_YAML_PARSE_ERROR`) propagates out of assembly if any document visited
+ *   during that walk has unparseable frontmatter. This function adds no `try`/`catch` of its own.
+ *
+ * `memory` **is** filtered by document status, in one direction only: a resolved element whose
+ * `status` is archived — `{deprecated, superseded}`, per the shared {@link isArchivedStatus}
+ * (`../memory`, the set ratified by `dl-028-archived-states-excluded-from-context`) — is dropped,
+ * leaving `memory` empty. That is REQ-STATE-06's Fit Criterion as amended: "a `deprecated` or
+ * `superseded` document never appears in an assembled agent context". The filter is applied to the
+ * lookup's *result* rather than pushed into `findMemoryDocumentByTypeAndId`, because that same
+ * primitive also serves `wingfoil://memory/{type}/{id}`, where explicit retrieval of archived content
+ * must keep working.
+ *
+ * `draft` is deliberately **not** excluded here, unlike in `./relevance.ts`. That module filters
+ * *candidate* documents for relevance (spec-012 §6, which does bar `draft` from a context); this
+ * function resolves the **subject** element the context is being assembled for (spec-012 §3's
+ * `resolve-element` stage), and blanking the context for a task still in `draft` would defeat the
+ * point of assembling it. dl-028 ratified the archived set as `{deprecated, superseded}` and did not
+ * put `draft` in it.
+ *
+ * An archived element produces no warning: {@link ExecutionContext.warnings} carries
+ * directive-resolution diagnostics only (dl-029, dl-037, dl-042), and adding an unratified entry would change a payload
+ * REQ-SYS-07 governs. An archived element is therefore indistinguishable here from an unresolvable
+ * one — both yield `memory: []`.
+ */
+export declare function assembleExecutionContext(inputs: ExecutionContextInputs): ExecutionContext;
+//# sourceMappingURL=context.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/core/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAmD,KAAK,qBAAqB,EAAE,MAAM,WAAW,CAAC;AACxG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,WAAW,uBAAuB;IACtC,mGAAmG;IACnG,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C,+FAA+F;IAC/F,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAWD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IAClD,2GAA2G;IAC3G,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAoBD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,SAAS,aAAa,EAAE,EACxC,GAAG,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,GACxB,kBAAkB,CAuBpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,SAAS,aAAa,EAAE,EACxC,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,GACX,uBAAuB,CAczB;AAED;wGACwG;AACxG,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B;2GACuG;IACvG,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;IAC9C;;0GAEsG;IACtG,QAAQ,CAAC,MAAM,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAClD;;;;6BAIyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED;;iGAEiG;AACjG,MAAM,WAAW,sBAAsB;IACrC;uBACmB;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,SAAS,aAAa,EAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,uBAAuB,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CASzF"}