open-wiki-spec 0.2.4 → 0.3.1

package/dist/types/verify.d.ts

@@ -1,15 +1,72 @@
 export type IssueSeverity = 'error' | 'warning' | 'info';
 export type VerifyDimension = 'completeness' | 'correctness' | 'coherence' | 'vault_integrity';
+/**
+ * Central taxonomy of verify issue codes.
+ * AI agents and automation should branch on these values.
+ */
+export declare const VERIFY_CODES: {
+    readonly MISSING_SECTION: "MISSING_SECTION";
+    readonly MISSING_REQUIREMENTS: "MISSING_REQUIREMENTS";
+    readonly MISSING_DELTA_SUMMARY: "MISSING_DELTA_SUMMARY";
+    readonly MISSING_TASKS: "MISSING_TASKS";
+    readonly MISSING_VALIDATION: "MISSING_VALIDATION";
+    readonly MISSING_LINK: "MISSING_LINK";
+    readonly MISSING_DESIGN_APPROACH: "MISSING_DESIGN_APPROACH";
+    readonly EMPTY_REQUIRED_SECTION: "EMPTY_REQUIRED_SECTION";
+    readonly INVALID_FRONTMATTER_REF: "INVALID_FRONTMATTER_REF";
+    readonly DELTA_MISMATCH_ADDED: "DELTA_MISMATCH_ADDED";
+    readonly DELTA_MISMATCH_MODIFIED: "DELTA_MISMATCH_MODIFIED";
+    readonly DELTA_MISMATCH_REMOVED: "DELTA_MISMATCH_REMOVED";
+    readonly DELTA_MISMATCH_RENAMED: "DELTA_MISMATCH_RENAMED";
+    readonly MODIFIED_NO_CHANGE: "MODIFIED_NO_CHANGE";
+    readonly STALE_BASE: "STALE_BASE";
+    readonly INVALID_STATUS_TRANSITION: "INVALID_STATUS_TRANSITION";
+    readonly BROKEN_DEPENDS_ON: "BROKEN_DEPENDS_ON";
+    readonly INVALID_DEPENDS_ON_TYPE: "INVALID_DEPENDS_ON_TYPE";
+    readonly SCHEMA_MISMATCH: "SCHEMA_MISMATCH";
+    readonly UNSUPPORTED_SCHEMA_VERSION: "UNSUPPORTED_SCHEMA_VERSION";
+    readonly BREAKING_CHANGE_WITHOUT_VERSION_BUMP: "BREAKING_CHANGE_WITHOUT_VERSION_BUMP";
+    readonly EXCESSIVE_DRIFT: "EXCESSIVE_DRIFT";
+    readonly UNFILLED_APPLY_MARKER: "UNFILLED_APPLY_MARKER";
+    readonly TOUCHES_OVERLAP_BLOCKED: "TOUCHES_OVERLAP_BLOCKED";
+    readonly TOUCHES_OVERLAP_CONFLICT: "TOUCHES_OVERLAP_CONFLICT";
+    readonly TOUCHES_OVERLAP_NEEDS_REVIEW: "TOUCHES_OVERLAP_NEEDS_REVIEW";
+    readonly REQUIREMENT_CONFLICT_CRITICAL: "REQUIREMENT_CONFLICT_CRITICAL";
+    readonly DEPENDENCY_CYCLE: "DEPENDENCY_CYCLE";
+    readonly OUT_OF_ORDER: "OUT_OF_ORDER";
+    readonly CONFLICTING_DESCRIPTIONS: "CONFLICTING_DESCRIPTIONS";
+    readonly INCONSISTENT_DECISION: "INCONSISTENT_DECISION";
+    readonly DUPLICATE_ID: "DUPLICATE_ID";
+    readonly MISSING_ID: "MISSING_ID";
+    readonly UNRESOLVED_WIKILINK: "UNRESOLVED_WIKILINK";
+    readonly AMBIGUOUS_ALIAS: "AMBIGUOUS_ALIAS";
+    readonly ORPHAN_NOTE: "ORPHAN_NOTE";
+    readonly ARCHIVE_PLACEMENT_ERROR: "ARCHIVE_PLACEMENT_ERROR";
+    readonly EMPTY_TYPED_NOTE: "EMPTY_TYPED_NOTE";
+    readonly TITLE_ID_COLLISION: "TITLE_ID_COLLISION";
+    readonly POTENTIAL_SECRET_LEAK: "POTENTIAL_SECRET_LEAK";
+    readonly TYPE_FOLDER_MISMATCH: "TYPE_FOLDER_MISMATCH";
+    readonly APPLY_IN_PROGRESS: "APPLY_IN_PROGRESS";
+    readonly ARCHIVED_TARGET: "ARCHIVED_TARGET";
+};
+export type VerifyCode = typeof VERIFY_CODES[keyof typeof VERIFY_CODES];
 export interface VerifyIssue {
     dimension: VerifyDimension;
     severity: IssueSeverity;
-    code: string;
+    code: VerifyCode | string;
     message: string;
     note_path?: string;
     note_id?: string;
     suggestion?: string;
 }
