wingfoil 0.2.1

package/dist/core/context.js

@@ -0,0 +1,192 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.selectDirectivesById = selectDirectivesById;
+exports.resolveRoleDirectives = resolveRoleDirectives;
+exports.assembleExecutionContext = assembleExecutionContext;
+/**
+ * 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.
+ */
+const memory_1 = require("../memory");
+const builtin_asset_1 = require("./builtin-asset");
+/** `assignments` is a plain object parsed from YAML, so a role named `toString`, `constructor`,
+ * `valueOf`, `hasOwnProperty` or `__proto__` would otherwise resolve to an inherited
+ * `Object.prototype` member instead of `undefined`. Read own properties only. */
+function ownAssignments(rolesYaml, role) {
+    return Object.prototype.hasOwnProperty.call(rolesYaml.assignments, role)
+        ? rolesYaml.assignments[role]
+        : undefined;
+}
+/**
+ * The single precedence rule between two directive files that share an id
+ * (`dl-037-builtin-vs-custom-directive-precedence` A.1, `spec-012` §5): negative when `a` wins.
+ *
+ * A `custom/` file beats any other — "custom" decided by REQ-SEC-07's structural discriminator
+ * {@link isRemovableCustomAssetPath}, which keys on the `custom` directory segment and accepts both
+ * path separators (`loadDirectives` builds `path` with the platform `join`). `frontmatter.kind` is not
+ * consulted: it can disagree with the directory, and the directory is what REQ-SEC-07 trusts. Within
+ * the same tier the lexicographically smallest `path` wins, so the order is total and independent of
+ * the order files arrive in (REQ-SYS-07).
+ */
+function compareDirectivePrecedence(a, b) {
+    const aCustom = (0, builtin_asset_1.isRemovableCustomAssetPath)('directive', a.path);
+    const bCustom = (0, builtin_asset_1.isRemovableCustomAssetPath)('directive', b.path);
+    if (aCustom !== bCustom)
+        return aCustom ? -1 : 1;
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+/**
+ * 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.
+ */
+function selectDirectivesById(directiveFiles, ids) {
+    const candidates = new Map();
+    for (const file of directiveFiles) {
+        const id = file.frontmatter.id;
+        if (ids !== undefined && !ids.has(id))
+            continue;
+        const list = candidates.get(id);
+        if (list === undefined)
+            candidates.set(id, [file]);
+        else
+            list.push(file);
+    }
+    const byId = new Map();
+    const warnings = [];
+    // Ascending by id (REQ-SYS-07): never `roles.yaml` listing order or file-system enumeration order.
+    // `candidates` is keyed by id, so no two keys are equal and a two-way compare is total here.
+    for (const [id, files] of [...candidates].sort(([a], [b]) => (a < b ? -1 : 1))) {
+        const [winner] = [...files].sort(compareDirectivePrecedence);
+        byId.set(id, winner);
+        if (files.length > 1) {
+            const paths = files.map((file) => file.path).sort();
+            warnings.push(`directive '${id}' defined in ${paths.join(', ')}; using ${winner.path}`);
+        }
+    }
+    return { byId, warnings };
+}
+/**
+ * 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).
+ */
+function resolveRoleDirectives(directiveFiles, rolesYaml, role) {
+    const assigned = ownAssignments(rolesYaml, role);
+    const warnings = assigned === undefined || assigned.length === 0
+        ? [`no directives assigned to role '${role}'`]
+        : [];
+    const allowedIds = new Set([...(assigned ?? []), ...rolesYaml.global]);
+    const selection = selectDirectivesById(directiveFiles, allowedIds);
+    const dangling = [...allowedIds].filter((id) => !selection.byId.has(id)).sort();
+    for (const id of dangling)
+        warnings.push(`directive '${id}' bound to role '${role}' has no directive file`);
+    warnings.push(...selection.warnings);
+    return { directives: [...selection.byId.values()], warnings };
+}
+/**
+ * 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: []`.
+ */
+function assembleExecutionContext(inputs) {
+    const { directives, warnings } = resolveRoleDirectives(inputs.directiveFiles, inputs.rolesYaml, inputs.role);
+    const doc = (0, memory_1.findMemoryDocumentByTypeAndId)(inputs.root, inputs.memoryYaml, inputs.element.type, inputs.element.id);
+    // `frontmatter` is untyped (`Record<string, unknown>`), so project `status` to the
+    // `string | undefined` shape `isArchivedStatus` takes — a non-string `status` is never archived,
+    // exactly as that predicate's contract states.
+    const status = typeof doc?.frontmatter.status === 'string' ? doc.frontmatter.status : undefined;
+    const memory = doc !== undefined && !(0, memory_1.isArchivedStatus)(status) ? [doc] : [];
+    return { dna: inputs.dna, directives, memory, warnings };
+}
+//# sourceMappingURL=context.js.map

package/dist/core/context.js.map

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

package/dist/core/directive-assign.d.ts

@@ -0,0 +1,131 @@
+import type { CoreError, CoreResult } from './types';
+/** The outcome of {@link updateRoleAssignments}: the role's list as it stands afterwards. */
+export interface RoleAssignmentUpdate {
+    /** `assignments.<role>` after the update (unchanged when nothing needed writing). */
+    readonly assignments: readonly string[];
+}
+/**
+ * Validate an assignment request before anything is written. The role is checked first (it is the
+ * binding's target and the REQ-SYS-08 check), then each id in argument order; the first failure wins.
+ *
+ * **The role catalogue is read from the `dna.yaml` committed at `HEAD`**, never from the working tree
+ * (task-091, `bug-082-directive-assign-validates-role-against-worktree`,
+ * `dl-080-which-baseline-each-command-reads` option (B)). This function therefore takes `root`, not a
+ * `DnaYaml`: a caller cannot hand it a working-tree catalogue even by accident, which is what makes
+ * the committed baseline a property of the read rather than of a precondition someone must remember
+ * to run. An uncommitted role used to be enough to commit a `roles.yaml` binding to a role no commit
+ * of the repository defines — a dangling reference by construction, since **REQ-SYS-08** binds
+ * directives by role and every other clone sees the binding without the role.
+ *
+ * The cost was measured and accepted at `dl-080`'s ratification: extending the catalogue becomes
+ * *edit, commit, then assign*. `dl-081`/`task-093` are building the `dna` verbs that fold the first
+ * two steps into one command; nothing here waits on them.
+ *
+ * Two fail-closed refusals come with the baseline, mirroring `requireApprovalAuthority`'s: no
+ * committed `dna.yaml` at all, and a committed one that does not parse or validate.
+ *
+ * **The directive inventory is read the same way**, since task-096 /
+ * `bug-086-directive-inventory-read-from-the-worktree` — `loadDirectivesAtHead`, the tree at `HEAD`.
+ * task-091 left this half on the files on disk and offered a boundary for it (the role catalogue is
+ * *governance*, the directive file is the *asset*); its reviewer showed the boundary does not hold,
+ * and `bug-086` settles that what actually separated them was **cost**: reading the inventory at a
+ * revision needs a directory listing at a revision, which `src/storage` did not have. It has one now
+ * (`listPathsAtRev`), so the parameter is gone too and the two halves of this one function read one
+ * baseline. Before that, an untracked directive file produced a committed `roles.yaml` binding to a
+ * directive present in no commit.
+ *
+ * An absent or empty committed inventory needs no special case: no id is known, so every request is
+ * refused with `unknown directive: <id>`. That is the right answer rather than a tolerated one — "may
+ * this id be bound" needs the *positive* fact that a directive with it exists, and a missing record
+ * cannot supply one. (Contrast {@link checkUnreferenced}, which needs the *absence* of a fact and is
+ * therefore satisfied by a missing record.)
+ *
+ * @param root - Project root; both committed baselines are read from it.
+ * @param role - The role to bind to.
+ * @param ids - The directive ids to bind.
+ * @returns `undefined` when assignable; otherwise an error carrying P3.2's exact message verbatim as
+ *   its first sentence — `unknown role '<role>' (not defined in dna.yaml)` or
+ *   `unknown directive: <id>` — or, for an absent/unreadable committed catalogue or an unreadable
+ *   committed directive file, a `VALIDATION` refusal naming the baseline.
+ */
+export declare function checkAssignable(root: string, role: string, ids: readonly string[]): CoreError | undefined;
+/**
+ * REQ-SEC-07 clause (b) for the Directives surface — *"removal of a still-referenced custom asset is
+ * rejected naming the referrer"* — assigned to `task-052-directive-remove` by
+ * `dl-030-req-sec-07-referenced-asset-ownership` (`ready`, option (b)). The counterpart to
+ * {@link checkAssignable}: that one guards a binding being *made*, this one guards an asset being
+ * removed while a binding still names it. It lives here for the same reason, over the same
+ * `roles.yaml` shape.
+ *
+ * `roles.yaml` binds by directive **`frontmatter.id`** (`src/directives/schema.ts`'s `RolesYaml`), so
+ * the comparison is against the id, never the filename.
+ *
+ * Two referrer kinds, checked in this order:
+ *
+ * 1. A role whose own `assignments` entry names the id → P3.3's verbatim message
+ *    `cannot remove '<id>': still assigned to role '<role>'`
+ *    (`p3-directives/P3.3-directive-remove.feature`, "Error - removing a directive still referenced"
+ *    — do not reword). When several roles bind it the **alphabetically first** is named: the message
+ *    must be a pure function of the file's content, never of YAML mapping order (REQ-SYS-07), and
+ *    `directives-list.ts` already walks role names in the same ascending order.
+ * 2. `roles.yaml`'s `global` list, which binds the directive to *every* role
+ *    (`spec-012-context-loader-relevance-filtering` §5) and is therefore the strongest reference of
+ *    all. `[AUTHORING]`: P3.3 pins only the per-role wording, and a global binding cannot be phrased
+ *    in it without naming a role the file does not name — so the message is
+ *    `cannot remove '<id>': still assigned to every role via roles.yaml 'global'`. Recorded in
+ *    `task-052-directive-remove`'s Execution Notes and raised for ratification, not assumed settled.
+ *
+ * A directive referenced from a *workflow* step is deliberately not checked: `src/workflow/schema.ts`
+ * has no field that can reference a directive, so P3.3's "or workflow step" precondition is vacuous
+ * today, and P4.9's workflow half of clause (b) has no owner in v0.2 per `dl-030`.
+ *
+ * **The bindings are read from the `roles.yaml` committed at `HEAD`**, never from the working tree
+ * (task-096, `bug-086-directive-inventory-read-from-the-worktree`, `dl-080` option (B)). This
+ * function therefore takes `root`, not a `RolesYaml`: a caller cannot hand it a working-tree copy
+ * even by accident, which is what makes the committed baseline a property of the read. Before that,
+ * deleting the two `- <id>` lines **without committing** was enough to walk past this check entirely
+ * and **destroy** a file the committed `roles.yaml` still bound — on the only verb in the system that
+ * deletes an artefact, and against the one clause REQ-SEC-07 (b) exists to enforce.
+ *
+ * A `roles.yaml` that is **not committed at all** is still "no bindings yet" (task-051/task-053's
+ * reading) and permits the removal. That is not a fail-open tolerance: this check needs the *negative*
+ * fact *nothing names this id*, and a record that does not exist answers it. (Contrast
+ * {@link checkAssignable}, which needs a positive fact and therefore refuses when its record is
+ * missing.) A committed `roles.yaml` that does not **validate** is the genuinely unanswerable case,
+ * and it refuses.
+ *
+ * @param root - Project root; the committed `roles.yaml` is read from it (`loadRolesYamlAtHead`).
+ * @param id - The directive id about to be removed.
+ * @returns `undefined` when nothing references it; otherwise a `CONFLICT` error (exit 1) carrying the
+ *   message above. `CONFLICT` and not `VALIDATION`: the request is well-formed and the *state*
+ *   refuses it — the same distinction `directiveCreate` draws for `directive already exists: <name>`,
+ *   as against `requireCustomAsset`'s `VALIDATION` for a request inadmissible on its own terms. An
+ *   unreadable committed `roles.yaml` is `VALIDATION`, naming the baseline.
+ */
+export declare function checkUnreferenced(root: string, id: string): CoreError | undefined;
+/**
+ * Apply `update` to `assignments.<role>` in `.wingfoil/roles.yaml` and commit the result as ONE commit
+ * staging only that file.
+ *
+ * - A missing `roles.yaml` means "no bindings yet" (task-053's reading) and is created with a
+ *   deterministic `dump` — there is nothing to preserve.
+ * - An unchanged list is an idempotent success: nothing is written and no commit is made.
+ * - The edit goes through `setRoleAssignmentsInText`, keeping every comment and unrelated line. When it
+ *   cannot apply, a whole-file `dump` is used only if the file contains no `#` at all; otherwise the
+ *   result is `CONFLICT` and the file is left untouched.
+ * - No second schema pass on the output is needed: the in-place edit is only accepted when its
+ *   re-parse equals the validated input with `assignments.<role>` replaced by a string list
+ *   (`setRoleAssignmentsInText`'s self-check), and the whole-file `dump` serializes exactly that object.
+ *
+ * Commits through `commitPaths`, which since bug-027's fix (`git commit --only -- <paths>`) records
+ * exactly the path it is given and leaves anything else staged untouched.
+ *
+ * @param root - Project root.
+ * @param role - The role whose list is updated (already validated by the caller).
+ * @param update - Pure function from the current list to the desired list.
+ * @param message - The commit subject.
+ * @returns The role's resulting list, with the commit when one was made.
+ * @throws whatever `git` raises inside `commitPaths`.
+ */
+export declare function updateRoleAssignments(root: string, role: string, update: (current: readonly string[]) => readonly string[], message: string): CoreResult<RoleAssignmentUpdate>;
+//# sourceMappingURL=directive-assign.d.ts.map

package/dist/core/directive-assign.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directive-assign.d.ts","sourceRoot":"","sources":["../../src/core/directive-assign.ts"],"names":[],"mappings":"AA2EA,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAIrD,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAiBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,SAAS,CAkDzG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CA8BjF;AAqBD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,EAAE,EACzD,OAAO,EAAE,MAAM,GACd,UAAU,CAAC,oBAAoB,CAAC,CA6ClC"}