wingfoil 0.2.2 → 0.3.0

package/dist/core/required-fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The required-field check two verbs share (`spec-010` § Validation rules): `memory submit` before
+ * leaving the initial state, and `memory amend` on a document already past it (task-127 review F1).
+ * One function, so the two can never disagree about what "filled" means.
+ *
+ * A field is refused when it is missing — absent, `null`, blank, a mapping, or a list on a field the
+ * type does not declare in `template.frontmatter.lists` (`bug-147`, task-168 re-review rulings) — or
+ * when it holds a
+ * not-applicable value that may not stand (`dl-124`, task-168): the type does not list the field in
+ * `template.frontmatter.not_applicable_allowed`, or the value is not `"n/a — <reason>"`. A required
+ * field the type does not list — `task.kind` in this repository — therefore cannot be skipped by
+ * writing `n/a` in it.
+ *
+ * A field the type's `template.frontmatter.exempt` lists for this document's `id` is not required of
+ * it at all (`bug-342`, task-279): neither checked nor named in the refusal. The declaration in
+ * `memory.yaml` is the only source of the exemption — this repository's releases added before
+ * `dl-092` carry no `kind`; no id is written here.
+ */
+import { type MemoryYaml } from '../memory';
+import { type CoreResult } from './types';
+/**
+ * `VALIDATION` (exit 1) naming every refused field, or `ok`. A list is a value only on the fields the
+ * type declares in `template.frontmatter.lists`. The message is
+ * `missing required field on <verb>: a, b`, then — joined by `; ` when both apply —
+ * `not-applicable value on <verb>: <field> …`, each clause in declared field order.
+ */
+export declare function requireRequiredFields(memoryYaml: MemoryYaml, type: string, frontmatter: Readonly<Record<string, unknown>>, verb: 'submit' | 'amend'): CoreResult<undefined>;
+//# sourceMappingURL=required-fields.d.ts.map

package/dist/core/required-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields.d.ts","sourceRoot":"","sources":["../../src/core/required-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAgD,KAAK,UAAU,EAA6B,MAAM,WAAW,CAAC;AAErH,OAAO,EAAmB,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAa3D;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,UAAU,EACtB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,IAAI,EAAE,QAAQ,GAAG,OAAO,GACvB,UAAU,CAAC,SAAS,CAAC,CAiBvB"}

package/dist/core/required-fields.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requireRequiredFields = requireRequiredFields;
+/**
+ * The required-field check two verbs share (`spec-010` § Validation rules): `memory submit` before
+ * leaving the initial state, and `memory amend` on a document already past it (task-127 review F1).
+ * One function, so the two can never disagree about what "filled" means.
+ *
+ * A field is refused when it is missing — absent, `null`, blank, a mapping, or a list on a field the
+ * type does not declare in `template.frontmatter.lists` (`bug-147`, task-168 re-review rulings) — or
+ * when it holds a
+ * not-applicable value that may not stand (`dl-124`, task-168): the type does not list the field in
+ * `template.frontmatter.not_applicable_allowed`, or the value is not `"n/a — <reason>"`. A required
+ * field the type does not list — `task.kind` in this repository — therefore cannot be skipped by
+ * writing `n/a` in it.
+ *
+ * A field the type's `template.frontmatter.exempt` lists for this document's `id` is not required of
+ * it at all (`bug-342`, task-279): neither checked nor named in the refusal. The declaration in
+ * `memory.yaml` is the only source of the exemption — this repository's releases added before
+ * `dl-092` carry no `kind`; no id is written here.
+ */
+const memory_1 = require("../memory");
+const types_1 = require("./types");
+function describeRefusal(type, refusal) {
+    switch (refusal.problem) {
+        case 'no-reason':
+            return `${refusal.field} needs a reason, written "n/a — <reason>"`;
+        case 'bad-form':
+            return `${refusal.field} must be written "n/a — <reason>", with an em dash before the reason`;
+        default:
+            return `${refusal.field} does not accept one (type '${type}' does not list it in template.frontmatter.not_applicable_allowed)`;
+    }
+}
+/**
+ * `VALIDATION` (exit 1) naming every refused field, or `ok`. A list is a value only on the fields the
+ * type declares in `template.frontmatter.lists`. The message is
+ * `missing required field on <verb>: a, b`, then — joined by `; ` when both apply —
+ * `not-applicable value on <verb>: <field> …`, each clause in declared field order.
+ */
+function requireRequiredFields(memoryYaml, type, frontmatter, verb) {
+    const template = memoryYaml.types[type]?.template?.frontmatter;
+    const id = frontmatter['id'];
+    const exempt = template?.exempt ?? {};
+    // Own properties only: a field named like an Object.prototype member (`constructor`, `toString`) is
+    // an ordinary required field, never the prototype's function (task-279 review F1).
+    const exemptIds = (field) => (Object.hasOwn(exempt, field) ? (exempt[field] ?? []) : []);
+    const required = (template?.required ?? []).filter((field) => !(typeof id === 'string' && exemptIds(field).includes(id)));
+    const missing = (0, memory_1.missingRequiredFields)(frontmatter, required, template?.lists ?? []);
+    const refused = (0, memory_1.notApplicableRefusals)(frontmatter, required, template?.not_applicable_allowed ?? []);
+    const clauses = [];
+    if (missing.length > 0)
+        clauses.push(`missing required field on ${verb}: ${missing.join(', ')}`);
+    if (refused.length > 0) {
+        clauses.push(`not-applicable value on ${verb}: ${refused.map((refusal) => describeRefusal(type, refusal)).join(', ')}`);
+    }
+    if (clauses.length === 0)
+        return (0, types_1.coreOk)(undefined);
+    return (0, types_1.coreErr)({ code: 'VALIDATION', message: clauses.join('; ') });
+}
+//# sourceMappingURL=required-fields.js.map

