@seanmars/tospec 0.23.0 → 0.26.0-beta

package/dist/core/validation/sister-changes.d.ts

@@ -0,0 +1,93 @@
+import { type DeltaPlan } from '../parsers/requirement-blocks.js';
+/** One capability's delta in another in-progress change. */
+export interface SisterChangeDelta {
+    /** The change's directory name under `tospec/changes/`. */
+    change: string;
+    /** The capability folder name, as that change's delta spells it. */
+    capability: string;
+    plan: DeltaPlan;
+}
+/**
+ * The parsed delta specs of every in-progress change except `changeName`.
+ * `changesDir` is `<root>/tospec/changes`; `archive/` is never listed.
+ *
+ * Validate reads one change against `tospec/specs/` only, so a delta written
+ * against a capability another change is still adding, or a requirement it is
+ * still rewriting, cannot be told from a plain mistake. This is the read that
+ * lets a finding name the other change.
+ *
+ * Best effort: a change or delta that cannot be read is left out, since the
+ * callers only add a hint to a finding that stands without it.
+ */
+export declare function listSisterChangeDeltas(changesDir: string, changeName: string): Promise<SisterChangeDelta[]>;
+export type DeltaOperation = 'ADDED' | 'MODIFIED' | 'REMOVED' | 'RENAMED';
+/** One requirement a delta acts on. */
+export interface DeltaTouch {
+    operation: DeltaOperation;
+    /** As the delta spells it; a RENAMED by its FROM name. */
+    requirement: string;
+    /** 1-based line of the entry (a RENAMED's FROM: line), where the caller has one. */
+    line?: number;
+}
+/**
+ * The requirements `plan` acts on through `operations`. A RENAMED counts by
+ * its FROM name: that is the requirement the main spec holds, and the one a
+ * second change's block would have been copied from.
+ */
+export declare function listDeltaTouches(plan: DeltaPlan, operations: readonly DeltaOperation[]): DeltaTouch[];
+/** A requirement this change's delta and another in-progress change's both act on. */
+export interface SharedRequirement {
+    /** The other change. */
+    change: string;
+    own: DeltaTouch;
+    sister: DeltaTouch;
+}
+/**
+ * Pairs each of `own` (the touches of one capability's delta) with every
+ * sister delta on the same capability that acts on the same requirement
+ * through `sisterOperations`.
+ *
+ * Names are compared folded, the rule the duplicate checks use: two changes
+ * spelling one requirement `Input validation` and `Input  Validation` are
+ * still about one requirement, and this only ever adds a WARNING.
+ */
+export declare function findSharedRequirements(capability: string, own: readonly DeltaTouch[], sisters: readonly SisterChangeDelta[], sisterOperations: readonly DeltaOperation[]): SharedRequirement[];
+/** A rewrite whose requirement a sister change ADDs under another spelling. */
+export interface HeaderMismatch {
+    /** The sister change. */
+    change: string;
+    own: DeltaTouch;
+    /** The name as the sister's ADDED spells it, the one the merge will hold. */
+    suggestedHeader: string;
+}
+/**
+ * The touches in `own` (MODIFIED, REMOVED, RENAMED) whose name folds onto a
+ * sister's ADDED name on the same capability without matching it exactly.
+ * The scan above matches folded, the merge exactly, so archiving the sister
+ * first, which the folded match implies, leaves this delta refused all the same.
+ *
+ * Skipped when the main spec already holds the name, exactly or folded: the
+ * merge matches against it, not the sister, and a near miss there has its
+ * own refusal. Also skipped when another sister ADDs the name exactly: that
+ * one is the requirement the delta was written against.
+ */
+export declare function findHeaderMismatches(capability: string, own: readonly DeltaTouch[], sisters: readonly SisterChangeDelta[], mainSpecNames: readonly string[]): HeaderMismatch[];
+/** When a file was created, or undefined when the platform cannot say. */
+export type BirthtimeSource = (file: string) => Promise<Date | undefined>;
+/**
+ * When the change at `changeDir` was created, in epoch milliseconds, or
+ * undefined when that can no longer be told. Two changes rewriting one
+ * requirement must agree on which archives first, and the older one is the
+ * only order both can read without a state store.
+ *
+ * A datetime `created` is the answer. A date-only one (every change made
+ * before `new change` wrote the time) is completed by the birthtime of
+ * `.tospec.yaml`, which `new change` wrote that day; but clone, checkout and
+ * copy all reset birthtime, and a platform without one reports the epoch, so
+ * it counts only when its local date is the `created` date. Anything less is
+ * undefined: a guessed order would tell one side to wait for the other with
+ * no ground for it. `birthtimeOf` is injectable because birthtime cannot be
+ * set on every platform, so tests cannot produce it on disk.
+ */
+export declare function readChangeOrderKey(changeDir: string, birthtimeOf?: BirthtimeSource): Promise<number | undefined>;
+//# sourceMappingURL=sister-changes.d.ts.map

