@platformos/platformos-mcp-supervisor 0.0.2 → 0.2.0

package/dist/result/assemble.spec.js

@@ -0,0 +1,319 @@
+import { describe, expect, it } from 'vitest';
+import { assembleNotApplicableResult, assembleResult } from './assemble.js';
+const diag = (over) => ({
+    check: 'SomeCheck',
+    severity: 'warning',
+    message: 'msg',
+    line: 1,
+    column: 1,
+    ...over,
+});
+// A neutral "not computed" impact used where the test does not exercise the
+// blast radius itself (it is threaded verbatim by assembleResult).
+const NO_IMPACT = {
+    scope: 'direct',
+    status: 'unavailable',
+    dependents: { total: 0, by_kind: {}, sample: [] },
+};
+// The always-empty envelope fields in this lint-only slice. Spread into each
+// expected result so every assertion checks the WHOLE object, catching any
+// field that unexpectedly starts being populated.
+const EMPTY_ENVELOPE = {
+    errors: [],
+    warnings: [],
+    infos: [],
+    impact: NO_IMPACT,
+};
+describe('Unit: assembleResult', () => {
+    it('buckets diagnostics by severity into the full result', () => {
+        const error = diag({ severity: 'error', check: 'E' });
+        const warning = diag({ severity: 'warning', check: 'W' });
+        const info = diag({ severity: 'info', check: 'I' });
+        expect(assembleResult([error, warning, info], NO_IMPACT)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'error',
+            // 'E' is not a blocking check code, so the file is reported as having an
+            // error WITHOUT the write being gated — see the status/gate separation below.
+            must_fix_before_write: false,
+            errors: [error],
+            warnings: [warning],
+            infos: [info],
+        });
+    });
+    it('derives status = error, and gates the write, for a BLOCKING error', () => {
+        const error = diag({ severity: 'error', check: 'MissingPartial' });
+        const warning = diag({ severity: 'warning' });
+        expect(assembleResult([error, warning], NO_IMPACT)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'error',
+            must_fix_before_write: true,
+            errors: [error],
+            warnings: [warning],
+        });
+    });
+    it('derives status = warning (no must_fix) when only warnings/infos are present', () => {
+        const warning = diag({ severity: 'warning' });
+        const info = diag({ severity: 'info' });
+        expect(assembleResult([warning, info], NO_IMPACT)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'warning',
+            must_fix_before_write: false,
+            warnings: [warning],
+            infos: [info],
+        });
+    });
+    it('derives status = ok with an empty envelope for no diagnostics', () => {
+        expect(assembleResult([], NO_IMPACT)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'ok',
+            must_fix_before_write: false,
+        });
+    });
+    it('derives status = ok for infos only', () => {
+        const info = diag({ severity: 'info' });
+        expect(assembleResult([info], NO_IMPACT)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'ok',
+            must_fix_before_write: false,
+            infos: [info],
+        });
+    });
+    it('carries the impact through verbatim (status unaffected by blast radius)', () => {
+        const impact = {
+            scope: 'direct',
+            status: 'computed',
+            dependents: {
+                total: 2,
+                by_kind: { render: 1, include: 1 },
+                sample: ['app/views/pages/index.liquid', 'app/views/partials/wrapper.liquid'],
+            },
+        };
+        expect(assembleResult([], impact)).toEqual({
+            ...EMPTY_ENVELOPE,
+            status: 'ok',
+            must_fix_before_write: false,
+            impact,
+        });
+    });
+});
+/**
+ * The result carries ONLY fields that are actually populated.
+ *
+ * An agent cannot tell an always-empty field from a meaningful one, so a permanently-empty
+ * stub is a standing invitation to conclude "no fixes available" from a field that was
+ * never going to say anything else. These assertions pin the EXACT key set, so
+ * reintroducing a stub fails here rather than silently widening the agent surface.
+ */
+describe('Unit: the result contract carries no permanently-empty stubs', () => {
+    const REMOVED = [
+        'proposed_fixes',
+        'clusters',
+        'scorecard',
+        'tips',
+        'domain_guide',
+        'parse_error',
+    ];
+    it('emits exactly the checked-result keys', () => {
+        const result = assembleResult([diag({ severity: 'error' })], NO_IMPACT);
+        expect(Object.keys(result).sort()).toEqual([
+            'errors',
+            'impact',
+            'infos',
+            'must_fix_before_write',
+            'status',
+            'warnings',
+        ]);
+    });
+    it('emits exactly the not-applicable keys, adding only the two that explain the refusal', () => {
+        const result = assembleNotApplicableResult({ code: 'ignored', reason: 'because' });
+        expect(Object.keys(result).sort()).toEqual([
+            'errors',
+            'impact',
+            'infos',
+            'must_fix_before_write',
+            'next_step',
+            'not_applicable_reason',
+            'status',
+            'warnings',
+        ]);
+    });
+    it.each(REMOVED)('does not emit the removed stub field %s', (field) => {
+        const checked = assembleResult([], NO_IMPACT);
+        const declined = assembleNotApplicableResult({ code: 'too_large', reason: 'r' });
+        expect(field in checked).toBe(false);
+        expect(field in declined).toBe(false);
+    });
+    it('survives a JSON round trip with no key reappearing', () => {
+        // The wire format is what the agent actually sees: an `undefined` value would
+        // vanish here, so this proves the keys are absent rather than merely undefined.
+        const wire = JSON.parse(JSON.stringify(assembleResult([], NO_IMPACT)));
+        expect(REMOVED.filter((field) => field in wire)).toEqual([]);
+    });
+    it('omits next_step and not_applicable_reason from a CHECKED result', () => {
+        // The mirror of the above: these two exist only to explain a refusal, so a
+        // checked file must not carry them either.
+        const wire = JSON.parse(JSON.stringify(assembleResult([], NO_IMPACT)));
+        expect(['next_step', 'not_applicable_reason'].filter((field) => field in wire)).toEqual([]);
+    });
+});
+/**
+ * `status` and `must_fix_before_write` answer DIFFERENT questions, and an agent depends on
+ * reading them independently.
+ *
+ *   status                -> what was FOUND (any error at all?)
+ *   must_fix_before_write -> will the file be BROKEN if written?
+ *
+ * The second is strictly narrower; collapsing them is what made a dead argument block.
+ */
+describe('Unit: status and the write gate are separate signals', () => {
+    const errorFrom = (check) => diag({ severity: 'error', check });
+    it('reports status=error but does NOT gate on a non-blocking error', () => {
+        // The reported bug, at the assembly layer.
+        const result = assembleResult([errorFrom('PartialCallArguments')], NO_IMPACT);
+        expect(result.status).toEqual('error');
+        expect(result.must_fix_before_write).toBe(false);
+        // Still fully reported — this is a de-escalation of the GATE, not suppression.
+        expect(result.errors).toEqual([errorFrom('PartialCallArguments')]);
+    });
+    it('reports status=error AND gates on a blocking error', () => {
+        const result = assembleResult([errorFrom('MissingPartial')], NO_IMPACT);
+        expect([result.status, result.must_fix_before_write]).toEqual(['error', true]);
+    });
+    it('gates when a blocking error is mixed among non-blocking ones', () => {
+        const result = assembleResult([errorFrom('ImgWidthAndHeight'), errorFrom('MissingPartial'), errorFrom('UnknownProperty')], NO_IMPACT);
+        expect(result.must_fix_before_write).toBe(true);
+        // And every one of them is still reported — nothing is dropped by the gate.
+        expect(result.errors).toHaveLength(3);
+    });
+    it('never gates on warnings or infos, whatever the check', () => {
+        const result = assembleResult([
+            diag({ severity: 'warning', check: 'MissingPartial' }),
+            diag({ severity: 'info', check: 'MissingPartial' }),
+        ], NO_IMPACT);
+        expect([result.status, result.must_fix_before_write]).toEqual(['warning', false]);
+    });
+    it('reports EVERY diagnostic, with no cap or truncation', () => {
+        // An agent must see the whole picture; a silently truncated list would let it
+        // "fix everything" and still be wrong.
+        const many = Array.from({ length: 60 }, (_, i) => diag({ severity: 'error', check: `Check${i}` }));
+        expect(assembleResult(many, NO_IMPACT).errors).toHaveLength(60);
+    });
+});
+/**
+ * Diagnostics are returned in READING ORDER (line, then column). `check()` batches by check
+ * code, so the raw order is grouped by check — an `ImgWidthAndHeight` on line 5 arrives
+ * before a `MissingPartial` on line 1, and an agent walking the list jumps around the file.
+ */
+describe('Unit: diagnostics are returned in reading order', () => {
+    const at = (line, column, check = 'Check') => diag({ severity: 'error', check, line, column });
+    it('sorts by line', () => {
+        const result = assembleResult([at(5, 1), at(1, 1), at(3, 1)], NO_IMPACT);
+        expect(result.errors.map((e) => e.line)).toEqual([1, 3, 5]);
+    });
+    it('sorts by column within a line', () => {
+        const result = assembleResult([at(2, 30), at(2, 5), at(2, 12)], NO_IMPACT);
+        expect(result.errors.map((e) => e.column)).toEqual([5, 12, 30]);
+    });
+    it('breaks an exact-position tie by check code, deterministically', () => {
+        // Without a stable tiebreak, byte-identical input could yield different output between
+        // runs, undermining offense-comparison verification.
+        const first = assembleResult([at(1, 1, 'Zebra'), at(1, 1, 'Alpha')], NO_IMPACT);
+        const second = assembleResult([at(1, 1, 'Alpha'), at(1, 1, 'Zebra')], NO_IMPACT);
+        expect(first.errors.map((e) => e.check)).toEqual(['Alpha', 'Zebra']);
+        expect(first).toEqual(second);
+    });
+    it('orders each severity bucket independently', () => {
+        const result = assembleResult([
+            diag({ severity: 'error', line: 9, column: 1, check: 'E' }),
+            diag({ severity: 'warning', line: 8, column: 1, check: 'W' }),
+            diag({ severity: 'error', line: 2, column: 1, check: 'E' }),
+            diag({ severity: 'warning', line: 1, column: 1, check: 'W' }),
+            diag({ severity: 'info', line: 7, column: 1, check: 'I' }),
+            diag({ severity: 'info', line: 3, column: 1, check: 'I' }),
+        ], NO_IMPACT);
+        expect(result.errors.map((d) => d.line)).toEqual([2, 9]);
+        expect(result.warnings.map((d) => d.line)).toEqual([1, 8]);
+        expect(result.infos.map((d) => d.line)).toEqual([3, 7]);
+    });
+    it('sorts the REAL grouped-by-check order the engine produces', () => {
+        // The reported shape: check() emits ImgWidthAndHeight (line 5) before the two
+        // MissingPartials (lines 1 and 2) because it batches per check.
+        const result = assembleResult([
+            diag({ severity: 'error', check: 'ImgWidthAndHeight', line: 5, column: 1 }),
+            diag({ severity: 'error', check: 'MissingPartial', line: 1, column: 11 }),
+            diag({ severity: 'error', check: 'MissingPartial', line: 2, column: 11 }),
+            diag({ severity: 'error', check: 'UnknownFilter', line: 3, column: 8 }),
+            diag({ severity: 'error', check: 'PartialCallArguments', line: 4, column: 31 }),
+        ], NO_IMPACT);
+        expect(result.errors.map((d) => `${d.line}:${d.column} ${d.check}`)).toEqual([
+            '1:11 MissingPartial',
+            '2:11 MissingPartial',
+            '3:8 UnknownFilter',
+            '4:31 PartialCallArguments',
+            '5:1 ImgWidthAndHeight',
+        ]);
+    });
+    it('does not mutate the caller’s array', () => {
+        // assembleResult is documented as PURE; sorting in place would violate that and
+        // could reorder a list the caller still holds.
+        const input = [at(3, 1), at(1, 1)];
+        const snapshot = [...input];
+        assembleResult(input, NO_IMPACT);
+        expect(input).toEqual(snapshot);
+    });
+});
+/**
+ * ORDER-INDEPENDENCE, stated as the property that can actually be violated: assembly is a
+ * set of independent transforms over one input, not a chain where each step reads what the
+ * last one wrote.
+ *
+ * The observable form of that claim is about the INPUT, because the transforms are not
+ * separately callable: the engine emits offenses grouped by check, and which check runs
+ * first is an implementation detail of `check()` that has changed before. A result that
+ * depended on it could gate differently across two runs over the same file.
+ *
+ * The fixture deliberately spans every bucket, both gate outcomes, an exact-position tie,
+ * and a blocking error placed LAST — the position a truncating or short-circuiting
+ * implementation would lose it from.
+ */
+describe('Unit: the result does not depend on the order diagnostics arrive in', () => {
+    const d = (check, severity, line, column) => ({ check, severity, message: `${check} fired`, line, column });
+    const FINDINGS = [
+        d('ImgWidthAndHeight', 'error', 5, 1), // non-blocking error
+        d('UnknownProperty', 'warning', 2, 4),
+        d('ParserBlockingScript', 'info', 9, 1),
+        d('UnknownFilter', 'error', 2, 4), // exact tie with the warning above, on position
+        d('MatchingTranslations', 'warning', 1, 1),
+        d('MissingPartial', 'error', 12, 3), // BLOCKING, and last in input order
+    ];
+    /** Deterministic permutations — a fixed set, so a failure is reproducible. */
+    const permutations = [
+        ['as given', FINDINGS],
+        ['reversed', [...FINDINGS].reverse()],
+        ['grouped by check code', [...FINDINGS].sort((a, b) => a.check.localeCompare(b.check))],
+        ['grouped by severity', [...FINDINGS].sort((a, b) => a.severity.localeCompare(b.severity))],
+        ['rotated', [...FINDINGS.slice(3), ...FINDINGS.slice(0, 3)]],
+    ];
+    it('produces an identical result for every input permutation', () => {
+        const results = permutations.map(([, input]) => assembleResult(input, NO_IMPACT));
+        const [first, ...rest] = results;
+        // Whole-value equality against the first, so a difference anywhere in the envelope
+        // fails — not merely a difference in the lists.
+        for (const result of rest)
+            expect(result).toEqual(first);
+    });
+    it('gates identically however the blocking error is positioned', () => {
+        expect(permutations.map(([name, input]) => [name, assembleResult(input, NO_IMPACT)])).toEqual(permutations.map(([name]) => [
+            name,
+            expect.objectContaining({ status: 'error', must_fix_before_write: true }),
+        ]));
+    });
+    it('resolves an exact-position tie the same way from either input order', () => {
+        // `UnknownFilter` and `UnknownProperty` share 2:4 but sit in different buckets, so
+        // the tie that matters is within one. Two errors at one position, both orders.
+        const a = d('UnknownFilter', 'error', 2, 4);
+        const b = d('MissingPartial', 'error', 2, 4);
+        expect(assembleResult([a, b], NO_IMPACT).errors).toEqual(assembleResult([b, a], NO_IMPACT).errors);
+    });
+});
+//# sourceMappingURL=assemble.spec.js.map

