@inharness-ai/claude4spec 1.0.0

package/dist/server/services/ui-view.js

@@ -0,0 +1,235 @@
+import { uiViewSlug } from './slug.js';
+import { DomainError } from './tags.js';
+const VALID_LOCATIONS = ['path', 'query', 'hash'];
+export class UiViewService {
+    db;
+    tags;
+    versions;
+    constructor(db, tags, versions) {
+        this.db = db;
+        this.tags = tags;
+        this.versions = versions;
+    }
+    create(input, actor) {
+        if (!input.name)
+            throw new DomainError('VALIDATION', 'name is required');
+        const slug = input.slug?.trim() || uiViewSlug(input.name);
+        if (!slug)
+            throw new DomainError('VALIDATION', 'slug resolves to empty');
+        const params = input.params ?? [];
+        const url = normaliseUrl(input.url);
+        const tx = this.db.transaction(() => {
+            const conflict = this.db.prepare(`SELECT 1 FROM ui_view WHERE slug = ?`).get(slug);
+            if (conflict)
+                throw new DomainError('SLUG_CONFLICT', `ui view slug '${slug}' already exists`);
+            const info = this.db
+                .prepare(`INSERT INTO ui_view (slug, name, url, description, params)
+           VALUES (?, ?, ?, ?, ?)`)
+                .run(slug, input.name, url, input.description ?? null, JSON.stringify(params));
+            const id = Number(info.lastInsertRowid);
+            if (input.tags?.length)
+                this.tags.assignTags('ui-view', id, input.tags);
+            const created = this.getByIdInternal(id);
+            this.versions.createVersion('ui-view', id, created, actor, 'Created');
+            const warnings = computeWarnings(url, params);
+            return { uiView: created, warnings };
+        });
+        return tx();
+    }
+    list(query = {}) {
+        const where = [];
+        const params = [];
+        if (query.search) {
+            where.push(`(name LIKE ? OR description LIKE ? OR slug LIKE ? OR url LIKE ?)`);
+            const like = `%${query.search}%`;
+            params.push(like, like, like, like);
+        }
+        const tagSlugs = query.tags?.filter(Boolean) ?? [];
+        if (tagSlugs.length) {
+            const placeholders = tagSlugs.map(() => '?').join(',');
+            if (query.tagFilter === 'or') {
+                where.push(`
+          id IN (
+            SELECT et.entity_id FROM entity_tag et
+              JOIN tag t ON t.id = et.tag_id
+             WHERE et.entity_type = 'ui-view' AND t.slug IN (${placeholders})
+          )
+        `);
+                params.push(...tagSlugs);
+            }
+            else {
+                where.push(`
+          id IN (
+            SELECT et.entity_id
+              FROM entity_tag et
+              JOIN tag t ON t.id = et.tag_id
+             WHERE et.entity_type = 'ui-view' AND t.slug IN (${placeholders})
+          GROUP BY et.entity_id
+            HAVING COUNT(DISTINCT t.slug) = ?
+          )
+        `);
+                params.push(...tagSlugs, tagSlugs.length);
+            }
+        }
+        const whereSql = where.length ? `WHERE ${where.join(' AND ')}` : '';
+        const limit = Math.min(Math.max(query.limit ?? 200, 1), 500);
+        const offset = Math.max(query.offset ?? 0, 0);
+        const rows = this.db
+            .prepare(`SELECT * FROM ui_view ${whereSql}
+         ORDER BY name
+         LIMIT ? OFFSET ?`)
+            .all(...params, limit, offset);
+        return rows.map((r) => this.hydrate(r));
+    }
+    getBySlug(slug) {
+        const row = this.db.prepare(`SELECT * FROM ui_view WHERE slug = ?`).get(slug);
+        return row ? this.hydrate(row) : null;
+    }
+    getIdBySlug(slug) {
+        const row = this.db.prepare(`SELECT id FROM ui_view WHERE slug = ?`).get(slug);
+        return row?.id ?? null;
+    }
+    update(slug, input, actor) {
+        const tx = this.db.transaction(() => {
+            const current = this.db.prepare(`SELECT * FROM ui_view WHERE slug = ?`).get(slug);
+            if (!current)
+                throw new DomainError('NOT_FOUND', `ui view '${slug}' not found`);
+            const nextName = input.name ?? current.name;
+            const autoSlug = uiViewSlug(nextName);
+            const nextSlug = input.newSlug?.trim() || autoSlug;
+            if (nextSlug !== slug) {
+                const conflict = this.db.prepare(`SELECT 1 FROM ui_view WHERE slug = ?`).get(nextSlug);
+                if (conflict)
+                    throw new DomainError('SLUG_CONFLICT', `ui view slug '${nextSlug}' already exists`);
+            }
+            const nextParams = input.params !== undefined ? JSON.stringify(input.params) : current.params;
+            const nextUrl = input.url !== undefined ? normaliseUrl(input.url) : current.url;
+            this.db
+                .prepare(`UPDATE ui_view
+             SET slug = ?, name = ?, url = ?, description = ?, params = ?,
+                 updated_at = datetime('now')
+           WHERE id = ?`)
+                .run(nextSlug, nextName, nextUrl, input.description !== undefined ? input.description : current.description, nextParams, current.id);
+            if (input.tags)
+                this.tags.assignTags('ui-view', current.id, input.tags);
+            const updated = this.getByIdInternal(current.id);
+            const summary = nextSlug !== slug ? `Renamed from '${slug}' to '${nextSlug}'` : 'Updated';
+            this.versions.createVersion('ui-view', current.id, updated, actor, summary);
+            const warnings = computeWarnings(updated.url, updated.params);
+            return { uiView: updated, previousSlug: slug, warnings };
+        });
+        return tx();
+    }
+    remove(slug, actor, brokenReferences = []) {
+        const tx = this.db.transaction(() => {
+            const row = this.db.prepare(`SELECT * FROM ui_view WHERE slug = ?`).get(slug);
+            if (!row)
+                throw new DomainError('NOT_FOUND', `ui view '${slug}' not found`);
+            this.versions.createVersion('ui-view', row.id, null, actor, 'Deleted');
+            this.db
+                .prepare(`DELETE FROM entity_tag WHERE entity_type = 'ui-view' AND entity_id = ?`)
+                .run(row.id);
+            this.db.prepare(`DELETE FROM ui_view WHERE id = ?`).run(row.id);
+            return { deleted: true, brokenReferences };
+        });
+        return tx();
+    }
+    getByIdInternal(id) {
+        const row = this.db.prepare(`SELECT * FROM ui_view WHERE id = ?`).get(id);
+        if (!row)
+            throw new Error(`ui_view id ${id} disappeared mid-tx`);
+        return this.hydrate(row);
+    }
+    hydrate(row) {
+        return {
+            slug: row.slug,
+            name: row.name,
+            url: row.url,
+            description: row.description,
+            params: parseParams(row.params),
+            tags: this.tags.getEntityTagSlugs('ui-view', row.id),
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+        };
+    }
+}
+function normaliseUrl(value) {
+    if (value === undefined || value === null)
+        return null;
+    const trimmed = value.trim();
+    return trimmed === '' ? null : trimmed;
+}
+function parseParams(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed
+            .filter((p) => p && typeof p === 'object' && typeof p.name === 'string')
+            .map((p) => {
+            const inValue = String(p.in ?? '');
+            const location = VALID_LOCATIONS.includes(inValue)
+                ? inValue
+                : 'query';
+            const out = {
+                name: String(p.name),
+                in: location,
+            };
+            if (typeof p.type === 'string')
+                out.type = p.type;
+            if (typeof p.required === 'boolean')
+                out.required = p.required;
+            if (typeof p.default === 'string')
+                out.default = p.default;
+            if (typeof p.description === 'string')
+                out.description = p.description;
+            return out;
+        });
+    }
+    catch {
+        return [];
+    }
+}
+const PATH_PARAM_RE = /:([a-zA-Z_][a-zA-Z0-9_]*)/g;
+export function computeWarnings(url, params) {
+    const warnings = [];
+    for (let i = 0; i < params.length; i++) {
+        const p = params[i];
+        if (!p.name) {
+            warnings.push(`params[${i}]: missing 'name'`);
+        }
+        if (!VALID_LOCATIONS.includes(p.in)) {
+            warnings.push(`params[${i}] '${p.name ?? '?'}': invalid 'in' value '${p.in}' (expected path|query|hash)`);
+        }
+    }
+    const seen = new Set();
+    for (const p of params) {
+        const key = `${p.in}::${p.name}`;
+        if (seen.has(key)) {
+            warnings.push(`Duplicate param (name='${p.name}', in='${p.in}')`);
+        }
+        seen.add(key);
+    }
+    const urlPathParams = new Set();
+    if (url) {
+        const matches = url.matchAll(PATH_PARAM_RE);
+        for (const m of matches)
+            urlPathParams.add(m[1]);
+    }
+    const declaredPathParams = new Set(params.filter((p) => p.in === 'path' && p.name).map((p) => p.name));
+    for (const name of urlPathParams) {
+        if (!declaredPathParams.has(name)) {
+            warnings.push(`path param ":${name}" in URL not declared in params[]`);
+        }
+    }
+    for (const name of declaredPathParams) {
+        if (url && !urlPathParams.has(name)) {
+            warnings.push(`path param '${name}' declared but not present in URL`);
+        }
+    }
+    if (url === null && declaredPathParams.size > 0) {
+        warnings.push(`path params declared but URL is null (modal/drawer should not have path params)`);
+    }
+    return warnings;
+}
+//# sourceMappingURL=ui-view.js.map