package/dist/core/required-fields.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"required-fields.js","sourceRoot":"","sources":["../../src/core/required-fields.ts"],"names":[],"mappings":";;AAuCA,sDAsBC;AA7DD;;;;;;;;;;;;;;;;;GAiBG;AACH,sCAAqH;AAErH,mCAA2D;AAE3D,SAAS,eAAe,CAAC,IAAY,EAAE,OAA6B;IAClE,QAAQ,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,KAAK,WAAW;YACd,OAAO,GAAG,OAAO,CAAC,KAAK,2CAA2C,CAAC;QACrE,KAAK,UAAU;YACb,OAAO,GAAG,OAAO,CAAC,KAAK,sEAAsE,CAAC;QAChG;YACE,OAAO,GAAG,OAAO,CAAC,KAAK,+BAA+B,IAAI,oEAAoE,CAAC;IACnI,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAgB,qBAAqB,CACnC,UAAsB,EACtB,IAAY,EACZ,WAA8C,EAC9C,IAAwB;IAExB,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC/D,MAAM,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,QAAQ,EAAE,MAAM,IAAI,EAAE,CAAC;IACtC,oGAAoG;IACpG,mFAAmF;IACnF,MAAM,SAAS,GAAG,CAAC,KAAa,EAAqB,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpH,MAAM,QAAQ,GAAG,CAAC,QAAQ,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1H,MAAM,OAAO,GAAG,IAAA,8BAAqB,EAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;IACpF,MAAM,OAAO,GAAG,IAAA,8BAAqB,EAAC,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,sBAAsB,IAAI,EAAE,CAAC,CAAC;IACrG,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,6BAA6B,IAAI,KAAK,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjG,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,2BAA2B,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,eAAe,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC1H,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAA,cAAM,EAAC,SAAS,CAAC,CAAC;IACnD,OAAO,IAAA,eAAO,EAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC"}

package/dist/core/revision.d.ts

