@inharness-ai/claude4spec 1.0.2 → 1.0.4

package/dist/server/services/patch.js

@@ -0,0 +1,196 @@
+/**
+ * M23 PatchService — thin wrapper over the third `PagesService` instance
+ * mounted on `patchesDir`. Patches are markdown files with mandatory YAML
+ * frontmatter (`type: patch`, `brief`, `patch_kind`, `created_at`,
+ * `created_by`, `status`). They are authored by coding agents in *other*
+ * terminals during brief implementation — claude4spec only reads them, lets
+ * the spec author flip `status`, and spins up a chat thread to fold the
+ * patch's findings back into the spec.
+ *
+ * Design notes (parallel to BriefService):
+ *   - **Zero new tables**. Listing comes from PagesFrontmatterIndexer.
+ *   - **Optimistic concurrency** by sha256 hash of full content.
+ *   - **Immutable frontmatter** keys protected (PATCH_IMMUTABLE_FRONTMATTER_KEYS);
+ *     only `status` is mutable from the claude4spec side.
+ *   - A patch links to a brief via the `brief` frontmatter field, or — when
+ *     absent — by filename prefix. Unresolvable ⇒ orphan (`briefPath: null`).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { PATCH_IMMUTABLE_FRONTMATTER_KEYS } from '../../shared/entities.js';
+import { DomainError } from './tags.js';
+import { ConflictError } from './brief.js';
+const VALID_PATCH_KINDS = new Set([
+    'drift',
+    'missing',
+    'incorrect',
+    'clarification',
+]);
+export class PatchService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    // ─── Reads ───────────────────────────────────────────────────────────────
+    async getPatch(relPath) {
+        if (!(await this.deps.patchesPages.exists(relPath))) {
+            throw new DomainError('NOT_FOUND', `patch '${relPath}' not found`);
+        }
+        const abs = this.absPath(relPath);
+        const content = await fs.readFile(abs, 'utf-8');
+        const parsed = matter(content);
+        const frontmatter = (parsed.data ?? {});
+        if (frontmatter.type !== 'patch') {
+            throw new DomainError('PATCH_INVALID_FRONTMATTER', `file '${relPath}' is not a patch (frontmatter.type=${JSON.stringify(frontmatter.type)})`);
+        }
+        return {
+            path: relPath,
+            title: extractTitle(parsed.content, frontmatter, relPath),
+            frontmatter,
+            body: parsed.content,
+            content,
+            hash: hashContent(content),
+        };
+    }
+    listPatches(opts = {}) {
+        const briefPaths = this.knownBriefPaths();
+        const records = this.deps.frontmatterIndexer.findByFrontmatterType('patch', {
+            rootDir: 'patches',
+        });
+        const out = [];
+        for (const rec of records) {
+            const fm = rec.frontmatter;
+            const status = fm.status === 'completed' ? 'completed' : 'awaiting';
+            const briefPath = this.resolveBriefPath(rec.path, fm, briefPaths);
+            if (opts.brief !== undefined && opts.brief !== briefPath)
+                continue;
+            if (opts.status !== undefined && opts.status !== status)
+                continue;
+            const lastVersion = this.deps.pageVersions.getLatestForPath(rec.path, undefined, 'patch');
+            const createdAt = toIso(fm.created_at);
+            out.push({
+                path: rec.path,
+                title: extractTitleFromFrontmatter(fm, rec.path),
+                briefPath,
+                patchKind: normalizeKind(fm.patch_kind),
+                status,
+                createdAt,
+                createdBy: String(fm.created_by ?? ''),
+                lastModified: lastVersion?.createdAt ?? createdAt,
+                threadCount: this.deps.chatService.threadCountForPatch(rec.path),
+            });
+        }
+        return out;
+    }
+    listThreadsForPatch(relPath) {
+        return this.deps.chatService.listThreadsForPatch(relPath).map((t) => ({
+            id: t.id,
+            title: t.title,
+            updatedAt: t.updatedAt,
+            messageCount: t.messageCount,
+        }));
+    }
+    // ─── Mutations ──────────────────────────────────────────────────────────
+    async updateContent(opts) {
+        const current = await this.getPatch(opts.path);
+        if (typeof opts.expectedHash === 'string' && opts.expectedHash !== current.hash) {
+            throw new ConflictError('PATCH_CONFLICT', 'patch changed since last read', current.hash);
+        }
+        const incoming = matter(opts.content);
+        const incomingFm = (incoming.data ?? {});
+        const violated = PATCH_IMMUTABLE_FRONTMATTER_KEYS.filter((k) => JSON.stringify(incomingFm[k]) !== JSON.stringify(current.frontmatter[k]));
+        if (violated.length > 0) {
+            throw new DomainError('PATCH_FRONTMATTER_IMMUTABLE', `cannot mutate immutable frontmatter keys: ${violated.join(', ')}`);
+        }
+        const abs = this.absPath(opts.path);
+        this.deps.patchesWatcher.suppress(opts.path);
+        await fs.writeFile(abs, opts.content, 'utf-8');
+        await this.deps.pageVersions.recordVersion(opts.path, 'update', 'user', undefined, this.deps.patchesSerializer, 'patch');
+        await this.deps.frontmatterIndexer.indexPage('patches', opts.path);
+        return this.getPatch(opts.path);
+    }
+    async updateFrontmatter(opts) {
+        const current = await this.getPatch(opts.path);
+        const next = { ...current.frontmatter, status: opts.status };
+        const newContent = matter.stringify(current.body, next);
+        const abs = this.absPath(opts.path);
+        this.deps.patchesWatcher.suppress(opts.path);
+        await fs.writeFile(abs, newContent, 'utf-8');
+        await this.deps.pageVersions.recordVersion(opts.path, 'update', 'user', undefined, this.deps.patchesSerializer, 'patch', `set status=${opts.status}`);
+        await this.deps.frontmatterIndexer.indexPage('patches', opts.path);
+        return this.getPatch(opts.path);
+    }
+    async createThreadForPatch(relPath, name) {
+        if (!(await this.deps.patchesPages.exists(relPath))) {
+            throw new DomainError('NOT_FOUND', `patch '${relPath}' not found`);
+        }
+        const thread = this.deps.chatService.createThread(name ?? `Patch: ${relPath}`, {
+            contextType: 'patch',
+            patchPath: relPath,
+        });
+        return { threadId: thread.id };
+    }
+    // ─── Internals ──────────────────────────────────────────────────────────
+    absPath(relPath) {
+        return path.join(this.deps.patchesPages.root, relPath);
+    }
+    knownBriefPaths() {
+        return this.deps.frontmatterIndexer
+            .findByFrontmatterType('brief', { rootDir: 'briefs' })
+            .map((r) => r.path);
+    }
+    /**
+     * Resolve the brief a patch belongs to: the `brief` frontmatter field if it
+     * names an existing brief, else the brief whose filename stem is the longest
+     * prefix of the patch filename stem, else `null` (orphan).
+     */
+    resolveBriefPath(patchPath, fm, briefPaths) {
+        if (typeof fm.brief === 'string' && fm.brief.length > 0) {
+            const declared = fm.brief;
+            if (briefPaths.includes(declared))
+                return declared;
+        }
+        const patchStem = stem(patchPath);
+        let best = null;
+        for (const bp of briefPaths) {
+            const briefStem = stem(bp);
+            if (patchStem === briefStem || patchStem.startsWith(briefStem + '-')) {
+                if (best === null || stem(bp).length > stem(best).length)
+                    best = bp;
+            }
+        }
+        return best;
+    }
+}
+/**
+ * YAML auto-parses ISO timestamps into JS `Date` objects — normalize back to
+ * an ISO 8601 string for DTO fields (`PatchListItem.createdAt`).
+ */
+function toIso(v) {
+    if (v instanceof Date)
+        return v.toISOString();
+    return v == null ? '' : String(v);
+}
+function stem(p) {
+    return path.basename(p).replace(/\.md$/i, '');
+}
+function normalizeKind(raw) {
+    return VALID_PATCH_KINDS.has(String(raw)) ? raw : 'clarification';
+}
+function extractTitle(body, fm, relPath) {
+    const h1 = body.match(/^#\s+(.+)$/m);
+    if (h1 && h1[1])
+        return h1[1].trim();
+    return extractTitleFromFrontmatter(fm, relPath);
+}
+function extractTitleFromFrontmatter(fm, relPath) {
+    if (typeof fm.title === 'string' && fm.title.length > 0)
+        return fm.title;
+    return stem(relPath);
+}
+function hashContent(content) {
+    return crypto.createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+//# sourceMappingURL=patch.js.map

package/dist/server/services/patch.js.map

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

package/dist/shared/entities.d.ts

@@ -446,8 +446,11 @@ export type ChatRole = 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'user
  * M21 generic context discriminator. 'chat' = default (full toolset, overlay UI).
  * 'brief' = brief editorial thread (whitelisted tools, brief-detail chrome,
  * brief_path points to FS file under briefsDir).
+ * M23 'patch' = patch resolution thread — applies a patch's findings to the
+ * spec. Full spec-editing toolset; patch_path points to FS file under
+ * patchesDir; the patch content is injected into the system prompt.
  */
-export type ChatContextType = 'chat' | 'brief';
+export type ChatContextType = 'chat' | 'brief' | 'patch';
 export interface ChatThread {
     id: string;
     title: string | null;
@@ -461,6 +464,8 @@ export interface ChatThread {
     hasSystemPrompt: boolean;
     contextType: ChatContextType;
     briefPath: string | null;
+    /** M23: FS path (relative to patchesDir) — set iff contextType='patch'. */
+    patchPath: string | null;
     createdAt: string;
     updatedAt: string;
 }
@@ -587,7 +592,6 @@ export interface BriefListItem {
     implemented: boolean;
     generatedAt: string;
     lastModifiedAt: string | null;
-    threadCount: number;
 }
 export interface BriefCreateRequest {
     /** `null` = initial brief (no previous release to compare against). */
@@ -620,3 +624,59 @@ export interface BriefThreadSummary {
     updatedAt: string;
     messageCount: number;
 }
+/** Why a coding agent filed the patch (frontmatter `patch_kind`). */
+export type PatchKind = 'drift' | 'missing' | 'incorrect' | 'clarification';
+/** Resolution state — `awaiting` until the spec author resolves the patch. */
+export type PatchStatus = 'awaiting' | 'completed';
+/**
+ * Reserved frontmatter keys — set by the terminal agent that authored the
+ * patch, immutable from the claude4spec side. Only `status` is mutable.
+ */
+export declare const PATCH_IMMUTABLE_FRONTMATTER_KEYS: readonly ["type", "brief", "patch_kind", "created_at", "created_by"];
+export interface PatchFrontmatter {
+    type: 'patch';
+    /** Path of the associated brief (relative to briefsDir). Absent ⇒ resolve by filename prefix. */
+    brief?: string;
+    patch_kind: PatchKind;
+    created_at: string;
+    created_by: string;
+    /** Absent is treated as `'awaiting'`. */
+    status?: PatchStatus;
+    [key: string]: unknown;
+}
+/** Response of `GET /api/patches/:path` and the result of PUT/PATCH writes. */
+export interface PatchResponse {
+    /** Path relative to patchesDir. */
+    path: string;
+    title: string;
+    frontmatter: PatchFrontmatter;
+    body: string;
+    /** Full file content (frontmatter + body, byte-faithful). */
+    content: string;
+    /** sha256 hex of `content` — used for optimistic concurrency. */
+    hash: string;
+}
+export interface PatchListItem {
+    path: string;
+    title: string;
+    /** `null` = orphan (no resolvable brief). */
+    briefPath: string | null;
+    patchKind: PatchKind;
+    status: PatchStatus;
+    createdAt: string;
+    createdBy: string;
+    /** `created_at` of the latest page_version row with kind='patch'. */
+    lastModified: string;
+    /** Count of chat threads with context_type='patch' pointing at this patch. */
+    threadCount: number;
+}
+export interface PatchContentUpdateRequest {
+    content: string;
+    expectedHash: string;
+}
+export interface PatchFrontmatterUpdateRequest {
+    status: PatchStatus;
+}
+export interface PatchThreadCreateRequest {
+    name?: string;
+}

package/dist/shared/entities.js

@@ -6,4 +6,15 @@ export const BRIEF_IMMUTABLE_FRONTMATTER_KEYS = [
     'generated_at',
     'generator_version',
 ];
+/**
+ * Reserved frontmatter keys — set by the terminal agent that authored the
+ * patch, immutable from the claude4spec side. Only `status` is mutable.
+ */
+export const PATCH_IMMUTABLE_FRONTMATTER_KEYS = [
+    'type',
+    'brief',
+    'patch_kind',
+    'created_at',
+    'created_by',
+];
 //# sourceMappingURL=entities.js.map

package/dist/shared/entities.js.map

@@ -1 +1 @@
-{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../src/shared/entities.ts"],"names":[],"mappings":"AA6oBA,sEAAsE;AACtE,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM;IACN,cAAc;IACd,YAAY;IACZ,cAAc;IACd,mBAAmB;CACX,CAAC"}
+{"version":3,"file":"entities.js","sourceRoot":"","sources":["../../src/shared/entities.ts"],"names":[],"mappings":"AAkpBA,sEAAsE;AACtE,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM;IACN,cAAc;IACd,YAAY;IACZ,cAAc;IACd,mBAAmB;CACX,CAAC;AAiFX;;;GAGG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG;IAC9C,MAAM;IACN,OAAO;IACP,YAAY;IACZ,YAAY;IACZ,YAAY;CACJ,CAAC"}

package/dist/shared/types.d.ts

@@ -67,12 +67,15 @@ export type WsEvent = {
 } | {
     kind: 'briefs:changed';
     path?: string;
+} | {
+    kind: 'patches:changed';
+    path?: string;
 } | {
     kind: 'hello';
     ts: number;
 };
-/** M02 multidir: discriminator dla source-of-truth (pagesDir vs briefsDir). */
-export type PagesRootDir = 'pages' | 'briefs';
+/** M02 multidir: discriminator dla source-of-truth (pagesDir / briefsDir / patchesDir). */
+export type PagesRootDir = 'pages' | 'briefs' | 'patches';
 export interface TodoHit {
     pagePath: string;
     line: number;

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@inharness-ai/claude4spec",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "Plan the whole system before your agent writes a line of code. Local-first planning layer with structured entities and typed relations.",
   "license": "MIT",
   "author": "Michael Tomala <mi.tomala@gmail.com>",
-  "homepage": "https://github.com/InHarness/claude4spec#readme",
+  "homepage": "https://claude4spec.inharness.ai",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/InHarness/claude4spec.git"
@@ -27,6 +27,7 @@
     "dist",
     ".claude/skills/c4s-spec-reader",
     ".claude/skills/c4s-brief-implementer",
+    "docs/screenshots",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"

package/dist/client/assets/channel-ArVcv4Yl.js

@@ -1 +0,0 @@
-import{ai as o,aj as n}from"./mermaid.core-C45sMDhS.js";const t=(a,r)=>o.lang.round(n.parse(a)[r]);export{t as c};

package/dist/client/assets/classDiagram-4FO5ZUOK-B3nmPR7w.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-BtRfbjBO.js";import{_ as i}from"./mermaid.core-C45sMDhS.js";import"./chunk-FMBD7UC4-B_VD4t8N.js";import"./chunk-ND2GUHAM-BvJdtX82.js";import"./chunk-55IACEB6-SgOSJYkL.js";import"./chunk-2J33WTMH-vDJ1slcJ.js";import"./index-D5ljIkCJ.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/classDiagram-v2-Q7XG4LA2-B3nmPR7w.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-727SXJPM-BtRfbjBO.js";import{_ as i}from"./mermaid.core-C45sMDhS.js";import"./chunk-FMBD7UC4-B_VD4t8N.js";import"./chunk-ND2GUHAM-BvJdtX82.js";import"./chunk-55IACEB6-SgOSJYkL.js";import"./chunk-2J33WTMH-vDJ1slcJ.js";import"./index-D5ljIkCJ.js";var n={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{n as diagram};

package/dist/client/assets/stateDiagram-v2-BHNVJYJU-CS6ocDH6.js

@@ -1 +0,0 @@
-import{s as e,b as r,a,S as s}from"./chunk-AQP2D5EJ-yIRaTgFg.js";import{_ as i}from"./mermaid.core-C45sMDhS.js";import"./chunk-55IACEB6-SgOSJYkL.js";import"./chunk-2J33WTMH-vDJ1slcJ.js";import"./index-D5ljIkCJ.js";var p={parser:a,get db(){return new s(2)},renderer:r,styles:e,init:i(t=>{t.state||(t.state={}),t.state.arrowMarkerAbsolute=t.arrowMarkerAbsolute},"init")};export{p as diagram};