wingfoil 0.2.1

package/dist/storage/templates.d.ts

@@ -0,0 +1,88 @@
+import { type ScaffoldFile } from './layout';
+/** A methodology starter template: the methodologies it seeds and the delivery sub-workflow it adds. */
+export interface TemplateDefinition {
+    /** Canonical display name, e.g. `Scrum` (matched case-insensitively by {@link resolveTemplate}). */
+    readonly name: string;
+    /** One-line human description surfaced in the wizard and generated headers. */
+    readonly description: string;
+    /** Methodologies written into `dna.yaml` `stacks.methodologies`. */
+    readonly methodologies: readonly string[];
+    /** Lower-case slug used for the delivery workflow filename (`<slug>-delivery.yaml`). */
+    readonly slug: string;
+    /** Human sentence describing the delivery cadence, embedded in the delivery workflow. */
+    readonly cadence: string;
+}
+/** The built-in methodology templates. Order fixed for deterministic listing (REQ-SYS-07). */
+export declare const TEMPLATES: readonly TemplateDefinition[];
+/** Canonical template names, in registry order (used by the wizard prompt and error messages). */
+export declare const TEMPLATE_NAMES: readonly string[];
+/** The template the wizard falls back to when the user selects nothing (first registered template). */
+export declare const DEFAULT_TEMPLATE: string;
+/** Resolve a (case-insensitive) template name to its canonical definition, or `null` if unknown. */
+export declare function resolveTemplate(name: string): TemplateDefinition | null;
+/** The single git subject `wingfoil init` commits (names the chosen template; deterministic). */
+export declare function initProjectCommitMessage(def: TemplateDefinition): string;
+/**
+ * Which pillar a {@link BuiltinTemplateSource} belongs to — `directive` for a P3.8 built-in directive
+ * `.md` file, `workflow` for a P4.17 built-in workflow `.yaml` file. Drives which pillar schema
+ * `core/builtin-integrity.ts`'s `verifyBuiltinTemplates` checks the source against, and which of
+ * REQ-SEC-10's two exact abort-message shapes a failure produces.
+ */
+export type BuiltinTemplateKind = 'directive' | 'workflow';
+/**
+ * One shipped built-in template asset, as raw content — a directive's full `.md` text (frontmatter +
+ * body) or a workflow's full `.yaml` text, exactly as it would be written under `.wingfoil/directives/
+ * built-in/` or `.wingfoil/workflows/built-in/`. This is the pure DATA shape only; `name`/`kind` are
+ * enough to identify and classify a source, and pillar-schema validation itself is a cross-pillar
+ * concern that lives in `core/builtin-integrity.ts` (this module never imports a pillar schema —
+ * REQ-SYS-02 keeps `storage` decoupled from `directives`/`workflow`).
+ */
+export interface BuiltinTemplateSource {
+    readonly name: string;
+    readonly kind: BuiltinTemplateKind;
+    readonly content: string;
+}
+/** Scaffold directory holding the P3.8 built-in directive templates (spec-011 storage layout). */
+export declare const BUILTIN_DIRECTIVES_DIR = ".wingfoil/directives/built-in";
+/** Scaffold directory holding the P4.17 built-in workflow templates (spec-011 storage layout). */
+export declare const BUILTIN_WORKFLOWS_DIR = ".wingfoil/workflows/built-in";
+/**
+ * Derive the built-in template assets to schema-check (REQ-SEC-10) from the very `ScaffoldFile[]`
+ * that `initStorage` is about to write — so the CHECKED set and the INSTALLED set are the same set by
+ * construction.
+ *
+ * This replaces the hand-maintained `BUILTIN_TEMPLATE_SOURCES` constant the first pass of
+ * `task-044-builtin-template-integrity` shipped. A standalone registry is fail-open by omission: a
+ * later task (`task-057` for P3.8, or a P4.17 workflow-template task) can add an asset to
+ * {@link templateScaffold} and forget the registry, installing a template nothing ever checks while
+ * every existing test stays green. Deriving makes "installed but unchecked" unrepresentable rather
+ * than merely untested — the fix `dl-031-req-sec-10-integrity-depth` flagged. (dl-031 ratified that
+ * schema validation IS the REQ-SEC-10 contract; there is deliberately no digest or manifest here.)
+ *
+ * Pure and order-preserving over `files` (REQ-SYS-07), so the derived order — and hence
+ * `verifyBuiltinTemplates`' first-failure choice — is the caller's own order, deterministic whenever
+ * that is. Both of today's callers qualify, for different reasons: {@link templateScaffold} returns a
+ * genuinely path-sorted list, whereas `scaffoldFiles` (./layout) returns a fixed hand-written literal
+ * that is stable but NOT sorted (see its doc comment). Reproducible is what matters here, not sorted.
+ *
+ * BOTH scaffolds flow through here since `task-054-project-directives`: `scaffoldFiles()` now reserves
+ * `.wingfoil/directives/built-in/` for the P3.5 layout, and `initWingfoilStorage` derives its checked
+ * set from it exactly as `initWingfoilProject` does from {@link templateScaffold}
+ * (`bug-018-init-storage-bypasses-integrity-guard`). Being generic over `ScaffoldFile[]` is what made
+ * that a one-line wiring rather than a second mechanism.
+ *
+ * What it returns is a fact about the scaffold CONTENT, not a property of this function: for
+ * {@link templateScaffold} it is the six P3.8 built-in directives `task-057-builtin-directive-templates`
+ * ships (`./builtin-directives`, rendered by `builtinDirectiveMd`), for `scaffoldFiles` it is `[]` (a
+ * `.gitkeep` only), and the workflows built-in directory still holds a `.gitkeep` only. Any asset added
+ * later is checked with no edit here. Each shipped built-in must satisfy its pillar schema on its own —
+ * `test/storage/builtin-directives.test.ts` runs every directive template through the real guard.
+ */
+export declare function builtinTemplateSources(files: readonly ScaffoldFile[]): BuiltinTemplateSource[];
+/**
+ * The COMPLETE spec-011 `.wingfoil/` layout for `def`, as a `ScaffoldFile[]` sorted by path
+ * (deterministic — REQ-SYS-07). Consumed by `initStorage(root, files, message)`; every path is under
+ * `.wingfoil/` so init never writes outside the WingFoil root.
+ */
+export declare function templateScaffold(def: TemplateDefinition): ScaffoldFile[];
+//# sourceMappingURL=templates.d.ts.map