@@ -0,0 +1,82 @@
+import { type BlobEntry } from '../storage';
+import type { CoreError, CoreErrorCode } from './types';
+/**
+ * A revision a `…AtRev` reader cannot read at. It is thrown, like the loaders' `ValidationError`, and
+ * it **is** a {@link CoreError} — `code`, `message`, `details: { rev }` — so a core function hands it
+ * on with `coreErr(error.toCoreError())`.
+ *
+ * - `VALIDATION`: the rev is malformed ({@link isWellFormedRevision}) and was never shown to git.
+ * - `NOT_FOUND`: the rev is well formed and names no commit — an unknown name, an unborn `HEAD`, a
+ *   tree or a blob.
+ *
+ * Both messages name the rev JSON-quoted, so an empty or whitespace rev is visible.
+ */
+export declare class RevisionError extends Error implements CoreError {
+    readonly code: CoreErrorCode;
+    readonly details: {
+        readonly rev: string;
+    };
+    constructor(code: 'VALIDATION' | 'NOT_FOUND', rev: string);
+    /** The plain {@link CoreError} value, for a `CoreResult` (spec-006 §2). */
+    toCoreError(): CoreError;
+}
+/**
+ * Whether `rev` has the shape a single-commit revision may have here. Refused: the empty string; a
+ * leading `-` (git would read it as an option); whitespace and control bytes (no ref name holds them,
+ * and a newline would split a batch request); `:` (that is `<rev>:<path>`, a blob, never a commit);
+ * `..` (a range, two commits). Everything else — `HEAD`, `HEAD~2`, a sha or its prefix, a branch, a tag,
+ * `main@{1}` — is left for git to resolve.
+ *
+ * The whitespace rule also refuses the revision forms that spell a phrase with spaces —
+ * `master@{1 day ago}`, `HEAD^{/fix bug}` — as `VALIDATION`. git's dotted spelling of an approxidate
+ * (`HEAD@{1.day.ago}`) has no space and resolves.
+ */
+export declare function isWellFormedRevision(rev: string): boolean;
+/**
+ * Resolve `rev` to the full sha of the commit it names (task-137).
+ *
+ * @param root - Project root (the git repository).
+ * @param rev - A revision naming one commit: `HEAD`, a sha, a branch, a tag.
+ * @returns The commit's full sha.
+ * @throws {@link RevisionError} `VALIDATION` for a malformed rev, `NOT_FOUND` for one naming no commit;
+ *   `StorageError` `E_GIT_READ_FAILED` when git cannot answer at all (a `root` that is not a
+ *   repository, a `git` that cannot run) — a broken environment is not a missing revision.
+ */
+export declare function resolveRevision(root: string, rev: string): string;
+/**
+ * Every file commit `sha` holds under `prefix` (`storage.listPathsAtRev`), for a sha
+ * {@link resolveRevision} has just resolved. `listPathsAtRev` answers `null` only for a revision that
+ * does not resolve, so a `null` here means git could not list a commit it had just resolved; that is a
+ * failed read, and it throws rather than passing for "the commit holds nothing" (the empty answer this
+ * module exists to keep away from an agent's context).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+export declare function listPathsAtCommit(root: string, sha: string, prefix: string): string[];
+/**
+ * {@link listPathsAtCommit} with each blob's kind (`storage.listBlobEntriesAtRev`): the Memory scan
+ * reads at a commit through this, so that a symbolic link is known as one rather than read as a
+ * document whose text is the link's target (task-171, `bug-189`).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+export declare function listBlobEntriesAtCommit(root: string, sha: string, prefix: string): BlobEntry[];
+/**
+ * Run a `…AtRev(root, 'HEAD')` read with the answer the `…AtHead` readers have always given when there
+ * is no `HEAD` to read — `fallback` (`null`, or `[]` for a directory) — rather than an error. Two
+ * conditions mean that, and only two (task-171, `bug-201`):
+ *
+ * - {@link RevisionError} `NOT_FOUND`: a repository with no commit yet (`HEAD` is a constant, so
+ *   `VALIDATION` cannot occur);
+ * - `StorageError` `E_GIT_READ_FAILED` when `root` holds no `.git`: it is not a repository, so nothing
+ *   is committed there.
+ *
+ * Their callers treat the fallback as "nothing committed" (task-090, task-091, task-096). Any other
+ * failure is thrown, and the caller refuses it by name: a `git` that cannot be spawned, an answer past
+ * the read buffer, a tree git cannot read. Until task-171 every `E_GIT_READ_FAILED` gave the fallback,
+ * so a failed read inside a repository passed for an empty baseline.
+ *
+ * @param root - The project root the read is against; asked only whether it holds `.git`.
+ */
+export declare function atHeadOr<T, F>(root: string, read: () => T, fallback: F): T | F;
+//# sourceMappingURL=revision.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"revision.d.ts","sourceRoot":"","sources":["../../src/core/revision.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,KAAK,SAAS,EAA6F,MAAM,YAAY,CAAC;AAEvI,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAExD;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,SAAQ,KAAM,YAAW,SAAS;IAC3D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;gBAE/B,IAAI,EAAE,YAAY,GAAG,WAAW,EAAE,GAAG,EAAE,MAAM;IAazD,2EAA2E;IAC3E,WAAW,IAAI,SAAS;CAGzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAKjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAMrF;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,CAM9F;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAQ9E"}

