localptp 0.1.0

package/dist/core/memoryManager.js

@@ -0,0 +1,181 @@
+/**
+ * Memory Manager (HLD-SRD §3.4).
+ *
+ * `scaffold()` ensures the `/ai`, `/ai/tasks`, `/ai/sessions` and
+ * `.ai-orchestrator` dirs exist, then writes each of the 14 starter templates
+ * ONLY if absent (preserving user edits). Returns a created/preserved report.
+ *
+ * `updateMarkerSection(filePath, markerId, body)` — edit-preserving marker-
+ * delimited section update for tool-owned regions (e.g. `<!-- BEGIN
+ * localcoder:index -->`). Appends a fresh block when markers are absent.
+ *
+ * `appendMemoryEntry(filePath, sectionHeading, rawEntry)` — accumulating
+ * append-only writer (0001_07). Adds a dated, length-capped entry under the
+ * named `## ` section, preserving all existing content and de-duplicating an
+ * identical same-day entry in the same section. Distinct from the marker-
+ * section regeneration approach used by the indexer.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureDir, writeIfAbsent, readIfExists } from "../utils/fs.js";
+import { MEMORY_TEMPLATES } from "../templates/memory.js";
+/**
+ * Per-entry character cap for appended memory entries (design §3, assumption 3).
+ * Content longer than this cap is truncated before writing.
+ */
+export const MAX_ENTRY_CHARS = 280;
+function dateStamp(d = new Date()) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+/**
+ * Replace or append a marker-delimited section in a file.
+ *
+ * Markers: `<!-- BEGIN localcoder:<markerId> -->` / `<!-- END localcoder:<markerId> -->`
+ *
+ * - If both markers exist: replaces the inner region with `\n${body}\n`, preserving
+ *   all content outside.
+ * - If markers are absent: appends a fresh BEGIN/body/END block.
+ * - If duplicate BEGIN markers: replaces the first complete block, warns.
+ * - If file doesn't exist: creates it with just the marker block.
+ */
+export async function updateMarkerSection(filePath, markerId, body) {
+    const begin = `<!-- BEGIN localcoder:${markerId} -->`;
+    const end = `<!-- END localcoder:${markerId} -->`;
+    const existing = (await readIfExists(filePath)) ?? "";
+    const beginIdx = existing.indexOf(begin);
+    const endIdx = existing.indexOf(end, beginIdx >= 0 ? beginIdx : 0);
+    let next;
+    if (beginIdx >= 0 && endIdx >= 0) {
+        // Check for duplicate BEGIN markers after the first END
+        const secondBeginIdx = existing.indexOf(begin, beginIdx + 1);
+        if (secondBeginIdx >= 0) {
+            process.stderr.write(`warning: updateMarkerSection: duplicate BEGIN localcoder:${markerId} markers found in ${filePath}; replacing the first complete block.\n`);
+        }
+        // Replace the inner content between begin and end markers
+        const before = existing.slice(0, beginIdx + begin.length);
+        const after = existing.slice(endIdx);
+        next = `${before}\n${body}\n${after}`;
+    }
+    else {
+        // Append a fresh block
+        const sep = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+        next = `${existing}${sep}\n${begin}\n${body}\n${end}\n`;
+    }
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, next, "utf8");
+}
+// ---------------------------------------------------------------------------
+// appendMemoryEntry (accumulating append-only writer, 0001_07)
+// ---------------------------------------------------------------------------
+function todayStamp(d = new Date()) {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+function titleFromFile(filePath) {
+    const base = path.basename(filePath, path.extname(filePath));
+    // Convert kebab-case to Title Case
+    return base
+        .split("-")
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ");
+}
+/**
+ * Append a dated, length-capped entry under `sectionHeading` in `filePath`.
+ *
+ * Algorithm:
+ *   1. Read the file (or default to a title heading if absent).
+ *   2. Build the entry line: `- YYYY-MM-DD — <truncated content>`.
+ *   3. If the file already contains that exact line anywhere inside
+ *      `## sectionHeading` → return (de-dupe same-day identical entry).
+ *   4. If `## sectionHeading` exists: insert the entry at the END of that
+ *      section (just before the next `## ` of same/lower level or EOF).
+ *   5. If not: append a fresh `\n## sectionHeading\n<entry>\n` block.
+ *   6. Write file — only the inserted line differs; all prior prose is intact.
+ */
+export async function appendMemoryEntry(filePath, sectionHeading, rawEntry) {
+    const today = todayStamp();
+    const truncated = rawEntry.length > MAX_ENTRY_CHARS
+        ? rawEntry.slice(0, MAX_ENTRY_CHARS)
+        : rawEntry;
+    const entryLine = `- ${today} — ${truncated}`;
+    // 1. Read or initialize the file body.
+    let body = (await readIfExists(filePath)) ?? `# ${titleFromFile(filePath)}\n`;
+    // 2. Check for de-duplication: is this exact entry already in the section?
+    //    We find the section's content range first and check within it.
+    const lines = body.split("\n");
+    const headingPattern = /^(#{1,6})\s+(.*?)\s*$/;
+    let sectionStart = -1;
+    let sectionLevel = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const m = headingPattern.exec(lines[i]);
+        if (m && m[2] === sectionHeading) {
+            sectionStart = i;
+            sectionLevel = m[1].length;
+            break;
+        }
+    }
+    if (sectionStart >= 0) {
+        // Find the end of the section.
+        let sectionEnd = lines.length;
+        for (let i = sectionStart + 1; i < lines.length; i++) {
+            const m = headingPattern.exec(lines[i]);
+            if (m && m[1].length <= sectionLevel) {
+                sectionEnd = i;
+                break;
+            }
+        }
+        // Check for duplicate in this section.
+        const sectionLines = lines.slice(sectionStart + 1, sectionEnd);
+        if (sectionLines.includes(entryLine)) {
+            return; // Already present — de-dupe.
+        }
+        // Insert the entry at the end of this section (before sectionEnd).
+        // Find the last non-blank line in the section and insert after it.
+        let insertAt = sectionEnd;
+        // Insert before sectionEnd, but we need to add it in lines[] then rejoin.
+        const before = lines.slice(0, insertAt);
+        const after = lines.slice(insertAt);
+        const merged = [...before, entryLine, ...after];
+        body = merged.join("\n");
+    }
+    else {
+        // Section does not exist — append it.
+        const sep = body.length > 0 && !body.endsWith("\n") ? "\n" : "";
+        body = `${body}${sep}\n## ${sectionHeading}\n${entryLine}\n`;
+    }
+    // Write the result.
+    await ensureDir(path.dirname(filePath));
+    await fs.writeFile(filePath, body, "utf8");
+}
+export class MemoryManager {
+    layout;
+    constructor(layout) {
+        this.layout = layout;
+    }
+    async scaffold() {
+        await ensureDir(this.layout.orchestratorDir);
+        await ensureDir(this.layout.aiDir);
+        await ensureDir(this.layout.tasksDir);
+        await ensureDir(this.layout.sessionsDir);
+        const stamp = dateStamp();
+        const created = [];
+        const preserved = [];
+        for (const template of MEMORY_TEMPLATES) {
+            const target = this.layout.memoryFile(template.name);
+            const wasCreated = await writeIfAbsent(target, template.render(stamp));
+            if (wasCreated) {
+                created.push(template.name);
+            }
+            else {
+                preserved.push(template.name);
+            }
+        }
+        return { created, preserved };
+    }
+}
+//# sourceMappingURL=memoryManager.js.map

package/dist/core/memoryManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryManager.js","sourceRoot":"","sources":["../../src/core/memoryManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAC;AAOnC,SAAS,SAAS,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE;IAC/B,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAAgB,EAChB,QAAgB,EAChB,IAAY;IAEZ,MAAM,KAAK,GAAG,yBAAyB,QAAQ,MAAM,CAAC;IACtD,MAAM,GAAG,GAAG,uBAAuB,QAAQ,MAAM,CAAC;IAElD,MAAM,QAAQ,GAAG,CAAC,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC;IAEtD,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAEnE,IAAI,IAAY,CAAC;IAEjB,IAAI,QAAQ,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QACjC,wDAAwD;QACxD,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,CAAC,CAAC,CAAC;QAC7D,IAAI,cAAc,IAAI,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4DAA4D,QAAQ,qBAAqB,QAAQ,yCAAyC,CAAC,CAAC;QACnK,CAAC;QAED,0DAA0D;QAC1D,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC1D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACrC,IAAI,GAAG,GAAG,MAAM,KAAK,IAAI,KAAK,KAAK,EAAE,CAAC;IACxC,CAAC;SAAM,CAAC;QACN,uBAAuB;QACvB,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,IAAI,GAAG,GAAG,QAAQ,GAAG,GAAG,KAAK,KAAK,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC;IAC1D,CAAC;IAED,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,8EAA8E;AAC9E,+DAA+D;AAC/D,8EAA8E;AAE9E,SAAS,UAAU,CAAC,CAAC,GAAG,IAAI,IAAI,EAAE;IAChC,MAAM,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1B,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACpD,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACjD,OAAO,GAAG,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7D,mCAAmC;IACnC,OAAO,IAAI;SACR,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SAClD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,cAAsB,EACtB,QAAgB;IAEhB,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;IAC3B,MAAM,SAAS,GACb,QAAQ,CAAC,MAAM,GAAG,eAAe;QAC/B,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC;QACpC,CAAC,CAAC,QAAQ,CAAC;IACf,MAAM,SAAS,GAAG,KAAK,KAAK,MAAM,SAAS,EAAE,CAAC;IAE9C,uCAAuC;IACvC,IAAI,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC,QAAQ,CAAC,IAAI,CAAC;IAE9E,2EAA2E;IAC3E,oEAAoE;IACpE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,cAAc,GAAG,uBAAuB,CAAC;IAE/C,IAAI,YAAY,GAAG,CAAC,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,cAAc,EAAE,CAAC;YACjC,YAAY,GAAG,CAAC,CAAC;YACjB,YAAY,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YAC3B,MAAM;QACR,CAAC;IACH,CAAC;IAED,IAAI,YAAY,IAAI,CAAC,EAAE,CAAC;QACtB,+BAA+B;QAC/B,IAAI,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC;QAC9B,KAAK,IAAI,CAAC,GAAG,YAAY,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACrD,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACxC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,YAAY,EAAE,CAAC;gBACrC,UAAU,GAAG,CAAC,CAAC;gBACf,MAAM;YACR,CAAC;QACH,CAAC;QAED,uCAAuC;QACvC,MAAM,YAAY,GAAG,KAAK,CAAC,KAAK,CAAC,YAAY,GAAG,CAAC,EAAE,UAAU,CAAC,CAAC;QAC/D,IAAI,YAAY,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YACrC,OAAO,CAAC,6BAA6B;QACvC,CAAC;QAED,mEAAmE;QACnE,mEAAmE;QACnE,IAAI,QAAQ,GAAG,UAAU,CAAC;QAC1B,0EAA0E;QAC1E,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QACxC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,CAAC,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC,CAAC;QAChD,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,IAAI,GAAG,GAAG,IAAI,GAAG,GAAG,QAAQ,cAAc,KAAK,SAAS,IAAI,CAAC;IAC/D,CAAC;IAED,oBAAoB;IACpB,MAAM,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C,KAAK,CAAC,QAAQ;QACZ,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;QAC7C,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACnC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAEzC,MAAM,KAAK,GAAG,SAAS,EAAE,CAAC;QAC1B,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,MAAM,SAAS,GAAa,EAAE,CAAC;QAE/B,KAAK,MAAM,QAAQ,IAAI,gBAAgB,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACrD,MAAM,UAAU,GAAG,MAAM,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACvE,IAAI,UAAU,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;IAChC,CAAC;CACF"}

package/dist/core/memoryPolicy.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Memory update policy (HLD-SRD §3.4, 0001_07).
+ *
+ * The §3.4 policy table maps canonical change types to their single target file.
+ * The model proposes {changeType, content} only — the code picks the file via
+ * POLICY. Out-of-table change types are dropped + warned (blocks .env/secret
+ * writes, §13).
+ *
+ * `normalize(loose)` maps loose model strings to canonical keys.
+ * `headingFor(key)` returns the section heading to append under.
+ */
+/** The §3.4 update-policy table: changeType → target memory file. */
+export declare const POLICY: Readonly<Record<string, string>>;
+/**
+ * Map a loose model-provided change type string to its canonical key.
+ * Returns `undefined` for an unknown/unmapped change type.
+ */
+export declare function normalize(loose: string): string | undefined;
+/**
+ * Return the section heading for a canonical change-type key.
+ * Returns `undefined` for an unknown key.
+ */
+export declare function headingFor(key: string): string | undefined;

package/dist/core/memoryPolicy.js

@@ -0,0 +1,73 @@
+/**
+ * Memory update policy (HLD-SRD §3.4, 0001_07).
+ *
+ * The §3.4 policy table maps canonical change types to their single target file.
+ * The model proposes {changeType, content} only — the code picks the file via
+ * POLICY. Out-of-table change types are dropped + warned (blocks .env/secret
+ * writes, §13).
+ *
+ * `normalize(loose)` maps loose model strings to canonical keys.
+ * `headingFor(key)` returns the section heading to append under.
+ */
+/** The §3.4 update-policy table: changeType → target memory file. */
+export const POLICY = {
+    "file-responsibility": "file-index.md",
+    "api-behavior": "api-map.md",
+    "data-model": "data-model.md",
+    "architectural-decision": "decisions.md",
+    "external-integration": "external-integrations.md",
+    "testing-process": "test-plan.md",
+    risk: "known-issues.md",
+};
+/** Human-readable section heading for each canonical change type. */
+const HEADINGS = {
+    "file-responsibility": "File Responsibility Changes",
+    "api-behavior": "API Behavior Changes",
+    "data-model": "Data Model Changes",
+    "architectural-decision": "Architectural Decisions",
+    "external-integration": "External Integration Changes",
+    "testing-process": "Testing Process Changes",
+    risk: "Risks / Known Issues",
+};
+// Ordered normalization rules: each entry is [pattern, canonical key].
+// Evaluated in order — first match wins.
+const NORMALIZE_RULES = [
+    // Exact canonical key first (identity pass)
+    [/^file-responsibility$/i, "file-responsibility"],
+    [/^api-behavior$/i, "api-behavior"],
+    [/^data-model$/i, "data-model"],
+    [/^architectural-decision$/i, "architectural-decision"],
+    [/^external-integration$/i, "external-integration"],
+    [/^testing-process$/i, "testing-process"],
+    [/^risk$/i, "risk"],
+    // Loose matches
+    [/\bapi\b|\bendpoint\b/i, "api-behavior"],
+    [/\barchitectural\b|\bdecision\b/i, "architectural-decision"],
+    [/\brisk\b|\bbug\b/i, "risk"],
+    [/\btest(ing)?\b/i, "testing-process"],
+    [/\bfile\b|\bmodule\b/i, "file-responsibility"],
+    [/\bdata\b|\bschema\b/i, "data-model"],
+    [/\bintegration\b|\bexternal\b/i, "external-integration"],
+];
+/**
+ * Map a loose model-provided change type string to its canonical key.
+ * Returns `undefined` for an unknown/unmapped change type.
+ */
+export function normalize(loose) {
+    const trimmed = loose.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    for (const [pattern, key] of NORMALIZE_RULES) {
+        if (pattern.test(trimmed))
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Return the section heading for a canonical change-type key.
+ * Returns `undefined` for an unknown key.
+ */
+export function headingFor(key) {
+    return HEADINGS[key];
+}
+//# sourceMappingURL=memoryPolicy.js.map

package/dist/core/memoryPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryPolicy.js","sourceRoot":"","sources":["../../src/core/memoryPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,MAAM,GAAqC;IACtD,qBAAqB,EAAE,eAAe;IACtC,cAAc,EAAE,YAAY;IAC5B,YAAY,EAAE,eAAe;IAC7B,wBAAwB,EAAE,cAAc;IACxC,sBAAsB,EAAE,0BAA0B;IAClD,iBAAiB,EAAE,cAAc;IACjC,IAAI,EAAE,iBAAiB;CACxB,CAAC;AAEF,qEAAqE;AACrE,MAAM,QAAQ,GAAqC;IACjD,qBAAqB,EAAE,6BAA6B;IACpD,cAAc,EAAE,sBAAsB;IACtC,YAAY,EAAE,oBAAoB;IAClC,wBAAwB,EAAE,yBAAyB;IACnD,sBAAsB,EAAE,8BAA8B;IACtD,iBAAiB,EAAE,yBAAyB;IAC5C,IAAI,EAAE,sBAAsB;CAC7B,CAAC;AAEF,uEAAuE;AACvE,yCAAyC;AACzC,MAAM,eAAe,GAA4B;IAC/C,4CAA4C;IAC5C,CAAC,wBAAwB,EAAE,qBAAqB,CAAC;IACjD,CAAC,iBAAiB,EAAE,cAAc,CAAC;IACnC,CAAC,eAAe,EAAE,YAAY,CAAC;IAC/B,CAAC,2BAA2B,EAAE,wBAAwB,CAAC;IACvD,CAAC,yBAAyB,EAAE,sBAAsB,CAAC;IACnD,CAAC,oBAAoB,EAAE,iBAAiB,CAAC;IACzC,CAAC,SAAS,EAAE,MAAM,CAAC;IACnB,gBAAgB;IAChB,CAAC,uBAAuB,EAAE,cAAc,CAAC;IACzC,CAAC,iCAAiC,EAAE,wBAAwB,CAAC;IAC7D,CAAC,mBAAmB,EAAE,MAAM,CAAC;IAC7B,CAAC,iBAAiB,EAAE,iBAAiB,CAAC;IACtC,CAAC,sBAAsB,EAAE,qBAAqB,CAAC;IAC/C,CAAC,sBAAsB,EAAE,YAAY,CAAC;IACtC,CAAC,+BAA+B,EAAE,sBAAsB,CAAC;CAC1D,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,eAAe,EAAE,CAAC;QAC7C,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,GAAG,CAAC;IACxC,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/core/modelClient.d.ts

@@ -0,0 +1,37 @@
+/**
+ * LM Studio model client (HLD-SRD §3.8, §12).
+ *
+ * Speaks the OpenAI-compatible REST API behind the single `ModelClient` seam,
+ * using the Node 20 built-in `fetch` + `AbortController` for timeouts. All
+ * transport/protocol failures are mapped to a typed `ModelClientError` whose
+ * `kind` callers branch on without string-matching.
+ */
+import { type ModelClient, type ModelRequest, type ModelResponse, type HealthResult } from "../types/model.js";
+export interface LmStudioClientOptions {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    temperature?: number;
+    timeoutMs?: number;
+}
+export declare class LmStudioClient implements ModelClient {
+    private readonly baseUrl;
+    private readonly model;
+    private readonly apiKey;
+    private readonly temperature;
+    private readonly timeoutMs;
+    constructor(opts: LmStudioClientOptions);
+    private headers;
+    /**
+     * Run a fetch with a timeout, translating transport failures (refused/timeout)
+     * into typed errors. The timeout covers BOTH the headers AND the body read:
+     * the abort timer stays armed until the body has been consumed, so a server
+     * that sends headers and then stalls the body cannot hang past `timeoutMs`.
+     */
+    private request;
+    complete(req: ModelRequest): Promise<ModelResponse>;
+    health(): Promise<HealthResult>;
+    private looksLikeModelNotLoaded;
+    private extractContent;
+    private extractModels;
+}

package/dist/core/modelClient.js

@@ -0,0 +1,160 @@
+/**
+ * LM Studio model client (HLD-SRD §3.8, §12).
+ *
+ * Speaks the OpenAI-compatible REST API behind the single `ModelClient` seam,
+ * using the Node 20 built-in `fetch` + `AbortController` for timeouts. All
+ * transport/protocol failures are mapped to a typed `ModelClientError` whose
+ * `kind` callers branch on without string-matching.
+ */
+import { ModelClientError, } from "../types/model.js";
+function connectionMessage(baseUrl) {
+    return (`Cannot connect to LM Studio at ${baseUrl}. ` +
+        `Make sure LM Studio Local Server is running and the model is loaded.`);
+}
+/** Join the base (which ends in /v1) with an endpoint path. */
+function urlFor(baseUrl, endpoint) {
+    return `${baseUrl.replace(/\/+$/, "")}/${endpoint.replace(/^\/+/, "")}`;
+}
+export class LmStudioClient {
+    baseUrl;
+    model;
+    apiKey;
+    temperature;
+    timeoutMs;
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl;
+        this.model = opts.model;
+        this.apiKey = opts.apiKey ?? "lm-studio";
+        this.temperature = opts.temperature ?? 0.2;
+        this.timeoutMs = opts.timeoutMs ?? 60000;
+    }
+    headers() {
+        return {
+            "content-type": "application/json",
+            authorization: `Bearer ${this.apiKey}`,
+        };
+    }
+    /**
+     * Run a fetch with a timeout, translating transport failures (refused/timeout)
+     * into typed errors. The timeout covers BOTH the headers AND the body read:
+     * the abort timer stays armed until the body has been consumed, so a server
+     * that sends headers and then stalls the body cannot hang past `timeoutMs`.
+     */
+    async request(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const res = await fetch(url, { ...init, signal: controller.signal });
+            // Read the body within the same abortable window so a stalled body still
+            // trips the timeout rather than hanging indefinitely.
+            const text = await res.text();
+            return { status: res.status, ok: res.ok, text };
+        }
+        catch (err) {
+            if (err.name === "AbortError") {
+                throw new ModelClientError("timeout", `Request to LM Studio at ${this.baseUrl} timed out after ${this.timeoutMs}ms. ` +
+                    connectionMessage(this.baseUrl), this.baseUrl, err);
+            }
+            throw new ModelClientError("refused", connectionMessage(this.baseUrl), this.baseUrl, err);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async complete(req) {
+        const url = urlFor(this.baseUrl, "chat/completions");
+        const body = {
+            model: this.model,
+            messages: [
+                { role: "system", content: req.systemPrompt },
+                { role: "user", content: req.userPrompt },
+            ],
+            temperature: req.temperature ?? this.temperature,
+            ...(req.maxTokens !== undefined ? { max_tokens: req.maxTokens } : {}),
+        };
+        const res = await this.request(url, {
+            method: "POST",
+            headers: this.headers(),
+            body: JSON.stringify(body),
+        });
+        const text = res.text;
+        if (!res.ok) {
+            // Non-2xx: distinguish model-not-loaded from a generic failure.
+            if (this.looksLikeModelNotLoaded(res.status, text)) {
+                throw new ModelClientError("model-not-loaded", `LM Studio at ${this.baseUrl} has no model loaded (HTTP ${res.status}). ` +
+                    connectionMessage(this.baseUrl), this.baseUrl);
+            }
+            throw new ModelClientError("refused", `LM Studio at ${this.baseUrl} returned HTTP ${res.status}. ` +
+                connectionMessage(this.baseUrl), this.baseUrl);
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new ModelClientError("malformed", "Model returned an empty/invalid response.", this.baseUrl, err);
+        }
+        const content = this.extractContent(parsed);
+        if (content === undefined || content.length === 0) {
+            throw new ModelClientError("empty", "Model returned an empty/invalid response.", this.baseUrl);
+        }
+        return { content, raw: parsed };
+    }
+    async health() {
+        const url = urlFor(this.baseUrl, "models");
+        const res = await this.request(url, {
+            method: "GET",
+            headers: this.headers(),
+        });
+        if (!res.ok) {
+            throw new ModelClientError("model-not-loaded", `LM Studio at ${this.baseUrl} returned HTTP ${res.status} for /models. ` +
+                connectionMessage(this.baseUrl), this.baseUrl);
+        }
+        const text = res.text;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (err) {
+            throw new ModelClientError("malformed", "Model returned an empty/invalid response.", this.baseUrl, err);
+        }
+        const models = this.extractModels(parsed);
+        return { reachable: true, models };
+    }
+    looksLikeModelNotLoaded(status, body) {
+        if (status === 404)
+            return true;
+        const lower = body.toLowerCase();
+        return (lower.includes("model_not_found") ||
+            lower.includes("not found") ||
+            lower.includes("no model"));
+    }
+    extractContent(parsed) {
+        if (typeof parsed !== "object" || parsed === null)
+            return undefined;
+        const choices = parsed.choices;
+        if (!Array.isArray(choices) || choices.length === 0)
+            return undefined;
+        const first = choices[0];
+        if (typeof first !== "object" || first === null)
+            return undefined;
+        const message = first.message;
+        if (typeof message !== "object" || message === null)
+            return undefined;
+        const content = message.content;
+        return typeof content === "string" ? content : undefined;
+    }
+    extractModels(parsed) {
+        if (typeof parsed !== "object" || parsed === null)
+            return [];
+        const data = parsed.data;
+        if (!Array.isArray(data))
+            return [];
+        return data
+            .map((d) => typeof d === "object" && d !== null
+            ? d.id
+            : undefined)
+            .filter((id) => typeof id === "string");
+    }
+}
+//# sourceMappingURL=modelClient.js.map

package/dist/core/modelClient.js.map

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

package/dist/core/patchManager.d.ts

@@ -0,0 +1,89 @@
+import type { AppConfig } from "../types/config.js";
+import type { PatchPlan } from "../types/patch.js";
+/** A path/target/ignore validation failure (§3.10, §13). Carries an exit code. */
+export declare class PatchValidationError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+/** A patch that does not cleanly apply, or an apply mechanism failure (§12.3). */
+export declare class PatchApplyError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+/** The working tree is not safe to apply onto (e.g. mid-merge/rebase) (§11.2). */
+export declare class WorkingTreeUnsafeError extends Error {
+    readonly exitCode = 1;
+    constructor(message: string);
+}
+/**
+ * Tolerantly extract a unified diff from raw model output. Strips code fences
+ * and surrounding prose, returning the diff block (from its first `diff --git`
+ * or `---` line through its last diff-shaped line). Returns null when there is
+ * no diff — empty/whitespace output, a `needs_context` JSON response, or plain
+ * prose.
+ */
+export declare function extractUnifiedDiff(raw: string): string | null;
+/**
+ * Parse a unified diff into a classified `PatchPlan`. Each `diff --git` (or, for
+ * a header-less diff, each `---`/`+++` pair) is one file section. Classification:
+ *   - `new file mode` / `--- /dev/null`  → add
+ *   - `deleted file mode` / `+++ /dev/null` → delete
+ *   - otherwise → modify
+ * `GIT binary patch` in any section sets `isBinary`.
+ */
+export declare function parsePatch(diff: string): PatchPlan;
+/**
+ * Normalize an ALREADY-prefix-stripped touched path (the paths in a `PatchPlan`
+ * have had their `a/`/`b/` diff prefix removed by `parsePatch`) to repo-relative
+ * POSIX form: convert Windows `\` separators and drop a `./` prefix. It does NOT
+ * re-strip an `a/`/`b/` prefix — doing so would corrupt a legitimate path whose
+ * first segment is literally `a` or `b` (e.g. `a/secure.txt`), causing the
+ * ignore / risky-path checks to inspect the wrong path. Absolute markers are
+ * preserved for the escape check.
+ */
+export declare function normalizeTouchedPath(p: string): string;
+/**
+ * Validate a parsed plan against the repo root + config. Throws
+ * `PatchValidationError` on the first violation:
+ *   - any touched path escaping the root (absolute, `../`, or symlink escape);
+ *   - any touched path matching the ignore list;
+ *   - a modify/delete whose target does not exist;
+ *   - an add whose target already exists (never overwrite).
+ * Resolves (undefined) when the plan is structurally safe to apply.
+ */
+export declare function validate(plan: PatchPlan, config: AppConfig, root: string): Promise<void>;
+/**
+ * Refuse to apply onto an unsafe working tree (§11.2). Unsafe = a repo in the
+ * middle of a merge / rebase / cherry-pick / revert / bisect (detected by the
+ * marker files / dirs git writes). Unrelated dirty files are tolerated — the
+ * `git apply --check` pre-flight gates the exact apply. A non-git dir has no
+ * merge state, so this is a no-op there.
+ */
+export declare function assertWorkingTreeSafe(root: string): Promise<void>;
+/**
+ * Pre-flight a diff with `git apply --check` (no mutation). Throws
+ * `PatchApplyError` when the patch would not apply cleanly. Git repos only —
+ * the command skips this for the non-git add-only path.
+ */
+export declare function gitApplyCheck(plan: PatchPlan, root: string): Promise<void>;
+/**
+ * Apply a parsed plan to the working tree, never partially.
+ *
+ * Git repo: `git apply --check` then `git apply` (atomic per call). A failing
+ * check leaves the tree untouched.
+ *
+ * Non-git dir: only an add-only patch is applied, via a controlled write of the
+ * new files (the Git pre-check is skipped). Any existing-file modify/delete in a
+ * non-git dir is refused with `PatchApplyError` — there is no rollback layer.
+ */
+export declare function apply(plan: PatchPlan, root: string): Promise<void>;
+export interface SavePatchOptions {
+    /** Injectable clock for deterministic tests. */
+    now?: Date;
+}
+/**
+ * Save the raw diff as a patch artifact under
+ * `<orchestratorDir>/patches/YYYY-MM-DD_HHMM_<step-id>.patch`. Returns the
+ * absolute path written. Never overwrites: a name collision appends `-2`, `-3`…
+ */
+export declare function savePatch(diff: string, stepId: string, orchestratorDir: string, opts?: SavePatchOptions): Promise<string>;