package/dist/storage/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/storage/templates.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,UAAU,CAAC;AAE3D,wGAAwG;AACxG,MAAM,WAAW,kBAAkB;IACjC,oGAAoG;IACpG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAkBD,8FAA8F;AAC9F,eAAO,MAAM,SAAS,EAAE,SAAS,kBAAkB,EAAoB,CAAC;AAExE,kGAAkG;AAClG,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAAiC,CAAC;AAE9E,uGAAuG;AACvG,eAAO,MAAM,gBAAgB,EAAE,MAAmB,CAAC;AAEnD,oGAAoG;AACpG,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI,CAGvE;AAED,iGAAiG;AACjG,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,CAExE;AAID;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,UAAU,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,kGAAkG;AAClG,eAAO,MAAM,sBAAsB,kCAAwC,CAAC;AAE5E,kGAAkG;AAClG,eAAO,MAAM,qBAAqB,iCAAuC,CAAC;AAyB1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,qBAAqB,EAAE,CAO9F;AA8QD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,YAAY,EAAE,CA2CxE"}

package/dist/storage/templates.js

@@ -0,0 +1,422 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILTIN_WORKFLOWS_DIR = exports.BUILTIN_DIRECTIVES_DIR = exports.DEFAULT_TEMPLATE = exports.TEMPLATE_NAMES = exports.TEMPLATES = void 0;
+exports.resolveTemplate = resolveTemplate;
+exports.initProjectCommitMessage = initProjectCommitMessage;
+exports.builtinTemplateSources = builtinTemplateSources;
+exports.templateScaffold = templateScaffold;
+/**
+ * Methodology templates for `wingfoil init` (task-029-implement-wingfoil-init, P5.1.1,
+ * spec-011-storage-layout). task-018 delivered only the minimal committed skeleton
+ * (`scaffoldFiles()` in ./layout) and EXPLICITLY deferred the complete spec-011 layout — `roles.yaml`,
+ * the `workflows/{built-in,custom}` split, `memory/templates/`, and real starter content — to this
+ * module. `templateScaffold(def)` returns that complete layout as a `ScaffoldFile[]` the same
+ * `initStorage(root, files, message)` write+commit path consumes. (The `directives/{built-in,custom}`
+ * split was deferred here too, until `task-054-project-directives` pulled it back into the minimal
+ * skeleton as well: P3.5 requires it after init, on whichever path ran.)
+ *
+ * A "template" (Scrum, Kanban — the names the P5.1.1 BDD uses as examples) is an AUTHORING starter:
+ * it selects the project's methodologies (written into `dna.yaml` `stacks.methodologies`) and a
+ * methodology-flavoured delivery sub-workflow; it is not a spec-mandated schema. All generated content
+ * is a pure function of the `TemplateDefinition` — no wall-clock, no randomness, no environment read —
+ * so `wingfoil init --template X` is byte-identical run to run (REQ-SYS-07), and the returned list is
+ * sorted by path so callers may diff the set safely.
+ */
+const builtin_directives_1 = require("./builtin-directives");
+const layout_1 = require("./layout");
+const SCRUM = {
+    name: 'Scrum',
+    description: 'Sprint-based iterative delivery with fixed-length timeboxes.',
+    methodologies: ['Scrum', 'Specification by Example (BDD)', 'TDD'],
+    slug: 'scrum',
+    cadence: 'Work is delivered in fixed-length sprints; each sprint plans, builds, reviews and retrospects a slice of the backlog.',
+};
+const KANBAN = {
+    name: 'Kanban',
+    description: 'Continuous-flow delivery with work-in-progress limits.',
+    methodologies: ['Kanban', 'Specification by Example (BDD)', 'TDD'],
+    slug: 'kanban',
+    cadence: 'Work flows continuously across the board under explicit WIP limits; there are no timeboxed iterations.',
+};
+/** The built-in methodology templates. Order fixed for deterministic listing (REQ-SYS-07). */
+exports.TEMPLATES = [SCRUM, KANBAN];
+/** Canonical template names, in registry order (used by the wizard prompt and error messages). */
+exports.TEMPLATE_NAMES = exports.TEMPLATES.map((t) => t.name);
+/** The template the wizard falls back to when the user selects nothing (first registered template). */
+exports.DEFAULT_TEMPLATE = SCRUM.name;
+/** Resolve a (case-insensitive) template name to its canonical definition, or `null` if unknown. */
+function resolveTemplate(name) {
+    const wanted = name.trim().toLowerCase();
+    return exports.TEMPLATES.find((t) => t.name.toLowerCase() === wanted) ?? null;
+}
+/** The single git subject `wingfoil init` commits (names the chosen template; deterministic). */
+function initProjectCommitMessage(def) {
+    return `chore(wingfoil): initialize .wingfoil/ with the ${def.name} template (P5.1.1)`;
+}
+/** Scaffold directory holding the P3.8 built-in directive templates (spec-011 storage layout). */
+exports.BUILTIN_DIRECTIVES_DIR = `${layout_1.WINGFOIL_DIR}/directives/built-in`;
+/** Scaffold directory holding the P4.17 built-in workflow templates (spec-011 storage layout). */
+exports.BUILTIN_WORKFLOWS_DIR = `${layout_1.WINGFOIL_DIR}/workflows/built-in`;
+/**
+ * The built-in source one scaffold file contributes, or `null` when the file is not a built-in
+ * template asset.
+ *
+ * Kind comes from the DIRECTORY holding the file, never from its extension: an unexpected file shape
+ * under a built-in directory is then still CHECKED (and fails, naming itself) instead of being waved
+ * through by an extension filter — the fail-closed reading. `name` is the basename with its final
+ * extension stripped. Dotfile placeholders (`.gitkeep`, which reserve an empty directory in git and
+ * carry no template content) are the single exclusion.
+ */
+function builtinSourceOf(file) {
+    const base = file.path.slice(file.path.lastIndexOf('/') + 1);
+    if (base === '' || base.startsWith('.'))
+        return null;
+    let kind;
+    if (file.path.startsWith(`${exports.BUILTIN_DIRECTIVES_DIR}/`))
+        kind = 'directive';
+    else if (file.path.startsWith(`${exports.BUILTIN_WORKFLOWS_DIR}/`))
+        kind = 'workflow';
+    else
+        return null;
+    const dot = base.lastIndexOf('.');
+    return { name: dot > 0 ? base.slice(0, dot) : base, kind, content: file.content };
+}
+/**
+ * Derive the built-in template assets to schema-check (REQ-SEC-10) from the very `ScaffoldFile[]`
+ * that `initStorage` is about to write — so the CHECKED set and the INSTALLED set are the same set by
+ * construction.
+ *
+ * This replaces the hand-maintained `BUILTIN_TEMPLATE_SOURCES` constant the first pass of
+ * `task-044-builtin-template-integrity` shipped. A standalone registry is fail-open by omission: a
+ * later task (`task-057` for P3.8, or a P4.17 workflow-template task) can add an asset to
+ * {@link templateScaffold} and forget the registry, installing a template nothing ever checks while
+ * every existing test stays green. Deriving makes "installed but unchecked" unrepresentable rather
+ * than merely untested — the fix `dl-031-req-sec-10-integrity-depth` flagged. (dl-031 ratified that
+ * schema validation IS the REQ-SEC-10 contract; there is deliberately no digest or manifest here.)
+ *
+ * Pure and order-preserving over `files` (REQ-SYS-07), so the derived order — and hence
+ * `verifyBuiltinTemplates`' first-failure choice — is the caller's own order, deterministic whenever
+ * that is. Both of today's callers qualify, for different reasons: {@link templateScaffold} returns a
+ * genuinely path-sorted list, whereas `scaffoldFiles` (./layout) returns a fixed hand-written literal
+ * that is stable but NOT sorted (see its doc comment). Reproducible is what matters here, not sorted.
+ *
+ * BOTH scaffolds flow through here since `task-054-project-directives`: `scaffoldFiles()` now reserves
+ * `.wingfoil/directives/built-in/` for the P3.5 layout, and `initWingfoilStorage` derives its checked
+ * set from it exactly as `initWingfoilProject` does from {@link templateScaffold}
+ * (`bug-018-init-storage-bypasses-integrity-guard`). Being generic over `ScaffoldFile[]` is what made
+ * that a one-line wiring rather than a second mechanism.
+ *
+ * What it returns is a fact about the scaffold CONTENT, not a property of this function: for
+ * {@link templateScaffold} it is the six P3.8 built-in directives `task-057-builtin-directive-templates`
+ * ships (`./builtin-directives`, rendered by `builtinDirectiveMd`), for `scaffoldFiles` it is `[]` (a
+ * `.gitkeep` only), and the workflows built-in directory still holds a `.gitkeep` only. Any asset added
+ * later is checked with no edit here. Each shipped built-in must satisfy its pillar schema on its own —
+ * `test/storage/builtin-directives.test.ts` runs every directive template through the real guard.
+ */
+function builtinTemplateSources(files) {
+    const sources = [];
+    for (const file of files) {
+        const source = builtinSourceOf(file);
+        if (source !== null)
+            sources.push(source);
+    }
+    return sources;
+}
+// --- Content generators -----------------------------------------------------------------------
+// Every generator is a pure function of its inputs (REQ-SYS-07): fixed strings only, no Date/random.
+const wf = (relative) => `${layout_1.WINGFOIL_DIR}/${relative}`;
+/** The Memory element types spec-011 requires a template scaffold for, in fixed order. */
+const MEMORY_TYPES = ['adr', 'bug', 'decision-log', 'release', 'release-line', 'task', 'tech-spec'];
+/**
+ * Default `id_pattern` per scaffolded type (task-002-validation-id-engine's `{n}`/`{slug}` token
+ * grammar, `src/validation/id.ts`) — required by `memoryAdd` (`src/core/index.ts`) even though
+ * `memory.yaml`'s own schema only marks the field `.optional()` (bug-005-init-scaffold-fails-schema-validation:
+ * without this, a freshly-`init`'d project's `wingfoil memory add` fails on every type). Mirrors this
+ * repository's own dogfooded `docs/self/.wingfoil/memory.yaml` scheme, a sensible [AUTHORING] default
+ * a user is free to change.
+ */
+const MEMORY_ID_PATTERNS = {
+    adr: 'adr-{n}-{slug}',
+    bug: 'bug-{n}-{slug}',
+    'decision-log': 'dl-{n}-{slug}',
+    release: 'release-{n}',
+    'release-line': 'rl-{n}',
+    task: 'task-{n}-{slug}',
+    'tech-spec': 'spec-{n}-{slug}',
+};
+/**
+ * The cross-cutting CUSTOM directives every starter project gets under `directives/custom/` — AUTHORING
+ * starters the user tailors. The six P3.8 categories are not here: since
+ * `task-057-builtin-directive-templates` they ship as official built-ins (`./builtin-directives`,
+ * installed under `directives/built-in/`), replacing the generated `custom/` stand-ins that would
+ * otherwise shadow them on every fresh project (`dl-037`: a same-id `custom/` file wins and is reported).
+ */
+const DIRECTIVES = [
+    { name: 'determinism', title: 'Determinism', summary: 'No wall-clock, randomness, or unordered iteration in context-building paths; prefer declared config.' },
+    { name: 'doc-versioning', title: 'Documentation versioning', summary: 'Bump a document version only on the first edit after it was committed; update its date when bumping.' },
+    { name: 'security-secrets', title: 'Secret hygiene', summary: 'Never commit credentials or secrets; the repository is the single source of truth and is shared.' },
+    { name: 'traceability', title: 'Traceability', summary: 'Maintain the feature -> story -> acceptance -> requirement -> task chain across every change.' },
+];
+function dnaYaml(def) {
+    // `stacks.methodologies` / `team.roles` are `MethodologyEntry`/`RoleEntry` OBJECT arrays
+    // (`{name, ...}`) per `spec-002-dna-yaml-schema`'s `DnaYaml` schema (`src/dna/schema.ts`) — a bare
+    // string list here fails `DnaYaml.safeParse` the moment `dna show`/`dna set`/`paths` load this file
+    // (bug-005-init-scaffold-fails-schema-validation). `team.members` is a REQUIRED (if possibly empty)
+    // array too; an empty list is schema-valid (the `Team` schema's role cross-check is vacuous over no
+    // members) and is the right default for a fresh, person-less scaffold — the user adds real members
+    // via `dna set` once the project has a team.
+    const methodologies = def.methodologies.map((m) => `    - name: ${m}`).join('\n');
+    return `# Project DNA (P2.4) — scaffolded by \`wingfoil init\` (${def.name} template).
+# Structural map of the project: modules, stacks, team + roles, resource paths. Customize freely.
+version: 1
+
+project:
+  name: ""                        # your project name
+  description: ""
+  methodology: ${def.name}        # ${def.description}
+
+# Modules — the parts of the system (anatomy for navigation). Add your own.
+modules: []
+
+# Stacks — technologies + methodologies in use. The methodologies come from the ${def.name} template.
+stacks:
+  technologies: []
+  methodologies:
+${methodologies}
+
+# Team & roles — AI agents execute as developer/reviewer/qa/architect and never hold approval authority.
+team:
+  members: []
+  roles:
+    - name: developer
+    - name: reviewer
+    - name: qa
+    - name: architect
+    - name: product-owner
+    - name: tech-lead
+    - name: approver
+
+# Resource paths — query categories used to navigate the project.
+paths:
+  sources: []
+  tests: []
+  docs: []
+  config: [.wingfoil]
+  governance: []
+`;
+}
+/**
+ * The scaffolded `memory.yaml` (P1.13, `spec-001-memory-yaml-schema`) — type registry **plus** the
+ * `defaults.states` machine every scaffolded type runs on.
+ *
+ * That `defaults` block is `bug-030-init-memory-yaml-has-no-state-machine` (task-071): this generator
+ * used to emit types only, while its own header comment promised "(per type) its state machine", so a
+ * freshly-`init`-ed project had no machine anywhere and `resolveStateMachine` refused every transition
+ * verb. The engine now also carries a built-in default (`DEFAULT_STATE_MACHINE`, `src/memory/state-machine.ts`)
+ * for hand-written files that declare nothing; the block is written out here anyway, and the header
+ * comment corrected to describe it, so the machine governing a new project is **visible and editable
+ * in the user's own file** rather than an invisible engine constant. It is `spec-001`'s worked
+ * `defaults` example verbatim, so this stays inside the top-level shape that spec already specifies
+ * (`defaults:` is optional there) — no per-type machine is invented for a starter project, which would
+ * be a product decision beyond this scaffold.
+ */
+function memoryYaml() {
+    const types = MEMORY_TYPES.map((type) => `  ${type}:
+    path: docs/memory/${type}/{id}.md
+    id_pattern: "${MEMORY_ID_PATTERNS[type]}"
+    template:
+      file: memory/templates/${type}.md
+      frontmatter:
+        required: [id, type, title, status]`).join('\n');
+    return `# Memory element schema (P1.13) — scaffolded by \`wingfoil init\`.
+# One entry per element type: its path pattern, its id pattern and its scaffold template. Every type
+# below shares the \`defaults\` state machine; give a type its own \`states:\` block to override it for
+# that type only (REQ-STATE-08).
+version: 1
+
+# Default state machine — applies to every type that declares no \`states:\` block of its own.
+# \`sequence\` is the ordered forward chain (\`submit\` walks it); a \`gates\` state's forward edge needs
+# \`approve\` instead, and its \`reject\` target is where a rejection lands. \`deprecated\` is implicit:
+# \`memory deprecate\` reaches it from any state, so it is never listed here.
+defaults:
+  states:
+    sequence: [ draft, pending, approved ]
+    gates:
+      pending: { reject: draft }
+
+types:
+${types}
+`;
+}
+function rolesYaml() {
+    return `# Directive role assignments (P3.2/P3.7) — scaffolded by \`wingfoil init\`.
+# Binds directives to roles by directive ID, independent of the built-in/custom subfolder holding the file.
+version: 1
+
+assignments:
+  developer:
+    - code-quality
+    - testing
+    - determinism
+  reviewer:
+    - code-review
+    - traceability
+  qa:
+    - testing
+  architect:
+    - architecture
+    - determinism
+    - traceability
+  product-owner:
+    - traceability
+  tech-lead:
+    - architecture
+    - code-review
+
+# Global directives apply to every role.
+global:
+  - doc-versioning
+  - documentation
+  - security-secrets
+`;
+}
+/** Ordered list of custom workflow filenames the manifest composes (main workflows + delivery sub). */
+function customWorkflowFiles(def) {
+    return [
+        'sw-life-cycle.yaml',
+        'bug-ingest.yaml',
+        'decision-log-ingest.yaml',
+        'adr-ingest.yaml',
+        `${def.slug}-delivery.yaml`,
+    ];
+}
+function workflowsYaml(def) {
+    const includes = customWorkflowFiles(def)
+        .map((f) => `  - workflows/custom/${f}`)
+        .join('\n');
+    return `# Project Workflow main configuration (P4.1) — scaffolded by \`wingfoil init\`.
+# This MAIN config file does not inline workflows; it include()s the custom (and, once populated,
+# built-in) workflow files. Startable mains + the ${def.name} delivery sub-workflow are composed below.
+version: 1
+
+include:
+${includes}
+`;
+}
+/**
+ * One scaffolded Directives-pillar document: YAML frontmatter + the rule text body.
+ *
+ * The frontmatter carries every field `spec-013-directive-frontmatter-schema` marks required — `id`,
+ * `name`, `type: directive`, `kind`, `title` — because that spec's realization,
+ * `DirectiveFrontmatter` (`src/directives/schema.ts`), is what `loadDirectives` (`src/core/loaders.ts`)
+ * validates every directive file against: a scaffold missing any of them makes `wingfoil directives
+ * list` fail `E_VALIDATION` on a freshly-`init`'d project (bug-006-init-directive-scaffold-schema-invalid,
+ * the Directives sibling of the `dna.yaml`/`memory.yaml` defect bug-005 fixed).
+ *
+ * `id` is the filename stem, per spec-013 ("Stable directive identifier … matches the filename stem").
+ * That is not cosmetic: it is the key `resolveRoleDirectives` (`src/core/context.ts`, spec-012 §5)
+ * binds roles on, and {@link rolesYaml} lists exactly those stems in its `assignments`/`global` blocks
+ * — so any other value would leave every scaffolded role binding dangling. Keep the two in step.
+ *
+ * `kind: custom` is correct for `directives/custom/`, the only place this generator's output is written;
+ * the P3.8 built-ins carry `kind: built-in` and have their own renderer (`builtinDirectiveMd`,
+ * `./builtin-directives`).
+ */
+function directiveMd(d) {
+    return `---
+id: ${d.name}
+name: ${d.name}
+type: directive
+kind: custom
+title: "${d.title}"
+---
+
+# ${d.title}
+
+${d.summary}
+
+<!-- Tailor this rule to your project's needs. Directives are auto-loaded per role (roles.yaml). -->
+`;
+}
+function memoryTemplateMd(type) {
+    return `---
+id: ""
+type: ${type}
+title: ""
+status: draft
+---
+
+<!-- ${type} body. \`wingfoil memory add\` copies this scaffold verbatim; \`memory submit\` replaces
+     these placeholder comments with real content and fills the required frontmatter fields. -->
+`;
+}
+function mainWorkflowYaml(name, description, phasesYaml) {
+    return `# ${description}
+name: ${name}
+kind: main
+description: "${description}"
+${phasesYaml}`;
+}
+function deliveryWorkflowYaml(def) {
+    return `# ${def.name} delivery loop (sub-workflow) — scaffolded by \`wingfoil init\`.
+# ${def.cadence}
+name: ${def.slug}-delivery
+kind: sub
+description: "${def.name} delivery loop"
+phases:
+  - name: plan
+    description: "Select the next slice of work to deliver."
+  - name: build
+    description: "Implement the work test-first (TDD)."
+  - name: review
+    description: "Review against the directives; run unit + acceptance tests."
+  - name: deliver
+    description: "Integrate the completed work."
+`;
+}
+/**
+ * The COMPLETE spec-011 `.wingfoil/` layout for `def`, as a `ScaffoldFile[]` sorted by path
+ * (deterministic — REQ-SYS-07). Consumed by `initStorage(root, files, message)`; every path is under
+ * `.wingfoil/` so init never writes outside the WingFoil root.
+ */
+function templateScaffold(def) {
+    const files = [
+        // Top-level pillar config (spec-011 "Top-level config files").
+        { path: wf('dna.yaml'), content: dnaYaml(def) },
+        { path: wf('memory.yaml'), content: memoryYaml() },
+        { path: wf('roles.yaml'), content: rolesYaml() },
+        { path: wf('workflows.yaml'), content: workflowsYaml(def) },
+        // Directives built-in/custom split (spec-011): the six P3.8 built-ins (task-057) + custom starters.
+        ...builtin_directives_1.BUILTIN_DIRECTIVE_TEMPLATES.map((t) => ({ path: `${exports.BUILTIN_DIRECTIVES_DIR}/${t.id}.md`, content: (0, builtin_directives_1.builtinDirectiveMd)(t) })),
+        ...DIRECTIVES.map((d) => ({ path: wf(`directives/custom/${d.name}.md`), content: directiveMd(d) })),
+        // Memory templates — one scaffold per element type (spec-011).
+        ...MEMORY_TYPES.map((type) => ({ path: wf(`memory/templates/${type}.md`), content: memoryTemplateMd(type) })),
+        // Workflows built-in/custom split (spec-011).
+        { path: `${exports.BUILTIN_WORKFLOWS_DIR}/.gitkeep`, content: '' },
+        {
+            path: wf('workflows/custom/sw-life-cycle.yaml'),
+            content: mainWorkflowYaml('sw-life-cycle', 'The end-to-end software life cycle', `phases:
+  - name: inception
+  - name: specification
+  - name: delivery
+    include: workflows/custom/${def.slug}-delivery.yaml
+  - name: sunset
+`),
+        },
+        {
+            path: wf('workflows/custom/bug-ingest.yaml'),
+            content: mainWorkflowYaml('bug-ingest', 'Capture a bug on demand', 'phases:\n  - name: capture\n'),
+        },
+        {
+            path: wf('workflows/custom/decision-log-ingest.yaml'),
+            content: mainWorkflowYaml('decision-log-ingest', 'Capture a decision-log on demand', 'phases:\n  - name: capture\n'),
+        },
+        {
+            path: wf('workflows/custom/adr-ingest.yaml'),
+            content: mainWorkflowYaml('adr-ingest', 'Capture an ADR on demand', 'phases:\n  - name: capture\n'),
+        },
+        { path: wf(`workflows/custom/${def.slug}-delivery.yaml`), content: deliveryWorkflowYaml(def) },
+    ];
+    return files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+}
+//# sourceMappingURL=templates.js.map