package/dist/core/revision.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RevisionError = void 0;
+exports.isWellFormedRevision = isWellFormedRevision;
+exports.resolveRevision = resolveRevision;
+exports.listPathsAtCommit = listPathsAtCommit;
+exports.listBlobEntriesAtCommit = listBlobEntriesAtCommit;
+exports.atHeadOr = atHeadOr;
+/**
+ * Resolving the revision a read is pinned to (task-137, `spec-012` §2 `stateRef`, `spec-016` §3.3
+ * step 7, `spec-017` §1.1).
+ *
+ * Every `…AtRev(root, rev)` reader — the pillar loaders (`./loaders.ts`) and the Memory scan
+ * (`../memory/query.ts`) — resolves its `rev` here, once, to the full sha of a commit, and reads every
+ * byte at that sha. A rev that resolves to nothing is a refusal, never an empty answer: an empty
+ * directive list or Memory scan is a legitimate answer for a commit that holds nothing, so handing it
+ * back for a mistyped rev would build an agent a wrong context that looks right.
+ */
+const fs_1 = require("fs");
+const path_1 = require("path");
+const storage_1 = require("../storage");
+/**
+ * A revision a `…AtRev` reader cannot read at. It is thrown, like the loaders' `ValidationError`, and
+ * it **is** a {@link CoreError} — `code`, `message`, `details: { rev }` — so a core function hands it
+ * on with `coreErr(error.toCoreError())`.
+ *
+ * - `VALIDATION`: the rev is malformed ({@link isWellFormedRevision}) and was never shown to git.
+ * - `NOT_FOUND`: the rev is well formed and names no commit — an unknown name, an unborn `HEAD`, a
+ *   tree or a blob.
+ *
+ * Both messages name the rev JSON-quoted, so an empty or whitespace rev is visible.
+ */
+class RevisionError extends Error {
+    code;
+    details;
+    constructor(code, rev) {
+        super(code === 'VALIDATION'
+            ? `malformed revision ${JSON.stringify(rev)}: a revision is a non-empty name with no leading '-', no whitespace or control character, no ':' and no '..'`
+            : `revision ${JSON.stringify(rev)} does not name a commit`);
+        this.name = 'RevisionError';
+        this.code = code;
+        this.details = { rev };
+        // Restore the prototype chain so `instanceof RevisionError` holds after transpilation.
+        Object.setPrototypeOf(this, RevisionError.prototype);
+    }
+    /** The plain {@link CoreError} value, for a `CoreResult` (spec-006 §2). */
+    toCoreError() {
+        return { code: this.code, message: this.message, details: { rev: this.details.rev } };
+    }
+}
+exports.RevisionError = RevisionError;
+/**
+ * Whether `rev` has the shape a single-commit revision may have here. Refused: the empty string; a
+ * leading `-` (git would read it as an option); whitespace and control bytes (no ref name holds them,
+ * and a newline would split a batch request); `:` (that is `<rev>:<path>`, a blob, never a commit);
+ * `..` (a range, two commits). Everything else — `HEAD`, `HEAD~2`, a sha or its prefix, a branch, a tag,
+ * `main@{1}` — is left for git to resolve.
+ *
+ * The whitespace rule also refuses the revision forms that spell a phrase with spaces —
+ * `master@{1 day ago}`, `HEAD^{/fix bug}` — as `VALIDATION`. git's dotted spelling of an approxidate
+ * (`HEAD@{1.day.ago}`) has no space and resolves.
+ */
+function isWellFormedRevision(rev) {
+    // eslint-disable-next-line no-control-regex
+    return rev.length > 0 && !rev.startsWith('-') && !/[\s\u0000-\u001f\u007f:]/.test(rev) && !rev.includes('..');
+}
+/**
+ * Resolve `rev` to the full sha of the commit it names (task-137).
+ *
+ * @param root - Project root (the git repository).
+ * @param rev - A revision naming one commit: `HEAD`, a sha, a branch, a tag.
+ * @returns The commit's full sha.
+ * @throws {@link RevisionError} `VALIDATION` for a malformed rev, `NOT_FOUND` for one naming no commit;
+ *   `StorageError` `E_GIT_READ_FAILED` when git cannot answer at all (a `root` that is not a
+ *   repository, a `git` that cannot run) — a broken environment is not a missing revision.
+ */
+function resolveRevision(root, rev) {
+    if (!isWellFormedRevision(rev))
+        throw new RevisionError('VALIDATION', rev);
+    const sha = (0, storage_1.resolveCommitAtRev)(root, rev);
+    if (sha === null)
+        throw new RevisionError('NOT_FOUND', rev);
+    return sha;
+}
+/**
+ * Every file commit `sha` holds under `prefix` (`storage.listPathsAtRev`), for a sha
+ * {@link resolveRevision} has just resolved. `listPathsAtRev` answers `null` only for a revision that
+ * does not resolve, so a `null` here means git could not list a commit it had just resolved; that is a
+ * failed read, and it throws rather than passing for "the commit holds nothing" (the empty answer this
+ * module exists to keep away from an agent's context).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+function listPathsAtCommit(root, sha, prefix) {
+    const listed = (0, storage_1.listPathsAtRev)(root, sha, prefix);
+    if (listed === null) {
+        throw new storage_1.StorageError(storage_1.E_GIT_READ_FAILED, `git ls-tree ${sha} -- ${prefix} failed in ${root}: the commit could not be listed`);
+    }
+    return listed;
+}
+/**
+ * {@link listPathsAtCommit} with each blob's kind (`storage.listBlobEntriesAtRev`): the Memory scan
+ * reads at a commit through this, so that a symbolic link is known as one rather than read as a
+ * document whose text is the link's target (task-171, `bug-189`).
+ *
+ * @throws `StorageError` `E_GIT_READ_FAILED` when the listing fails.
+ */
+function listBlobEntriesAtCommit(root, sha, prefix) {
+    const listed = (0, storage_1.listBlobEntriesAtRev)(root, sha, prefix);
+    if (listed === null) {
+        throw new storage_1.StorageError(storage_1.E_GIT_READ_FAILED, `git ls-tree ${sha} -- ${prefix} failed in ${root}: the commit could not be listed`);
+    }
+    return listed;
+}
+/**
+ * Run a `…AtRev(root, 'HEAD')` read with the answer the `…AtHead` readers have always given when there
+ * is no `HEAD` to read — `fallback` (`null`, or `[]` for a directory) — rather than an error. Two
+ * conditions mean that, and only two (task-171, `bug-201`):
+ *
+ * - {@link RevisionError} `NOT_FOUND`: a repository with no commit yet (`HEAD` is a constant, so
+ *   `VALIDATION` cannot occur);
+ * - `StorageError` `E_GIT_READ_FAILED` when `root` holds no `.git`: it is not a repository, so nothing
+ *   is committed there.
+ *
+ * Their callers treat the fallback as "nothing committed" (task-090, task-091, task-096). Any other
+ * failure is thrown, and the caller refuses it by name: a `git` that cannot be spawned, an answer past
+ * the read buffer, a tree git cannot read. Until task-171 every `E_GIT_READ_FAILED` gave the fallback,
+ * so a failed read inside a repository passed for an empty baseline.
+ *
+ * @param root - The project root the read is against; asked only whether it holds `.git`.
+ */
+function atHeadOr(root, read, fallback) {
+    try {
+        return read();
+    }
+    catch (error) {
+        if (error instanceof RevisionError && error.code === 'NOT_FOUND')
+            return fallback;
+        if (error instanceof storage_1.StorageError && error.code === storage_1.E_GIT_READ_FAILED && !(0, fs_1.existsSync)((0, path_1.join)(root, '.git')))
+            return fallback;
+        throw error;
+    }
+}
+//# sourceMappingURL=revision.js.map