package/dist/server/services/ui-view.js.map

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

package/dist/server/services/versions.d.ts

@@ -0,0 +1,59 @@
+import type Database from 'better-sqlite3';
+import type { ChangedBy, EntityType, VersionDetail, VersionListItem } from '../../shared/entities.js';
+import type { PluginHost } from '../core/plugin-host/types.js';
+import type { RawEntityReader, RawEntityType } from '../domain/raw-entity-reader.js';
+export type VersionOp = 'create' | 'update' | 'delete';
+export interface CreateVersionInput {
+    entityType: EntityType;
+    entityId: number;
+    data: unknown;
+    changedBy: ChangedBy;
+    changeSummary?: string | null;
+    /** M17: which kind of mutation. Required for new code; legacy callers omit. */
+    op?: VersionOp;
+    /** M17: serializer.version at time of capture. Null for legacy rows. */
+    serializerVersion?: string | null;
+}
+export declare class VersionService {
+    private db;
+    private snapshotDeps;
+    constructor(db: Database.Database);
+    /** M17: wire snapshot dependencies. Called once during server bootstrap. */
+    configureSnapshot(reader: RawEntityReader, host: PluginHost): void;
+    /**
+     * M17: capture a deterministic snapshot of an entity into entity_version.
+     * Falls back to `createVersion(..., entity, ...)` if snapshot deps not wired
+     * yet (very early in bootstrap or for tests). For `op = 'delete'`, calls
+     * host.snapshot BEFORE the caller deletes the row — pass `previousSnapshot`
+     * explicitly to capture a tombstone with last-known data.
+     */
+    captureEntitySnapshot(type: RawEntityType, entityId: number, op: VersionOp, actor: ChangedBy, summary: string | null, serializerVersion: string): VersionListItem;
+    /**
+     * Capture a new version. M17 augments the row with `op` and
+     * `serializer_version`; `release_id` always starts NULL and is assigned by
+     * `releaseService.createRelease()`.
+     */
+    createVersion(entityType: EntityType, entityId: number, data: unknown, changedBy: ChangedBy, changeSummary?: string | null, op?: VersionOp, serializerVersion?: string | null): VersionListItem;
+    listVersions(entityType: EntityType, entityId: number): VersionListItem[];
+    getVersion(entityType: EntityType, entityId: number, version: number): VersionDetail | null;
+    /**
+     * M17: latest captured version of an entity at-or-before a given release.
+     * `releaseId === null` returns the latest unreleased capture (release_id IS NULL).
+     * `releaseId === undefined` returns the latest overall (no release filter).
+     */
+    getLatestVersionForEntity(entityType: EntityType, entityId: number, releaseId?: number | null): VersionDetail | null;
+    diff(entityType: EntityType, entityId: number, fromVersion: number, toVersion: number): {
+        from: VersionDetail;
+        to: VersionDetail;
+        changes: DiffEntry[];
+    };
+    private nextVersionNumber;
+    private toListItem;
+    private toDetail;
+}
+export interface DiffEntry {
+    path: string;
+    from: unknown;
+    to: unknown;
+}
+export declare function computeDiff(from: unknown, to: unknown, prefix?: string): DiffEntry[];