+/**
+ * JSON contract version for VerifyReport. Bump this when the shape of the
+ * report changes in a way that breaks existing consumers.
+ */
+export declare const VERIFY_REPORT_SCHEMA_VERSION = "1.0.0";
 export interface VerifyReport {
+    /** Schema version for the report JSON contract. See VERIFY_REPORT_SCHEMA_VERSION. */
+    schema_version?: string;
     scanned_at: string;
     total_notes: number;
     issues: VerifyIssue[];

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

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/types/verify.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF,IAAI,EAAE,OAAO,CAAC;CACf"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/types/verify.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,aAAa,GAAG,WAAW,GAAG,iBAAiB,CAAC;AAE/F;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmDf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,OAAO,YAAY,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAExE,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,eAAe,CAAC;IAC3B,QAAQ,EAAE,aAAa,CAAC;IACxB,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,eAAO,MAAM,4BAA4B,UAAU,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF,IAAI,EAAE,OAAO,CAAC;CACf"}

package/dist/types/verify.js

@@ -1,2 +1,59 @@
-export {};
+/**
+ * Central taxonomy of verify issue codes.
+ * AI agents and automation should branch on these values.
+ */
+export const VERIFY_CODES = {
+    // completeness
+    MISSING_SECTION: 'MISSING_SECTION',
+    MISSING_REQUIREMENTS: 'MISSING_REQUIREMENTS',
+    MISSING_DELTA_SUMMARY: 'MISSING_DELTA_SUMMARY',
+    MISSING_TASKS: 'MISSING_TASKS',
+    MISSING_VALIDATION: 'MISSING_VALIDATION',
+    MISSING_LINK: 'MISSING_LINK',
+    MISSING_DESIGN_APPROACH: 'MISSING_DESIGN_APPROACH',
+    EMPTY_REQUIRED_SECTION: 'EMPTY_REQUIRED_SECTION',
+    // correctness
+    INVALID_FRONTMATTER_REF: 'INVALID_FRONTMATTER_REF',
+    DELTA_MISMATCH_ADDED: 'DELTA_MISMATCH_ADDED',
+    DELTA_MISMATCH_MODIFIED: 'DELTA_MISMATCH_MODIFIED',
+    DELTA_MISMATCH_REMOVED: 'DELTA_MISMATCH_REMOVED',
+    DELTA_MISMATCH_RENAMED: 'DELTA_MISMATCH_RENAMED',
+    MODIFIED_NO_CHANGE: 'MODIFIED_NO_CHANGE',
+    STALE_BASE: 'STALE_BASE',
+    INVALID_STATUS_TRANSITION: 'INVALID_STATUS_TRANSITION',
+    BROKEN_DEPENDS_ON: 'BROKEN_DEPENDS_ON',
+    INVALID_DEPENDS_ON_TYPE: 'INVALID_DEPENDS_ON_TYPE',
+    SCHEMA_MISMATCH: 'SCHEMA_MISMATCH',
+    UNSUPPORTED_SCHEMA_VERSION: 'UNSUPPORTED_SCHEMA_VERSION',
+    BREAKING_CHANGE_WITHOUT_VERSION_BUMP: 'BREAKING_CHANGE_WITHOUT_VERSION_BUMP',
+    EXCESSIVE_DRIFT: 'EXCESSIVE_DRIFT',
+    UNFILLED_APPLY_MARKER: 'UNFILLED_APPLY_MARKER',
+    // coherence
+    TOUCHES_OVERLAP_BLOCKED: 'TOUCHES_OVERLAP_BLOCKED',
+    TOUCHES_OVERLAP_CONFLICT: 'TOUCHES_OVERLAP_CONFLICT',
+    TOUCHES_OVERLAP_NEEDS_REVIEW: 'TOUCHES_OVERLAP_NEEDS_REVIEW',
+    REQUIREMENT_CONFLICT_CRITICAL: 'REQUIREMENT_CONFLICT_CRITICAL',
+    DEPENDENCY_CYCLE: 'DEPENDENCY_CYCLE',
+    OUT_OF_ORDER: 'OUT_OF_ORDER',
+    CONFLICTING_DESCRIPTIONS: 'CONFLICTING_DESCRIPTIONS',
+    INCONSISTENT_DECISION: 'INCONSISTENT_DECISION',
+    // vault_integrity
+    DUPLICATE_ID: 'DUPLICATE_ID',
+    MISSING_ID: 'MISSING_ID',
+    UNRESOLVED_WIKILINK: 'UNRESOLVED_WIKILINK',
+    AMBIGUOUS_ALIAS: 'AMBIGUOUS_ALIAS',
+    ORPHAN_NOTE: 'ORPHAN_NOTE',
+    ARCHIVE_PLACEMENT_ERROR: 'ARCHIVE_PLACEMENT_ERROR',
+    EMPTY_TYPED_NOTE: 'EMPTY_TYPED_NOTE',
+    TITLE_ID_COLLISION: 'TITLE_ID_COLLISION',
+    POTENTIAL_SECRET_LEAK: 'POTENTIAL_SECRET_LEAK',
+    TYPE_FOLDER_MISMATCH: 'TYPE_FOLDER_MISMATCH',
+    APPLY_IN_PROGRESS: 'APPLY_IN_PROGRESS',
+    ARCHIVED_TARGET: 'ARCHIVED_TARGET',
+};
+/**
+ * JSON contract version for VerifyReport. Bump this when the shape of the
+ * report changes in a way that breaks existing consumers.
+ */
+export const VERIFY_REPORT_SCHEMA_VERSION = '1.0.0';
 //# sourceMappingURL=verify.js.map