package/dist/storage/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/storage/templates.ts"],"names":[],"mappings":";;;AA4DA,0CAGC;AAGD,4DAEC;AAuFD,wDAOC;AAmRD,4CA2CC;AAheD;;;;;;;;;;;;;;;;GAgBG;AACH,6DAAuF;AACvF,qCAA2D;AAgB3D,MAAM,KAAK,GAAuB;IAChC,IAAI,EAAE,OAAO;IACb,WAAW,EAAE,8DAA8D;IAC3E,aAAa,EAAE,CAAC,OAAO,EAAE,gCAAgC,EAAE,KAAK,CAAC;IACjE,IAAI,EAAE,OAAO;IACb,OAAO,EAAE,uHAAuH;CACjI,CAAC;AAEF,MAAM,MAAM,GAAuB;IACjC,IAAI,EAAE,QAAQ;IACd,WAAW,EAAE,wDAAwD;IACrE,aAAa,EAAE,CAAC,QAAQ,EAAE,gCAAgC,EAAE,KAAK,CAAC;IAClE,IAAI,EAAE,QAAQ;IACd,OAAO,EAAE,wGAAwG;CAClH,CAAC;AAEF,8FAA8F;AACjF,QAAA,SAAS,GAAkC,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAExE,kGAAkG;AACrF,QAAA,cAAc,GAAsB,iBAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAE9E,uGAAuG;AAC1F,QAAA,gBAAgB,GAAW,KAAK,CAAC,IAAI,CAAC;AAEnD,oGAAoG;AACpG,SAAgB,eAAe,CAAC,IAAY;IAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACzC,OAAO,iBAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC;AACxE,CAAC;AAED,iGAAiG;AACjG,SAAgB,wBAAwB,CAAC,GAAuB;IAC9D,OAAO,mDAAmD,GAAG,CAAC,IAAI,oBAAoB,CAAC;AACzF,CAAC;AA0BD,kGAAkG;AACrF,QAAA,sBAAsB,GAAG,GAAG,qBAAY,sBAAsB,CAAC;AAE5E,kGAAkG;AACrF,QAAA,qBAAqB,GAAG,GAAG,qBAAY,qBAAqB,CAAC;AAE1E;;;;;;;;;GASG;AACH,SAAS,eAAe,CAAC,IAAkB;IACzC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7D,IAAI,IAAI,KAAK,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAErD,IAAI,IAAyB,CAAC;IAC9B,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,8BAAsB,GAAG,CAAC;QAAE,IAAI,GAAG,WAAW,CAAC;SACtE,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,6BAAqB,GAAG,CAAC;QAAE,IAAI,GAAG,UAAU,CAAC;;QACzE,OAAO,IAAI,CAAC;IAEjB,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAClC,OAAO,EAAE,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;AACpF,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,SAAgB,sBAAsB,CAAC,KAA8B;IACnE,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,iGAAiG;AACjG,qGAAqG;AAErG,MAAM,EAAE,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,GAAG,qBAAY,IAAI,QAAQ,EAAE,CAAC;AAEvE,0FAA0F;AAC1F,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AAE7G;;;;;;;GAOG;AACH,MAAM,kBAAkB,GAA4D;IAClF,GAAG,EAAE,gBAAgB;IACrB,GAAG,EAAE,gBAAgB;IACrB,cAAc,EAAE,eAAe;IAC/B,OAAO,EAAE,aAAa;IACtB,cAAc,EAAE,QAAQ;IACxB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,iBAAiB;CAC/B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,GAAoE;IAClF,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,sGAAsG,EAAE;IAC9J,EAAE,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,0BAA0B,EAAE,OAAO,EAAE,sGAAsG,EAAE;IAC9K,EAAE,IAAI,EAAE,kBAAkB,EAAE,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,kGAAkG,EAAE;IAClK,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,+FAA+F,EAAE;CAC1J,CAAC;AAEF,SAAS,OAAO,CAAC,GAAuB;IACtC,yFAAyF;IACzF,mGAAmG;IACnG,oGAAoG;IACpG,oGAAoG;IACpG,oGAAoG;IACpG,mGAAmG;IACnG,6CAA6C;IAC7C,MAAM,aAAa,GAAG,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClF,OAAO,2DAA2D,GAAG,CAAC,IAAI;;;;;;;iBAO3D,GAAG,CAAC,IAAI,aAAa,GAAG,CAAC,WAAW;;;;;kFAK6B,GAAG,CAAC,IAAI;;;;EAIxF,aAAa;;;;;;;;;;;;;;;;;;;;;CAqBd,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAS,UAAU;IACjB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAC5B,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI;wBACC,IAAI;mBACT,kBAAkB,CAAC,IAAI,CAAC;;+BAEZ,IAAI;;4CAES,CACzC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACb,OAAO;;;;;;;;;;;;;;;;;EAiBP,KAAK;CACN,CAAC;AACF,CAAC;AAED,SAAS,SAAS;IAChB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BR,CAAC;AACF,CAAC;AAED,uGAAuG;AACvG,SAAS,mBAAmB,CAAC,GAAuB;IAClD,OAAO;QACL,oBAAoB;QACpB,iBAAiB;QACjB,0BAA0B;QAC1B,iBAAiB;QACjB,GAAG,GAAG,CAAC,IAAI,gBAAgB;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,GAAuB;IAC5C,MAAM,QAAQ,GAAG,mBAAmB,CAAC,GAAG,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,wBAAwB,CAAC,EAAE,CAAC;SACvC,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO;;oDAE2C,GAAG,CAAC,IAAI;;;;EAI1D,QAAQ;CACT,CAAC;AACF,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,WAAW,CAAC,CAA8B;IACjD,OAAO;MACH,CAAC,CAAC,IAAI;QACJ,CAAC,CAAC,IAAI;;;UAGJ,CAAC,CAAC,KAAK;;;IAGb,CAAC,CAAC,KAAK;;EAET,CAAC,CAAC,OAAO;;;CAGV,CAAC;AACF,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO;;QAED,IAAI;;;;;OAKL,IAAI;;CAEV,CAAC;AACF,CAAC;AAED,SAAS,gBAAgB,CAAC,IAAY,EAAE,WAAmB,EAAE,UAAkB;IAC7E,OAAO,KAAK,WAAW;QACjB,IAAI;;gBAEI,WAAW;EACzB,UAAU,EAAE,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAAC,GAAuB;IACnD,OAAO,KAAK,GAAG,CAAC,IAAI;IAClB,GAAG,CAAC,OAAO;QACP,GAAG,CAAC,IAAI;;gBAEA,GAAG,CAAC,IAAI;;;;;;;;;;CAUvB,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,SAAgB,gBAAgB,CAAC,GAAuB;IACtD,MAAM,KAAK,GAAmB;QAC5B,+DAA+D;QAC/D,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE;QAC/C,EAAE,IAAI,EAAE,EAAE,CAAC,aAAa,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE;QAClD,EAAE,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE;QAChD,EAAE,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE;QAC3D,oGAAoG;QACpG,GAAG,gDAA2B,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,GAAG,8BAAsB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,IAAA,uCAAkB,EAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC7H,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,qBAAqB,CAAC,CAAC,IAAI,KAAK,CAAC,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACnG,+DAA+D;QAC/D,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,oBAAoB,IAAI,KAAK,CAAC,EAAE,OAAO,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC7G,8CAA8C;QAC9C,EAAE,IAAI,EAAE,GAAG,6BAAqB,WAAW,EAAE,OAAO,EAAE,EAAE,EAAE;QAC1D;YACE,IAAI,EAAE,EAAE,CAAC,qCAAqC,CAAC;YAC/C,OAAO,EAAE,gBAAgB,CACvB,eAAe,EACf,oCAAoC,EACpC;;;;gCAIwB,GAAG,CAAC,IAAI;;CAEvC,CACM;SACF;QACD;YACE,IAAI,EAAE,EAAE,CAAC,kCAAkC,CAAC;YAC5C,OAAO,EAAE,gBAAgB,CAAC,YAAY,EAAE,yBAAyB,EAAE,8BAA8B,CAAC;SACnG;QACD;YACE,IAAI,EAAE,EAAE,CAAC,2CAA2C,CAAC;YACrD,OAAO,EAAE,gBAAgB,CAAC,qBAAqB,EAAE,kCAAkC,EAAE,8BAA8B,CAAC;SACrH;QACD;YACE,IAAI,EAAE,EAAE,CAAC,kCAAkC,CAAC;YAC5C,OAAO,EAAE,gBAAgB,CAAC,YAAY,EAAE,0BAA0B,EAAE,8BAA8B,CAAC;SACpG;QACD,EAAE,IAAI,EAAE,EAAE,CAAC,oBAAoB,GAAG,CAAC,IAAI,gBAAgB,CAAC,EAAE,OAAO,EAAE,oBAAoB,CAAC,GAAG,CAAC,EAAE;KAC/F,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC"}