package/dist/result/blocking.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Which diagnostics actually block a write.
+ *
+ * check-common's severities are calibrated for a LINTER IN AN EDITOR, where `ERROR` means
+ * "red squiggle, look at this". A write gate answers a different question — will this file
+ * be broken if I write it? — and that is a strictly smaller set than `Severity.ERROR`.
+ *
+ * THE MEMBERSHIP RULE, for whoever adds the next check:
+ *
+ *   BLOCKING     Writing this file produces something broken. Any one of:
+ *                  - it will not parse;
+ *                  - it will raise at runtime;
+ *                  - the deploy converter REJECTS it, which fails the whole changeset
+ *                    rather than this one file.
+ *
+ *   EXCEPTION    Two members block without meeting that bar, because the file violates a
+ *                contract its own author WROTE DOWN in this repository rather than a rule
+ *                we inferred. Nothing joins them without making that argument explicitly.
+ *
+ *   NOT BLOCKING everything else — dead code, style, performance advice, hygiene,
+ *                degraded-but-working output. Still REPORTED (severity is untouched).
+ *
+ * MEMBERSHIP IS ESTABLISHED BY MEASUREMENT, NOT BY READING THE CHECK'S NAME, and the
+ * measurement runs through THIS SERVER rather than through `check()`. A member clears two
+ * independent bars: the diagnostic means the file is broken (measured against a live
+ * instance), and a buffer this server accepts can produce it at all. The "every blocking
+ * check can actually block" group in `transport/validate-code.spec.ts` drives every member
+ * end to end, so adding one here without a fixture there fails the suite.
+ *
+ * Severity is deliberately NOT changed: a non-member stays an `error` in `errors[]` and
+ * keeps `status: 'error'`, it just no longer gates the write. Correctness lives in
+ * check-common; the supervisor keeps ONLY agent ergonomics.
+ */
+/**
+ * Check codes whose presence means the file is broken.
+ *
+ * Each entry states WHY it blocks, because "it felt severe" is how this list rots back into
+ * a copy of the severity table.
+ */
+export declare const BLOCKING_CHECKS: ReadonlySet<string>;
+/**
+ * NOT in the set, and deliberately so — recorded because each looks severe:
+ *
+ * - `ValidJSON` and `JSONSyntaxError` — UNREACHABLE from here, which is a different reason
+ *   from every other entry. Both declare `type: SourceCodeType.JSON`, check-common runs a
+ *   check only against files of its own type, and this server admits only `.liquid`,
+ *   `.graphql` and `.yml`/`.yaml`. A `.json` buffer is declined `unsupported_type` before
+ *   any check runs. The checks themselves are fine and do fire for the CLI and language
+ *   server; if this server ever admits `.json`, re-add both.
+ * - `PartialCallArguments` reports TWO things under one code — an unknown (dead) argument
+ *   and a missing required one — with no structured discriminator, and non-goal #2 forbids
+ *   regex over messages. Safe to leave out wholesale because the check only looks at
+ *   UNDOCUMENTED partials: a partial whose `{% doc %}` declares a contract is owned by
+ *   `MissingRenderPartialArguments` (which DOES block). What is left rests on required
+ *   params INFERRED from undefined variables, and the failure mode is a nil value.
+ * - `UnrecognizedRenderPartialArguments` is the same dead-argument finding.
+ * - `MissingAsset` — measured: `asset_url` is pure string construction, never resolves the
+ *   asset and never raises; the page returns HTTP 200 and `--dry-run` accepts. It also
+ *   misfires on assets that exist on the instance but not in the local tree.
+ * - `ReservedVariableName` — measured: `{% assign blank = 'oops' %}` renders `[]` and the
+ *   deployed page returns HTTP 200. Visibly wrong code, still a working page.
+ * - `TranslationKeyExists` / `MatchingTranslations` — a missing key renders the key or an
+ *   empty string. Visibly wrong, still a working page.
+ * - `UnknownProperty` — resolves to nil; the page renders.
+ * - `UniqueDocParamNames`, `ValidDocParamTypes` — doc hygiene with no runtime effect, since
+ *   `{% doc %}` is inert at runtime.
+ * - `ImgWidthAndHeight`, `ParserBlockingScript` — performance advice.
+ * - `DeprecatedFrontmatterField` — measured: a deprecated key (`layout_name` naming a layout
+ *   that exists, `redirect_url`) and a deprecated `home.liquid` filename are all ACCEPTED by
+ *   the converter. Superseded, not broken.
+ *
+ * `ValidFrontmatter` used to be listed here, recorded as blocked on a discriminator
+ * (TASK-26) because "two of its three findings" were fatal and blocking the code would have
+ * created one false block. Both halves were wrong. It had seven reachable shapes, not three,
+ * and `layout: false` — the finding named as the harmless one — is itself a converter
+ * rejection. It has since been split into per-shape codes, which is the discriminator the
+ * task was waiting for: three of them are in the set above, two are named here.
+ */
+/** A diagnostic, narrowed to what the gate reads. */
+interface GateInput {
+    check: string;
+    severity: string;
+}
+/**
+ * Whether this set of diagnostics should stop the agent writing the file.
+ *
+ * An UNRECOGNIZED check code is treated as NON-blocking: check-common gains checks over
+ * time, and a gate that blocked on codes it had never heard of would over-block every time
+ * the engine grew. The supervisor never blocks on its own uncertainty.
+ */
+export declare function blocksWrite(diagnostics: readonly GateInput[]): boolean;
+export {};

