freeharness 0.4.1 → 0.4.2

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/requirement-blocks.d.ts

@@ -14,9 +14,10 @@ export declare function normalizeRequirementName(name: string): string;
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
  * matching itself is case-sensitive (normalizeRequirementName); this fold
- * exists only for typo detection - near-miss REMOVED headers and the
- * RENAMED+REMOVED cross-section conflict - where two spellings that differ
- * only in case or interior whitespace mean a mistake, never two requirements.
+ * exists only for typo detection - near-miss REMOVED, ADDED and RENAMED
+ * headers and the RENAMED+REMOVED cross-section conflict - where two
+ * spellings that differ only in case or interior whitespace mean a mistake,
+ * never two requirements.
  */
 export declare function foldRequirementName(name: string): string;
 /**
@@ -33,14 +34,36 @@ export interface SkippedHeader {
     section: string;
     line: number;
 }
+/** A `TO:` line in RENAMED with no pending `FROM:` - not left to silently pair with a later, unrelated `FROM:`. */
+export interface UnpairedRename {
+    side: 'TO';
+    name: string;
+    line: number;
+}
+/** A canonical `### Requirement:` block outside every delta section (`## Notes`, above the first `## ` header, ...). */
+export interface OrphanedRequirement {
+    name: string;
+    section: string | null;
+    line: number;
+}
+/** Delta text archive never carries into the main spec; `text` lets a warning quote it. */
+export interface UnappliedContent {
+    section: string | null;
+    line: number;
+    text: string;
+}
 export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
     removed: string[];
+    removedBlocks: RequirementBlock[];
     renamed: Array<{
         from: string;
         to: string;
     }>;