package/dist/server/services/versions.js

@@ -0,0 +1,181 @@
+import { DomainError } from './tags.js';
+export class VersionService {
+    db;
+    // M17: lazily wired by index.ts after pluginHost.consolidate. When present,
+    // entity services prefer captureSnapshot(...) over createVersion(...) so
+    // entity_version.data carries the full snapshot (decyzja 4 — portable identity).
+    snapshotDeps = null;
+    constructor(db) {
+        this.db = db;
+    }
+    /** M17: wire snapshot dependencies. Called once during server bootstrap. */
+    configureSnapshot(reader, host) {
+        this.snapshotDeps = { reader, host };
+    }
+    /**
+     * M17: capture a deterministic snapshot of an entity into entity_version.
+     * Falls back to `createVersion(..., entity, ...)` if snapshot deps not wired
+     * yet (very early in bootstrap or for tests). For `op = 'delete'`, calls
+     * host.snapshot BEFORE the caller deletes the row — pass `previousSnapshot`
+     * explicitly to capture a tombstone with last-known data.
+     */
+    captureEntitySnapshot(type, entityId, op, actor, summary, serializerVersion) {
+        if (!this.snapshotDeps) {
+            // Fallback: deps not yet wired. Store legacy domain object via createVersion.
+            return this.createVersion(type, entityId, null, actor, summary, op, serializerVersion);
+        }
+        // For all ops (including delete), snapshot the entity *as it currently is*
+        // (callers must call this BEFORE the row is deleted from its table).
+        const rawEntity = this.snapshotDeps.reader.getEntityById(type, entityId);
+        if (!rawEntity) {
+            // Entity not found — fall back to last-known snapshot so tombstone has
+            // restorable data. This path is only hit if a caller calls capture
+            // post-delete (anti-pattern but defensive).
+            const last = this.getLatestVersionForEntity(type, entityId);
+            return this.createVersion(type, entityId, last?.data ?? null, actor, summary, op, serializerVersion);
+        }
+        const ctx = { reader: this.snapshotDeps.reader, depth: 0, maxDepth: 1 };
+        const snapshot = this.snapshotDeps.host.snapshot(type, rawEntity, ctx);
+        return this.createVersion(type, entityId, snapshot, actor, summary, op, serializerVersion);
+    }
+    /**
+     * Capture a new version. M17 augments the row with `op` and
+     * `serializer_version`; `release_id` always starts NULL and is assigned by
+     * `releaseService.createRelease()`.
+     */
+    createVersion(entityType, entityId, data, changedBy, changeSummary, op, serializerVersion) {
+        const next = this.nextVersionNumber(entityType, entityId);
+        const inferredOp = op ?? (data === null ? 'delete' : (next === 1 ? 'create' : 'update'));
+        const info = this.db
+            .prepare(`INSERT INTO entity_version
+           (entity_type, entity_id, version, data, changed_by, change_summary, op, serializer_version)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(entityType, entityId, next, JSON.stringify(data), changedBy, changeSummary ?? null, inferredOp, serializerVersion ?? null);
+        const row = this.db
+            .prepare(`SELECT * FROM entity_version WHERE id = ?`)
+            .get(info.lastInsertRowid);
+        return this.toListItem(row);
+    }
+    listVersions(entityType, entityId) {
+        const rows = this.db
+            .prepare(`SELECT id, version, changed_by, change_summary, created_at, release_id, op
+           FROM entity_version
+          WHERE entity_type = ? AND entity_id = ?
+          ORDER BY version DESC`)
+            .all(entityType, entityId);
+        return rows.map((r) => ({
+            id: r.id,
+            version: r.version,
+            changedBy: r.changed_by,
+            changeSummary: r.change_summary,
+            createdAt: r.created_at,
+            ...(r.release_id !== null ? { releaseId: r.release_id } : {}),
+            ...(r.op ? { op: r.op } : {}),
+        }));
+    }
+    getVersion(entityType, entityId, version) {
+        const row = this.db
+            .prepare(`SELECT * FROM entity_version
+          WHERE entity_type = ? AND entity_id = ? AND version = ?`)
+            .get(entityType, entityId, version);
+        if (!row)
+            return null;
+        return this.toDetail(row);
+    }
+    /**
+     * M17: latest captured version of an entity at-or-before a given release.
+     * `releaseId === null` returns the latest unreleased capture (release_id IS NULL).
+     * `releaseId === undefined` returns the latest overall (no release filter).
+     */
+    getLatestVersionForEntity(entityType, entityId, releaseId) {
+        let row;
+        if (releaseId === undefined) {
+            row = this.db
+                .prepare(`SELECT * FROM entity_version
+            WHERE entity_type = ? AND entity_id = ?
+            ORDER BY version DESC LIMIT 1`)
+                .get(entityType, entityId);
+        }
+        else if (releaseId === null) {
+            row = this.db
+                .prepare(`SELECT * FROM entity_version
+            WHERE entity_type = ? AND entity_id = ? AND release_id IS NULL
+            ORDER BY version DESC LIMIT 1`)
+                .get(entityType, entityId);
+        }
+        else {
+            row = this.db
+                .prepare(`SELECT * FROM entity_version
+            WHERE entity_type = ? AND entity_id = ? AND release_id IS NOT NULL AND release_id <= ?
+            ORDER BY version DESC LIMIT 1`)
+                .get(entityType, entityId, releaseId);
+        }
+        return row ? this.toDetail(row) : null;
+    }
+    diff(entityType, entityId, fromVersion, toVersion) {
+        const from = this.getVersion(entityType, entityId, fromVersion);
+        const to = this.getVersion(entityType, entityId, toVersion);
+        if (!from || !to)
+            throw new DomainError('NOT_FOUND', 'version not found');
+        return { from, to, changes: computeDiff(from.data, to.data) };
+    }
+    nextVersionNumber(entityType, entityId) {
+        const row = this.db
+            .prepare(`SELECT MAX(version) AS v FROM entity_version WHERE entity_type = ? AND entity_id = ?`)
+            .get(entityType, entityId);
+        return (row.v ?? 0) + 1;
+    }
+    toListItem(row) {
+        return {
+            id: row.id,
+            version: row.version,
+            changedBy: row.changed_by,
+            changeSummary: row.change_summary,
+            createdAt: row.created_at,
+            ...(row.release_id !== null ? { releaseId: row.release_id } : {}),
+            ...(row.op ? { op: row.op } : {}),
+        };
+    }
+    toDetail(row) {
+        return {
+            id: row.id,
+            entityType: row.entity_type,
+            entityId: row.entity_id,
+            version: row.version,
+            data: safeParse(row.data),
+            changedBy: row.changed_by,
+            changeSummary: row.change_summary,
+            createdAt: row.created_at,
+            ...(row.release_id !== null ? { releaseId: row.release_id } : {}),
+            ...(row.op ? { op: row.op } : {}),
+        };
+    }
+}
+function safeParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+export function computeDiff(from, to, prefix = '') {
+    if (deepEqual(from, to))
+        return [];
+    if (!isObj(from) || !isObj(to))
+        return [{ path: prefix || '/', from, to }];
+    const keys = new Set([...Object.keys(from), ...Object.keys(to)]);
+    const changes = [];
+    for (const key of keys) {
+        const sub = prefix ? `${prefix}.${key}` : key;
+        changes.push(...computeDiff(from[key], to[key], sub));
+    }
+    return changes;
+}
+function isObj(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+function deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+//# sourceMappingURL=versions.js.map

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

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

package/dist/server/skills/brief-author/SKILL.md

@@ -0,0 +1,117 @@
+---
+title: Brief Author
+description: "Generates and edits release briefs — self-contained narrative artifacts that summarise what changed between two releases (M17). TRIGGER automatically loaded for chat threads with context_type='brief'. The agent has access to ONLY brief-tools (4) and release-tools (read-only) — no filesystem access. Defines the brief genre (audience, format, tooling, branches, error handling); the active writing-style skill supplies methodology-specific guidance via its `workflows/brief.md`."
+version: 2
+language: en
+scope: contextual
+---
+
+# Brief Author
+
+You are the **Brief Author**, a specialised editorial agent collaborating with a human user on a single brief artifact. A brief is a **self-contained markdown narrative** that summarises what changed between two releases of a specification.
+
+The system prompt already binds you to the **self-contained invariant**: the brief is consumed both inside claude4spec (rendered Tiptap, clickable references) AND in some other terminal where the reader has only the raw file bytes — no database, no MCP, no claude4spec UI, no CLI. The second audience is load-bearing — it is what justifies storing the brief on disk instead of in a DB. Everything below is the brief *genre*: rules that hold regardless of which writing style the underlying spec uses.
+
+> **Methodology-specific guidance — read second.** This skill defines the genre. **How to interpret an `MCPReleaseDiff` for the active writing style** — what counts as feature substance vs. spec-format convention, how to inline its entity types, what to put in "For implementers" — lives in the active writing-style skill at `workflows/brief.md`. The system prompt names which writing style is active. After loading this skill, load that one and read its `workflows/brief.md` before composing the brief.
+
+---
+
+## What you can and cannot do
+
+**Available tools:**
+- `get_brief` — read the current brief state. Returns `{ frontmatter, body, content, hash }`. Use `hash` as `expectedHash` for the next `update_brief` to detect concurrent edits.
+- `update_brief` — edit the body via `replace`, `append`, or `insert_after_section`. You CANNOT modify frontmatter (immutable: `type`, `from_release`, `to_release`, `generated_at`, `generator_version`).
+- `list_brief_versions` / `get_brief_version` — inspect history, diff against earlier versions.
+- `release-tools` (read-only) — `release_list`, `release_show`, and `release_diff(fromIdOrName, toIdOrName, include?, entityTypes?)` returning a self-contained `MCPReleaseDiff`. Use `release_diff(brief.frontmatter.from_release, brief.frontmatter.to_release)` to obtain the `MCPReleaseDiff` that grounds your narrative — one round-trip is all you need.
+
+**`release-tools` is the ONLY plugin MCP available in this thread.** There is no `get_endpoint` / `get_dto` / `get_database-table` / `get_ui-view` / `get_ac`, no `Read pages/...`, no `Grep`, no filesystem. The `MCPReleaseDiff` payload is your entire ground truth — every snapshot you need is carried inside it.
+
+**You cannot:**
+- Read or write any file on disk (no `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`).
+- Mutate any entity, page, plan, or release. Briefs are write-side only.
+- Modify brief frontmatter (immutable to agents — only the user can toggle `archived` via the UI Settings popover).
+- Drill down into entities or pages on demand. The diff is self-contained by design (see "Self-containment" below).
+
+---
+
+## Two operating branches
+
+### Branch A — Initial generation (body is empty)
+
+Triggered when `get_brief` returns a brief whose body contains only the H1 heading (or is otherwise empty).
+
+**Initial brief detection:** if `frontmatter.from_release === null`, this is an *initial brief* — there is no previous release. Skip the two-release diff; instead call `release-tools.release_diff({ fromIdOrName: null, toIdOrName: <to_release> })` to obtain an `MCPReleaseDiff` where every entry is `op: 'create'` with `before` omitted (synthetic empty `from` snapshot). Frame the narrative as *"the project starts here — this is the initial state of `<to_release>`"*, not as a delta. The H1 should be `# Initial brief: <to_release>` (already pre-filled by the system).
+
+1. Call `get_brief` to confirm `frontmatter.from_release` and `frontmatter.to_release` and capture `hash`.
+2. Call `release-tools.release_diff({ fromIdOrName, toIdOrName })` to obtain the `MCPReleaseDiff`. This is your single source of truth — full `before`/`after` snapshots per entity and full `before`/`after` raw markdown per modified section travel in the payload. Default filters (`include: ['pages','entities']`, all entity types) cover everything; pass narrower filters only if you have a clear context-budget reason.
+3. **Filter the diff using the active writing style's `workflows/brief.md`.** It defines what counts as feature substance (keep, translate, inline) vs. spec-format convention (drop) vs. editorial noise (drop) for this methodology.
+4. **Mine the kept entries** for inlinable content — entity shapes, code/SQL fragments, file paths — per the writing style's inlining patterns.
+5. **For each entity with `op: 'update'`**: compare `MCPEntityDelta.before` vs `MCPEntityDelta.after` directly — both are full snapshots produced by the plugin's serializer. Describe the diff in prose. **Do NOT call any drill-down tool — there is none available in this thread.** Slugs, field shapes, every value you need is in the snapshot.
+6. **For each entity with `op: 'create'`**: read `MCPEntityDelta.after` for any inline content needed in prose. You MAY insert `<inline_mention type="<type>" slug="<slug>"/>` in the narrative for the claude4spec UI audience — it renders as a live entity view. The second-audience terminal sees the literal tag; treat such mentions as supplements, never as substitutes for inlined content.
+7. **For each entity with `op: 'delete'`**: only `before` is present. Frame the deletion in prose; the second-audience reader needs to know what disappeared, not what replaced it (often nothing).
+8. **For each `MCPPageDelta.sections[i]`**: use `before` / `after` raw markdown directly. NEVER consume `line_diff` — there is none in this payload. For `op: 'move'`, both fields are absent (content unchanged, only position shifted) — usually drop from the brief unless ordering itself is the user-visible change.
+9. **`MCPPageDelta.frontmatter` / `MCPPageDelta.xmlRefs`**: present iff changed. Read `before`/`after` only when relevant to narrative (e.g. `pageType: module → layer`). Default: ignore — metadata, not content.
+10. Compose a narrative that:
+    - Opens with a short summary (2–4 sentences) describing the *intent* of the release. The reader should learn *why* in the first paragraph.
+    - Groups changes by user-visible theme (new capabilities, breaking changes, internal refactors), not by entity type or by spec page.
+    - For each theme: state what the system now does in plain prose and **inline the change content** per the writing style's patterns.
+    - Closes with a **For implementers** section — concrete edit targets per the writing style's structure.
+11. **Język/styl/audytorium** wynika z pierwszej user-message w threadzie — klient dokleja `additionalPrompt` z modala „Generate brief from this release" (np. *„po polsku, dla juniora, ton formalny"*). Jeśli pierwsza wiadomość zawiera takie wytyczne, uszanuj je. Domyślnie pisz w angielskim, krótkimi deklaratywnymi zdaniami.
+12. Submit via `update_brief({ action: 'replace', content: <full markdown body>, expectedHash: <hash from step 1>, changeSummary: 'initial generation' })`.
+
+### Branch B — Editorial (body already exists)
+
+Triggered when `get_brief` returns a brief with non-trivial body content.
+
+1. Always start with `get_brief` to refresh `expectedHash` (another thread or the user may have edited since).
+2. Read the user's request carefully. Common patterns:
+   - **"Make it shorter"** → favour `replace` with a tightened version, but **never** drop inlined diff fragments / file paths / signatures (those are what makes the brief usable to the second audience). Tighten prose, not facts.
+   - **"Add a section about X"** → use `insert_after_section({ anchor: '<8char>', content })` — extract the anchor from the body (the `<!-- anchor: ... -->` comment immediately preceding the target heading). Prefer `anchor` over `heading` (anchors are stable across renames).
+   - **"Append an FAQ"** → `update_brief({ action: 'append', content })`.
+3. Never wholesale-replace if a smaller surgical edit would do. `replace` discards section anchors; `insert_after_section` preserves them.
+4. If you receive `BRIEF_CONFLICT`, the brief was edited by another writer. Call `get_brief` again, reconcile your intended change against the new content, then retry.
+5. If a target anchor is missing, the tool falls back to append-at-end with a warning — re-evaluate whether that is what the user wanted before continuing.
+
+---
+
+## Self-containment — the genre invariant
+
+Two rules sit above any methodology-specific guidance:
+
+1. **The `MCPReleaseDiff` payload is your only source.** There is no fetch-on-demand path in this thread — no `get_<type>`, no `Read pages/...`. Every snapshot you need is already in the payload (`MCPEntityDelta.before/after`, `MCPSectionDelta.before/after`). Whenever a change involves a concrete artefact — DTO field, endpoint signature, SQL, view URL, code snippet — paste it into the brief. The reader cannot fetch it on demand. Phrases like *"see the release diff"*, *"per the spec page"*, or *"as defined elsewhere"* are failures.
+2. **Describe the SYSTEM, not the spec edits.** The brief is about how the specified system behaves now vs. before — not about which markdown files gained/lost sections. Editorial mechanics (anchor injection, section reorder without content change, typo, prose smoothing, comment edit, heading rename without semantic shift) belong in version history, not in the brief. *Drop them.*
+
+   - GOOD: *"Brief threads whitelist their toolset — only `brief-tools` and `release-tools` are mounted; plan/entity MCPs are silently omitted to keep the editorial agent on its lane."*
+   - BAD: *"Section 'Tool whitelist' was added to `m05-chat-agent.md` between 'Context registry' and 'System prompt builder'."*
+
+When this invariant conflicts with brevity, choose self-containment. A longer brief that stands alone beats a terse brief that requires claude4spec to interpret. The writing-style workflow refines *which* parts of an `MCPReleaseDiff` count as substance vs. format vs. editorial — but the invariant above governs all of them.
+
+If after filtering nothing substantive remains in a release, say so explicitly: *"This release contains only editorial cleanup of the specification — no system behaviour changes."* Do not pad.
+
+---
+
+## Style & quality bar
+
+- **Concrete over abstract.** Write *"the `endpoint.dto` link became polymorphic (`{ kind: 'request' | 'response' | 'error' }`)"* rather than *"we improved entity flexibility."*
+- **One concept per paragraph.** Both audiences benefit from short paragraphs (skimming humans, pattern-matching agents).
+- **No marketing tone.** Engineering documentation, not a release announcement.
+- **Inline the diff, don't paraphrase it.** When a section change matters, paste the relevant fragment with a short framing sentence.
+- **Two delimited sections** at minimum: `## What changed` (human-context narrative) and `## For implementers` (second-audience payload). The brief may have other sections in between — these two are the floor.
+
+---
+
+## Tool error handling
+
+| Error code | Action |
+|------------|--------|
+| `BRIEF_CONFLICT` | Re-`get_brief`, reconcile, retry once. If conflict persists, ask the user to reconcile manually. |
+| `BRIEF_FRONTMATTER_IMMUTABLE` | Your `content` accidentally altered frontmatter. Strip the YAML header — `update_brief` always preserves the existing frontmatter. |
+| `BRIEF_ARCHIVED` | The user archived this brief. Inform the user and stop editing until they unarchive. |
+| `MISSING_TARGET` | `insert_after_section` requires `anchor` or `heading`. Re-issue with one of them. |
+| `AMBIGUOUS_HEADING` | Two sections share the same heading text — switch to `anchor`. |
+| `VERSION_NOT_FOUND` | The version number you passed does not exist. List versions first. |
+| `INVALID_INCLUDE_FILTER` | `release_diff` / `release_show` rejected an empty `include` array. Drop the arg to fall back to defaults (`['pages','entities']`). |
+| `INVALID_ENTITY_TYPES_FILTER` | Empty `entityTypes` array. Drop the arg to fall back to defaults (all 5 types). |
+| `CONFLICTING_FILTERS` | You passed `entityTypes` without `'entities'` in `include`. Either add `'entities'` to `include` or drop `entityTypes`. |
+
+If `release-tools.release_diff` returns an empty diff (both `entities` and `pages` empty — e.g. `from === to`), report that to the user — do not fabricate changes.