package/dist/core/revision.js.map

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

package/dist/core/types.d.ts

@@ -18,28 +18,54 @@ export interface CoreError {
     readonly code: CoreErrorCode;
     readonly message: string;
     readonly details?: Record<string, unknown>;
+    /**
+     * One sentence suggesting what to do next, which the CLI prints as `spec-005` §3.1's `hint:` line
+     * (the `hint` field under `json`/`yaml`). It never changes the refusal or its code: `agent show`
+     * says through it that only the working tree holds the run it refused (task-220, `spec-016` §6,
+     * the `command-baseline` directive: the working tree may explain a refusal, never decide it).
+     * Absent when there is nothing to suggest.
+     */
+    readonly hint?: string;
 }
 /**
  * The discriminated-union return of every {@link CoreFn} (spec-006 §2): `ok: true` with the operation's
  * `value` (and, for a mutation, the `commit` it produced), or `ok: false` with a {@link CoreError}.
  * Expected domain failures travel here, never as a thrown exception.
+ *
+ * `warnings` (task-169, `dl-062` Q1 option 3) is the **success-warning channel**: what a successful
+ * operation wants the operator told — e.g. that `directive assign --force` rewrote `roles.yaml` as a
+ * whole file and what that normalized — kept apart from `value` so it never becomes part of the
+ * payload a script parses. Each entry is one operator-facing sentence, in the order core recorded it
+ * (REQ-SYS-07). The key is absent when there is nothing to say, never an empty list. Each surface
+ * renders it in one place: the CLI on stderr (`src/cli/warning.ts`), the MCP Tool result in
+ * `structuredContent` (`src/mcp/registrar.ts`).
  */
 export type CoreResult<T> = {
     readonly ok: true;
     readonly value: T;
+    /**
+     * The commit the operation produced. `message` is the operation's message, not the stored body:
+     * `commitPaths` appends the `WingFoil-Version:` trailer paragraph to what it records (task-192,
+     * `dl-111`), and `git log --format=%B <sha>` reads the stored body.
+     */
     readonly commit?: {
         readonly sha: string;
         readonly message: string;
     };
+    readonly warnings?: readonly string[];
 } | {
     readonly ok: false;
     readonly error: CoreError;
 };
