@seanmars/tospec 0.19.0-beta.8 → 0.20.0

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

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/validation/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAGrC,eAAO,MAAM,sBAAsB,OAAO,CAAC;AAC3C,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAQxC,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAC/E,eAAO,MAAM,0BAA0B,oCAAoC,CAAC;AAG5E,eAAO,MAAM,mBAAmB;aAE9B,cAAc,EAAE,+BAA+B;aAC/C,iBAAiB,EAAE,kCAAkC;aACrD,oBAAoB,EAAE,gDAAgD;aACtE,wBAAwB,EAAE,6CAA6C;aACvE,eAAe,EAAE,2BAA2B;aAC5C,kBAAkB,EAAE,iCAAiC;aACrD,oBAAoB,EAAE,yCAAyC;aAC/D,iBAAiB,EAAE,6BAA6B;aAChD,oBAAoB;aACpB,mBAAmB;aACnB,iBAAiB,EAAE,sCAAsC;aACzD,gBAAgB,EAAE,qCAAqC;aACvD,sBAAsB;aACtB,gBAAgB,EAAE,2BAA2B;aAC7C,uBAAuB,EAAE,mCAAmC;aAG5D,iBAAiB;aACjB,sBAAsB;aAKtB,oBAAoB;aACpB,2BAA2B,EAAE,gCAAgC;aAC7D,0BAA0B,EAAE,mCAAmC;aAQ/D,eAAe,EACb,0iBAA0iB;aAC5iB,2BAA2B,EACzB,6QAA6Q;aAC/Q,6BAA6B,EAC3B,0IAA0I;aAC5I,qBAAqB,EACnB,0IAA0I;CACpI,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/core/validation/constants.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAC/C,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAOxC,eAAO,MAAM,0BAA0B,uCAAuC,CAAC;AAC/E,eAAO,MAAM,0BAA0B,oCAAoC,CAAC;AAE5E,eAAO,MAAM,mBAAmB;aAE9B,cAAc,EAAE,+BAA+B;aAC/C,iBAAiB,EAAE,kCAAkC;aACrD,oBAAoB,EAAE,gDAAgD;aACtE,wBAAwB,EAAE,6CAA6C;aACvE,eAAe,EAAE,2BAA2B;aAC5C,kBAAkB,EAAE,iCAAiC;aACrD,oBAAoB,EAAE,yCAAyC;aAC/D,iBAAiB,EAAE,6BAA6B;aAChD,iBAAiB,EAAE,sCAAsC;aACzD,gBAAgB,EAAE,qCAAqC;aACvD,sBAAsB;aACtB,gBAAgB,EAAE,2BAA2B;aAC7C,uBAAuB,EAAE,mCAAmC;aAG5D,iBAAiB;aACjB,sBAAsB;aAQtB,uBAAuB;aAIvB,qBAAqB;aAIrB,4BAA4B;aAK5B,oBAAoB;aAKpB,eAAe,EACb,4hBAA4hB;aAC9hB,2BAA2B,EACzB,6QAA6Q;aAC/Q,6BAA6B,EAC3B,0IAA0I;aAC5I,qBAAqB,EACnB,0IAA0I;CACpI,CAAC"}

package/dist/core/validation/constants.js

@@ -1,22 +1,16 @@
-/**
- * Validation threshold constants
- */
-// Minimum character lengths
-export const MIN_WHY_SECTION_LENGTH = 50;
+// Thresholds shared by the validator's imperative checks. Per-section bounds
+// such as `Why`'s are not here: those are declared per artifact in
+// `schemas/<name>/schema.yaml` (`minSectionLength` / `maxSectionLength`).
 export const MIN_PURPOSE_LENGTH = 50;
-// Maximum character/item limits
-export const MAX_WHY_SECTION_LENGTH = 1000;
 export const MAX_REQUIREMENT_TEXT_LENGTH = 500;
 export const MAX_DELTAS_PER_CHANGE = 10;
-// The Purpose `tospec archive` stamps into a main spec it creates when the delta
-// introduced the capability without a usable `## Purpose`. Named here and
-// composed from these two halves at the write site so validation recognises the
-// placeholder through the same definition that produces it: a second, hand-copied
-// spelling stops matching the day the wording changes, and a check that matches
-// nothing looks exactly like a check that found nothing.
+// The Purpose `tospec archive` stamps into a main spec it creates for a delta
+// that introduced the capability without a usable `## Purpose`. Composed from
+// these two halves at the write site so validation recognises it through the
+// same definition that produces it: a second spelling stops matching the day
+// the wording changes, and a check that matches nothing looks like a clean one.
 export const PURPOSE_PLACEHOLDER_PREFIX = 'TBD - created by archiving change ';
 export const PURPOSE_PLACEHOLDER_SUFFIX = '. Update Purpose after archive.';