package/dist/validation/error-mapper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Zod-issue → {@link ValidationError} mapper (spec-009-validation-strategy §3).
+ *
+ * Every Pass-1 Zod issue is mapped to an `E_*` code via the caller-supplied `ErrorMap` (keyed by
+ * dot-path). Any issue whose path has no entry falls back to `E_VALIDATION`, so no failure is ever
+ * silently dropped for lack of a specific code.
+ */
+import type { ZodError } from 'zod';
+import { ValidationError } from './errors';
+/**
+ * Map a Zod parse failure to a {@link ValidationError} (spec-009 §3): each issue's dot-path is looked
+ * up in `errorMap` for its `E_*` code, falling back to `E_VALIDATION` so no issue is dropped. `filePath`
+ * is attached to every issue for operator-facing messages.
+ */
+export declare function toValidationError(zodError: ZodError, filePath: string, errorMap?: Record<string, string>): ValidationError;
+//# sourceMappingURL=error-mapper.d.ts.map

package/dist/validation/error-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.d.ts","sourceRoot":"","sources":["../../src/validation/error-mapper.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAEpC,OAAO,EAAgB,eAAe,EAAmB,MAAM,UAAU,CAAC;AAE1E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACpC,eAAe,CAOjB"}

package/dist/validation/error-mapper.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toValidationError = toValidationError;
+const errors_1 = require("./errors");
+/**
+ * Map a Zod parse failure to a {@link ValidationError} (spec-009 §3): each issue's dot-path is looked
+ * up in `errorMap` for its `E_*` code, falling back to `E_VALIDATION` so no issue is dropped. `filePath`
+ * is attached to every issue for operator-facing messages.
+ */
+function toValidationError(zodError, filePath, errorMap = {}) {
+    const issues = zodError.issues.map((issue) => {
+        const path = issue.path.join('.');
+        const code = errorMap[path] ?? errors_1.E_VALIDATION;
+        return { code, path, file: filePath, message: issue.message };
+    });
+    return new errors_1.ValidationError(issues);
+}
+//# sourceMappingURL=error-mapper.js.map