-/** Build a success {@link CoreResult}, optionally carrying the git commit the operation produced. */
+/**
+ * Build a success {@link CoreResult}, optionally carrying the git commit the operation produced and
+ * the warnings to show the operator (task-169). An empty `warnings` list is the same as none: the
+ * result then has no `warnings` key, the shape every success had before the channel existed.
+ */
 export declare function coreOk<T>(value: T, commit?: {
     sha: string;
     message: string;
-}): CoreResult<T>;
+}, warnings?: readonly string[]): CoreResult<T>;
 /** Build a failure {@link CoreResult} from a {@link CoreError}. */
 export declare function coreErr<T = never>(error: CoreError): CoreResult<T>;
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtD,qGAAqG;AACrG,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,UAAU,CAAC,CAAC,CAAC,CAE5F;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,sEAAsE;AACtE,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,oBAAoB,GAAG,YAAY,GAAG,UAAU,GAAG,IAAI,CAAC;AAElG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC,GACD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEtD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,CAAC,EACtB,KAAK,EAAE,CAAC,EACR,MAAM,CAAC,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EACzC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,GAC3B,UAAU,CAAC,CAAC,CAAC,CAOf;AAED,mEAAmE;AACnE,wBAAgB,OAAO,CAAC,CAAC,GAAG,KAAK,EAAE,KAAK,EAAE,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,CAElE"}

package/dist/core/types.js

@@ -11,9 +11,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.coreOk = coreOk;
 exports.coreErr = coreErr;