package/dist/types/verify.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/types/verify.ts"],"names":[],"mappings":""}
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/types/verify.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,eAAe;IACf,eAAe,EAAE,iBAAiB;IAClC,oBAAoB,EAAE,sBAAsB;IAC5C,qBAAqB,EAAE,uBAAuB;IAC9C,aAAa,EAAE,eAAe;IAC9B,kBAAkB,EAAE,oBAAoB;IACxC,YAAY,EAAE,cAAc;IAC5B,uBAAuB,EAAE,yBAAyB;IAClD,sBAAsB,EAAE,wBAAwB;IAEhD,cAAc;IACd,uBAAuB,EAAE,yBAAyB;IAClD,oBAAoB,EAAE,sBAAsB;IAC5C,uBAAuB,EAAE,yBAAyB;IAClD,sBAAsB,EAAE,wBAAwB;IAChD,sBAAsB,EAAE,wBAAwB;IAChD,kBAAkB,EAAE,oBAAoB;IACxC,UAAU,EAAE,YAAY;IACxB,yBAAyB,EAAE,2BAA2B;IACtD,iBAAiB,EAAE,mBAAmB;IACtC,uBAAuB,EAAE,yBAAyB;IAClD,eAAe,EAAE,iBAAiB;IAClC,0BAA0B,EAAE,4BAA4B;IACxD,oCAAoC,EAAE,sCAAsC;IAC5E,eAAe,EAAE,iBAAiB;IAClC,qBAAqB,EAAE,uBAAuB;IAE9C,YAAY;IACZ,uBAAuB,EAAE,yBAAyB;IAClD,wBAAwB,EAAE,0BAA0B;IACpD,4BAA4B,EAAE,8BAA8B;IAC5D,6BAA6B,EAAE,+BAA+B;IAC9D,gBAAgB,EAAE,kBAAkB;IACpC,YAAY,EAAE,cAAc;IAC5B,wBAAwB,EAAE,0BAA0B;IACpD,qBAAqB,EAAE,uBAAuB;IAE9C,kBAAkB;IAClB,YAAY,EAAE,cAAc;IAC5B,UAAU,EAAE,YAAY;IACxB,mBAAmB,EAAE,qBAAqB;IAC1C,eAAe,EAAE,iBAAiB;IAClC,WAAW,EAAE,aAAa;IAC1B,uBAAuB,EAAE,yBAAyB;IAClD,gBAAgB,EAAE,kBAAkB;IACpC,kBAAkB,EAAE,oBAAoB;IACxC,qBAAqB,EAAE,uBAAuB;IAC9C,oBAAoB,EAAE,sBAAsB;IAC5C,iBAAiB,EAAE,mBAAmB;IACtC,eAAe,EAAE,iBAAiB;CAC1B,CAAC;AAcX;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC"}