+    unpairedRenames: UnpairedRename[];
+    orphanedRequirements: OrphanedRequirement[];
+    unappliedContent: UnappliedContent[];
     skippedHeaders: SkippedHeader[];
     sectionPresence: {
         added: boolean;
@@ -53,13 +76,30 @@ export interface DeltaPlan {
  * Parse a delta-formatted spec change file content into a DeltaPlan with raw blocks.
  */
 export declare function parseDeltaSpec(content: string): DeltaPlan;
+export declare function describeUnappliedContent(content: UnappliedContent, sentenceStart?: boolean): string;
+/** Standalone entry for callers holding raw file text rather than a plan. */
+export declare function findUnappliedContent(content: string): UnappliedContent[];
+/** Both directions of the scenario-name comparison, plus the two totals. */
+export interface ScenarioNameDiff {
+    /** Names the current block has that the incoming block does not cover. */
+    missing: string[];
+    /** Names the incoming block introduces that the current block does not have. */
+    added: string[];
+    /** Level-4 headers in the current block. */
+    currentCount: number;
+    /** Level-4 headers in the incoming block. */
+    incomingCount: number;
+}
 /**
- * Scenario names the current requirement block has and the incoming
- * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
- * so every name reported here would be dropped from the main spec.
- *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions. `missing` is the loss the guard exists
+ * to catch; `added` and the two counts are reported alongside it, since a
+ * block that omits two names and introduces two reads as a rename while one
+ * that introduces none reads as a truncation - neither is proof, so this
+ * decides nothing and only says what the two blocks contain.
  */
+export declare function diffScenarioNames(current: RequirementBlock, incoming: RequirementBlock): ScenarioNameDiff;
+/** Scenario names the current block has that the incoming block drops - the `missing` half of diffScenarioNames. */
 export declare function findMissingCurrentScenarios(current: RequirementBlock, incoming: RequirementBlock): string[];
+/** The one sentence archive and validate both append when the scenario-loss guard fires. */
+export declare function describeScenarioBalance(diff: ScenarioNameDiff): string;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/requirement-blocks.js

@@ -1,13 +1,17 @@
 import { buildCodeFenceMask, SCENARIO_HEADER } from './requirement-text.js';
 export function normalizeRequirementName(name) {
-    return name.trim();
+    // A trailing ATX closing run of `#`s is not part of the name (`### Foo ###`
+    // renders as `Foo`); only a run preceded by a space/tab closes the heading,
+    // so `C#` keeps its `#`.
+    return name.replace(/[ \t]+#+[ \t]*$/, '').trim();
 }
 /**
  * Case- and whitespace-insensitive fold of a requirement name. Requirement
  * matching itself is case-sensitive (normalizeRequirementName); this fold
- * exists only for typo detection - near-miss REMOVED headers and the
- * RENAMED+REMOVED cross-section conflict - where two spellings that differ
- * only in case or interior whitespace mean a mistake, never two requirements.
+ * exists only for typo detection - near-miss REMOVED, ADDED and RENAMED
+ * headers and the RENAMED+REMOVED cross-section conflict - where two
+ * spellings that differ only in case or interior whitespace mean a mistake,
+ * never two requirements.
  */
 export function foldRequirementName(name) {
     return normalizeRequirementName(name).toLowerCase().replace(/\s+/g, ' ');
@@ -115,15 +119,22 @@ export function parseDeltaSpec(content) {
         sink: skippedHeaders,
     }));
     const removedNames = removedLookup.bodies.flatMap((body) => parseRemovedNames(body));
+    const removedBlocks = removedLookup.bodies.flatMap((body) => parseRequirementBlocksFromSection(body));
     // Pairs are read per section, so a FROM in one copy of the header can never
     // pair with a TO written under a different copy.
-    const renamedPairs = renamedLookup.bodies.flatMap((body) => parseRenamedPairs(body, { section: renamedLookup.title, sink: skippedHeaders }));
+    const unpairedRenames = [];
+    const renamedPairs = renamedLookup.bodies.flatMap((body) => parseRenamedPairs(body, { section: renamedLookup.title, sink: skippedHeaders }, unpairedRenames));
+    unpairedRenames.sort((a, b) => a.line - b.line);
     skippedHeaders.sort((a, b) => a.line - b.line);
     return {
         added,
         modified,
         removed: removedNames,
+        removedBlocks,
         renamed: renamedPairs,
+        unpairedRenames,
+        orphanedRequirements: findOrphanedRequirements(lines, fenceMask),
+        unappliedContent: collectUnappliedContent(lines, fenceMask),
         skippedHeaders,
         sectionPresence: {
             added: addedLookup.found,
@@ -133,6 +144,94 @@ export function parseDeltaSpec(content) {
         },
     };
 }
+/** The four section titles the delta reader acts on, folded like `getSectionsCaseInsensitive` folds them. */
+const DELTA_SECTION_TITLES = new Set(['ADDED Requirements', 'MODIFIED Requirements', 'REMOVED Requirements', 'RENAMED Requirements'].map((title) => title.toLowerCase()));
+/** Every canonical `### Requirement:` header outside a delta section, in document order. */
+function findOrphanedRequirements(lines, fenceMask) {
+    const orphans = [];
+    let section = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (fenceMask[i])
+            continue;
+        // Same `## ` test splitTopLevelSections uses, so both agree on sections.
+        const sectionMatch = lines[i].match(/^(##)\s+(.+)$/);
+        if (sectionMatch) {
+            section = sectionMatch[2].trim();
+            continue;
+        }
+        if (section !== null && DELTA_SECTION_TITLES.has(section.toLowerCase()))
+            continue;
+        const header = lines[i].match(REQUIREMENT_HEADER_REGEX);
+        if (header) {
+            orphans.push({ name: normalizeRequirementName(header[1]), section, line: i + 1 });
+        }
+    }
+    return orphans;
+}
+/** Quoted text is cut here so one long paragraph cannot flood a warning line. */
+const MAX_QUOTED_TEXT = 100;
+export function describeUnappliedContent(content, sentenceStart = false) {
+    const where = content.section === null
+        ? 'text above the first "## " section'
+        : DELTA_SECTION_TITLES.has(content.section.toLowerCase())
+            ? `text before the first requirement in "## ${content.section}"`
+            : `section "## ${content.section}"`;
+    const quoted = content.text.length > MAX_QUOTED_TEXT ? `${content.text.slice(0, MAX_QUOTED_TEXT)}...` : content.text;
+    const text = `${where} ("${quoted}")`;
+    return sentenceStart ? text.charAt(0).toUpperCase() + text.slice(1) : text;
+}
+/** Standalone entry for callers holding raw file text rather than a plan. */
+export function findUnappliedContent(content) {
+    const lines = normalizeLineEndings(content).split('\n');
+    return collectUnappliedContent(lines, buildCodeFenceMask(lines));
+}
+/**
+ * HTML comments, `# ` titles, Purpose (warned about separately), REMOVED and
+ * RENAMED bodies, and stray `###` headers before the first requirement (INFO
+ * since #498) are not reported.
+ */
+function collectUnappliedContent(lines, fenceMask) {
+    // Comments only decide whether a line holds text; sections come from the
+    // merge's own split, and fenced lines keep their text so a `<!--` sample
+    // never hides what follows the fence.
+    const comments = lines
+        .map((line, i) => (fenceMask[i] ? '' : line))
+        .join('\n')
+        .replace(/<!--[\s\S]*?(?:--!?>|$)/g, (m) => m.replace(/[^\n]/g, ' '))
+        .split('\n');
+    const masked = lines.map((line, i) => (fenceMask[i] ? line : comments[i]));
+    const sections = splitTopLevelSections(lines, fenceMask);
+    const firstText = (from, to, skip) => {
+        for (let i = from; i < to; i++)
+            if (masked[i].trim() && !skip?.test(masked[i]))
+                return i;
+        return -1;
+    };
+    const found = [];
+    const preamble = firstText(0, sections.length ? sections[0].body.bodyStartLine - 2 : lines.length, /^#\s/);
+    if (preamble !== -1)
+        found.push({ section: null, line: preamble + 1, text: masked[preamble].trim() });
+    for (const { title, body } of sections) {
+        const folded = title.toLowerCase();
+        const start = body.bodyStartLine - 1;
+        if (folded === 'added requirements' || folded === 'modified requirements') {
+            const block = body.lines.findIndex((l, i) => !body.fenceMask[i] && REQUIREMENT_HEADER_REGEX.test(l));
+            const first = firstText(start, start + (block === -1 ? body.lines.length : block), /^###\s/);
+            if (first !== -1)
+                found.push({ section: title, line: first + 1, text: masked[first].trim() });
+        }
+        else if (!DELTA_SECTION_TITLES.has(folded)) {
+            // The Purpose carry-over reads past commented-out headers, so only a
+            // `## Purpose` outside a comment is the one archive handles.
+            if (folded === 'purpose' && masked[start - 1].trim())
+                continue;
+            const first = firstText(start, start + body.lines.length);
+            if (first !== -1)
+                found.push({ section: title, line: start, text: masked[first].trim() });
+        }
+    }
+    return found;
+}
 /**
  * Every `## ` section of a delta file, as a list rather than a title-keyed
  * record.
@@ -276,7 +375,7 @@ function parseRemovedNames(sectionBody) {
  * or `+` into a silent no-op - archive reports success while the rename never
  * happens.
  */
-function parseRenamedPairs(sectionBody, skipped) {
+function parseRenamedPairs(sectionBody, skipped, unpaired) {
     const { lines, fenceMask, bodyStartLine } = sectionBody;
     if (lines.length === 0)
         return [];
@@ -305,47 +404,76 @@ function parseRenamedPairs(sectionBody, skipped) {
             current.fromLine = i;
         }
         else if (toMatch) {
-            current.to = normalizeRequirementName(toMatch[1]);
-            if (current.from && current.to) {
-                pairs.push({ from: current.from, to: current.to });
-                current = {};
+            const to = normalizeRequirementName(toMatch[1]);
+            if (current.from === undefined) {
+                // No pending FROM: used to linger in `current.to` and silently pair
+                // with whichever FROM arrived next (#1806) - reported instead.
+                unpaired?.push({ side: 'TO', name: to, line: bodyStartLine + i });
+                continue;
             }
+            pairs.push({ from: current.from, to });
+            current = {};
         }
     }
     flushUnpairedFrom();
     return pairs;
 }
 /**
- * Scenario names the current requirement block has and the incoming
- * (MODIFIED) block does not. A MODIFIED requirement replaces the whole block,
- * so every name reported here would be dropped from the main spec.
- *
- * Shared by archive (which refuses to apply the block) and validate (which
- * reports the same loss at authoring time, #1477), so the two cannot disagree
- * about what counts as a dropped scenario.
+ * Compare the scenario names of a current requirement block and an incoming
+ * (MODIFIED) one, in both directions. `missing` is the loss the guard exists
+ * to catch; `added` and the two counts are reported alongside it, since a
+ * block that omits two names and introduces two reads as a rename while one
+ * that introduces none reads as a truncation - neither is proof, so this
+ * decides nothing and only says what the two blocks contain.
  */
-export function findMissingCurrentScenarios(current, incoming) {
-    // Multiplicity-aware: a name present N times in current and M times in
-    // incoming means max(0, N - M) instances are missing. Set membership would
-    // treat N>M as fully covered and let archive silently drop duplicates
-    // (residual #1246 / duplicate-scenario-name blind spot).
-    const remainingIncoming = new Map();
-    for (const scenario of parseScenarioBlocks(incoming.raw)) {
-        const name = scenario.name;
-        remainingIncoming.set(name, (remainingIncoming.get(name) ?? 0) + 1);
-    }
-    const missing = [];
-    for (const scenario of parseScenarioBlocks(current.raw)) {
-        const name = scenario.name;
-        const remaining = remainingIncoming.get(name) ?? 0;
-        if (remaining > 0) {
-            remainingIncoming.set(name, remaining - 1);
-        }
-        else {
-            missing.push(name);
+export function diffScenarioNames(current, incoming) {
+    const currentNames = parseScenarioBlocks(current.raw).map((scenario) => scenario.name);
+    const incomingNames = parseScenarioBlocks(incoming.raw).map((scenario) => scenario.name);
+    // Multiplicity-aware: a name present N times on one side and M times on the
+    // other leaves max(0, N - M) instances unmatched. Set membership would treat
+    // N>M as fully covered and let archive silently drop duplicates (residual
+    // #1246 / duplicate-scenario-name blind spot).
+    const unmatched = (names, against) => {
+        const remaining = new Map();
+        for (const name of against)
+            remaining.set(name, (remaining.get(name) ?? 0) + 1);
+        const out = [];
+        for (const name of names) {
+            const left = remaining.get(name) ?? 0;
+            if (left > 0)
+                remaining.set(name, left - 1);
+            else
+                out.push(name);
         }
+        return out;
+    };
+    return {
+        missing: unmatched(currentNames, incomingNames),
+        added: unmatched(incomingNames, currentNames),
+        currentCount: currentNames.length,
+        incomingCount: incomingNames.length,
+    };
+}
+/** Scenario names the current block has that the incoming block drops - the `missing` half of diffScenarioNames. */
+export function findMissingCurrentScenarios(current, incoming) {
+    return diffScenarioNames(current, incoming).missing;
+}
+/** At most this many added names are listed before the rest are counted. */
+const MAX_LISTED_ADDED_SCENARIOS = 3;
+/** The one sentence archive and validate both append when the scenario-loss guard fires. */
+export function describeScenarioBalance(diff) {
+    const count = (value) => `${value} ${value === 1 ? 'scenario' : 'scenarios'}`;
+    const scale = `The modified block has ${count(diff.incomingCount)}; the current spec has ${count(diff.currentCount)}.`;
+    if (diff.added.length === 0) {
+        return `${scale} It adds none.`;
     }
-    return missing;
+    const listed = diff.added
+        .slice(0, MAX_LISTED_ADDED_SCENARIOS)
+        .map((name) => `"${name}"`)
+        .join(', ');
+    const rest = diff.added.length - MAX_LISTED_ADDED_SCENARIOS;
+    const names = rest > 0 ? `${listed} and ${rest} more` : listed;
+    return `${scale} It adds ${count(diff.added.length)} not in the current spec: ${names}.`;
 }
 /**
  * Any non-fenced level-4 header on the given (masked) line. Reuses the spec

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/requirement-text.d.ts

@@ -15,8 +15,26 @@ export { buildCodeFenceMask } from './code-fence.js';
  * as a scenario, so the delta counter must too (parity). The delta/loss path
  * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
  * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ * A header alone is not yet a scenario on either path: see hasScenarioBody.
  */
 export declare const SCENARIO_HEADER: RegExp;
+/**
+ * EARS scenario title: `Scenario: WHEN <event> THE SYSTEM SHALL <behavior>`
+ * (also WHILE/WHERE/IF ... SHALL). FreeHarness addition (V4-P4): an EARS
+ * scenario carries its whole behavior in the header and may have no body -
+ * both the spec path (`MarkdownParser.parseScenarios`) and the delta counter
+ * below count it as a real scenario, matched case-insensitively against the
+ * text after `#### `.
+ */
+export declare const EARS_SCENARIO_TITLE: RegExp;
+/**
+ * Whether a scenario's body has content. The spec path
+ * (`MarkdownParser.parseScenarios`) drops a scenario whose body is empty, so
+ * the delta counter must too (parity): otherwise `validate` accepts a
+ * requirement whose only scenario is a bare header, and archive rejects it
+ * when it validates the rebuilt spec.
+ */
+export declare function hasScenarioBody(body: string): boolean;
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept
@@ -48,8 +66,11 @@ export declare function extractRequirementBody(bodyLines: string[]): string;
  */
 export declare function extractRequirementText(headerTitle: string, bodyLines: string[]): string;
 /**
- * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
- * lines. A `#### Scenario:` that lives inside a fenced example is not a real
- * scenario and is not counted.
+ * Count the real scenarios in a requirement block: `#### ` headers on
+ * non-fenced lines whose body has content, or whose header is EARS-shaped. A
+ * `#### Scenario:` that lives inside a fenced example is not a real scenario
+ * and is not counted, and neither is a plain header with nothing under it.
  */
 export declare function countScenarios(bodyLines: string[]): number;
+/** Count the `#### ` headers in a requirement block that do not count as a scenario. */
+export declare function countEmptyScenarios(bodyLines: string[]): number;

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/requirement-text.js

@@ -22,8 +22,30 @@ const HEADER_LINE = /^#{1,6}\s/;
  * as a scenario, so the delta counter must too (parity). The delta/loss path
  * reuses this exact constant via `scenarioHeaderAt` in requirement-blocks.ts;
  * keep both paths on it rather than reintroducing a separate `Scenario:` regex.
+ * A header alone is not yet a scenario on either path: see hasScenarioBody.
  */
 export const SCENARIO_HEADER = /^####\s+/;
+/** A header at scenario level or above (`#` to `####`): where a scenario body ends. */
+const SCENARIO_BODY_END = /^#{1,4}\s/;
+/**
+ * EARS scenario title: `Scenario: WHEN <event> THE SYSTEM SHALL <behavior>`
+ * (also WHILE/WHERE/IF ... SHALL). FreeHarness addition (V4-P4): an EARS
+ * scenario carries its whole behavior in the header and may have no body -
+ * both the spec path (`MarkdownParser.parseScenarios`) and the delta counter
+ * below count it as a real scenario, matched case-insensitively against the
+ * text after `#### `.
+ */
+export const EARS_SCENARIO_TITLE = /^Scenario:\s*(?:WHEN|WHILE|WHERE|IF)\b[\s\S]*\b(?:SHALL|MUST)\b/i;
+/**
+ * Whether a scenario's body has content. The spec path
+ * (`MarkdownParser.parseScenarios`) drops a scenario whose body is empty, so
+ * the delta counter must too (parity): otherwise `validate` accepts a
+ * requirement whose only scenario is a bare header, and archive rejects it
+ * when it validates the rebuilt spec.
+ */
+export function hasScenarioBody(body) {
+    return body.trim().length > 0;
+}
 /**
  * The one predicate for normative-keyword detection. Matches `SHALL` or `MUST`
  * as whole words so the change-delta reader and the schema-based reader accept
@@ -81,18 +103,43 @@ export function extractRequirementText(headerTitle, bodyLines) {
     return extractRequirementBody(bodyLines) || headerTitle.trim();
 }
 /**
- * Count the real scenarios in a requirement block: `#### ` headers on non-fenced
- * lines. A `#### Scenario:` that lives inside a fenced example is not a real
- * scenario and is not counted.
+ * Whether a scenario counts as real: a non-empty body, or an EARS-shaped
+ * header, which carries its whole behavior in the title and needs none.
+ */
+function isCountedScenario(scenario) {
+    return hasScenarioBody(scenario.body) || EARS_SCENARIO_TITLE.test(scenario.header);
+}
+/**
+ * Count the real scenarios in a requirement block: `#### ` headers on
+ * non-fenced lines whose body has content, or whose header is EARS-shaped. A
+ * `#### Scenario:` that lives inside a fenced example is not a real scenario
+ * and is not counted, and neither is a plain header with nothing under it.
  */
 export function countScenarios(bodyLines) {
+    return readScenarios(bodyLines).filter(isCountedScenario).length;
+}
+/** Count the `#### ` headers in a requirement block that do not count as a scenario. */
+export function countEmptyScenarios(bodyLines) {
+    return readScenarios(bodyLines).filter((scenario) => !isCountedScenario(scenario)).length;
+}
+/**
+ * Each scenario in a requirement block, as its header text and body. A body
+ * runs to the next non-fenced header of level 4 or above, the boundary the
+ * spec path uses, so a fenced block or a deeper `#####` header is part of it.
+ */
+function readScenarios(bodyLines) {
     const mask = buildCodeFenceMask(bodyLines);
-    let count = 0;
+    const scenarios = [];
     for (let i = 0; i < bodyLines.length; i++) {
-        if (mask[i])
+        if (mask[i] || !SCENARIO_HEADER.test(bodyLines[i]))
             continue;
-        if (SCENARIO_HEADER.test(bodyLines[i]))
-            count++;
+        let end = i + 1;
+        while (end < bodyLines.length && (mask[end] || !SCENARIO_BODY_END.test(bodyLines[end])))
+            end++;
+        scenarios.push({
+            header: bodyLines[i].replace(SCENARIO_HEADER, ''),
+            body: bodyLines.slice(i + 1, end).join('\n'),
+        });
     }
-    return count;
+    return scenarios;
 }

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/parsers/spec-structure.js

@@ -1,4 +1,5 @@
 import { buildCodeFenceMask } from './code-fence.js';
+import { normalizeRequirementName } from './requirement-blocks.js';
 const REQUIREMENTS_SECTION_HEADER = /^##\s+Requirements\s*$/i;
 const TOP_LEVEL_SECTION_HEADER = /^##\s+/;
 const DELTA_HEADER = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
@@ -53,7 +54,9 @@ export function findMainSpecStructureIssues(content) {
             });
             continue;
         }
-        const requirementName = requirementMatch[1].trim();
+        // The same name every other reader uses, so a closed heading
+        // (`### Requirement: Foo ###`) duplicates `### Requirement: Foo`.
+        const requirementName = normalizeRequirementName(requirementMatch[1]);
         const previousLine = requirementLines.get(requirementName);
         if (previousLine !== undefined) {
             issues.push({

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/purpose-placeholder.js

@@ -1,15 +1,25 @@
 import { buildCodeFenceMask } from './parsers/code-fence.js';
 import { PURPOSE_PLACEHOLDER_PREFIX, PURPOSE_PLACEHOLDER_SUFFIX } from './constants.js';
 /**
- * A `TBD` or `TODO` opening the Purpose. The lookahead keeps it off a longer
- * word that merely begins with those letters, like "TBDs" or "TODOs", while
- * still allowing the punctuation a marker is usually written with: `TODO:`,
- * `TBD -`. It rejects any letter, digit or combining mark rather than only the
- * ASCII ones `\b` knows about, because a Purpose is prose and prose is not
- * always written in Latin script - `TBD` followed by an Arabic-Indic digit is
- * as much a longer word as `TBDs` is.
+ * A `TBD` or `TODO` opening the Purpose. `WORD_END` keeps the marker off a
+ * longer word merely starting with those letters ("TBDs"), while allowing the
+ * punctuation a marker is usually written with (`TODO:`, `TBD -`); it rejects
+ * any letter/digit/combining mark, not only ASCII, since prose is not always
+ * Latin script.
+ *
+ * Case separates the marker from the word: `TODO` shouted in capitals is the
+ * marker whatever follows it, so `TODO write this later` is still unwritten.
+ * Any other case is a marker only when punctuation or the line end follows,
+ * because `todo` opens ordinary Spanish/Portuguese sentences ("Todo el...",
+ * "Todo o...") that are not placeholders - while `todo - write this later`
+ * and `tbd.` still report.
  */
-const LEADING_MARKER = /^(?:TBD|TODO)(?![\p{L}\p{N}\p{M}_])/iu;
+const WORD_END = '(?![\\p{L}\\p{N}\\p{M}_])';
+const MARKER_PUNCTUATION = '(?=[ \\t]*(?:$|\\n|[:\\-–—.,;()\\[\\]{}]))';
+/** `TBD`/`TODO` in capitals: the marker, whatever follows it. */
+const LEADING_MARKER_SHOUTED = new RegExp(`^(?:TBD|TODO)${WORD_END}`, 'u');
+/** Any other case: a marker only when punctuation or the line end says so. */
+const LEADING_MARKER_PUNCTUATED = new RegExp(`^(?:TBD|TODO)${WORD_END}${MARKER_PUNCTUATION}`, 'iu');
 const PURPOSE_HEADER = /^ {0,3}##(?!#)[ \t]+Purpose[ \t]*$/i;
 const TOP_LEVEL_HEADER = /^ {0,3}#{1,2}(?!#)[ \t]+/;
 /**
@@ -60,7 +70,7 @@ export function findPurposePlaceholderIssue(overview, content) {
     // that is nothing but a fenced block reduces to the same empty text here, and
     // is left to the brevity and empty-Purpose rules for the same reason.
     const prose = unfencedLines(overview).join('\n').trim();
-    const leading = LEADING_MARKER.test(prose);
+    const leading = LEADING_MARKER_SHOUTED.test(prose) || LEADING_MARKER_PUNCTUATED.test(prose);
     if (!leading && generatedPlaceholderPrefixIndex(prose) === undefined)
         return null;
     // Which rule matched decides where the placeholder is, so the locator is told.

package/node_modules/@freeharness/sdd/dist/vendor/openspec/validation/spec-discovery.d.ts

@@ -37,3 +37,13 @@ export declare function discoverSpecFiles(specsRoot: string): Promise<Discovered
  * decide.
  */
 export declare function hasAnyFileUnder(dirPath: string): Promise<boolean>;
+export interface UnreadDeltaFile {
+    /** File path relative to the specs root, forward-slash separated. */
+    path: string;
+    /** The spec.md the merge path reads for it, relative to the specs root. */
+    expected: string;
+}
+/** Async driver of walkUnreadDeltaFiles. */
+export declare function findUnreadDeltaFiles(specsRoot: string): Promise<UnreadDeltaFile[]>;
+/** Sync driver of walkUnreadDeltaFiles, for the instructions shim. */
+export declare function findUnreadDeltaFilesSync(specsRoot: string): UnreadDeltaFile[];