-/** Build a success {@link CoreResult}, optionally carrying the git commit the operation produced. */
-function coreOk(value, commit) {
-    return commit ? { ok: true, value, commit } : { ok: true, value };
+/**
+ * Build a success {@link CoreResult}, optionally carrying the git commit the operation produced and
+ * the warnings to show the operator (task-169). An empty `warnings` list is the same as none: the
+ * result then has no `warnings` key, the shape every success had before the channel existed.
+ */
+function coreOk(value, commit, warnings) {
+    return {
+        ok: true,
+        value,
+        ...(commit ? { commit } : {}),
+        ...(warnings !== undefined && warnings.length > 0 ? { warnings: [...warnings] } : {}),
+    };
 }
 /** Build a failure {@link CoreResult} from a {@link CoreError}. */
 function coreErr(error) {

package/dist/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AA8BH,wBAEC;AAGD,0BAEC;AARD,qGAAqG;AACrG,SAAgB,MAAM,CAAI,KAAQ,EAAE,MAAyC;IAC3E,OAAO,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACpE,CAAC;AAED,mEAAmE;AACnE,SAAgB,OAAO,CAAY,KAAgB;IACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAwDH,wBAWC;AAGD,0BAEC;AArBD;;;;GAIG;AACH,SAAgB,MAAM,CACpB,KAAQ,EACR,MAAyC,EACzC,QAA4B;IAE5B,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK;QACL,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtF,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,SAAgB,OAAO,CAAY,KAAgB;IACjD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC"}

package/dist/core/workflow-core-checks.d.ts

@@ -0,0 +1,34 @@
+import type { DnaYaml } from '../dna/schema';
+import type { MemoryYaml } from '../memory/schema';
+import type { Diagnostic } from '../validation';
+import { type BindingsYaml } from '../workflow/bindings';
+import { type Workflow } from '../workflow/schema';
+/** What the core checks read besides the workflow files: the other pillars, from one baseline. */
+export interface WorkflowCoreInputs {
+    /** `memory.yaml`, or `null` when the project has none. */
+    readonly memoryYaml: MemoryYaml | null;
+    /** `dna.yaml`, or `null` when the project has none. */
+    readonly dnaYaml: DnaYaml | null;
+    /**
+     * The frontmatter fields the template of `type` declares, or `null` when the type has no template or
+     * it cannot be read (the field half of `W_PHASE_TOKEN_OUT_OF_SCOPE` is then not decided).
+     */
+    readonly templateFields: (type: string) => ReadonlySet<string> | null;
+}
+/** The registry the checks run on: the loader's accepted result. */
+export interface CheckedRegistry {
+    /** The manifest's `include` list — the diagnostics' `file`, one per workflow. */
+    readonly include: readonly string[];
+    /** The workflows, in `include` order. */
+    readonly workflows: readonly Workflow[];
+    /** `workflows/bindings.yaml`, or `null` when the project has none. */
+    readonly bindings: BindingsYaml | null;
+}
+/** `W_WORKFLOW_CHECKS_NOT_RUN` (`bug-281`, spec-003 "Where each check runs"): a core check skipped for want of its input. */
+export declare const W_WORKFLOW_CHECKS_NOT_RUN = "W_WORKFLOW_CHECKS_NOT_RUN";
+/**
+ * Every core diagnostic of `registry` (spec-003 § "Diagnostics", `core` rows), in spec-003's order.
+ * Pure: it reads only its arguments.
+ */
+export declare function workflowCoreDiagnostics(registry: CheckedRegistry, inputs: WorkflowCoreInputs): Diagnostic[];
+//# sourceMappingURL=workflow-core-checks.d.ts.map

package/dist/core/workflow-core-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-core-checks.d.ts","sourceRoot":"","sources":["../../src/core/workflow-core-checks.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAiE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxH,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAIlE,kGAAkG;AAClG,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;IACvC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;CACvE;AAED,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,QAAQ,EAAE,CAAC;IACxC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;CACxC;AA6DD,6HAA6H;AAC7H,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AAErE;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,EAAE,kBAAkB,GAAG,UAAU,EAAE,CAK3G"}