wingfoil 0.2.1

package/dist/core/directive-assign.js

@@ -0,0 +1,352 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkAssignable = checkAssignable;
+exports.checkUnreferenced = checkUnreferenced;
+exports.updateRoleAssignments = updateRoleAssignments;
+/**
+ * Role ↔ directive binding support — the `roles.yaml`-facing half of the Directives pillar's
+ * commands. It began as `wingfoil directive assign`'s support module (task-051-directive-assign,
+ * P3.2), whose two pieces were built so that `directive remove` (P3.3, task-052) and
+ * multi-directive assignment (P3.7, task-056) would not re-derive them; it now holds **three**
+ * pieces, because P3.3 turned out to need a different one:
+ *
+ * **What `directive remove` actually uses.** It uses {@link checkUnreferenced} — which task-052
+ * *contributed* here, it did not inherit it — and it uses **neither** of the two task-051 pieces.
+ * Not {@link checkAssignable}: a removal has no role argument to validate. And, importantly, **not**
+ * {@link updateRoleAssignments}: P3.3 Scenario 2 *refuses* a still-assigned directive rather than
+ * unbinding it, so a removal has no `roles.yaml` write to make at all and never reaches the
+ * `setRoleAssignmentsInText` → fallback path below. (Correcting task-051's original prediction, which
+ * `dl-062-roles-yaml-unwritable-fallback` quotes from this doc range as evidence that P3.3 would be a
+ * second consumer of that fallback decision. It is not.)
+ *
+ * **What P3.7 actually uses — now an observed fact, no longer a prediction.**
+ * `task-056-role-based-directive-assignment` shipped multi-directive assignment (P3.7, US-4-06) as a
+ * comma-separated `--directive` on the *same* `directive assign` verb — it registers no operation of
+ * its own — and it reuses **both** task-051 pieces **without a single change to this file**:
+ * {@link checkAssignable} already took a list and validated every id before anything was written
+ * (which is exactly P3.7 Sc.3's "no partial assignment is persisted"), and
+ * {@link updateRoleAssignments} already took an arbitrary `update` function. So P3.7 *is* the second
+ * consumer of the fallback decision that `dl-062-roles-yaml-unwritable-fallback` is about — it reaches
+ * the `setRoleAssignmentsInText` → fallback path below on exactly the same inputs `directive assign`
+ * always did, no more and no fewer.
+ *
+ * - {@link checkAssignable} — the pre-write validation: the role must be defined in `dna.yaml`
+ *   (REQ-SYS-08, via task-034's binding resolver `isRoleDefined`/`UnknownRoleError` — never the
+ *   approval-authority module, dl-033) and every directive id must exist under
+ *   `.wingfoil/directives/**` **as committed at `HEAD`** (built-in or custom alike: assignment binds
+ *   by id and modifies no asset, dl-037/dl-030). Both halves read the committed repository since
+ *   task-096 (`bug-086`); everything is checked before anything is written, so a request is applied
+ *   whole or not at all.
+ * - {@link checkUnreferenced} — the mirror-image pre-write validation for `directive remove` (P3.3,
+ *   task-052): REQ-SEC-07 clause (b), refusing to remove a directive any role — or `global` — still
+ *   binds, naming the referrer.
+ * - {@link updateRoleAssignments} — the ONE read → edit → validate → write → commit path for
+ *   `.wingfoil/roles.yaml`. It edits through the comment-preserving `setRoleAssignmentsInText`
+ *   (`src/directives/roles-edit.ts`); only when that cannot apply does it consider a whole-file
+ *   `dump`, and then only for a file with no comment to lose — otherwise it fails closed (bug-019's
+ *   lesson: never a silent comment loss). **This `#`-gated split is what `dl-062` ratified away**
+ *   (Q1 option 3, `ready`, approve commit `4cd1876`): `undefined` is to mean `CONFLICT` regardless of
+ *   any `#`, with the whole-file rewrite reachable only behind an explicit `--force` and a stderr
+ *   warning naming what it normalizes. That is **not implemented here** — it needs a
+ *   success-warning channel this codebase does not have (`CoreResult`'s success arm carries `value`
+ *   and `commit` and nothing else) — and is scheduled to v0.3 as its own task. The code below is
+ *   therefore knowingly one step behind a ratified decision; read `dl-062`, not this paragraph, for
+ *   the intended contract.
+ *
+ * Lives in `src/core` (not `src/directives`) for the same reason `directives-list.ts` does: it
+ * operates on `DirectiveFile` (`./loaders`) and returns `CoreResult`s, so a `src/directives` home
+ * would need a `core → directives → core` cycle.
+ */
+const path_1 = require("path");
+const js_yaml_1 = require("js-yaml");
+const roles_1 = require("../dna/roles");
+const roles_edit_1 = require("../directives/roles-edit");
+const schema_1 = require("../directives/schema");
+const storage_1 = require("../storage");
+const validation_1 = require("../validation");
+const loaders_1 = require("./loaders");
+const types_1 = require("./types");
+const write_guard_1 = require("./write-guard");
+/**
+ * A second sentence for the unknown-role refusal, appended **only** when the *working tree's*
+ * `dna.yaml` does define the role — the same diagnostic shape as `task-090`'s `workingTreeWouldGrant`
+ * (`./approval-authority.ts`): it tells a user whose editor shows the role why the tool disagrees,
+ * instead of leaving them to argue with the file on their screen. Any failure to read or parse the
+ * working-tree file is simply "no", so it can never change an outcome owned by `HEAD`.
+ */
+function workingTreeWouldDefine(root, role) {
+    try {
+        return (0, roles_1.isRoleDefined)((0, loaders_1.loadDnaYaml)(root), role);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 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.
+ */
+function checkAssignable(root, role, ids) {
+    let committed;
+    try {
+        committed = (0, loaders_1.loadDnaYamlAtHead)(root);
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        return {
+            code: 'VALIDATION',
+            message: `cannot resolve the role catalogue: the committed '${loaders_1.DNA_YAML_PATH}' (at HEAD) is not readable as DNA: ` +
+                `${error.message}. A role binding is validated against the catalogue the repository records (dl-080), so the ` +
+                'committed file must be valid; fix it and commit the fix, then retry.',
+            details: { issues: error.issues },
+        };
+    }
+    if (committed === null) {
+        return {
+            code: 'VALIDATION',
+            message: `cannot resolve the role catalogue: '${loaders_1.DNA_YAML_PATH}' is not committed at HEAD. A binding must reference a ` +
+                `role the repository records, not one a working tree holds (REQ-SYS-08, dl-080); commit '${loaders_1.DNA_YAML_PATH}' ` +
+                'first, then retry.',
+        };
+    }
+    if (!(0, roles_1.isRoleDefined)(committed, role)) {
+        const uncommittedRole = workingTreeWouldDefine(root, role)
+            ? ` — the working tree's '${loaders_1.DNA_YAML_PATH}' defines it, but that change is not committed, and a binding is ` +
+                `validated against the committed catalogue (REQ-SYS-08, dl-080); commit '${loaders_1.DNA_YAML_PATH}' first, then retry`
+            : '';
+        return { code: 'NOT_FOUND', message: `${new roles_1.UnknownRoleError(role).message}${uncommittedRole}` };
+    }
+    let inventory;
+    try {
+        inventory = (0, loaders_1.loadDirectivesAtHead)(root);
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        return {
+            code: 'VALIDATION',
+            message: `cannot resolve the directive inventory: a file committed under '${loaders_1.DIRECTIVES_DIR_PATH}' (at HEAD) is not ` +
+                `readable as a directive: ${error.message}. A binding is validated against the directives the repository ` +
+                'records (dl-080), so the committed files must be valid; fix it and commit the fix, then retry.',
+            details: { issues: error.issues },
+        };
+    }
+    const known = new Set(inventory.map((file) => file.frontmatter.id));
+    const unknown = ids.find((id) => !known.has(id));
+    return unknown === undefined ? undefined : { code: 'NOT_FOUND', message: `unknown directive: ${unknown}` };
+}
+/**
+ * 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.
+ */
+function checkUnreferenced(root, id) {
+    let rolesYaml;
+    try {
+        rolesYaml = (0, loaders_1.loadRolesYamlAtHead)(root);
+    }
+    catch (error) {
+        if (!(error instanceof validation_1.ValidationError))
+            throw error;
+        return {
+            code: 'VALIDATION',
+            message: `cannot resolve the directive bindings: the committed '${loaders_1.ROLES_YAML_PATH}' (at HEAD) is not readable as ` +
+                `role assignments: ${error.message}. Whether an asset may be deleted is answered from the bindings the ` +
+                'repository records (REQ-SEC-07, dl-080), so the committed file must be valid; fix it and commit the fix, ' +
+                'then retry.',
+            details: { issues: error.issues },
+        };
+    }
+    if (rolesYaml === null)
+        return undefined;
+    // `Object.entries` (own enumerable properties only) + an explicit ascending sort, never YAML
+    // mapping order — REQ-SYS-07, and the same walk `directives-list.ts` uses.
+    const [boundRole] = Object.entries(rolesYaml.assignments)
+        .filter(([, ids]) => ids.includes(id))
+        .map(([role]) => role)
+        .sort((a, b) => (a < b ? -1 : 1));
+    if (boundRole !== undefined) {
+        return { code: 'CONFLICT', message: `cannot remove '${id}': still assigned to role '${boundRole}'` };
+    }
+    if (rolesYaml.global.includes(id)) {
+        return { code: 'CONFLICT', message: `cannot remove '${id}': still assigned to every role via roles.yaml 'global'` };
+    }
+    return undefined;
+}
+function validationError(error) {
+    return (0, types_1.coreErr)({ code: 'VALIDATION', message: error.message, details: { issues: error.issues } });
+}
+/** Parse and schema-check `roles.yaml` text, as a plain object (for re-serialization) plus its typed view. */
+function parseRoles(text, filePath) {
+    let raw;
+    try {
+        raw = (0, validation_1.parseYaml)(text, filePath);
+    }
+    catch (error) {
+        // `parseYaml` wraps every YAML syntax failure in a `ValidationError` and throws nothing else
+        // (`src/validation/yaml.ts`).
+        return validationError(error);
+    }
+    const parsed = schema_1.RolesYaml.safeParse(raw);
+    if (!parsed.success)
+        return validationError((0, validation_1.toValidationError)(parsed.error, filePath));
+    return (0, types_1.coreOk)({ raw: raw, roles: parsed.data });
+}
+/**
+ * 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`.
+ */
+function updateRoleAssignments(root, role, update, message) {
+    // dl-080 (B) / bug-078: refuse while `roles.yaml` carries modifications this operation does not
+    // own — otherwise an unrelated uncommitted edit rides into `wf(directive): assign <id> to <role>`,
+    // whose subject names only the binding. Before the read, so the refusal cannot depend on a value
+    // the dirty copy contributed. An ABSENT `roles.yaml` is clean (porcelain reports nothing), which is
+    // what keeps the first `directive assign` on a fresh project working.
+    const unmodified = (0, write_guard_1.requireUnmodifiedTarget)(root, loaders_1.ROLES_YAML_PATH);
+    if (!unmodified.ok)
+        return unmodified;
+    const filePath = (0, path_1.join)(root, loaders_1.ROLES_YAML_PATH);
+    const exists = (0, storage_1.documentExists)(filePath);
+    const text = exists ? (0, storage_1.readDocument)(filePath) : '';
+    let raw = { version: 1, assignments: {}, global: [] };
+    let current = [];
+    if (exists) {
+        const parsed = parseRoles(text, filePath);
+        if (!parsed.ok)
+            return parsed;
+        raw = parsed.value.raw;
+        current = Object.prototype.hasOwnProperty.call(parsed.value.roles.assignments, role)
+            ? parsed.value.roles.assignments[role]
+            : [];
+    }
+    const next = update(current);
+    if (JSON.stringify(next) === JSON.stringify(current))
+        return (0, types_1.coreOk)({ assignments: current });
+    const wholeFile = () => (0, js_yaml_1.dump)({ ...raw, assignments: { ...raw.assignments, [role]: next } }, { lineWidth: -1 });
+    let serialized = exists ? (0, roles_edit_1.setRoleAssignmentsInText)(text, role, next) : wholeFile();
+    if (serialized === undefined) {
+        if (text.includes('#')) {
+            return (0, types_1.coreErr)({
+                code: 'CONFLICT',
+                message: `roles.yaml cannot be updated without discarding its comments; edit assignments.${role} by hand`,
+            });
+        }
+        serialized = wholeFile();
+    }
+    (0, storage_1.writeDocument)(filePath, serialized);
+    const sha = (0, storage_1.commitPaths)(root, [loaders_1.ROLES_YAML_PATH], message);
+    const leaked = (0, write_guard_1.committedScopeError)(root, sha, loaders_1.ROLES_YAML_PATH, serialized);
+    if (leaked)
+        return leaked;
+    return (0, types_1.coreOk)({ assignments: next }, { sha, message });
+}
+//# sourceMappingURL=directive-assign.js.map

package/dist/core/directive-assign.js.map

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

package/dist/core/directives-list.d.ts

@@ -0,0 +1,80 @@
+import type { DirectiveFrontmatter, RolesYaml } from '../directives/schema';
+import { type DirectiveFile } from './loaders';
+/**
+ * {@link DirectiveListEntry.assignment} for a directive no role names and `roles.yaml`'s `global`
+ * list does not carry. The exact wording is the BDD's own: P3.4's "each directive shows its assigned
+ * roles (or `unassigned`)".
+ */
+export declare const UNASSIGNED_ASSIGNMENT = "unassigned";
+/**
+ * {@link DirectiveListEntry.assignment} prefix for a directive in `roles.yaml`'s `global` list.
+ * Phrased from `spec-012-context-loader-relevance-filtering` §5's own description of that list — the
+ * "global directives applied to all roles" — because such a directive is bound to *every* role and so
+ * is neither enumerable as a role list nor, in any sense, `unassigned`.
+ */
+export declare const GLOBAL_ASSIGNMENT = "global (all roles)";
+/** One directive in the listing: the file, and who is bound to it. */
+export interface DirectiveListEntry {
+    /** Root-relative path as `loadDirectives` records it (`directives/<built-in|custom>/<name>.md`). */
+    readonly path: string;
+    /** The file's validated frontmatter, unchanged — carries `id`, `name`, `kind`, `title`, `tags`, `ref`. */
+    readonly frontmatter: DirectiveFrontmatter;
+    /**
+     * Role names whose `roles.yaml` `assignments` entry names this directive's **`frontmatter.id`**
+     * (never its `name` — `assignments` values are ids, per `src/directives/schema.ts`'s `RolesYaml`),
+     * ascending. Empty for a directive nothing binds *and* for a `global` one, whose binding is carried
+     * by {@link global} instead — listing every role name for a global directive would require reading
+     * `dna.yaml`'s role catalogue, a different pillar (REQ-SYS-02), and would still misreport a role
+     * that has no `assignments` entry of its own.
+     */
+    readonly roles: readonly string[];
+    /** `true` when `roles.yaml`'s `global` list names this directive's id — it applies to every role. */
+    readonly global: boolean;
+    /**
+     * The two fields above rendered as one human-readable string, so P3.4's `unassigned` wording is
+     * present in the payload itself and reads identically under `--format console`, `json` and `yaml`.
+     * (`--format console` renders the payload as pretty-printed JSON today; `renderSuccess`,
+     * `src/cli/output.ts`, states that a command-specific console rendering needs a command-specific
+     * spec, and none exists for this command.) Never display-only: `roles`/`global` carry the same
+     * fact structurally for machine consumers.
+     */
+    readonly assignment: string;
+}
+/**
+ * The `directives list` payload (`dl-042-directives-list-output-contract`): the inventory and the
+ * operator diagnostics about it, side by side. `[AUTHORING]` like {@link DirectiveListEntry} (dl-042 C).
+ */
+export interface DirectiveListing {
+    /** One entry per directive file on disk — never deduplicated (see the module doc comment). */
+    readonly entries: readonly DirectiveListEntry[];
+    /** Shadowed ids (always); no-assignments and dangling-binding warnings (with a role filter). Fixed
+     * order, empty when there is nothing to report. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Annotate `directiveFiles` with their `roles.yaml` bindings, optionally keeping only those bound to
+ * `role`, and attach the warnings described on {@link DirectiveListing}.
+ *
+ * `rolesYaml` is optional: `undefined` means the project has no `roles.yaml`, which is "nothing is
+ * bound yet" (every entry `unassigned`), not a failure — the Directives files and `roles.yaml` are
+ * independent artefacts (REQ-SYS-02) and directives can exist before anyone binds them.
+ *
+ * The `role` filter keeps an entry when that role's own `assignments` name it **or** when it is
+ * `global`, because `spec-012` §5 makes globals unconditional for every role. An unbound or unknown
+ * role is therefore not an error and not empty: it lists exactly the globals, matching
+ * `dl-029-role-with-no-directive-assignments` (the ratified hybrid) rather than inventing a
+ * `NOT_FOUND` this read-only command has no grounds to return.
+ */
+export declare function buildDirectiveListing(directiveFiles: readonly DirectiveFile[], rolesYaml: RolesYaml | undefined, role?: string): DirectiveListing;
+/**
+ * Load both pillars' artefacts and build the listing — the filesystem half of
+ * {@link buildDirectiveListing}, kept separate so the annotation rules stay unit-testable without
+ * touching disk.
+ *
+ * `.wingfoil/roles.yaml` is read only when it exists; when it does exist it goes through the same
+ * validating `loadRolesYaml` every other consumer uses, so a malformed or schema-invalid file still
+ * raises a `ValidationError` (surfaced as `VALIDATION`, exit 1) rather than being silently downgraded
+ * to "nothing is bound". Only a genuinely absent file is tolerated.
+ */
+export declare function loadDirectiveListing(root: string, role?: string): DirectiveListing;
+//# sourceMappingURL=directives-list.d.ts.map

package/dist/core/directives-list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directives-list.d.ts","sourceRoot":"","sources":["../../src/core/directives-list.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAG5E,OAAO,EAAiC,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,uBAAuB,CAAC;AAEtD,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,0GAA0G;IAC1G,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,qGAAqG;IACrG,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,QAAQ,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAChD;uDACmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAsCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,cAAc,EAAE,SAAS,aAAa,EAAE,EACxC,SAAS,EAAE,SAAS,GAAG,SAAS,EAChC,IAAI,CAAC,EAAE,MAAM,GACZ,gBAAgB,CAsBlB;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAIlF"}

package/dist/core/directives-list.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GLOBAL_ASSIGNMENT = exports.UNASSIGNED_ASSIGNMENT = void 0;
+exports.buildDirectiveListing = buildDirectiveListing;
+exports.loadDirectiveListing = loadDirectiveListing;
+/**
+ * `wingfoil directives list` — the listing behind the `directives.directivesList` operation
+ * (P3.4 / US-4-04, BDD `p3-directives/P3.4-directives-list.feature`; spec-006-core-domain-api §3
+ * pins the operation's name and both surfaces). task-053-directives-list.
+ *
+ * **What this is.** An *inventory* of the directive files installed under `.wingfoil/directives/**`,
+ * each annotated with the roles that name it in `.wingfoil/roles.yaml`. It is deliberately NOT the
+ * per-role *resolved* set that {@link resolveRoleDirectives} (`./context.ts`) produces for an agent
+ * execution context; the two answer different questions and are kept separate:
+ *
+ * - `resolveRoleDirectives` answers "which rules must role R obey", so it deduplicates by directive
+ *   id and returns one file per id (`spec-012-context-loader-relevance-filtering` §5).
+ * - This function answers "which directive files exist here, and who is bound to them" (P3.4: "so I
+ *   manage rules with visibility"), so it **never deduplicates**. When a built-in and a custom file
+ *   share an id, both appear, each with its own `path`. `spec-012` §5, as amended by
+ *   `dl-037-builtin-vs-custom-directive-precedence` (option B.1), requires that a shadowed directive
+ *   be "reported, never silently dropped"; a listing that hid one would reproduce exactly the defect
+ *   dl-037 was raised about, in the one command whose purpose is directive visibility.
+ *
+ * **Warnings** (`dl-042-directives-list-output-contract` A + D, task-055-auto-load-directives-by-role).
+ * The payload is {@link DirectiveListing} — `entries` plus a `warnings` channel — so the two things a
+ * reader cannot see in the inventory are said out loud: which of two same-id files is in force, and
+ * whether a role is bound at all. Neither is computed here. Without a role filter the warnings are
+ * {@link selectDirectivesById}'s shadow warnings over every file; with `--role` they are exactly
+ * {@link resolveRoleDirectives}' warnings for that role (no-assignments, dangling binding, shadowed
+ * ids). Both live in `./context.ts`, so the precedence rule the listing reports is the one context
+ * assembly applies — it is never implemented twice.
+ *
+ * **Placement.** This lives in `src/core` rather than `src/directives` for the same reason
+ * `resolveRoleDirectives` does: the {@link DirectiveFile} shape it operates on is declared in
+ * `./loaders.ts`, so putting it under `src/directives` would create a `core → directives → core`
+ * import cycle. `src/directives` keeps owning the pillar's own schemas (REQ-SYS-02).
+ *
+ * **Determinism** (REQ-SYS-07): the output is a pure function of the two files on disk. Entry order
+ * is `loadDirectives`'s own lexicographic path order; the per-directive `roles` array is built by
+ * walking `assignments`' role names in sorted order, never in YAML mapping order.
+ */
+const path_1 = require("path");
+const storage_1 = require("../storage");
+const context_1 = require("./context");
+const loaders_1 = require("./loaders");
+/**
+ * {@link DirectiveListEntry.assignment} for a directive no role names and `roles.yaml`'s `global`
+ * list does not carry. The exact wording is the BDD's own: P3.4's "each directive shows its assigned
+ * roles (or `unassigned`)".
+ */
+exports.UNASSIGNED_ASSIGNMENT = 'unassigned';
+/**
+ * {@link DirectiveListEntry.assignment} prefix for a directive in `roles.yaml`'s `global` list.
+ * Phrased from `spec-012-context-loader-relevance-filtering` §5's own description of that list — the
+ * "global directives applied to all roles" — because such a directive is bound to *every* role and so
+ * is neither enumerable as a role list nor, in any sense, `unassigned`.
+ */
+exports.GLOBAL_ASSIGNMENT = 'global (all roles)';
+/** `roles.yaml` as seen when the file is absent: nothing bound, no globals. */
+const NO_BINDINGS = { assignments: {}, global: [] };
+/**
+ * Invert `roles.yaml`'s `assignments` (role → directive ids) into directive id → role names.
+ *
+ * A `Map` rather than a plain object on purpose: the keys are directive ids read from files on disk,
+ * so an id like `constructor` or `__proto__` would otherwise collide with an `Object.prototype`
+ * member — the same hazard `ownAssignments` guards against in `./context.ts`, arriving here from the
+ * opposite direction. Role names are walked in sorted order (REQ-SYS-07), which is also what makes
+ * each entry's `roles` array ascending without a second sort.
+ */
+function rolesByDirectiveId(rolesYaml) {
+    const byId = new Map();
+    if (rolesYaml === undefined)
+        return byId;
+    // `Object.entries` (own enumerable properties only) rather than `Object.keys` + an index read: it
+    // hands back the id array already typed, with no `?? []` fallback that `noUncheckedIndexedAccess`
+    // would otherwise force onto a key that by construction exists.
+    const assignments = Object.entries(rolesYaml.assignments).sort(([a], [b]) => (a < b ? -1 : 1));
+    for (const [role, ids] of assignments) {
+        for (const id of ids) {
+            const roles = byId.get(id);
+            if (roles === undefined)
+                byId.set(id, [role]);
+            // A role listing the same directive id twice must not produce a duplicated role name.
+            else if (!roles.includes(role))
+                roles.push(role);
+        }
+    }
+    return byId;
+}
+/** Render {@link DirectiveListEntry.assignment} from the entry's `roles`/`global` pair. */
+function renderAssignment(roles, isGlobal) {
+    const parts = isGlobal ? [exports.GLOBAL_ASSIGNMENT, ...roles] : [...roles];
+    return parts.length > 0 ? parts.join(', ') : exports.UNASSIGNED_ASSIGNMENT;
+}
+/**
+ * Annotate `directiveFiles` with their `roles.yaml` bindings, optionally keeping only those bound to
+ * `role`, and attach the warnings described on {@link DirectiveListing}.
+ *
+ * `rolesYaml` is optional: `undefined` means the project has no `roles.yaml`, which is "nothing is
+ * bound yet" (every entry `unassigned`), not a failure — the Directives files and `roles.yaml` are
+ * independent artefacts (REQ-SYS-02) and directives can exist before anyone binds them.
+ *
+ * The `role` filter keeps an entry when that role's own `assignments` name it **or** when it is
+ * `global`, because `spec-012` §5 makes globals unconditional for every role. An unbound or unknown
+ * role is therefore not an error and not empty: it lists exactly the globals, matching
+ * `dl-029-role-with-no-directive-assignments` (the ratified hybrid) rather than inventing a
+ * `NOT_FOUND` this read-only command has no grounds to return.
+ */
+function buildDirectiveListing(directiveFiles, rolesYaml, role) {
+    const byId = rolesByDirectiveId(rolesYaml);
+    const globalIds = new Set(rolesYaml?.global ?? []);
+    const entries = [];
+    for (const file of directiveFiles) {
+        const roles = byId.get(file.frontmatter.id) ?? [];
+        const isGlobal = globalIds.has(file.frontmatter.id);
+        if (role !== undefined && !isGlobal && !roles.includes(role))
+            continue;
+        entries.push({
+            path: file.path,
+            frontmatter: file.frontmatter,
+            // Copy, so two entries sharing an id (a shadowed built-in/custom pair) never alias one array.
+            roles: [...roles],
+            global: isGlobal,
+            assignment: renderAssignment(roles, isGlobal),
+        });
+    }
+    const warnings = role === undefined
+        ? (0, context_1.selectDirectivesById)(directiveFiles).warnings
+        : (0, context_1.resolveRoleDirectives)(directiveFiles, rolesYaml ?? NO_BINDINGS, role).warnings;
+    return { entries, warnings };
+}
+/**
+ * Load both pillars' artefacts and build the listing — the filesystem half of
+ * {@link buildDirectiveListing}, kept separate so the annotation rules stay unit-testable without
+ * touching disk.
+ *
+ * `.wingfoil/roles.yaml` is read only when it exists; when it does exist it goes through the same
+ * validating `loadRolesYaml` every other consumer uses, so a malformed or schema-invalid file still
+ * raises a `ValidationError` (surfaced as `VALIDATION`, exit 1) rather than being silently downgraded
+ * to "nothing is bound". Only a genuinely absent file is tolerated.
+ */
+function loadDirectiveListing(root, role) {
+    const directiveFiles = (0, loaders_1.loadDirectives)(root);
+    const rolesYaml = (0, storage_1.documentExists)((0, path_1.join)(root, '.wingfoil', 'roles.yaml')) ? (0, loaders_1.loadRolesYaml)(root) : undefined;
+    return buildDirectiveListing(directiveFiles, rolesYaml, role);
+}
+//# sourceMappingURL=directives-list.js.map

package/dist/core/directives-list.js.map

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