package/dist/core/validation/sister-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sister-changes.d.ts","sourceRoot":"","sources":["../../../src/core/validation/sister-changes.ts"],"names":[],"mappings":"AAOA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,kCAAkC,CAAC;AAE1C,4DAA4D;AAC5D,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,iBAAiB,EAAE,CAAC,CA4B9B;AAED,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1E,uCAAuC;AACvC,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,cAAc,CAAC;IAC1B,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,cAAc,EAAE,GAAG,UAAU,EAAE,CAerG;AAED,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;IAChB,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,SAAS,UAAU,EAAE,EAC1B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,gBAAgB,EAAE,SAAS,cAAc,EAAE,GAC1C,iBAAiB,EAAE,CAcrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,UAAU,CAAC;IAChB,6EAA6E;IAC7E,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,SAAS,UAAU,EAAE,EAC1B,OAAO,EAAE,SAAS,iBAAiB,EAAE,EACrC,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,cAAc,EAAE,CAgBlB;AAED,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;AAU1E;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,MAAM,EACjB,WAAW,GAAE,eAA+B,GAC3C,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAe7B"}

package/dist/core/validation/sister-changes.js

@@ -0,0 +1,180 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { parse as parseYaml } from 'yaml';
+import { listActiveChangeDirs } from '../../utils/item-discovery.js';
+import { formatLocalDate, parseCreated } from '../../utils/timestamp.js';
+import { METADATA_FILENAME } from '../../utils/change-metadata.js';
+import { findDeltaSpecSources } from '../specs-apply.js';
+import { findFoldedMatch, foldRequirementName, normalizeRequirementName, parseDeltaSpec, } from '../parsers/requirement-blocks.js';
+/**
+ * The parsed delta specs of every in-progress change except `changeName`.
+ * `changesDir` is `<root>/tospec/changes`; `archive/` is never listed.
+ *
+ * Validate reads one change against `tospec/specs/` only, so a delta written
+ * against a capability another change is still adding, or a requirement it is
+ * still rewriting, cannot be told from a plain mistake. This is the read that
+ * lets a finding name the other change.
+ *
+ * Best effort: a change or delta that cannot be read is left out, since the
+ * callers only add a hint to a finding that stands without it.
+ */
+export async function listSisterChangeDeltas(changesDir, changeName) {
+    let changes;
+    try {
+        changes = await listActiveChangeDirs(changesDir);
+    }
+    catch {
+        return [];
+    }
+    const deltas = [];
+    for (const change of changes) {
+        if (change === changeName)
+            continue;
+        let sources;
+        try {
+            // The merge's own list, so a misplaced file archive would never read
+            // cannot be named as the change that adds a capability.
+            sources = await findDeltaSpecSources(path.join(changesDir, change, 'specs'));
+        }
+        catch {
+            continue;
+        }
+        for (const { capability, source } of sources) {
+            try {
+                deltas.push({ change, capability, plan: parseDeltaSpec(await fs.readFile(source, 'utf-8')) });
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return deltas;
+}
+/**
+ * The requirements `plan` acts on through `operations`. A RENAMED counts by
+ * its FROM name: that is the requirement the main spec holds, and the one a
+ * second change's block would have been copied from.
+ */
+export function listDeltaTouches(plan, operations) {
+    const touches = [];
+    if (operations.includes('ADDED')) {
+        for (const block of plan.added)
+            touches.push({ operation: 'ADDED', requirement: block.name, line: block.startLine });
+    }
+    if (operations.includes('MODIFIED')) {
+        for (const block of plan.modified)
+            touches.push({ operation: 'MODIFIED', requirement: block.name, line: block.startLine });
+    }
+    if (operations.includes('REMOVED')) {
+        for (const entry of plan.removedEntries)
+            touches.push({ operation: 'REMOVED', requirement: entry.name, line: entry.startLine });
+    }
+    if (operations.includes('RENAMED')) {
+        for (const { from, fromLine } of plan.renamedEntries)
+            touches.push({ operation: 'RENAMED', requirement: from, line: fromLine });
+    }
+    return touches;
+}
+/**
+ * Pairs each of `own` (the touches of one capability's delta) with every
+ * sister delta on the same capability that acts on the same requirement
+ * through `sisterOperations`.
+ *
+ * Names are compared folded, the rule the duplicate checks use: two changes
+ * spelling one requirement `Input validation` and `Input  Validation` are
+ * still about one requirement, and this only ever adds a WARNING.
+ */
+export function findSharedRequirements(capability, own, sisters, sisterOperations) {
+    const shared = [];
+    for (const sisterDelta of sisters) {
+        if (sisterDelta.capability !== capability)
+            continue;
+        const sisterTouches = listDeltaTouches(sisterDelta.plan, sisterOperations);
+        for (const ownTouch of own) {
+            const folded = foldRequirementName(ownTouch.requirement);
+            for (const sisterTouch of sisterTouches) {
+                if (foldRequirementName(sisterTouch.requirement) !== folded)
+                    continue;
+                shared.push({ change: sisterDelta.change, own: ownTouch, sister: sisterTouch });
+            }
+        }
+    }
+    return shared;
+}
+/**
+ * The touches in `own` (MODIFIED, REMOVED, RENAMED) whose name folds onto a
+ * sister's ADDED name on the same capability without matching it exactly.
+ * The scan above matches folded, the merge exactly, so archiving the sister
+ * first, which the folded match implies, leaves this delta refused all the same.
+ *
+ * Skipped when the main spec already holds the name, exactly or folded: the
+ * merge matches against it, not the sister, and a near miss there has its
+ * own refusal. Also skipped when another sister ADDs the name exactly: that
+ * one is the requirement the delta was written against.
+ */
+export function findHeaderMismatches(capability, own, sisters, mainSpecNames) {
+    const adders = sisters.filter((s) => s.capability === capability);
+    const mismatches = [];
+    for (const ownTouch of own) {
+        if (ownTouch.operation === 'ADDED')
+            continue;
+        if (findFoldedMatch(mainSpecNames, ownTouch.requirement) !== undefined)
+            continue;
+        const exact = normalizeRequirementName(ownTouch.requirement);
+        const addedNames = adders.flatMap((s) => s.plan.added.map((block) => ({ change: s.change, name: block.name })));
+        if (addedNames.some(({ name }) => normalizeRequirementName(name) === exact))
+            continue;
+        const folded = foldRequirementName(ownTouch.requirement);
+        for (const { change, name } of addedNames) {
+            if (foldRequirementName(name) !== folded)
+                continue;
+            mismatches.push({ change, own: ownTouch, suggestedHeader: normalizeRequirementName(name) });
+        }
+    }
+    return mismatches;
+}
+const statBirthtime = async (file) => {
+    try {
+        return (await fs.stat(file)).birthtime;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * When the change at `changeDir` was created, in epoch milliseconds, or
+ * undefined when that can no longer be told. Two changes rewriting one
+ * requirement must agree on which archives first, and the older one is the
+ * only order both can read without a state store.
+ *
+ * A datetime `created` is the answer. A date-only one (every change made
+ * before `new change` wrote the time) is completed by the birthtime of
+ * `.tospec.yaml`, which `new change` wrote that day; but clone, checkout and
+ * copy all reset birthtime, and a platform without one reports the epoch, so
+ * it counts only when its local date is the `created` date. Anything less is
+ * undefined: a guessed order would tell one side to wait for the other with
+ * no ground for it. `birthtimeOf` is injectable because birthtime cannot be
+ * set on every platform, so tests cannot produce it on disk.
+ */
+export async function readChangeOrderKey(changeDir, birthtimeOf = statBirthtime) {
+    const metadataPath = path.join(changeDir, METADATA_FILENAME);
+    let created;
+    try {
+        created = parseYaml(await fs.readFile(metadataPath, 'utf-8'))?.created;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof created !== 'string')
+        return undefined;
+    const parsed = parseCreated(created);
+    if (parsed === null)
+        return undefined;
+    if (parsed.hasTime)
+        return parsed.date.getTime();
+    const birthtime = await birthtimeOf(metadataPath);
+    if (birthtime === undefined || Number.isNaN(birthtime.getTime()))
+        return undefined;
+    return formatLocalDate(birthtime) === created ? birthtime.getTime() : undefined;
+}
+//# sourceMappingURL=sister-changes.js.map

package/dist/core/validation/sister-changes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sister-changes.js","sourceRoot":"","sources":["../../../src/core/validation/sister-changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,wBAAwB,EACxB,cAAc,GAEf,MAAM,kCAAkC,CAAC;AAW1C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,UAAkB,EAClB,UAAkB;IAElB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,oBAAoB,CAAC,UAAU,CAAC,CAAC;IACnD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,KAAK,UAAU;YAAE,SAAS;QACpC,IAAI,OAAsD,CAAC;QAC3D,IAAI,CAAC;YACH,qEAAqE;YACrE,wDAAwD;YACxD,OAAO,GAAG,MAAM,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;QAC/E,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,KAAK,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YAC7C,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,cAAc,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;YAChG,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS;YACX,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAaD;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAe,EAAE,UAAqC;IACrF,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,IAAI,UAAU,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACjC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IACvH,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QACpC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAC7H,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;IAClI,CAAC;IACD,IAAI,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,cAAc;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;IAClI,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAUD;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,UAAkB,EAClB,GAA0B,EAC1B,OAAqC,EACrC,gBAA2C;IAE3C,MAAM,MAAM,GAAwB,EAAE,CAAC;IACvC,KAAK,MAAM,WAAW,IAAI,OAAO,EAAE,CAAC;QAClC,IAAI,WAAW,CAAC,UAAU,KAAK,UAAU;YAAE,SAAS;QACpD,MAAM,aAAa,GAAG,gBAAgB,CAAC,WAAW,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;QAC3E,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;YACzD,KAAK,MAAM,WAAW,IAAI,aAAa,EAAE,CAAC;gBACxC,IAAI,mBAAmB,CAAC,WAAW,CAAC,WAAW,CAAC,KAAK,MAAM;oBAAE,SAAS;gBACtE,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAWD;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAClC,UAAkB,EAClB,GAA0B,EAC1B,OAAqC,EACrC,aAAgC;IAEhC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,KAAK,UAAU,CAAC,CAAC;IAClE,MAAM,UAAU,GAAqB,EAAE,CAAC;IACxC,KAAK,MAAM,QAAQ,IAAI,GAAG,EAAE,CAAC;QAC3B,IAAI,QAAQ,CAAC,SAAS,KAAK,OAAO;YAAE,SAAS;QAC7C,IAAI,eAAe,CAAC,aAAa,EAAE,QAAQ,CAAC,WAAW,CAAC,KAAK,SAAS;YAAE,SAAS;QACjF,MAAM,KAAK,GAAG,wBAAwB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC7D,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAChH,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,wBAAwB,CAAC,IAAI,CAAC,KAAK,KAAK,CAAC;YAAE,SAAS;QACtF,MAAM,MAAM,GAAG,mBAAmB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QACzD,KAAK,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,UAAU,EAAE,CAAC;YAC1C,IAAI,mBAAmB,CAAC,IAAI,CAAC,KAAK,MAAM;gBAAE,SAAS;YACnD,UAAU,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,eAAe,EAAE,wBAAwB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9F,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAKD,MAAM,aAAa,GAAoB,KAAK,EAAE,IAAI,EAAE,EAAE;IACpD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAiB,EACjB,WAAW,GAAoB,aAAa;IAE5C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC;IAC7D,IAAI,OAAgB,CAAC;IACrB,IAAI,CAAC;QACH,OAAO,GAAI,SAAS,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAoC,EAAE,OAAO,CAAC;IAC7G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAClD,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACtC,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;IACjD,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,YAAY,CAAC,CAAC;IAClD,IAAI,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IACnF,OAAO,eAAe,CAAC,SAAS,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClF,CAAC"}

package/dist/core/validation/task-markers.d.ts

@@ -0,0 +1,9 @@
+import type { TaskNumberingDocument } from './task-numbering.js';
+export interface TaskMarkerIssue {
+    path: string;
+    /** Absent for the file-level "no tasks" finding. */
+    line?: number;
+    message: string;
+}
+export declare function findTaskMarkerIssues(documents: readonly TaskNumberingDocument[]): TaskMarkerIssue[];
+//# sourceMappingURL=task-markers.d.ts.map

package/dist/core/validation/task-markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-markers.d.ts","sourceRoot":"","sources":["../../../src/core/validation/task-markers.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAgCjE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAC1C,eAAe,EAAE,CAyCnB"}

package/dist/core/validation/task-markers.js

@@ -0,0 +1,71 @@
+import { parseTasksFromContent } from '../../utils/task-progress.js';
+import { buildCodeFenceMask, normalizeDocument } from '../parsers/requirement-text.js';
+/**
+ * Tracked-task lines the counter cannot see.
+ *
+ * The counter follows GFM on purpose (see `TASK_PATTERN`): a box GitHub does
+ * not draw is not a task. The cost is that `- [~] 1.2 deferred` drops out of the
+ * denominator, so a change with that line left reads `all_done` and archives
+ * with no gate firing. Widening the counter would count boxes nobody can tick
+ * in the rendered file, so validate names the line instead.
+ */
+/**
+ * A list item opening with a short bracket. Kept narrow so prose does not trip
+ * it: at most two characters inside (`[~]`, `[]`, `[ x]`), and the `]` not
+ * followed by `(`, `[` or `:`, which would make it a link, a reference link or
+ * a link definition. A leading `^` is a footnote reference.
+ *
+ * Linear by construction: anchored, `[ \t]*` and the list marker share no
+ * character, and the bracket body is bounded.
+ */
+const CHECKBOX_LIKE = /^[ \t]*(?:[-*+]|\d{1,9}[.)])[ \t]+\[(?!\^)([^\]\r\n]{0,2})\](?![([:])/;
+/**
+ * A letter or digit other than x reads as a label (`[P1]`, `[v2]`, `[a]`), not
+ * a mistyped box. The length bound alone let those through, and under
+ * `--strict` the warning refused a change over a priority tag. `[v]` goes with
+ * them: a check-mark habit for some, but telling it from a one-letter label is
+ * a guess, and a missed warning costs less than a refused change.
+ */
+const LABEL_CHARACTER = /[0-9a-wyz]/i;
+export function findTaskMarkerIssues(documents) {
+    const issues = [];
+    let taskCount = 0;
+    const nonBlankPaths = [];
+    for (const document of documents) {
+        // Split and masked exactly as parseTasksFromContent does, so the line
+        // numbers reported here are the ones the counter uses.
+        const lines = normalizeDocument(document.content).split('\n');
+        const fenced = buildCodeFenceMask(lines);
+        const taskLines = new Set(parseTasksFromContent(document.content).map((t) => t.line));
+        taskCount += taskLines.size;
+        if (document.content.trim() !== '')
+            nonBlankPaths.push(document.path);
+        lines.forEach((line, index) => {
+            if (fenced[index] || taskLines.has(index + 1))
+                return;
+            const match = CHECKBOX_LIKE.exec(line);
+            if (!match || LABEL_CHARACTER.test(match[1]))
+                return;
+            const marker = `[${match[1]}]`;
+            issues.push({
+                path: document.path,
+                line: index + 1,
+                message: /^[ xX]$/.test(match[1])
+                    ? `"${marker}" has no blank after it, so GitHub does not draw a checkbox and the line is not counted as a task. Add a space after "${marker}".`
+                    : `"${marker}" is not a checkbox GitHub draws, so the line is not counted as a task. Use "[ ]" for open work or "[x]" for done work.`,
+            });
+        });
+    }
+    // Judged across all tracked files, like apply's "contains no tasks" state: in
+    // a multi-file schema one file without tasks (an index, say) is legitimate.
+    if (taskCount === 0) {
+        for (const filePath of nonBlankPaths) {
+            issues.push({
+                path: filePath,
+                message: `${filePath} has content but no tasks, so apply reports it blocked and archive cannot count progress. Write each task as "- [ ] <id> <text>".`,
+            });
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=task-markers.js.map

package/dist/core/validation/task-markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-markers.js","sourceRoot":"","sources":["../../../src/core/validation/task-markers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGvF;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,MAAM,aAAa,GAAG,uEAAuE,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,aAAa,CAAC;AAStC,MAAM,UAAU,oBAAoB,CAClC,SAA2C;IAE3C,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,aAAa,GAAa,EAAE,CAAC;IAEnC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,sEAAsE;QACtE,uDAAuD;QACvD,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;QACzC,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,qBAAqB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACtF,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC;QAC5B,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE;YAAE,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAEtE,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;YAC5B,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC;gBAAE,OAAO;YACtD,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACvC,IAAI,CAAC,KAAK,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;gBAAE,OAAO;YACrD,MAAM,MAAM,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;YAC/B,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,IAAI,EAAE,KAAK,GAAG,CAAC;gBACf,OAAO,EAAE,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;oBAC/B,CAAC,CAAC,IAAI,MAAM,yHAAyH,MAAM,IAAI;oBAC/I,CAAC,CAAC,IAAI,MAAM,yHAAyH;aACxI,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,4EAA4E;IAC5E,IAAI,SAAS,KAAK,CAAC,EAAE,CAAC;QACpB,KAAK,MAAM,QAAQ,IAAI,aAAa,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC;gBACV,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,GAAG,QAAQ,mIAAmI;aACxJ,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -15,7 +15,51 @@ export interface ValidationIssue {
      * `ValidationReport.notes`, deduplicated, and clears them from the issues.
      */
     note?: string;
+    /**
+     * Set only on findings a caller has to act on without reading the message
+     * (`ARCHIVE_REFUSAL_CODE`, `SISTER_CHANGE_OVERLAP_CODE`,
+     * `REQUIREMENT_HEADER_MISMATCH_CODE`). Most issues have
+     * none: their level and path say enough.
+     */
+    code?: string;
+    /**
+     * The other in-progress changes that must archive before this one, when the
+     * archive order is the whole cause: no edit to this delta settles it, and
+     * an agent told to clear every WARNING would otherwise "fix" a correct
+     * delta. Set only where the message itself says to archive them first.
+     */
+    blockedBy?: string[];
+    /**
+     * The exact requirement name to write instead, on a delta name that differs
+     * only in case or spacing from one another in-progress change ADDs
+     * (`REQUIREMENT_HEADER_MISMATCH_CODE`, and the refusal it causes) or from
+     * one the main spec holds (that refusal alone). A field, so the name can be
+     * fixed without parsing the message.
+     */
+    suggestedHeader?: string;
 }
+/**
+ * A delta archive's merge would refuse. A WARNING, not an ERROR: when a sister
+ * change still has to add the capability, this change is not wrong, only
+ * early. So `valid` stays true and an agent reading only the verdict or the
+ * exit code missed it; matching the message text breaks on any rewording.
+ */
+export declare const ARCHIVE_REFUSAL_CODE = "archive_would_refuse";
+/**
+ * This delta rewrites a requirement another in-progress change also acts on,
+ * so whichever archives second overwrites the first one's edit. A WARNING
+ * coded for the same reason as a refusal: what to do turns on the order, and
+ * the order is in `blockedBy`, not in the wording.
+ */
+export declare const SISTER_CHANGE_OVERLAP_CODE = "sister_change_overlap";
+/**
+ * A MODIFIED, REMOVED or RENAMED (FROM) name that folds onto a sister
+ * change's ADDED name but is not spelled the same. The sister scan matches
+ * folded and the merge matches exactly, so "archive the sister first" would
+ * promise a fix the merge then refuses. An ERROR, unlike the refusal: no
+ * archive order makes the delta apply, only the edit `suggestedHeader` names.
+ */
+export declare const REQUIREMENT_HEADER_MISMATCH_CODE = "requirement_header_mismatch";
 export interface ValidationReport {
     valid: boolean;
     issues: ValidationIssue[];
@@ -27,6 +71,20 @@ export interface ValidationReport {
     /** Distinct `ValidationIssue.note` values, each carried once. */
     notes?: string[];
 }
+/**
+ * Why archive would refuse a rebuilt spec. `main`: the main spec already
+ * fails, so `issues` are its own and `specPath` is the file to fix. `delta`:
+ * the main spec is valid, so the change's delta caused the rebuilt spec's
+ * `issues`.
+ */
+export type RebuiltSpecFailure = {
+    source: 'main';
+    specPath: string;
+    issues: ValidationIssue[];
+} | {
+    source: 'delta';
+    issues: ValidationIssue[];
+};
 /**
  * Severity symbol for human output. Shared so no two surfaces show different
  * glyphs for one level; the line formats around it differ on purpose

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAInE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,gCAAgC,gCAAgC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,GAC/D;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,eAAe,EAAE,CAAA;CAAE,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,GAAG,MAAM,CAInE"}

package/dist/core/validation/types.js

@@ -1,3 +1,25 @@
+/**
+ * A delta archive's merge would refuse. A WARNING, not an ERROR: when a sister
+ * change still has to add the capability, this change is not wrong, only
+ * early. So `valid` stays true and an agent reading only the verdict or the
+ * exit code missed it; matching the message text breaks on any rewording.
+ */
+export const ARCHIVE_REFUSAL_CODE = 'archive_would_refuse';
+/**
+ * This delta rewrites a requirement another in-progress change also acts on,
+ * so whichever archives second overwrites the first one's edit. A WARNING
+ * coded for the same reason as a refusal: what to do turns on the order, and
+ * the order is in `blockedBy`, not in the wording.
+ */
+export const SISTER_CHANGE_OVERLAP_CODE = 'sister_change_overlap';
+/**
+ * A MODIFIED, REMOVED or RENAMED (FROM) name that folds onto a sister
+ * change's ADDED name but is not spelled the same. The sister scan matches
+ * folded and the merge matches exactly, so "archive the sister first" would
+ * promise a fix the merge then refuses. An ERROR, unlike the refusal: no
+ * archive order makes the delta apply, only the edit `suggestedHeader` names.
+ */
+export const REQUIREMENT_HEADER_MISMATCH_CODE = 'requirement_header_mismatch';
 /**
  * Severity symbol for human output. Shared so no two surfaces show different
  * glyphs for one level; the line formats around it differ on purpose

package/dist/core/validation/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AAgCA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAA+B;IACzD,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACpC,OAAO,GAAG,CAAC;AACb,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/validation/types.ts"],"names":[],"mappings":"AA0CA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAC;AAElE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,6BAA6B,CAAC;AAwB9E;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,KAA+B;IACzD,IAAI,KAAK,KAAK,OAAO;QAAE,OAAO,GAAG,CAAC;IAClC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IACpC,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/core/validation/validator.d.ts

@@ -1,9 +1,49 @@
-import { ValidationReport } from './types.js';
+import { ValidationReport, ValidationIssue, RebuiltSpecFailure } from './types.js';
+import { type DeltaOperation } from './sister-changes.js';
+/**
+ * The edit that writes `suggestedHeader` into the delta. A RENAMED names its
+ * requirement on the `- FROM:` bullet, and "change the header" sent the
+ * author to a `### Requirement:` line the entry does not have.
+ */
+export declare function headerCorrectionClause(operation: DeltaOperation, suggestedHeader: string): string;
+/**
+ * What a refusal's `suggestedHeader` corrects, for apply's fix: which line to
+ * edit (a RENAMED's is the FROM line) and whose spelling the name is. Kept
+ * off `ValidationIssue`: validate's message already says both, and apply's
+ * fix is the only text written from them.
+ */
+export interface HeaderCorrection {
+    operation: DeltaOperation;
+    /** A sister change's ADDED, which no archive order settles, or the main spec's own name. */
+    source: 'sister-change' | 'main-spec';
+}
+/** One delta archive's merge would refuse, as `findArchiveRefusals` reports it. */
+export interface ArchiveRefusal {
+    issue: ValidationIssue;
+    /** Set exactly when `issue.suggestedHeader` is. */
+    headerCorrection?: HeaderCorrection;
+}
 export declare class Validator {
     private strictMode;
     constructor(strictMode?: boolean);
     validateSpec(filePath: string): Promise<ValidationReport>;
     validateSpecContent(specName: string, content: string): Promise<ValidationReport>;
+    /**
+     * Whether archive would refuse to write `rebuilt`, and whose fault that is.
+     * Null when it would write it.
+     *
+     * The verdict counts ERRORs only, whatever this validator's strictness:
+     * archive judges the rebuilt spec non-strictly, and this answers for archive.
+     *
+     * A main spec that already fails is the cause, even if the delta adds its own
+     * faults: those the change's validation reports anyway, while the main
+     * spec's are reported nowhere a change author looks — and its issue paths,
+     * unlike the rebuilt spec's, are the ones `tospec validate <spec>` prints.
+     */
+    diagnoseRebuiltSpec(specName: string, rebuilt: string, original: {
+        path: string;
+        content: string;
+    } | undefined): Promise<RebuiltSpecFailure | null>;
     /**
      * Validate delta-formatted spec files under a change directory: at least one
      * delta overall, ADDED/MODIFIED requirements carrying SHALL/MUST and a
@@ -17,9 +57,22 @@ export declare class Validator {
      * `archivePreflight` is opt-out because the dry run rebuilds every updated
      * spec. For `tospec validate` that is the point; for `archive` it is
      * duplication, since the real merge follows moments later.
+     *
+     * `requireDelta: false` is for a change whose schema demands no delta. Every
+     * other check still runs, because archive merges each
+     * specs/<capability>/spec.md whatever the schema says. Dropped: the "at least
+     * one delta" ERROR, and the specs/spec.md ERROR for a file with no delta
+     * header, which such a schema leaves as notes, as at the rest of the root.
+     *
+     * `sisterChanges: false` drops the check against other in-progress changes'
+     * deltas. Archive turns it off: it runs its own check, in the direction the
+     * archive decides (this change goes first), where this one would advise
+     * archiving the other change first.
      */
     validateChangeDeltaSpecs(changeDir: string, mainSpecsDir?: string, options?: {
         archivePreflight?: boolean;
+        requireDelta?: boolean;
+        sisterChanges?: boolean;
     }): Promise<ValidationReport>;
     private convertZodErrors;
     private applySpecRules;
@@ -36,6 +89,7 @@ export declare class Validator {
     /**
      * The main spec's two Purpose rules, applied to a delta that is about to
      * create that main spec. Placeholder before brevity, as on the spec path.
+     * For an existing capability, only that a delta Purpose will be dropped.
      *
      * `mainSpecsDir` absent means new capabilities cannot be told from existing
      * ones, so nothing is reported.
@@ -65,9 +119,32 @@ export declare class Validator {
      * is missing is also what a change modifying a sibling's unarchived
      * requirement looks like. INFO was wrong because `--strict` ignores it, so the
      * pre-archive gate waved through changes archive would refuse.
-     * tospec/decisions/20260916_154000-archive-dry-run-findings-are-warnings.md
      */
     private findArchiveBlockers;
+    /**
+     * The header mismatches behind a missing-target refusal: the one requirement
+     * a MODIFIED or RENAMED names, or, for a capability with no main spec, every
+     * rewrite in the delta, since the merge stops before reading any of them.
+     * Through `findHeaderMismatches`, so the refusal and the sister scan's
+     * ERROR cannot disagree about which headers mismatch.
+     */
+    private findDeltaHeaderMismatches;
+    /**
+     * What archive's merge would refuse in this change, from the dry run above,
+     * for `instructions apply` to report before the work starts: it said ready
+     * for a delta validate already called unarchivable, so the agent learned it
+     * after implementing. One dry run serves both, so they cannot disagree.
+     *
+     * Without the structural pass's paths: apply reports none of its findings,
+     * so a delta fault that resurfaces in the rebuilt spec is the only word apply
+     * gets of it. Suppressed there as already reported, apply would say nothing.
+     */
+    findArchiveRefusals(changeDir: string, mainSpecsDir: string): Promise<ArchiveRefusal[]>;
+    /**
+     * The rebuilt spec's validation failures, as archive would meet them. WARNING
+     * for the reason `findArchiveBlockers` gives.
+     */
+    private findRebuiltSpecBlockers;
     /**
      * Scenario-quality rules for a delta requirement block: only `#### Scenario:`
      * headers count, each scenario body must contain uppercase WHEN and THEN, and

package/dist/core/validation/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/validator.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,gBAAgB,EAAoC,MAAM,YAAY,CAAC;AAoFhF,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAU;IAE5B,YAAY,UAAU,GAAE,OAAe,EAEtC;IAEK,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc9D;IAEK,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgBtF;IAED;;;;;;;;;;;;;OAaG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;KAAO,GAC3C,OAAO,CAAC,gBAAgB,CAAC,CA4Z3B;IAED,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,cAAc;IAgFtB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,sBAAsB;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAuBtC;;;;;;OAMG;YACW,yBAAyB;IA4CvC;;;;;;;;;;OAUG;YACW,4BAA4B;IAoJ1C;;;;;;;;;;;;;OAaG;YACW,mBAAmB;IAyEjC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAqE7B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;CAalC"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/validator.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,gBAAgB,EAChB,eAAe,EAEf,kBAAkB,EAInB,MAAM,YAAY,CAAC;AA2CpB,OAAO,EAML,KAAK,cAAc,EAIpB,MAAM,qBAAqB,CAAC;AA6J7B;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAGjG;AA8DD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,cAAc,CAAC;IAC1B,4FAA4F;IAC5F,MAAM,EAAE,eAAe,GAAG,WAAW,CAAC;CACvC;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,eAAe,CAAC;IACvB,mDAAmD;IACnD,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACrC;AAeD,qBAAa,SAAS;IACpB,OAAO,CAAC,UAAU,CAAU;IAE5B,YAAY,UAAU,GAAE,OAAe,EAEtC;IAEK,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAc9D;IAEK,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAiBtF;IAED;;;;;;;;;;;OAWG;IACG,mBAAmB,CACvB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,GACtD,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAUpC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,wBAAwB,CAC5B,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,OAAO,GAAE;QAAE,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,YAAY,CAAC,EAAE,OAAO,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAC5F,OAAO,CAAC,gBAAgB,CAAC,CA0iB3B;IAED,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,cAAc;IA+EtB,OAAO,CAAC,mBAAmB;IAc3B,OAAO,CAAC,YAAY;IA0BpB,OAAO,CAAC,sBAAsB;IAQ9B;;;;;OAKG;IACH,OAAO,CAAC,8BAA8B;IAuBtC;;;;;;;OAOG;YACW,yBAAyB;IAiEvC;;;;;;;;;;OAUG;YACW,4BAA4B;IA4J1C;;;;;;;;;;;;OAYG;YACW,mBAAmB;IAmIjC;;;;;;OAMG;YACW,yBAAyB;IAsBvC;;;;;;;;;OASG;IACG,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAK5F;IAED;;;OAGG;YACW,uBAAuB;IA4BrC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAqE7B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;CAalC"}