-// Validation messages
 export const VALIDATION_MESSAGES = {
     // Required content
     SCENARIO_EMPTY: 'Scenario text cannot be empty',
@@ -27,8 +21,6 @@ export const VALIDATION_MESSAGES = {
     SPEC_PURPOSE_EMPTY: 'Purpose section cannot be empty',
     SPEC_NO_REQUIREMENTS: 'Spec must have at least one requirement',
     CHANGE_NAME_EMPTY: 'Change name cannot be empty',
-    CHANGE_WHY_TOO_SHORT: `Why section must be at least ${MIN_WHY_SECTION_LENGTH} characters`,
-    CHANGE_WHY_TOO_LONG: `Why section should not exceed ${MAX_WHY_SECTION_LENGTH} characters`,
     CHANGE_WHAT_EMPTY: 'What Changes section cannot be empty',
     CHANGE_NO_DELTAS: 'Change must have at least one delta',
     CHANGE_TOO_MANY_DELTAS: `Consider splitting changes with more than ${MAX_DELTAS_PER_CHANGE} deltas`,
@@ -40,16 +32,24 @@ export const VALIDATION_MESSAGES = {
         'writes for a new capability, or a `TBD`/`TODO` marker left in its place). Replace it with what this ' +
         'capability is for, editing the main spec directly: a `## Purpose` in a delta is read only when the ' +
         'capability is created, so it cannot replace this one.',
+    // Delta-side twins of the two rules above, worded separately on purpose: the
+    // main-spec messages say to edit the main spec, and there is none to edit
+    // while the capability exists only as a delta.
+    DELTA_PURPOSE_TOO_BRIEF: `Purpose section is too brief (less than ${MIN_PURPOSE_LENGTH} characters). ` +
+        'This capability has no main spec yet, so `tospec archive` will copy this Purpose into the one it ' +
+        'creates — write it here, in the delta, while you still can.',
+    DELTA_PURPOSE_MISSING: 'Delta has no `## Purpose`. This capability has no main spec yet, so `tospec archive` will create ' +
+        'one and, with nothing to copy, write a `TBD` placeholder as its Purpose. Open the delta with one ' +
+        'sentence on why this capability exists.',
+    DELTA_PURPOSE_IS_PLACEHOLDER: 'Purpose section is still a placeholder rather than a Purpose anyone wrote (a `TBD`/`TODO` marker, or ' +
+        'the sentence `tospec archive` writes when a delta supplies none). This capability has no main spec ' +
+        'yet, so archive will copy this text into the one it creates — replace it here, in the delta, with ' +
+        'what this capability is for.',
     REQUIREMENT_TOO_LONG: `Requirement text is very long (>${MAX_REQUIREMENT_TEXT_LENGTH} characters). Consider breaking it down.`,
-    DELTA_DESCRIPTION_TOO_BRIEF: 'Delta description is too brief',
-    DELTA_MISSING_REQUIREMENTS: 'Delta should include requirements',
-    // Guidance snippets (appended to primary messages for remediation)
-    // The skip_specs sentence is not an aside. Without it this message offers one
-    // way out — write a delta — to a change that may genuinely have no observable
-    // behaviour, which is exactly the pressure the schema warns against when it
-    // says "never invent a Requirement to get past validation". Naming the second,
-    // legitimate exit is what stops the first from being taken dishonestly.
-    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "tospec show <change-id> --json --deltas-only" to inspect parsed deltas. If this change genuinely has no externally observable effect (tooling, CI, docs-only), set `skip_specs: true` in its .tospec.yaml instead — never invent a Requirement to satisfy this check.',
+    // Guidance snippets, appended to a primary message. The skip_specs sentence is
+    // load-bearing: without it the only way out offered is "write a delta", to a
+    // change that may genuinely have no observable behaviour.
+    GUIDE_NO_DELTAS: 'No deltas found. Ensure your change has a specs/ directory with capability folders (e.g. specs/http-server/spec.md) containing .md files that use delta headers (## ADDED/MODIFIED/REMOVED/RENAMED Requirements) and that each requirement includes at least one "#### Scenario:" block. Tip: run "tospec show <change-id> --json" to inspect parsed deltas. If this change genuinely has no externally observable effect (tooling, CI, docs-only), set `skip_specs: true` in its .tospec.yaml instead — never invent a Requirement to satisfy this check.',
     GUIDE_MISSING_SPEC_SECTIONS: 'Missing required sections. Expected headers: "## Purpose" and "## Requirements". Example:\n## Purpose\n[brief purpose]\n\n## Requirements\n### Requirement: Clear requirement statement\nUsers SHALL ...\n\n#### Scenario: Descriptive name\n- **WHEN** ...\n- **THEN** ...',
     GUIDE_MISSING_CHANGE_SECTIONS: 'Missing required sections. Expected headers: "## Why" and "## What Changes". Ensure deltas are documented in specs/ using delta headers.',
     GUIDE_SCENARIO_FORMAT: 'Scenarios must use level-4 headers. Convert bullet lists into:\n#### Scenario: Short name\n- **WHEN** ...\n- **THEN** ...\n- **AND** ...',

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

@@ -1 +1 @@
-{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/validation/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,4BAA4B;AAC5B,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AACzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAErC,gCAAgC;AAChC,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC;AAC3C,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,iFAAiF;AACjF,0EAA0E;AAC1E,gFAAgF;AAChF,kFAAkF;AAClF,gFAAgF;AAChF,yDAAyD;AACzD,MAAM,CAAC,MAAM,0BAA0B,GAAG,oCAAoC,CAAC;AAC/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,iCAAiC,CAAC;AAE5E,sBAAsB;AACtB,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,mBAAmB;IACnB,cAAc,EAAE,+BAA+B;IAC/C,iBAAiB,EAAE,kCAAkC;IACrD,oBAAoB,EAAE,gDAAgD;IACtE,wBAAwB,EAAE,6CAA6C;IACvE,eAAe,EAAE,2BAA2B;IAC5C,kBAAkB,EAAE,iCAAiC;IACrD,oBAAoB,EAAE,yCAAyC;IAC/D,iBAAiB,EAAE,6BAA6B;IAChD,oBAAoB,EAAE,gCAAgC,sBAAsB,aAAa;IACzF,mBAAmB,EAAE,iCAAiC,sBAAsB,aAAa;IACzF,iBAAiB,EAAE,sCAAsC;IACzD,gBAAgB,EAAE,qCAAqC;IACvD,sBAAsB,EAAE,6CAA6C,qBAAqB,SAAS;IACnG,gBAAgB,EAAE,2BAA2B;IAC7C,uBAAuB,EAAE,mCAAmC;IAE5D,WAAW;IACX,iBAAiB,EAAE,2CAA2C,kBAAkB,cAAc;IAC9F,sBAAsB,EACpB,2GAA2G;QAC3G,sGAAsG;QACtG,qGAAqG;QACrG,uDAAuD;IACzD,oBAAoB,EAAE,mCAAmC,2BAA2B,0CAA0C;IAC9H,2BAA2B,EAAE,gCAAgC;IAC7D,0BAA0B,EAAE,mCAAmC;IAE/D,mEAAmE;IACnE,8EAA8E;IAC9E,8EAA8E;IAC9E,4EAA4E;IAC5E,+EAA+E;IAC/E,wEAAwE;IACxE,eAAe,EACb,0iBAA0iB;IAC5iB,2BAA2B,EACzB,6QAA6Q;IAC/Q,6BAA6B,EAC3B,0IAA0I;IAC5I,qBAAqB,EACnB,0IAA0I;CACpI,CAAC"}
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../../src/core/validation/constants.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,mEAAmE;AACnE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,kBAAkB,GAAG,EAAE,CAAC;AACrC,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAC/C,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,oCAAoC,CAAC;AAC/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,iCAAiC,CAAC;AAE5E,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,mBAAmB;IACnB,cAAc,EAAE,+BAA+B;IAC/C,iBAAiB,EAAE,kCAAkC;IACrD,oBAAoB,EAAE,gDAAgD;IACtE,wBAAwB,EAAE,6CAA6C;IACvE,eAAe,EAAE,2BAA2B;IAC5C,kBAAkB,EAAE,iCAAiC;IACrD,oBAAoB,EAAE,yCAAyC;IAC/D,iBAAiB,EAAE,6BAA6B;IAChD,iBAAiB,EAAE,sCAAsC;IACzD,gBAAgB,EAAE,qCAAqC;IACvD,sBAAsB,EAAE,6CAA6C,qBAAqB,SAAS;IACnG,gBAAgB,EAAE,2BAA2B;IAC7C,uBAAuB,EAAE,mCAAmC;IAE5D,WAAW;IACX,iBAAiB,EAAE,2CAA2C,kBAAkB,cAAc;IAC9F,sBAAsB,EACpB,2GAA2G;QAC3G,sGAAsG;QACtG,qGAAqG;QACrG,uDAAuD;IACzD,6EAA6E;IAC7E,0EAA0E;IAC1E,+CAA+C;IAC/C,uBAAuB,EACrB,2CAA2C,kBAAkB,gBAAgB;QAC7E,mGAAmG;QACnG,6DAA6D;IAC/D,qBAAqB,EACnB,mGAAmG;QACnG,mGAAmG;QACnG,yCAAyC;IAC3C,4BAA4B,EAC1B,uGAAuG;QACvG,qGAAqG;QACrG,oGAAoG;QACpG,8BAA8B;IAChC,oBAAoB,EAAE,mCAAmC,2BAA2B,0CAA0C;IAE9H,+EAA+E;IAC/E,6EAA6E;IAC7E,0DAA0D;IAC1D,eAAe,EACb,4hBAA4hB;IAC9hB,2BAA2B,EACzB,6QAA6Q;IAC/Q,6BAA6B,EAC3B,0IAA0I;IAC5I,qBAAqB,EACnB,0IAA0I;CACpI,CAAC"}

package/dist/core/validation/prose-length.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How much prose a string carries, one unit being roughly one English
+ * character.
+ *
+ * The minimum-length thresholds were calibrated on English — 50 characters is
+ * about eight words — while the same eight words of Traditional Chinese are
+ * around 20, so a full answer reads as too brief purely for being written in
+ * Chinese. Counting a double-width character as two units puts both languages
+ * on one scale.
+ *
+ * Applied to minimums only. A maximum asks "is this an essay?", where the raw
+ * character count is the conservative answer.
+ */
+export declare function proseLength(text: string): number;
+//# sourceMappingURL=prose-length.d.ts.map

package/dist/core/validation/prose-length.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose-length.d.ts","sourceRoot":"","sources":["../../../src/core/validation/prose-length.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD"}

package/dist/core/validation/prose-length.js

@@ -0,0 +1,29 @@
+/**
+ * East Asian Wide and Fullwidth code points — the ones a terminal draws in two
+ * columns. The conventional wcwidth set, not a full Unicode property scan: this
+ * is a length *heuristic*, and a missed rare block costs one unit.
+ */
+const WIDE_CHARACTER = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︐-︙︰-﹯＀-｠￠-￦]|[\u{20000}-\u{3FFFD}]/u;
+/**
+ * How much prose a string carries, one unit being roughly one English
+ * character.
+ *
+ * The minimum-length thresholds were calibrated on English — 50 characters is
+ * about eight words — while the same eight words of Traditional Chinese are
+ * around 20, so a full answer reads as too brief purely for being written in
+ * Chinese. Counting a double-width character as two units puts both languages
+ * on one scale.
+ *
+ * Applied to minimums only. A maximum asks "is this an essay?", where the raw
+ * character count is the conservative answer.
+ */
+export function proseLength(text) {
+    let units = 0;
+    // Iterating yields whole code points, so an astral CJK character counts once
+    // (as 2 units) rather than twice as its surrogate halves.
+    for (const character of text) {
+        units += WIDE_CHARACTER.test(character) ? 2 : 1;
+    }
+    return units;
+}
+//# sourceMappingURL=prose-length.js.map

package/dist/core/validation/prose-length.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prose-length.js","sourceRoot":"","sources":["../../../src/core/validation/prose-length.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,cAAc,GAClB,+DAA+D,CAAC;AAElE;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,6EAA6E;IAC7E,0DAA0D;IAC1D,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;QAC7B,KAAK,IAAI,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/core/validation/purpose-placeholder.d.ts

@@ -2,24 +2,17 @@
  * Detects a `## Purpose` that is still a placeholder rather than one somebody
  * wrote.
  *
- * When a delta introduces a capability with no usable `## Purpose`, archive
- * stamps the placeholder into the new main spec. That text is longer than
- * MIN_PURPOSE_LENGTH, so the brevity check cannot reach it: the one rule that
- * exists to catch a Purpose nobody wrote is satisfied by the exact string
- * meaning nobody wrote one. Nothing else read it afterwards, so the capability
- * kept a to-do in it while every command reported success.
+ * Archive's generated placeholder is longer than MIN_PURPOSE_LENGTH, so the
+ * brevity check cannot reach it.
  *
  * Two things count, and deliberately nothing else:
  *
- * - the placeholder this tool generates, recognised through the same constants
- *   the writer composes it from, wherever it sits in the Purpose — nobody types
- *   that sentence by accident;
- * - a `TBD` or `TODO` *opening* the Purpose, which is the marker left behind
- *   when someone is told to leave a brief placeholder and never comes back.
+ * - the generated placeholder, recognised through the same constants the writer
+ *   composes it from, wherever it sits;
+ * - a `TBD` or `TODO` *opening* the Purpose.
  *
  * A marker inside a sentence is left alone: "the retry budget is TBD pending
- * benchmarks" is a real Purpose with an open question in it, and reporting it
- * would teach people to ignore the warning.
+ * benchmarks" is a real Purpose with an open question in it.
  */
 export interface PurposePlaceholderIssue {
     /** 1-based line of the placeholder text, when it can be located. */
@@ -29,9 +22,9 @@ export interface PurposePlaceholderIssue {
  * Reports the Purpose of a main spec as an unwritten placeholder, or null when
  * it reads as authored content.
  *
- * An empty Purpose needs no branch of its own: neither rule matches empty text,
- * so it falls through to null and SPEC_PURPOSE_EMPTY covers it alone. A Purpose
- * that is nothing but a fenced block reduces to the same empty text here.
+ * An empty Purpose needs no branch: neither rule matches empty text, so it falls
+ * through to null and SPEC_PURPOSE_EMPTY covers it. A Purpose that is nothing
+ * but a fenced block reduces to the same empty text here.
  */
 export declare function findPurposePlaceholderIssue(overview: string, content?: string): PurposePlaceholderIssue | null;
 //# sourceMappingURL=purpose-placeholder.d.ts.map

package/dist/core/validation/purpose-placeholder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"purpose-placeholder.d.ts","sourceRoot":"","sources":["../../../src/core/validation/purpose-placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA+CD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,uBAAuB,GAAG,IAAI,CAOhC"}
+{"version":3,"file":"purpose-placeholder.d.ts","sourceRoot":"","sources":["../../../src/core/validation/purpose-placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA2CD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,uBAAuB,GAAG,IAAI,CAOhC"}

package/dist/core/validation/purpose-placeholder.js

@@ -2,62 +2,51 @@
  * Detects a `## Purpose` that is still a placeholder rather than one somebody
  * wrote.
  *
- * When a delta introduces a capability with no usable `## Purpose`, archive
- * stamps the placeholder into the new main spec. That text is longer than
- * MIN_PURPOSE_LENGTH, so the brevity check cannot reach it: the one rule that
- * exists to catch a Purpose nobody wrote is satisfied by the exact string
- * meaning nobody wrote one. Nothing else read it afterwards, so the capability
- * kept a to-do in it while every command reported success.
+ * Archive's generated placeholder is longer than MIN_PURPOSE_LENGTH, so the
+ * brevity check cannot reach it.
  *
  * Two things count, and deliberately nothing else:
  *
- * - the placeholder this tool generates, recognised through the same constants
- *   the writer composes it from, wherever it sits in the Purpose — nobody types
- *   that sentence by accident;
- * - a `TBD` or `TODO` *opening* the Purpose, which is the marker left behind
- *   when someone is told to leave a brief placeholder and never comes back.
+ * - the generated placeholder, recognised through the same constants the writer
+ *   composes it from, wherever it sits;
+ * - a `TBD` or `TODO` *opening* the Purpose.
  *
  * A marker inside a sentence is left alone: "the retry budget is TBD pending
- * benchmarks" is a real Purpose with an open question in it, and reporting it
- * would teach people to ignore the warning.
+ * benchmarks" is a real Purpose with an open question in it.
  */
-import { buildCodeFenceMask } from '../parsers/requirement-text.js';
+import { buildCodeFenceMask, normalizeDocument } from '../parsers/requirement-text.js';
 import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX } from './constants.js';
 /**
  * A `TBD`/`TODO` opening the Purpose. The lookahead keeps it off a longer word
- * that merely starts with those letters ("TODOs are tracked in the issue") while
- * still allowing the punctuation a marker is written with: `TODO:`, `TBD -`. It
- * rejects any letter, digit or combining mark rather than only the ASCII ones
- * `\b` knows about — a Purpose is prose and prose is not always Latin script.
+ * starting with those letters ("TODOs are tracked in the issue") while allowing
+ * the punctuation a marker carries: `TODO:`, `TBD -`. It rejects any letter,
+ * digit or combining mark rather than only the ASCII ones `\b` knows about,
+ * since a Purpose is prose and prose is not always Latin script.
  */
 const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
 const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
 const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
 /**
- * The lines of `text` outside a fenced code block, line endings normalised.
- *
- * Fenced content is quoted material, not the Purpose speaking. Without this a
- * spec documenting the sentence archive writes is reported as carrying it — the
- * check failing the one document that explains it. `buildCodeFenceMask` is the
- * masker the requirement and structure parsers already share, so all three read
- * fences the same way.
+ * The lines of `text` outside a fenced code block. Fenced content is quoted
+ * material, not the Purpose speaking: without this, a spec documenting the
+ * sentence archive writes is reported as carrying it.
  */
 function unfencedLines(text) {
-    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    const lines = normalizeDocument(text).split('\n');
     const fenced = buildCodeFenceMask(lines);
     return lines.filter((_, index) => !fenced[index]);
 }
 /**
  * Offset of the generated placeholder in `text`, or undefined. Matched as its
- * two fixed halves in order because the change name between them varies — the
- * check follows the writer's own definition instead of a second copy of it.
+ * two fixed halves in order because the change name between them varies, so the
+ * check follows the writer's own definition rather than a copy of it.
  */
 function generatedPlaceholderPrefixIndex(text) {
     let suffixAt = text.indexOf(PURPOSE_PLACEHOLDER_SUFFIX);
     while (suffixAt !== -1) {
         // The closest prefix before this suffix: authored prose can mention the
-        // prefix above the real placeholder, and the first prefix would then point
-        // the diagnostic at the explanation instead of the text to replace.
+        // prefix above the real placeholder, and the first one would point the
+        // diagnostic at the explanation instead of the text to replace.
         const prefixAt = text.lastIndexOf(PURPOSE_PLACEHOLDER_PREFIX, suffixAt);
         if (prefixAt !== -1)
             return prefixAt;
@@ -69,9 +58,9 @@ function generatedPlaceholderPrefixIndex(text) {
  * Reports the Purpose of a main spec as an unwritten placeholder, or null when
  * it reads as authored content.
  *
- * An empty Purpose needs no branch of its own: neither rule matches empty text,
- * so it falls through to null and SPEC_PURPOSE_EMPTY covers it alone. A Purpose
- * that is nothing but a fenced block reduces to the same empty text here.
+ * An empty Purpose needs no branch: neither rule matches empty text, so it falls
+ * through to null and SPEC_PURPOSE_EMPTY covers it. A Purpose that is nothing
+ * but a fenced block reduces to the same empty text here.
  */
 export function findPurposePlaceholderIssue(overview, content) {
     const prose = unfencedLines(overview).join('\n').trim();
@@ -79,7 +68,7 @@ export function findPurposePlaceholderIssue(overview, content) {
     if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
         return null;
     // Which rule matched decides where the placeholder sits, so the locator is
-    // told. When both match the leading marker wins — it is the earlier of the two.
+    // told. When both match the leading marker wins, being the earlier.
     return { line: content === undefined ? undefined : findPlaceholderLine(content, leading) };
 }
 /**
@@ -87,25 +76,22 @@ export function findPurposePlaceholderIssue(overview, content) {
  * at the text to replace rather than at the file.
  *
  * Which line that is depends on the rule that matched. A leading marker is the
- * section's first non-blank line by definition; the generated sentence is not —
- * it can follow prose somebody wrote, and naming the first non-blank line then
- * points at a line the reader can see is fine, which reads as the check being
- * broken rather than the Purpose being unwritten.
+ * section's first non-blank line by definition; the generated sentence is not,
+ * and can follow prose somebody wrote.
  *
- * Undefined when the placeholder cannot be located, because a wrong line number
- * is worse than none. Line endings are normalised first so the same spec reports
- * the same line on Windows and on macOS/Linux.
+ * Undefined when the placeholder cannot be located: a wrong line number is worse
+ * than none.
  */
 function findPlaceholderLine(content, leading) {
-    const lines = content.replace(/\r\n?/g, '\n').split('\n');
+    const lines = normalizeDocument(content).split('\n');
     const fenced = buildCodeFenceMask(lines);
     const headerIndex = lines.findIndex((line, index) => !fenced[index] && PURPOSE_HEADER.test(line));
     if (headerIndex === -1)
         return undefined;
     const purposeLines = [];
     for (let i = headerIndex + 1; i < lines.length; i++) {
-        // Fenced lines are skipped for the reason detection skips them, and so a
-        // `## Requirements` quoted inside a fence cannot end the section early.
+        // Skipped as in detection, and so a `## Requirements` quoted inside a fence
+        // cannot end the section early.
         if (fenced[i])
             continue;
         if (TOP_LEVEL_HEADER.test(lines[i]))

package/dist/core/validation/purpose-placeholder.js.map

@@ -1 +1 @@
-{"version":3,"file":"purpose-placeholder.js","sourceRoot":"","sources":["../../../src/core/validation/purpose-placeholder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"purpose-placeholder.js","sourceRoot":"","sources":["../../../src/core/validation/purpose-placeholder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACvF,OAAO,EAAE,0BAA0B,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAOxF;;;;;;GAMG;AACH,MAAM,cAAc,GAAG,uCAAuC,CAAC;AAE/D,MAAM,cAAc,GAAG,qCAAqC,CAAC;AAC7D,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACzC,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAS,+BAA+B,CAAC,IAAY;IACnD,IAAI,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACxD,OAAO,QAAQ,KAAK,CAAC,CAAC,EAAE,CAAC;QACvB,wEAAwE;QACxE,uEAAuE;QACvE,gEAAgE;QAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,0BAA0B,EAAE,QAAQ,CAAC,CAAC;QACxE,IAAI,QAAQ,KAAK,CAAC,CAAC;YAAE,OAAO,QAAQ,CAAC;QACrC,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,0BAA0B,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,QAAgB,EAChB,OAAgB;IAEhB,MAAM,KAAK,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACxD,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,OAAO,IAAI,+BAA+B,CAAC,KAAK,CAAC,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAClF,2EAA2E;IAC3E,oEAAoE;IACpE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;GAUG;AACH,SAAS,mBAAmB,CAAC,OAAe,EAAE,OAAgB;IAC5D,MAAM,KAAK,GAAG,iBAAiB,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,WAAW,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAClG,IAAI,WAAW,KAAK,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IAEzC,MAAM,YAAY,GAA0C,EAAE,CAAC;IAC/D,KAAK,IAAI,CAAC,GAAG,WAAW,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpD,4EAA4E;QAC5E,gCAAgC;QAChC,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,SAAS;QACxB,IAAI,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,MAAM;QAC3C,IAAI,OAAO,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE;YAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,YAAY,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,CAAC;IAED,IAAI,OAAO;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,OAAO,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,+BAA+B,CAAC,OAAO,CAAC,CAAC;IAC1D,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7C,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;IACrE,OAAO,YAAY,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;AACxC,CAAC"}

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

@@ -2,6 +2,7 @@ import type { ValidationIssue } from './types.js';
 export interface SectionValidationRules {
     requiredSections: string[];
     minSectionLength: Record<string, number>;
+    maxSectionLength?: Record<string, number>;
 }
 export interface SectionValidationContext {
     /** Reported as ValidationIssue.path (typically the file's relative path). */
@@ -10,10 +11,9 @@ export interface SectionValidationContext {
     templateRef?: string;
 }
 /**
- * Validates a document's headings against schema-declared rules, for
- * artifacts (ticket.md, design.md, task.md, ...) that have no Requirement
- * grammar to check structurally. Rules live in schema.yaml so new document
- * types don't require validator code changes.
+ * Heading rules for artifacts (ticket.md, design.md, task.md, ...) that have no
+ * Requirement grammar to check structurally. The rules live in schema.yaml so a
+ * new document type needs no validator code.
  */
 export declare function validateSections(content: string, rules: SectionValidationRules, context: SectionValidationContext): ValidationIssue[];
 //# sourceMappingURL=section-validator.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"section-validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/section-validator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAeD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,wBAAwB,GAChC,eAAe,EAAE,CA8CnB"}
+{"version":3,"file":"section-validator.d.ts","sourceRoot":"","sources":["../../../src/core/validation/section-validator.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,sBAAsB;IACrC,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAcD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,wBAAwB,GAChC,eAAe,EAAE,CAiEnB"}

package/dist/core/validation/section-validator.js

@@ -1,21 +1,20 @@
 import { MarkdownParser, findSection } from '../parsers/markdown-parser.js';
+import { proseLength } from './prose-length.js';
 /**
  * The prose a section actually carries, with HTML comments removed.
  *
  * Templates put their guidance in `<!-- ... -->`, which counts as text to a
- * naive length check. The proposal template's Why hint is 71 characters and the
- * rule it is hinting at is a 50-character minimum, so an untouched template
- * satisfied its own threshold while a real ten-word answer was warned about
- * (round 4 report 4). What is measured has to be what the author wrote.
+ * naive length check: the proposal template's Why hint is 71 characters against
+ * a 50-character minimum, so an untouched template would satisfy its own
+ * threshold while a real ten-word answer is warned about.
  */
 function authoredContent(sectionContent) {
     return sectionContent.replace(/<!--[\s\S]*?-->/g, '').trim();
 }
 /**
- * Validates a document's headings against schema-declared rules, for
- * artifacts (ticket.md, design.md, task.md, ...) that have no Requirement
- * grammar to check structurally. Rules live in schema.yaml so new document
- * types don't require validator code changes.
+ * Heading rules for artifacts (ticket.md, design.md, task.md, ...) that have no
+ * Requirement grammar to check structurally. The rules live in schema.yaml so a
+ * new document type needs no validator code.
  */
 export function validateSections(content, rules, context) {
     const issues = [];
@@ -32,9 +31,9 @@ export function validateSections(content, rules, context) {
             continue;
         }
         if (!authoredContent(section.content)) {
-            // Distinguish the two, because the fix differs: a blank section needs
-            // writing, a comment-only one needs the placeholder replaced — and a
-            // reader who can see text under the heading would not believe "is empty".
+            // Told apart because the fix differs: a blank section needs writing, a
+            // comment-only one needs the placeholder replaced — and "is empty" reads
+            // as wrong to someone looking at text under the heading.
             const onlyComments = section.content.trim().length > 0;
             issues.push({
                 level: 'WARNING',
@@ -50,7 +49,9 @@ export function validateSections(content, rules, context) {
         if (!section) {
             continue; // absence is already reported above when also required
         }
-        const length = authoredContent(section.content).length;
+        // Width-aware, so the English-calibrated threshold means the same amount
+        // of prose in a double-width script.
+        const length = proseLength(authoredContent(section.content));
         if (length > 0 && length < minLength) {
             issues.push({
                 level: 'WARNING',
@@ -59,6 +60,23 @@ export function validateSections(content, rules, context) {
             });
         }
     }
+    for (const [sectionTitle, maxLength] of Object.entries(rules.maxSectionLength ?? {})) {
+        const section = findSection(sections, sectionTitle);
+        if (!section)
+            continue;
+        // Raw characters: unlike the floor, a ceiling asks "is this an essay?", and
+        // widening the unit for double-width scripts would reject long but
+        // legitimate CJK prose.
+        // tospec/decisions/20260919_193441-width-aware-minimum-length.md
+        const length = authoredContent(section.content).length;
+        if (length > maxLength) {
+            issues.push({
+                level: 'WARNING',
+                path: context.path,
+                message: `Section "${sectionTitle}" is longer than the recommended ${maxLength} characters (found ${length}) — consider moving detail into design.md or splitting the change`,
+            });
+        }
+    }
     return issues;
 }
 //# sourceMappingURL=section-validator.js.map

package/dist/core/validation/section-validator.js.map

@@ -1 +1 @@
-{"version":3,"file":"section-validator.js","sourceRoot":"","sources":["../../../src/core/validation/section-validator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAe5E;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,cAAsB;IAC7C,OAAO,cAAc,CAAC,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAe,EACf,KAA6B,EAC7B,OAAiC;IAEjC,MAAM,MAAM,GAAsB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;IAE3D,KAAK,MAAM,aAAa,IAAI,KAAK,CAAC,gBAAgB,EAAE,CAAC;QACnD,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,mBAAmB,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAClF,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,OAAO;gBACd,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,OAAO,EAAE,6BAA6B,aAAa,IAAI,IAAI,EAAE;aAC9D,CAAC,CAAC;YACH,SAAS;QACX,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,sEAAsE;YACtE,qEAAqE;YACrE,0EAA0E;YAC1E,MAAM,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;YACvD,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,OAAO,EAAE,YAAY;oBACnB,CAAC,CAAC,YAAY,aAAa,oDAAoD;oBAC/E,CAAC,CAAC,YAAY,aAAa,YAAY;aAC1C,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,KAAK,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC/E,MAAM,OAAO,GAAG,WAAW,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,SAAS,CAAC,uDAAuD;QACnE,CAAC;QACD,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC;QACvD,IAAI,MAAM,GAAG,CAAC,IAAI,MAAM,GAAG,SAAS,EAAE,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC;gBACV,KAAK,EAAE,SAAS;gBAChB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,OAAO,EAAE,YAAY,YAAY,qCAAqC,SAAS,sBAAsB,MAAM,GAAG;aAC/G,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"section-validator.js","sourceRoot":"","sources":["../../../src/core/validation/section-validator.ts"],"names":[],"mappings":"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"}

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

@@ -3,11 +3,14 @@
  *
  * Task IDs are how apply refers to work ("continue with 2.3"), so a duplicated
  * ID or one that contradicts its group heading makes that reference point at
- * the wrong item — silently, because nothing else reads the numbers.
+ * the wrong item, silently.
  *
  * Numbering is interpreted only inside numbered group headings. Unnumbered
- * sections, unnumbered tasks, and files with no numbered group at all are
- * ignored on purpose: they are a legitimate style, not a defect.
+ * sections and tasks are a legitimate style, not a defect.
+ *
+ * Gaps are not checked: 1.1 followed by 1.3 still leaves every ID pointing at
+ * exactly one task, which is the property this module defends. Demanding a
+ * renumber would invalidate every reference already made.
  */
 export interface TaskNumberingDocument {
     /** Display path, relative to the change directory. */

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

@@ -1 +1 @@
-{"version":3,"file":"task-numbering.d.ts","sourceRoot":"","sources":["../../../src/core/validation/task-numbering.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAC1C,kBAAkB,EAAE,CAuDtB"}
+{"version":3,"file":"task-numbering.d.ts","sourceRoot":"","sources":["../../../src/core/validation/task-numbering.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAsBD,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAC1C,kBAAkB,EAAE,CAkEtB"}

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

@@ -1,9 +1,10 @@
 import { parseTasksFromContent } from '../../utils/task-progress.js';
+import { buildCodeFenceMask, normalizeDocument } from '../parsers/requirement-text.js';
 /**
  * A group heading is level 2 or 3, because the two schemas differ: sdd's
- * `tasks.md` numbers slices at `## 1.`, while issue's `task.md` puts `### 1. Fix`
- * under an unnumbered `## Tasks`. Matching only one level would make the check
- * silently inert for the other schema.
+ * `tasks.md` numbers slices at `## 1.`, while issue's `task.md` puts
+ * `### 1. Fix` under an unnumbered `## Tasks`. Matching one level would leave
+ * the check inert for the other schema.
  */
 const GROUP_HEADING = /^ {0,3}#{2,3}[ \t]+/;
 const NUMBERED_GROUP_HEADING = /^ {0,3}#{2,3}[ \t]+(\d+)\./;
@@ -15,24 +16,35 @@ export function findTaskNumberingIssues(documents) {
     const issues = [];
     const firstLocationById = new Map();
     for (const document of documents) {
-        const lines = document.content.split(/\r?\n/);
+        const lines = normalizeDocument(document.content).split('\n');
         if (!lines.some((line) => NUMBERED_GROUP_HEADING.test(line)))
             continue;
+        // Parsed once for the whole document, then addressed by line — never
+        // `parseTasksFromContent(line)` per line, which opts out of fence masking:
+        // the mask is built from surrounding lines, so a line handed over alone can
+        // never be inside a fence, and a tasks.md documenting its own format would
+        // draw warnings over its fenced examples.
+        const taskByLine = new Map();
+        for (const task of parseTasksFromContent(document.content)) {
+            taskByLine.set(task.line, task);
+        }
+        // Headings need the mask for the same reason: a `## 9. …` inside a fence is
+        // a quoted example, and letting it open a numbered group misjudges every
+        // real task below it.
+        const fenced = buildCodeFenceMask(lines);
         let currentGroup;
         lines.forEach((line, index) => {
+            if (fenced[index])
+                return;
             if (GROUP_HEADING.test(line)) {
-                // An unnumbered heading at either level ends the numbered group rather
-                // than letting it leak across sections.
+                // An unnumbered heading at either level ends the numbered group, so it
+                // cannot leak across sections.
                 currentGroup = line.match(NUMBERED_GROUP_HEADING)?.[1];
                 return;
             }
             if (currentGroup === undefined)
                 return;
-            // Deliberately the same line-based reader progress counting uses, fenced
-            // blocks and all. A checkbox in a fence is miscounted by both or neither;
-            // making only this side fence-aware would put the two readers back out of
-            // step, which is the failure mode worth avoiding here.
-            const task = parseTasksFromContent(line)[0];
+            const task = taskByLine.get(index + 1);
             const id = task?.text.match(TASK_ID)?.[1];
             if (!id)
                 return;

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

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

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

@@ -5,6 +5,16 @@ export interface ValidationIssue {
     message: string;
     line?: number;
     column?: number;
+    /**
+     * Background explaining the rule rather than this occurrence of it — why the
+     * check is a warning, what it cannot see, what to do in general.
+     *
+     * Separate from the per-occurrence `message` because it is identical every
+     * time the rule fires; inlined, it repeats once per occurrence and buries the
+     * names that differ. `createReport` hoists these into
+     * `ValidationReport.notes`, deduplicated, and clears them from the issues.
+     */
+    note?: string;
 }
 export interface ValidationReport {
     valid: boolean;
@@ -14,5 +24,13 @@ export interface ValidationReport {
         warnings: number;
         info: number;
     };
+    /** Distinct `ValidationIssue.note` values, each carried once. */
+    notes?: string[];
 }
+/**
+ * Severity symbol for human output. Shared so no two surfaces show different
+ * glyphs for one level; the line formats around it differ on purpose
+ * (`validate` prints the level, `archive` does not), so only this is common.
+ */
+export declare function issueSymbol(level: ValidationLevel | string): string;
 //# sourceMappingURL=types.d.ts.map

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;CACjB;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;CACH"}
+{"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"}