package/dist/validation/error-mapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-mapper.js","sourceRoot":"","sources":["../../src/validation/error-mapper.ts"],"names":[],"mappings":";;AAgBA,8CAWC;AAlBD,qCAA0E;AAE1E;;;;GAIG;AACH,SAAgB,iBAAiB,CAC/B,QAAkB,EAClB,QAAgB,EAChB,WAAmC,EAAE;IAErC,MAAM,MAAM,GAAsB,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9D,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,qBAAY,CAAC;QAC5C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;IAChE,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,wBAAe,CAAC,MAAM,CAAC,CAAC;AACrC,CAAC"}

package/dist/validation/errors.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shared validation error types and exit codes (spec-009-validation-strategy §3).
+ *
+ * A single {@link ValidationError} carries the full list of mapped issues from one validation run
+ * so no failure is ever silently dropped. Its {@link ValidationError.exitCode} follows spec-009 §3,
+ * which keys the code on the **nature** of the failure, not on the pass that detects it: parse and
+ * system-integrity failures exit `2`; every other validation failure — field-level, mapped, generic,
+ * and business-rule failures detected in Pass 2 (e.g. `E_INVALID_TRANSITION`, `E_INVALID_STATE`) —
+ * exits `1`, matching spec-008's exit-code table.
+ */
+/** A single mapped validation failure — one Zod issue or one semantic-check failure. */
+export interface ValidationIssue {
+    /** `E_*` code from the shared convention (spec-009 §3), e.g. `E_INVALID_ID`, `E_VALIDATION`. */
+    readonly code: string;
+    /** Dot-joined path to the offending field (empty string for whole-document failures). */
+    readonly path: string;
+    /** Path of the file the failure was found in. */
+    readonly file: string;
+    /** Human-readable description (typically the raw Zod message). */
+    readonly message: string;
+    /**
+     * Optional longer explanation kept apart from {@link message} — for a failure whose `message` is a
+     * pinned contract string, the diagnostic that says *why* travels here instead of replacing it
+     * (`dl-032-illegal-transition-message-contract`, option (c)). Absent for most issues.
+     */
+    readonly detail?: string;
+}
+/**
+ * Process exit code for a validation failure whose worst issue is a mapped `E_INVALID_*` /
+ * `E_INVALID_*_SCHEMA` or the generic `E_VALIDATION` fallback (spec-009 §3, spec-008 exit table).
+ */
+export declare const EXIT_VALIDATION = 1;
+/**
+ * Process exit code for a parse or system-integrity failure — `E_YAML_PARSE_ERROR`, and the
+ * cross-file integrity checks that presuppose a parseable tree: the input could not be understood,
+ * or the installation is inconsistent (spec-009 §3, spec-008 exit table). **Not** every Pass-2
+ * failure: spec-009 §3 keys exit codes on the nature of the failure, not the pass, so a business-rule
+ * failure found in Pass 2 (an illegal transition, an invalid state) exits {@link EXIT_VALIDATION}.
+ */
+export declare const EXIT_INTEGRITY = 2;
+/** `E_*` code emitted when a file cannot be parsed as YAML at all, before Zod runs (spec-009 §3). */
+export declare const E_YAML_PARSE_ERROR = "E_YAML_PARSE_ERROR";
+/** Generic fallback code for any issue with no explicit `ErrorMap` entry (spec-009 §3). */
+export declare const E_VALIDATION = "E_VALIDATION";
+/**
+ * The single error type thrown by every validation path. Extends {@link Error} so it integrates
+ * with normal throw/catch, but always carries the structured {@link issues} list and the process
+ * {@link exitCode} the CLI/MCP surface should exit with.
+ */
+export declare class ValidationError extends Error {
+    readonly issues: readonly ValidationIssue[];
+    readonly exitCode: number;
+    constructor(issues: ValidationIssue[], exitCode?: number);
+    /**
+     * Build a pre-parse YAML failure. Exits `2` (integrity) because it means the file could not even
+     * be turned into a data structure — Zod never ran.
+     */
+    static yamlParse(filePath: string, message: string): ValidationError;
+    /**
+     * Build a **system-integrity** failure detected after parsing. Exits `2` ({@link EXIT_INTEGRITY}).
+     * Use it only when the input could not be understood or the installation is inconsistent (e.g. a
+     * loader's cross-file check, a malformed `id_pattern`). It is **not** the constructor for every
+     * Pass-2 check: spec-009 §3 keys exit codes on the nature of the failure, not the detecting pass,
+     * so a business-rule failure found in Pass 2 (`E_INVALID_TRANSITION`, `E_INVALID_STATE`) is built
+     * with the plain constructor and exits `1`.
+     */
+    static semantic(issues: ValidationIssue[]): ValidationError;
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/validation/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/validation/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,wFAAwF;AACxF,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iDAAiD;IACjD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,IAAI,CAAC;AAEhC,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,uBAAuB,CAAC;AAEvD,2FAA2F;AAC3F,eAAO,MAAM,YAAY,iBAAiB,CAAC;AAE3C;;;;GAIG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,MAAM,EAAE,eAAe,EAAE,EAAE,QAAQ,GAAE,MAAwB;IAazE;;;OAGG;IACH,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,eAAe;IAOpE;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,eAAe;CAG5D"}