package/dist/utils/conventions.d.ts

@@ -0,0 +1,9 @@
+export interface ReadConventionsDeps {
+    readFile: (filePath: string) => string;
+}
+/**
+ * Read project conventions from wiki/00-meta/conventions.md (best-effort).
+ * Returns undefined if the file doesn't exist or is empty.
+ */
+export declare function readConventionsContent(vaultRoot: string, deps: ReadConventionsDeps): string | undefined;
+//# sourceMappingURL=conventions.d.ts.map

package/dist/utils/conventions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.d.ts","sourceRoot":"","sources":["../../src/utils/conventions.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;CACxC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,mBAAmB,GACxB,MAAM,GAAG,SAAS,CAUpB"}

package/dist/utils/conventions.js

@@ -0,0 +1,22 @@
+/**
+ * Shared utility for reading project conventions from wiki/00-meta/conventions.md.
+ * Used by propose and continue workflows to inject project rules into agent context.
+ */
+import * as path from 'node:path';
+/**
+ * Read project conventions from wiki/00-meta/conventions.md (best-effort).
+ * Returns undefined if the file doesn't exist or is empty.
+ */
+export function readConventionsContent(vaultRoot, deps) {
+    try {
+        const conventionsPath = path.join(vaultRoot, 'wiki', '00-meta', 'conventions.md');
+        const content = deps.readFile(conventionsPath);
+        const stripped = content.replace(/^---[\s\S]*?---\s*/, '');
+        const trimmed = stripped.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=conventions.js.map

package/dist/utils/conventions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conventions.js","sourceRoot":"","sources":["../../src/utils/conventions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAMlC;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,IAAyB;IAEzB,IAAI,CAAC;QACH,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QAClF,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;QAC/C,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAChC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/utils/id-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAQhE"}
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBhE"}

package/dist/utils/id-generator.js

@@ -14,11 +14,19 @@
  */
 export function generateId(type, title) {
     const slug = title
+        .normalize('NFC') // Unicode normalization for consistent macOS NFD / Linux NFC compare
         .toLowerCase()
         .replace(/[\s_]+/g, '-')
         .replace(/[^\p{L}\p{N}-]/gu, '')
         .replace(/-+/g, '-')
         .replace(/^-|-$/g, '');
+    // If the title degenerates to an empty slug (e.g., "!!!" or "   "),
+    // fall back to a timestamp-based slug so we never produce an ID like "feature-"
+    // which would fail schema validation and collide with other degenerate titles.
+    if (slug.length === 0) {
+        const timestamp = Date.now().toString(36);
+        return `${type}-untitled-${timestamp}`;
+    }
     return `${type}-${slug}`;
 }
 //# sourceMappingURL=id-generator.js.map

package/dist/utils/id-generator.js.map

@@ -1 +1 @@
-{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,IAAc,EAAE,KAAa;IACtD,MAAM,IAAI,GAAG,KAAK;SACf,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IACzB,OAAO,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,UAAU,CAAC,IAAc,EAAE,KAAa;IACtD,MAAM,IAAI,GAAG,KAAK;SACf,SAAS,CAAC,KAAK,CAAC,CAAE,qEAAqE;SACvF,WAAW,EAAE;SACb,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAEzB,oEAAoE;IACpE,gFAAgF;IAChF,+EAA+E;IAC/E,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;QAC1C,OAAO,GAAG,IAAI,aAAa,SAAS,EAAE,CAAC;IACzC,CAAC;IACD,OAAO,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;AAC3B,CAAC"}

package/dist/utils/normalize.d.ts

@@ -1,11 +1,14 @@
 /**
- * Normalize a string for comparison: trim, collapse whitespace, lowercase.
+ * Normalize a string for comparison: strip invisible chars, Unicode NFC,
+ * trim, collapse whitespace, lowercase.
+ * NFC ensures macOS NFD-encoded filenames compare equal to NFC-encoded ones.
  */
 export declare function normalizeString(input: string): string;
 /**
- * Normalize text for content hashing: trim and collapse all whitespace to single spaces.
- * Case is preserved (hashing is case-sensitive).
- * Deterministic regardless of line endings (CRLF vs LF).
+ * Normalize text for content hashing: strip invisible chars, Unicode NFC,
+ * trim, collapse whitespace. Case is preserved (hashing is case-sensitive).
+ * Deterministic regardless of line endings (CRLF vs LF), Unicode form
+ * (NFC vs NFD), and invisible character pollution.
  */
 export declare function normalizeForHash(text: string): string;
 //# sourceMappingURL=normalize.d.ts.map

package/dist/utils/normalize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAErD"}
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrD"}

package/dist/utils/normalize.js

@@ -1,15 +1,52 @@
 /**
- * Normalize a string for comparison: trim, collapse whitespace, lowercase.
+ * Zero-width and invisible characters that are visually indistinguishable from
+ * empty but differ byte-for-byte. We strip these during normalization so that
+ * e.g. `Feature: Auth\u200D` and `Feature: Auth` compare equal. This also
+ * blocks trivial spoofing attacks where a malicious Feature title inserts a
+ * ZWJ to bypass duplicate detection.
+ *
+ * Includes: BOM (U+FEFF), ZWSP (U+200B), ZWNJ (U+200C), ZWJ (U+200D),
+ * ZWNBSP (U+FEFF), directional marks (U+200E/F, U+202A-E), word joiner (U+2060).
+ */
+const INVISIBLE_CHARS_RE = /[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g;
+/**
+ * ASCII control characters (0x00-0x08, 0x0B, 0x0C, 0x0E-0x1F, 0x7F) that have
+ * no place in a note title, alias, or body comparison string. Tab (0x09),
+ * line feed (0x0A), and carriage return (0x0D) are preserved — downstream
+ * whitespace collapse handles them. Stripping the rest blocks:
+ *   - BEL/backspace terminal escape tricks in log output
+ *   - Spoofed titles that render identically but compare differently
+ *   - DEL (0x7F) used to bypass slug dedup checks
+ * Without this, a record with `title: "Auth\x01"` would compare unequal to
+ * `"Auth"` and slip past the duplicate / alias resolution checks.
+ */
+const CONTROL_CHARS_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g;
+/**
+ * Normalize a string for comparison: strip invisible chars, Unicode NFC,
+ * trim, collapse whitespace, lowercase.
+ * NFC ensures macOS NFD-encoded filenames compare equal to NFC-encoded ones.
  */
 export function normalizeString(input) {
-    return input.trim().replace(/\s+/g, ' ').toLowerCase();
+    return input
+        .replace(INVISIBLE_CHARS_RE, '')
+        .replace(CONTROL_CHARS_RE, '')
+        .normalize('NFC')
+        .trim()
+        .replace(/\s+/g, ' ')
+        .toLowerCase();
 }
 /**
- * Normalize text for content hashing: trim and collapse all whitespace to single spaces.
- * Case is preserved (hashing is case-sensitive).
- * Deterministic regardless of line endings (CRLF vs LF).
+ * Normalize text for content hashing: strip invisible chars, Unicode NFC,
+ * trim, collapse whitespace. Case is preserved (hashing is case-sensitive).
+ * Deterministic regardless of line endings (CRLF vs LF), Unicode form
+ * (NFC vs NFD), and invisible character pollution.
  */
 export function normalizeForHash(text) {
-    return text.trim().replace(/\s+/g, ' ');
+    return text
+        .replace(INVISIBLE_CHARS_RE, '')
+        .replace(CONTROL_CHARS_RE, '')
+        .normalize('NFC')
+        .trim()
+        .replace(/\s+/g, ' ');
 }
 //# sourceMappingURL=normalize.js.map

package/dist/utils/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1C,CAAC"}
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../src/utils/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,kBAAkB,GAAG,2CAA2C,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,MAAM,gBAAgB,GAAG,mCAAmC,CAAC;AAE7D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,OAAO,KAAK;SACT,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,SAAS,CAAC,KAAK,CAAC;SAChB,IAAI,EAAE;SACN,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO,IAAI;SACR,OAAO,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAC/B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,SAAS,CAAC,KAAK,CAAC;SAChB,IAAI,EAAE;SACN,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-wiki-spec",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Obsidian-first wiki workflow engine for specification management",
   "type": "module",
   "bin": {
@@ -13,7 +13,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "@huggingface/transformers": "^3.0.0",
@@ -35,6 +35,7 @@
     "dist/",
     "bin/",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "keywords": [