package/dist/result/blocking.js

@@ -0,0 +1,116 @@
+/**
+ * Which diagnostics actually block a write.
+ *
+ * check-common's severities are calibrated for a LINTER IN AN EDITOR, where `ERROR` means
+ * "red squiggle, look at this". A write gate answers a different question — will this file
+ * be broken if I write it? — and that is a strictly smaller set than `Severity.ERROR`.
+ *
+ * THE MEMBERSHIP RULE, for whoever adds the next check:
+ *
+ *   BLOCKING     Writing this file produces something broken. Any one of:
+ *                  - it will not parse;
+ *                  - it will raise at runtime;
+ *                  - the deploy converter REJECTS it, which fails the whole changeset
+ *                    rather than this one file.
+ *
+ *   EXCEPTION    Two members block without meeting that bar, because the file violates a
+ *                contract its own author WROTE DOWN in this repository rather than a rule
+ *                we inferred. Nothing joins them without making that argument explicitly.
+ *
+ *   NOT BLOCKING everything else — dead code, style, performance advice, hygiene,
+ *                degraded-but-working output. Still REPORTED (severity is untouched).
+ *
+ * MEMBERSHIP IS ESTABLISHED BY MEASUREMENT, NOT BY READING THE CHECK'S NAME, and the
+ * measurement runs through THIS SERVER rather than through `check()`. A member clears two
+ * independent bars: the diagnostic means the file is broken (measured against a live
+ * instance), and a buffer this server accepts can produce it at all. The "every blocking
+ * check can actually block" group in `transport/validate-code.spec.ts` drives every member
+ * end to end, so adding one here without a fixture there fails the suite.
+ *
+ * Severity is deliberately NOT changed: a non-member stays an `error` in `errors[]` and
+ * keeps `status: 'error'`, it just no longer gates the write. Correctness lives in
+ * check-common; the supervisor keeps ONLY agent ergonomics.
+ */
+/**
+ * Check codes whose presence means the file is broken.
+ *
+ * Each entry states WHY it blocks, because "it felt severe" is how this list rots back into
+ * a copy of the severity table.
+ */
+export const BLOCKING_CHECKS = new Set([
+    // Does not parse. Nothing downstream can be trusted about the file at all.
+    'LiquidHTMLSyntaxError',
+    // Unparseable YAML. Measured: `pos-cli deploy --dry-run` REJECTS the file ("Body
+    // contains invalid YAML"), failing the WHOLE changeset. Scoped to SYNTAX, which is a
+    // narrower claim than it used to make here: a REAL deploy rejects an unknown property
+    // TYPE (now `InvalidSchemaPropertyType`) and an unknown top-level key, both of which
+    // `--dry-run` misses by returning before the nested converter. Duplicate property names
+    // ARE accepted — measured.
+    'YAMLSyntaxError',
+    // `Attribute type `x` is not allowed`, from the nested `CustomAttributeConverter`.
+    // Measured by a REAL deploy; `--dry-run` accepts it.
+    'InvalidSchemaPropertyType',
+    // Broken reference: the target does not exist, so the render fails at runtime.
+    'MissingPartial',
+    // platformOS raises on an unknown filter rather than ignoring it.
+    'UnknownFilter',
+    // A KNOWN filter applied with the wrong number of arguments: `Liquid::ArgumentError`,
+    // page 500 — the same runtime failure class as `UnknownFilter`. A filter the docset
+    // publishes no arity for produces nothing, so a vocabulary gap cannot refuse working
+    // code; swept over 8 real projects / ~11k liquid files with 0 false positives.
+    'FilterArity',
+    // A single-quoted key or value inside a `{% assign %}` JSON literal. Measured:
+    // `{% assign o = {'k': 'v'} %}` raises `Liquid syntax error: Invalid JSON in assign`,
+    // and `pos-cli deploy --dry-run` REJECTS, failing every file in the changeset.
+    'JsonLiteralQuoteStyle',
+    // The query is invalid against the schema, or references a variable that does
+    // not exist: it fails when executed.
+    'GraphQLCheck',
+    'GraphQLVariablesCheck',
+    // Runtime error on execution, MEASURED: `hash_assign` against a number, string, boolean
+    // or range each raises `HashAssignTagError` ("x is 5, expected Hash or Array"), while
+    // the object case it permits renders HTTP 200. Filter return types come from the docset,
+    // and an unknown one produces nothing, so a docset gap cannot refuse working code.
+    'InvalidWriteTarget',
+    // --- The two deliberate exceptions to the membership rule. ---
+    //
+    // Neither will fail to parse, raise, or be rejected on deploy. Both block because
+    // the file breaks a contract its author WROTE DOWN, which is a stronger signal of
+    // a mistake than any inference we could make.
+    // A required `@param` the partial's own doc block DECLARES was not passed.
+    // Measured: `{% doc %}` is inert at runtime, so this cannot raise — the page
+    // deploys and returns HTTP 200 with the params empty (`a=[] b=[]`). It blocks
+    // because the author declared the parameter required in this repository.
+    'MissingRenderPartialArguments',
+    // A layout that never outputs `content_for_layout`. Measured: HTTP 200 with the
+    // page body silently dropped. It blocks because a layout exists to render its
+    // content, so one that cannot is a defeated contract — and a silently blank page
+    // is harder to diagnose than an error.
+    'MissingContentForLayout',
+    // --- Frontmatter, split out of `ValidFrontmatter`. Each is a measured converter
+    // rejection, which fails the WHOLE changeset. ---
+    // `Body contains invalid YAML: <parser error>`. `YAMLSyntaxError` cannot cover this —
+    // it is YAML-typed and never sees a `.liquid` file.
+    'InvalidFrontmatterSyntax',
+    // `Unknown properties: <key>.`
+    'UnknownFrontmatterField',
+    // `Request method 'POST' is not allowed`, and `layout: false` → `undefined method 'sub'
+    // for false` (YAML reads it as a boolean; `set_layout` guards `nil`, not `false`).
+    'InvalidFrontmatterValue',
+    // `Could not find Layout with layout: <name>`.
+    'MissingLayout',
+    // `<page> tries to assign authorization_policies which do not exist: <name>`. Measured by
+    // a REAL deploy — `--dry-run` accepts it, returning before the association write.
+    'MissingFrontmatterAssociation',
+]);
+/**
+ * Whether this set of diagnostics should stop the agent writing the file.
+ *
+ * An UNRECOGNIZED check code is treated as NON-blocking: check-common gains checks over
+ * time, and a gate that blocked on codes it had never heard of would over-block every time
+ * the engine grew. The supervisor never blocks on its own uncertainty.
+ */
+export function blocksWrite(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === 'error' && BLOCKING_CHECKS.has(diagnostic.check));
+}
+//# sourceMappingURL=blocking.js.map

package/dist/result/blocking.spec.d.ts

@@ -0,0 +1 @@
+export {};