wingfoil 0.2.2 → 0.3.0

package/dist/directives/schema.d.ts

@@ -1,34 +1,34 @@
 /**
- * DirectiveFrontmatter schema (task-004-decoupled-pillars, REQ-SYS-02) — the fourth pillar named by
- * this task's Acceptance Criteria ("memory.yaml, dna.yaml, directives/*.yaml, and workflows.yaml
- * each validate against their own Zod schema independently").
+ * DirectiveFrontmatter schema (task-004-decoupled-pillars, REQ-SYS-02) — the Directives pillar's
+ * per-file YAML frontmatter shape, validated independently of the other three pillars (`memory.yaml`,
+ * `dna.yaml`, `workflows.yaml`).
  *
- * UNLIKE memory.yaml/dna.yaml/workflows.yaml, there is currently no dedicated, approved tech-spec
- * for the Directives pillar's own file shape: spec-010-memory-frontmatter-schema's scope is
- * explicitly `docs/04_memory/**\/*.md frontmatter` (Memory documents), not
- * `.wingfoil/directives/**` (Directives files are `.md` with YAML frontmatter, not `.yaml` — the
- * AC's "directives/*.yaml" phrasing does not match the real file extension either). This schema is
- * therefore an [AUTHORING]-level minimal shape, grounded directly in the fields every one of the
- * twelve real files under `.wingfoil/directives/custom/*.md` actually carries (`id`,
- * `name`, `type: directive`, `kind`, `title`, `tags`, `ref`, and — on three files — `scope`), not a
- * transcription of an approved spec. See this task's Execution Notes for why this was not treated
- * as a hard STOP (design-gap) and the follow-up this leaves for the reviewer/approver (a candidate
- * `spec-013-directive-frontmatter-schema`).
+ * The shape is specified by `spec-013-directive-frontmatter-schema` (`approved`), which `task-004`'s
+ * fast-follow wrote to close the traceability gap this schema was first shipped with: its field table
+ * is the authority for every key below, and this file is its reference implementation. The files are
+ * `.md` with YAML frontmatter, not `.yaml` (spec-013 Context corrects REQ-SYS-02's
+ * "directives/*.yaml" wording).
  *
- * `name` is REQUIRED, not merely observed: REQ-SYS-02's own traceability cites
- * `p3-directives/P3.5-project-directives.feature`, whose "Error - a directive file missing required
- * header fields" scenario is explicit ("Given a custom directive file lacks its required 'name'
- * header ... Then loading reports the file as invalid") — the one piece of that BDD contract this
- * schema honors even without a tech-spec of its own.
+ * `name` is REQUIRED as a `[SPEC]` field: `p3-directives/P3.5-project-directives.feature`'s "Error - a
+ * directive file missing required header fields" scenario reports a file lacking `name` as invalid.
+ * The other required keys are `[AUTHORING]` (spec-013 Consequences).
+ *
+ * `scope` and `version` are declared optional keys since `task-144` (spec-013 Revision 2026-10-01;
+ * bug-113, bug-148): a directive carrying either one no longer prints spec-009's unknown-field warning.
+ * `scope` does not decide anything — `roles.yaml`'s `global:` list is the authority on which directives
+ * bind every role, and `directives list` reports a disagreement between the two (`src/core/directive-scope.ts`).
  *
  * `.passthrough()` per spec-009-validation-strategy §2, matching every other pillar schema.
  */
 import { z } from 'zod';
 /**
- * The YAML frontmatter of a `.wingfoil/directives/**\/*.md` file — the minimal [AUTHORING] shape
- * grounded in the fields the real custom directive files carry (see the module doc for why there is
- * no dedicated tech-spec). `name` is required per REQ-SYS-08's BDD contract. `.passthrough()` per
- * spec-009 §2.
+ * The YAML frontmatter of a `.wingfoil/directives/**\/*.md` file, per `spec-013`'s field table. `name`
+ * is required per P3.5's BDD contract. `scope` is any string: `global` is the one value spec-013
+ * defines, and `directives list` reports any other rather than failing the pillar (forward
+ * compatibility, approver ruling R2 2026-10-02). `version` is a string or a number, like
+ * `memory.yaml`'s and `roles.yaml`'s (R1); `./version` warns when a number loses what was written.
+ * `format` is the frontmatter's format, distinct from `version` (`dl-149`, task-251: absent = 1).
+ * `.passthrough()` per spec-009 §2.
  */
 export declare const DirectiveFrontmatter: z.ZodObject<{
     id: z.ZodString;
@@ -38,25 +38,30 @@ export declare const DirectiveFrontmatter: z.ZodObject<{
     title: z.ZodString;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
     ref: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    scope: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    format: z.ZodOptional<z.ZodNumber>;
 }, z.core.$loose>;
 /** Parsed shape of the {@link DirectiveFrontmatter} schema. */
 export type DirectiveFrontmatter = z.infer<typeof DirectiveFrontmatter>;
 /**
  * `.wingfoil/roles.yaml` schema (task-037-role-task-scoped-context, REQ-STATE-05's
  * `directive-loader`, P3.2/P3.7) — the role → directive binding config
- * `resolveRoleDirectives`/`assembleExecutionContext` (`src/core/context.ts`) resolve against. Same
- * [AUTHORING]-level rationale as {@link DirectiveFrontmatter}: no dedicated tech-spec covers this
- * pillar's own file shapes yet (spec-012-context-loader-relevance-filtering §5 describes the
- * `directive-loader`'s *behavior* — "look up the request role in `roles.yaml`" — but not roles.yaml's
- * own schema), so this is grounded directly in the fields the real, live
+ * `resolveRoleDirectives`/`assembleExecutionContext` (`src/core/context.ts`) resolve against. An
+ * [AUTHORING]-level shape: `spec-013` specifies the directive files only, and
+ * spec-012-context-loader-relevance-filtering §5 describes the `directive-loader`'s *behavior* — "look
+ * up the request role in `roles.yaml`" — but not roles.yaml's own schema, so this is grounded directly
+ * in the fields the real, live
  * `.wingfoil/roles.yaml` file carries: `version`, `assignments` (role name -> directive id
  * array), and `global` (directive ids applied to every role). `assignments` keys are role names
  * (validated against `dna.yaml`'s `team.roles` catalogue elsewhere, by REQ-SYS-08/task-034 — NOT here,
  * to keep this pillar's schema independent per REQ-SYS-02); `assignments` values and `global` entries
- * are directive **ids** (`DirectiveFrontmatter.id`), not `name`s. `.passthrough()` per spec-009 §2.
+ * are directive **ids** (`DirectiveFrontmatter.id`), not `name`s. `format` is the file's format
+ * (`dl-149`, task-251: absent = 1). `.passthrough()` per spec-009 §2.
  */
 export declare const RolesYaml: z.ZodObject<{
     version: z.ZodOptional<z.ZodNumber>;
+    format: z.ZodOptional<z.ZodNumber>;
     assignments: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
     global: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$loose>;

package/dist/directives/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/directives/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;iBAUjB,CAAC;AACjB,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,SAAS;;;;iBAMN,CAAC;AACjB,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/directives/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;iBAajB,CAAC;AACjB,+DAA+D;AAC/D,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS;;;;;iBAON,CAAC;AACjB,oDAAoD;AACpD,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,SAAS,CAAC,CAAC"}

package/dist/directives/schema.js

@@ -2,36 +2,37 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RolesYaml = exports.DirectiveFrontmatter = void 0;
 /**
- * DirectiveFrontmatter schema (task-004-decoupled-pillars, REQ-SYS-02) — the fourth pillar named by
- * this task's Acceptance Criteria ("memory.yaml, dna.yaml, directives/*.yaml, and workflows.yaml
- * each validate against their own Zod schema independently").
+ * DirectiveFrontmatter schema (task-004-decoupled-pillars, REQ-SYS-02) — the Directives pillar's
+ * per-file YAML frontmatter shape, validated independently of the other three pillars (`memory.yaml`,
+ * `dna.yaml`, `workflows.yaml`).
  *
- * UNLIKE memory.yaml/dna.yaml/workflows.yaml, there is currently no dedicated, approved tech-spec
- * for the Directives pillar's own file shape: spec-010-memory-frontmatter-schema's scope is
- * explicitly `docs/04_memory/**\/*.md frontmatter` (Memory documents), not
- * `.wingfoil/directives/**` (Directives files are `.md` with YAML frontmatter, not `.yaml` — the
- * AC's "directives/*.yaml" phrasing does not match the real file extension either). This schema is
- * therefore an [AUTHORING]-level minimal shape, grounded directly in the fields every one of the
- * twelve real files under `.wingfoil/directives/custom/*.md` actually carries (`id`,
- * `name`, `type: directive`, `kind`, `title`, `tags`, `ref`, and — on three files — `scope`), not a
- * transcription of an approved spec. See this task's Execution Notes for why this was not treated
- * as a hard STOP (design-gap) and the follow-up this leaves for the reviewer/approver (a candidate
- * `spec-013-directive-frontmatter-schema`).
+ * The shape is specified by `spec-013-directive-frontmatter-schema` (`approved`), which `task-004`'s
+ * fast-follow wrote to close the traceability gap this schema was first shipped with: its field table
+ * is the authority for every key below, and this file is its reference implementation. The files are
+ * `.md` with YAML frontmatter, not `.yaml` (spec-013 Context corrects REQ-SYS-02's
+ * "directives/*.yaml" wording).
  *
- * `name` is REQUIRED, not merely observed: REQ-SYS-02's own traceability cites
- * `p3-directives/P3.5-project-directives.feature`, whose "Error - a directive file missing required
- * header fields" scenario is explicit ("Given a custom directive file lacks its required 'name'
- * header ... Then loading reports the file as invalid") — the one piece of that BDD contract this
- * schema honors even without a tech-spec of its own.
+ * `name` is REQUIRED as a `[SPEC]` field: `p3-directives/P3.5-project-directives.feature`'s "Error - a
+ * directive file missing required header fields" scenario reports a file lacking `name` as invalid.
+ * The other required keys are `[AUTHORING]` (spec-013 Consequences).
+ *
+ * `scope` and `version` are declared optional keys since `task-144` (spec-013 Revision 2026-10-01;
+ * bug-113, bug-148): a directive carrying either one no longer prints spec-009's unknown-field warning.
+ * `scope` does not decide anything — `roles.yaml`'s `global:` list is the authority on which directives
+ * bind every role, and `directives list` reports a disagreement between the two (`src/core/directive-scope.ts`).
  *
  * `.passthrough()` per spec-009-validation-strategy §2, matching every other pillar schema.
  */
 const zod_1 = require("zod");
+const format_1 = require("../validation/format");
 /**
- * The YAML frontmatter of a `.wingfoil/directives/**\/*.md` file — the minimal [AUTHORING] shape
- * grounded in the fields the real custom directive files carry (see the module doc for why there is
- * no dedicated tech-spec). `name` is required per REQ-SYS-08's BDD contract. `.passthrough()` per
- * spec-009 §2.
+ * The YAML frontmatter of a `.wingfoil/directives/**\/*.md` file, per `spec-013`'s field table. `name`
+ * is required per P3.5's BDD contract. `scope` is any string: `global` is the one value spec-013
+ * defines, and `directives list` reports any other rather than failing the pillar (forward
+ * compatibility, approver ruling R2 2026-10-02). `version` is a string or a number, like
+ * `memory.yaml`'s and `roles.yaml`'s (R1); `./version` warns when a number loses what was written.
+ * `format` is the frontmatter's format, distinct from `version` (`dl-149`, task-251: absent = 1).
+ * `.passthrough()` per spec-009 §2.
  */
 exports.DirectiveFrontmatter = zod_1.z
     .object({
@@ -42,25 +43,30 @@ exports.DirectiveFrontmatter = zod_1.z
     title: zod_1.z.string(),
     tags: zod_1.z.array(zod_1.z.string()).optional(),
     ref: zod_1.z.array(zod_1.z.string()).optional(),
+    scope: zod_1.z.string().optional(),
+    version: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional(),
+    format: (0, format_1.formatField)(format_1.DIRECTIVE_FORMAT),
 })
     .passthrough();
 /**
  * `.wingfoil/roles.yaml` schema (task-037-role-task-scoped-context, REQ-STATE-05's
  * `directive-loader`, P3.2/P3.7) — the role → directive binding config
- * `resolveRoleDirectives`/`assembleExecutionContext` (`src/core/context.ts`) resolve against. Same
- * [AUTHORING]-level rationale as {@link DirectiveFrontmatter}: no dedicated tech-spec covers this
- * pillar's own file shapes yet (spec-012-context-loader-relevance-filtering §5 describes the
- * `directive-loader`'s *behavior* — "look up the request role in `roles.yaml`" — but not roles.yaml's
- * own schema), so this is grounded directly in the fields the real, live
+ * `resolveRoleDirectives`/`assembleExecutionContext` (`src/core/context.ts`) resolve against. An
+ * [AUTHORING]-level shape: `spec-013` specifies the directive files only, and
+ * spec-012-context-loader-relevance-filtering §5 describes the `directive-loader`'s *behavior* — "look
+ * up the request role in `roles.yaml`" — but not roles.yaml's own schema, so this is grounded directly
+ * in the fields the real, live
  * `.wingfoil/roles.yaml` file carries: `version`, `assignments` (role name -> directive id
  * array), and `global` (directive ids applied to every role). `assignments` keys are role names
  * (validated against `dna.yaml`'s `team.roles` catalogue elsewhere, by REQ-SYS-08/task-034 — NOT here,
  * to keep this pillar's schema independent per REQ-SYS-02); `assignments` values and `global` entries
- * are directive **ids** (`DirectiveFrontmatter.id`), not `name`s. `.passthrough()` per spec-009 §2.
+ * are directive **ids** (`DirectiveFrontmatter.id`), not `name`s. `format` is the file's format
+ * (`dl-149`, task-251: absent = 1). `.passthrough()` per spec-009 §2.
  */
 exports.RolesYaml = zod_1.z
     .object({
     version: zod_1.z.number().optional(),
+    format: (0, format_1.formatField)(format_1.ROLES_YAML_FORMAT),
     assignments: zod_1.z.record(zod_1.z.string(), zod_1.z.array(zod_1.z.string())),
     global: zod_1.z.array(zod_1.z.string()).default([]),
 })

package/dist/directives/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/directives/schema.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,6BAAwB;AAExB;;;;;GAKG;AACU,QAAA,oBAAoB,GAAG,OAAC;KAClC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,OAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC5B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,GAAG,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;CACpC,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;;;;;;;;;;GAaG;AACU,QAAA,SAAS,GAAG,OAAC;KACvB,MAAM,CAAC;IACN,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACxC,CAAC;KACD,WAAW,EAAE,CAAC"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/directives/schema.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,6BAAwB;AAExB,iDAAwF;AAExF;;;;;;;;GAQG;AACU,QAAA,oBAAoB,GAAG,OAAC;KAClC,MAAM,CAAC;IACN,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE;IACd,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,IAAI,EAAE,OAAC,CAAC,OAAO,CAAC,WAAW,CAAC;IAC5B,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE;IAChB,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE;IACjB,IAAI,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACpC,GAAG,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IACnC,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,OAAO,EAAE,OAAC,CAAC,KAAK,CAAC,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE;IACrD,MAAM,EAAE,IAAA,oBAAW,EAAC,yBAAgB,CAAC;CACtC,CAAC;KACD,WAAW,EAAE,CAAC;AAIjB;;;;;;;;;;;;;;GAcG;AACU,QAAA,SAAS,GAAG,OAAC;KACvB,MAAM,CAAC;IACN,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC9B,MAAM,EAAE,IAAA,oBAAW,EAAC,0BAAiB,CAAC;IACtC,WAAW,EAAE,OAAC,CAAC,MAAM,CAAC,OAAC,CAAC,MAAM,EAAE,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IACtD,MAAM,EAAE,OAAC,CAAC,KAAK,CAAC,OAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACxC,CAAC;KACD,WAAW,EAAE,CAAC"}

package/dist/directives/version.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A directive's `version:` frontmatter key is never a reason to fail the Directives pillar
+ * (`spec-013-directive-frontmatter-schema`, Revision 2026-10-01; approver ruling R1 at `task-144`'s
+ * review, 2026-10-02). It accepts a string or a number, like `memory.yaml`'s and `roles.yaml`'s own
+ * `version`. Two cases still deserve a word to the author, and this module decides them over the parsed
+ * frontmatter plus the frontmatter's own text:
+ *
+ * - **An unquoted number that does not read back as written.** YAML reads `version: 1.10` as the
+ *   number `1.1`, and `version: 1.0` as `1`: the digits the author typed are lost. The value loads as
+ *   parsed, and the warning tells the author to quote it.
+ * - **A value that is neither a string nor a number** (a list, a mapping, a boolean). It is dropped
+ *   before validation, with a warning, so the rest of the file — and every other directive — still
+ *   loads.
+ *
+ * Pure (REQ-SYS-07): the caller decides where the warning goes (`loadDirectiveInventory` puts it in its
+ * `warnings` as `directive '<.wingfoil/directives/…>': <warning>`).
+ */
+/** The parsed frontmatter, possibly without its `version`, and the warning to show, if any. */
+export interface DirectiveVersionCheck {
+    readonly data: unknown;
+    readonly warning: string | null;
+}
+/**
+ * Check `data.version` against the text it was parsed from. Returns `data` unchanged unless the
+ * version is neither a string nor a number, in which case a shallow copy without `version` is returned.
+ */
+export declare function checkDirectiveVersion(data: unknown, frontmatterText: string): DirectiveVersionCheck;
+//# sourceMappingURL=version.d.ts.map

package/dist/directives/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/directives/version.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,+FAA+F;AAC/F,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAWD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,qBAAqB,CAenG"}

package/dist/directives/version.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * A directive's `version:` frontmatter key is never a reason to fail the Directives pillar
+ * (`spec-013-directive-frontmatter-schema`, Revision 2026-10-01; approver ruling R1 at `task-144`'s
+ * review, 2026-10-02). It accepts a string or a number, like `memory.yaml`'s and `roles.yaml`'s own
+ * `version`. Two cases still deserve a word to the author, and this module decides them over the parsed
+ * frontmatter plus the frontmatter's own text:
+ *
+ * - **An unquoted number that does not read back as written.** YAML reads `version: 1.10` as the
+ *   number `1.1`, and `version: 1.0` as `1`: the digits the author typed are lost. The value loads as
+ *   parsed, and the warning tells the author to quote it.
+ * - **A value that is neither a string nor a number** (a list, a mapping, a boolean). It is dropped
+ *   before validation, with a warning, so the rest of the file — and every other directive — still
+ *   loads.
+ *
+ * Pure (REQ-SYS-07): the caller decides where the warning goes (`loadDirectiveInventory` puts it in its
+ * `warnings` as `directive '<.wingfoil/directives/…>': <warning>`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkDirectiveVersion = checkDirectiveVersion;
+/**
+ * The scalar written after `version:` on its own top-level line of `frontmatterText`, or `null` when
+ * there is no such line. A trailing `# comment` is not part of the value.
+ */
+function writtenVersionToken(frontmatterText) {
+    const match = /^version:[ \t]*([^\s#]+)/m.exec(frontmatterText);
+    return match?.[1] ?? null;
+}
+/**
+ * Check `data.version` against the text it was parsed from. Returns `data` unchanged unless the
+ * version is neither a string nor a number, in which case a shallow copy without `version` is returned.
+ */
+function checkDirectiveVersion(data, frontmatterText) {
+    if (data === null || typeof data !== 'object' || Array.isArray(data) || !('version' in data)) {
+        return { data, warning: null };
+    }
+    const { version, ...rest } = data;
+    if (typeof version === 'string')
+        return { data, warning: null };
+    if (typeof version === 'number') {
+        const written = writtenVersionToken(frontmatterText);
+        if (written === null || written === String(version))
+            return { data, warning: null };
+        return {
+            data,
+            warning: `version: ${written} reads as the number ${String(version)}; quote it (version: "${written}") to keep it as written`,
+        };
+    }
+    return { data: rest, warning: 'version must be a string or a number; ignored' };
+}
+//# sourceMappingURL=version.js.map

package/dist/directives/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/directives/version.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;GAgBG;;AAqBH,sDAeC;AA5BD;;;GAGG;AACH,SAAS,mBAAmB,CAAC,eAAuB;IAClD,MAAM,KAAK,GAAG,2BAA2B,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC;IAChE,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,IAAa,EAAE,eAAuB;IAC1E,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,IAAI,IAAI,CAAC,EAAE,CAAC;QAC7F,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACjC,CAAC;IACD,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,IAA+B,CAAC;IAC7D,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAChE,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,MAAM,OAAO,GAAG,mBAAmB,CAAC,eAAe,CAAC,CAAC;QACrD,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,MAAM,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACpF,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,YAAY,OAAO,wBAAwB,MAAM,CAAC,OAAO,CAAC,yBAAyB,OAAO,0BAA0B;SAC9H,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,+CAA+C,EAAE,CAAC;AAClF,CAAC"}

package/dist/dna/edit.d.ts

@@ -42,8 +42,9 @@ export type DnaTextEdit =
 };
 /**
  * Apply `edit` to the RAW TEXT of a `dna.yaml`, editing as few lines as possible, and return the new
- * text — or `undefined`, deliberately and not as an error, when no provably-minimal edit exists, so the
- * caller falls back to the whole-file `dump()`.
+ * text — or `undefined`, deliberately and not as an error, when no provably-minimal edit exists. The
+ * caller then refuses the write, or rewrites the whole file when `--force` authorizes it and says that
+ * the comments were not kept (task-193, `runDnaMutation` in `src/core`).
  *
  * `intended` is the document the mutation produced (`applyDnaMutation`'s `dna`). It serves twice: an
  * inline flow sequence is re-rendered from it rather than patched token-by-token, and — the part that
@@ -52,10 +53,10 @@ export type DnaTextEdit =
  * while key values are the contract; a mis-located edit fails the comparison and costs the comments,
  * never the content.
  *
- * Declines (returns `undefined`) when: the text is not one valid YAML document; a step of the path is
- * absent from the text; the target or a value it must rewrite spans more than its own line (a block
- * scalar, a nested block); a value has no single-line YAML form; or the result does not read back as
- * `intended`.
+ * Declines (returns `undefined`) when: the text is not one valid YAML document; an absent step of the
+ * path cannot be inserted (a sequence index, or a parent holding an inline value other than `{}`); the
+ * target spans more than its own line as a nested block (a block scalar is replaced, not declined); a
+ * value has no single-line YAML form; or the result does not read back as `intended`.
  */
 export declare function applyDnaEditInText(text: string, edit: DnaTextEdit, intended: unknown): string | undefined;
 //# sourceMappingURL=edit.d.ts.map

package/dist/dna/edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/dna/edit.ts"],"names":[],"mappings":"AA0BA,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,oFAAoF;AACpF,MAAM,MAAM,WAAW;AACrB,8FAA8F;AAC5F;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACjG,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE;AACxE,uDAAuD;GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;AAC9G,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAC/G,gEAAgE;GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;AAC9G,oGAAoG;GAClG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,CAAC;AA8YvE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAkBzG"}
+{"version":3,"file":"edit.d.ts","sourceRoot":"","sources":["../../src/dna/edit.ts"],"names":[],"mappings":"AA6BA,gGAAgG;AAChG,MAAM,MAAM,WAAW,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEhF,oFAAoF;AACpF,MAAM,MAAM,WAAW;AACrB,8FAA8F;AAC5F;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE;AACjG,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE;AACxE,uDAAuD;GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;AAC9G,sEAAsE;GACpE;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AAC/G,gEAAgE;GAC9D;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE;AAC9G,oGAAoG;GAClG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CAAE,CAAC;AA8bvE;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAyBzG"}

package/dist/dna/edit.js

@@ -16,9 +16,12 @@ exports.applyDnaEditInText = applyDnaEditInText;
  *
  * The safety contract is `setDnaValueInText`'s, unchanged and strengthened: every candidate edit is
  * verified by re-parsing it and comparing the **whole document** against the intended object before it
- * is returned, and anything that cannot be done provably-minimally returns `undefined` so the caller
- * falls back to `dump()` rather than writing something subtly wrong. A mis-located edit therefore
- * cannot corrupt a file; at worst it costs the comments.
+ * is returned, and anything that cannot be done provably-minimally returns `undefined` rather than
+ * writing something subtly wrong. A mis-located edit therefore cannot corrupt a file. Since task-193
+ * (`bug-019`, `bug-126`) the caller no longer falls back to `dump()` on its own: it refuses the write
+ * unless `--force` authorizes the whole-file rewrite, and a forced rewrite is reported in a warning.
+ * Absent keys (with absent parents), block-scalar values and CRLF files are edited here, so that
+ * refusal is left to shapes such as a key under a non-empty flow mapping.
  *
  * Pure and deterministic (REQ-SYS-07): a function of `(text, edit, intended)` alone — no wall-clock, no
  * randomness, no filesystem, and the input text is never mutated.
@@ -134,7 +137,7 @@ function locate(lines, path) {
 }
 /**
  * Render a value as the single-line YAML token `js-yaml` itself would emit — which is what keeps this
- * editor's bytes identical to the whole-file `dump()` fallback's at the same position, including
+ * editor's bytes identical to the `--force`d whole-file `dump()`'s at the same position, including
  * defensive quoting (`'2'` stays a string, `'y'` is quoted because YAML 1.1 reads a bare `y` as a
  * boolean).
  *
@@ -221,7 +224,14 @@ function deepEqual(a, b) {
         return false;
     return leftKeys.every((key) => Object.prototype.hasOwnProperty.call(right, key) && deepEqual(left[key], right[key]));
 }
-/** Write a value at the mapping key the path ends on, inserting the key when the block does not carry it. */
+/**
+ * Write a value at the mapping key the path ends on, inserting the key — and any of its parent keys the
+ * text does not carry — when it is absent ({@link insertMissingPath}).
+ *
+ * A key holding a block scalar (`>-`, `|`) is rewritten as a one-line key and its continuation lines
+ * are dropped: those lines ARE the old value, so removing them is the edit, not a loss (task-193,
+ * `bug-019`). An inline comment on the key line is kept, as for any other rewrite.
+ */
 function editSetScalar(lines, path, value) {
     const scalar = renderInline(value);
     const parentPath = path.slice(0, -1);
@@ -229,21 +239,62 @@ function editSetScalar(lines, path, value) {
     if (last === undefined || !('key' in last))
         return undefined;
     const parent = locate(lines, parentPath);
-    if (parent === undefined)
+    const existing = parent === undefined ? undefined : findKey(lines, parent.region, parent.indent, last.key);
+    if (existing === undefined) {
+        return insertMissingPath(lines, path, (indent) => [`${' '.repeat(indent)}${last.key}: ${scalar}`]);
+    }
+    const region = blockRegion(lines, existing);
+    const currentValue = (0, set_1.valueOf)(existing.rest);
+    if (currentValue.startsWith('|') || currentValue.startsWith('>')) {
+        lines.splice(existing.line, Math.max(region.end, existing.line + 1) - existing.line, rewriteKeyLine(lines[existing.line], existing, scalar));
+        return lines;
+    }
+    // A value that continues past its own line (a nested block) has no one-line edit.
+    if (region.end > existing.line + 1)
         return undefined;
-    const existing = findKey(lines, parent.region, parent.indent, last.key);
-    if (existing !== undefined) {
-        // A value that continues past its own line (a block scalar, a nested block) has no one-line edit.
-        const currentValue = (0, set_1.valueOf)(existing.rest);
-        if (currentValue.startsWith('|') || currentValue.startsWith('>'))
-            return undefined;
-        if (blockRegion(lines, existing).end > existing.line + 1)
+    lines[existing.line] = rewriteKeyLine(lines[existing.line], existing, scalar);
+    return lines;
+}
+/**
+ * Insert a key the text does not carry, together with every ancestor key it does not carry either
+ * (task-193, `bug-126`: the first `dna add team.agents` on a file with no `agents:`, or a
+ * `dna set project.name` on a file with no `project:`). The deepest ancestor the text DOES carry is the
+ * parent; each missing key is written on its own line, two columns deeper than the one before, at the
+ * end of the parent's content (before any trailing comment block, which introduces what comes next).
+ * `render` writes the last key's own line(s) at the indentation it is handed.
+ *
+ * Declines when a missing step is a sequence index (there is no entry to descend into), or when the
+ * parent key holds an inline value — a flow mapping `{ a: 1 }`, a plain scalar — under which no block
+ * line can be added. An empty flow mapping `{}` holds nothing to lose, so it is opened into a block
+ * (`paths: {}` becomes `paths:`) and the key inserted below it.
+ */
+function insertMissingPath(lines, path, render) {
+    let depth = path.length - 1;
+    let parent = locate(lines, path.slice(0, depth));
+    while (parent === undefined) {
+        depth -= 1;
+        parent = locate(lines, path.slice(0, depth));
+    }
+    const missing = path.slice(depth);
+    if (!missing.every((step) => 'key' in step))
+        return undefined;
+    const key = parent.key;
+    if (key !== undefined) {
+        const currentValue = (0, set_1.valueOf)(key.rest);
+        if (currentValue === '{}') {
+            lines[key.line] = rewriteKeyLine(lines[key.line], key, '').replace(/: $/, ':');
+        }
+        else if (currentValue !== '') {
             return undefined;
-        lines[existing.line] = rewriteKeyLine(lines[existing.line], existing, scalar);
-        return lines;
+        }
     }
+    const keys = missing.map((step) => step.key);
+    const opened = keys.slice(0, -1).map((name, level) => `${' '.repeat(parent.indent + 2 * level)}${name}:`);
+    const tail = render(parent.indent + 2 * opened.length);
+    if (tail === undefined)
+        return undefined;
     // `lastContentLine` returns `region.start - 1` for an empty block, so the insert lands at its start.
-    lines.splice(lastContentLine(lines, parent.region) + 1, 0, `${' '.repeat(parent.indent)}${last.key}: ${scalar}`);
+    lines.splice(lastContentLine(lines, parent.region) + 1, 0, ...opened, ...tail);
     return lines;
 }
 /** Drop the mapping key the path ends on, together with the block hanging below it. */
@@ -258,7 +309,18 @@ function editDeleteKey(lines, path) {
 /** Append items to the sequence the path ends on, in whichever form that sequence is written. */
 function editAppendItems(lines, path, items, intended) {
     const cursor = locate(lines, path);
-    if (cursor?.key === undefined)
+    if (cursor === undefined) {
+        // The sequence is absent from the text (the first entry of `team.agents`, task-193 / `bug-126`):
+        // open it under its parent, with the new items as its first lines.
+        const last = path[path.length - 1];
+        if (last === undefined || !('key' in last))
+            return undefined;
+        return insertMissingPath(lines, path, (indent) => {
+            const rendered = renderItems(items, indent + 2);
+            return rendered === undefined ? undefined : [`${' '.repeat(indent)}${last.key}:`, ...rendered];
+        });
+    }
+    if (cursor.key === undefined)
         return undefined;
     const key = cursor.key;
     const currentValue = (0, set_1.valueOf)(key.rest);
@@ -374,25 +436,11 @@ function applyOne(lines, edit, intended) {
         }
     }
 }
-/**
- * The one shape the walker above cannot reach: a scalar whose PARENT key is itself absent from the
- * text, so there is no block to insert into (`project.name` in a file with no `project:` at all).
- * `setDnaValueInText` (`task-063`) already solves exactly that — it inserts the missing tail of a
- * mapping path, comments intact — so it is reused rather than re-implemented, for the mapping-only
- * paths it understands. Anything else still falls through to the caller's `dump()`.
- */
-function insertMissingScalarPath(text, edit) {
-    if (edit.kind !== 'set-scalar' || typeof edit.value !== 'string')
-        return undefined;
-    if (!edit.path.every((step) => 'key' in step))
-        return undefined;
-    const keyPath = edit.path.map((step) => step.key).join('.');
-    return (0, set_1.setDnaValueInText)(text, keyPath, edit.value);
-}
 /**
  * Apply `edit` to the RAW TEXT of a `dna.yaml`, editing as few lines as possible, and return the new
- * text — or `undefined`, deliberately and not as an error, when no provably-minimal edit exists, so the
- * caller falls back to the whole-file `dump()`.
+ * text — or `undefined`, deliberately and not as an error, when no provably-minimal edit exists. The
+ * caller then refuses the write, or rewrites the whole file when `--force` authorizes it and says that
+ * the comments were not kept (task-193, `runDnaMutation` in `src/core`).
  *
  * `intended` is the document the mutation produced (`applyDnaMutation`'s `dna`). It serves twice: an
  * inline flow sequence is re-rendered from it rather than patched token-by-token, and — the part that
@@ -401,10 +449,10 @@ function insertMissingScalarPath(text, edit) {
  * while key values are the contract; a mis-located edit fails the comparison and costs the comments,
  * never the content.
  *
- * Declines (returns `undefined`) when: the text is not one valid YAML document; a step of the path is
- * absent from the text; the target or a value it must rewrite spans more than its own line (a block
- * scalar, a nested block); a value has no single-line YAML form; or the result does not read back as
- * `intended`.
+ * Declines (returns `undefined`) when: the text is not one valid YAML document; an absent step of the
+ * path cannot be inserted (a sequence index, or a parent holding an inline value other than `{}`); the
+ * target spans more than its own line as a nested block (a block scalar is replaced, not declined); a
+ * value has no single-line YAML form; or the result does not read back as `intended`.
  */
 function applyDnaEditInText(text, edit, intended) {
     try {
@@ -413,10 +461,15 @@ function applyDnaEditInText(text, edit, intended) {
     catch {
         return undefined;
     }
-    const edited = applyOne(text.split('\n'), edit, intended) ?? insertMissingScalarPath(text, edit);
+    // CRLF line endings (task-193, `bug-019`): the key-line pattern cannot span a `\r`, so a file whose
+    // every line ends in CRLF is edited in its LF form and written back with CRLF. A file mixing the two
+    // has no single ending to restore and is edited as it is, where its LF lines allow.
+    const crlf = text.includes('\r\n') && !text.replace(/\r\n/g, '').includes('\n');
+    const source = crlf ? text.replace(/\r\n/g, '\n') : text;
+    const edited = applyOne(source.split('\n'), edit, intended);
     if (edited === undefined)
         return undefined;
-    const result = Array.isArray(edited) ? edited.join('\n') : edited;
+    const result = edited.join('\n');
     let parsed;
     try {
         parsed = (0, js_yaml_1.load)(result);
@@ -424,6 +477,8 @@ function applyDnaEditInText(text, edit, intended) {
     catch {
         return undefined;
     }
-    return deepEqual(parsed, intended) ? result : undefined;
+    if (!deepEqual(parsed, intended))
+        return undefined;
+    return crlf ? result.replace(/\n/g, '\r\n') : result;
 }
 //# sourceMappingURL=edit.js.map