@aicoffe/ai-native-sdlc-mcp 0.1.0

package/dist/workflow/events.js

@@ -0,0 +1,50 @@
+export function workflowStartedEvent(workflow_id, title) {
+    return {
+        type: 'workflow.started',
+        workflow_id,
+        title,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function stageCompletedEvent(workflow_id, stage_id, output) {
+    return {
+        type: 'stage.completed',
+        workflow_id,
+        stage_id,
+        output,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function gateDecisionEvent(args) {
+    const event = {
+        type: 'gate.decision',
+        workflow_id: args.workflow_id,
+        stage_id: args.stage_id,
+        decision: args.decision,
+        approved_by: args.approved_by,
+        timestamp: new Date().toISOString(),
+    };
+    if (args.changes !== undefined) {
+        event.changes = args.changes;
+    }
+    return event;
+}
+export function actionCompletedEvent(workflow_id, stage_id, result) {
+    return {
+        type: 'action.completed',
+        workflow_id,
+        stage_id,
+        result,
+        timestamp: new Date().toISOString(),
+    };
+}
+export function actionFailedEvent(workflow_id, stage_id, error, retryable) {
+    return {
+        type: 'action.failed',
+        workflow_id,
+        stage_id,
+        error,
+        retryable,
+        timestamp: new Date().toISOString(),
+    };
+}

package/dist/workflow/handlers/close-intent.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function closeIntentHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/close-intent.js

@@ -0,0 +1,21 @@
+// mcp-server/src/workflow/handlers/close-intent.ts
+import { readFile, writeFile } from 'node:fs/promises';
+import { resolveUnder, validateContextVars } from './contain.js';
+import { pathExists } from './fs-utils.js';
+export function closeIntentHandler(deps) {
+    return async (params, state) => {
+        validateContextVars(state.context);
+        const status = String(params.update_status ?? 'implemented');
+        const relPath = `intent/${String(state.context.date)}-${String(state.context.slug)}.md`;
+        const absPath = resolveUnder(deps.repoRoot, relPath);
+        if (!(await pathExists(absPath))) {
+            throw new Error(`Intent file not found: ${relPath} (expected at ${absPath})`);
+        }
+        const content = await readFile(absPath, 'utf8');
+        const updated = content.replace(/^Status:.*$/m, `Status: ${status}`);
+        if (updated !== content) {
+            await writeFile(absPath, updated, 'utf8');
+        }
+        return { context_updates: { intent_status: status }, intent_file: relPath };
+    };
+}

package/dist/workflow/handlers/contain.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Resolves relPath under rootAbs with strict containment: absolute paths and
+ * any '..' segment are rejected (non-retryable), the resolved result must stay
+ * under rootAbs. Guards against poisoned .workflow state writing outside
+ * REPO_ROOT (e.g. context.date/slug/domain containing traversal segments).
+ */
+export declare function resolveUnder(rootAbs: string, relPath: string): string;
+/**
+ * Validates the context vars that feed handler-built paths. Called by
+ * recoverWorkflows before executing any action so a hostile state file cannot
+ * drive filesystem writes at startup.
+ */
+export declare function validateContextVars(context: Record<string, unknown>): void;

package/dist/workflow/handlers/contain.js

@@ -0,0 +1,42 @@
+// mcp-server/src/workflow/handlers/contain.ts
+import path from 'node:path';
+/**
+ * Resolves relPath under rootAbs with strict containment: absolute paths and
+ * any '..' segment are rejected (non-retryable), the resolved result must stay
+ * under rootAbs. Guards against poisoned .workflow state writing outside
+ * REPO_ROOT (e.g. context.date/slug/domain containing traversal segments).
+ */
+export function resolveUnder(rootAbs, relPath) {
+    if (path.isAbsolute(relPath)) {
+        throw new Error(`Path escapes repository root (absolute not allowed): ${relPath}`);
+    }
+    const segments = relPath.split(/[\\/]/);
+    if (segments.includes('..')) {
+        throw new Error(`Path escapes repository root: ${relPath}`);
+    }
+    const base = path.resolve(rootAbs);
+    const resolved = path.resolve(base, relPath);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+        throw new Error(`Path escapes repository root: ${relPath}`);
+    }
+    return resolved;
+}
+/**
+ * Validates the context vars that feed handler-built paths. Called by
+ * recoverWorkflows before executing any action so a hostile state file cannot
+ * drive filesystem writes at startup.
+ */
+export function validateContextVars(context) {
+    const date = String(context.date ?? '');
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
+        throw new Error(`Invalid context.date: "${date}"`);
+    }
+    const slug = String(context.slug ?? '');
+    if (!/^[a-z0-9-]{1,64}$/.test(slug)) {
+        throw new Error(`Invalid context.slug: "${slug}"`);
+    }
+    const domain = context.domain === undefined ? 'default' : String(context.domain);
+    if (!/^[a-z0-9-]{0,64}$/.test(domain)) {
+        throw new Error(`Invalid context.domain: "${domain}"`);
+    }
+}

package/dist/workflow/handlers/create-feature-branch.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function createFeatureBranchHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/create-feature-branch.js

@@ -0,0 +1,25 @@
+// mcp-server/src/workflow/handlers/create-feature-branch.ts
+import { renderTemplate } from '../template.js';
+import { branchExists, currentBranch, git, hasCommits, workingTreeDirty } from './git.js';
+export function createFeatureBranchHandler(deps) {
+    return async (params, state) => {
+        const pattern = String(params.branch_pattern ?? 'feature/{date}-{slug}');
+        const target = renderTemplate(pattern, state.context);
+        const repoRoot = deps.repoRoot;
+        if ((await currentBranch(repoRoot)) === target) {
+            return { context_updates: { branch: target }, branch: target, reused: true };
+        }
+        if (!(await hasCommits(repoRoot))) {
+            throw new Error(`Cannot create branch "${target}": HEAD is unborn (no commits yet); make an initial commit first.`);
+        }
+        if (await branchExists(repoRoot, target)) {
+            if (await workingTreeDirty(repoRoot)) {
+                throw new Error(`Working tree is dirty; commit or stash your changes before checking out "${target}".`);
+            }
+            await git(repoRoot, 'checkout', target);
+            return { context_updates: { branch: target }, branch: target, reused: true };
+        }
+        await git(repoRoot, 'checkout', '-b', target);
+        return { context_updates: { branch: target }, branch: target, reused: false };
+    };
+}

package/dist/workflow/handlers/create-pr.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function createPrHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/create-pr.js

@@ -0,0 +1,45 @@
+// mcp-server/src/workflow/handlers/create-pr.ts
+import { renderTemplate } from '../template.js';
+export function createPrHandler(deps) {
+    return async (params, state) => {
+        const head = renderTemplate('feature/{date}-{slug}', state.context);
+        const base = String(params.base_branch ?? 'main');
+        const titlePattern = String(params.title_pattern ?? 'feat: {title}');
+        const existing = await deps.gh.findPrByBranch(head);
+        if (existing) {
+            return {
+                context_updates: { pr_number: existing.number, pr_url: existing.url },
+                pr_number: existing.number,
+                pr_url: existing.url,
+                reused: true,
+            };
+        }
+        const pr = await deps.gh.createPr({
+            head,
+            base,
+            title: renderTemplate(titlePattern, state.context),
+            body: generatePrBody(state),
+        });
+        if (params.trigger_ai_review === true) {
+            await deps.gh.addComment(pr.number, '@claude review');
+        }
+        return {
+            context_updates: { pr_number: pr.number, pr_url: pr.url },
+            pr_number: pr.number,
+            pr_url: pr.url,
+            reused: false,
+        };
+    };
+}
+function generatePrBody(state) {
+    return [
+        `# ${state.title}`,
+        '',
+        `- Workflow: ${state.workflow_id}`,
+        `- Intent: ${state.intent_id}`,
+        `- Spec: specs/${String(state.context.date)}-${String(state.context.slug)}/`,
+        '',
+        '此 PR 由 AI-native SDLC 工作流自动创建。',
+        '',
+    ].join('\n');
+}

package/dist/workflow/handlers/create-spec-dir.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function createSpecDirHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/create-spec-dir.js

@@ -0,0 +1,50 @@
+// mcp-server/src/workflow/handlers/create-spec-dir.ts
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { commitStagedIfAny, git } from './git.js';
+import { resolveUnder, validateContextVars } from './contain.js';
+import { pathExists } from './fs-utils.js';
+export function createSpecDirHandler(deps) {
+    return async (params, state) => {
+        validateContextVars(state.context);
+        const createSubdirs = params.create_subdirs ?? [];
+        const writeFiles = params.write_files ?? [];
+        const gitCommit = params.git_commit === true;
+        const specDirRel = `specs/${String(state.context.date)}-${String(state.context.slug)}`;
+        const specDirAbs = resolveUnder(deps.repoRoot, specDirRel);
+        await mkdir(specDirAbs, { recursive: true });
+        for (const subdir of createSubdirs) {
+            await mkdir(resolveUnder(deps.repoRoot, `${specDirRel}/${subdir}`), { recursive: true });
+        }
+        for (const file of writeFiles) {
+            const filePath = resolveUnder(deps.repoRoot, `${specDirRel}/${file}`);
+            if (await pathExists(filePath))
+                continue;
+            await mkdir(path.dirname(filePath), { recursive: true });
+            await writeFile(filePath, generateFileContent(file, state), 'utf8');
+        }
+        if (gitCommit) {
+            const status = await git(deps.repoRoot, 'status', '--porcelain');
+            if (status.trim()) {
+                await git(deps.repoRoot, 'add', '--', specDirRel);
+                await commitStagedIfAny(deps.repoRoot, `chore: create spec dir for ${state.intent_id}`, [specDirRel]);
+            }
+        }
+        return { context_updates: { spec_dir: specDirRel }, spec_dir: specDirRel };
+    };
+}
+function generateFileContent(file, state) {
+    if (file === 'reviews/intent-review.md') {
+        const reviewer = state.context.approved_by !== undefined ? String(state.context.approved_by) : 'auto';
+        return [
+            '# Intent Review',
+            '',
+            `**Intent**: ${state.intent_id}`,
+            `**Reviewer**: ${reviewer}`,
+            '**Decision**: Accepted',
+            `**Date**: ${new Date().toISOString()}`,
+            '',
+        ].join('\n');
+    }
+    return '';
+}

package/dist/workflow/handlers/exec.d.ts

@@ -0,0 +1,5 @@
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+}
+export declare function execFileAsync(command: string, args: string[], cwd: string): Promise<ExecResult>;

package/dist/workflow/handlers/exec.js

@@ -0,0 +1,13 @@
+// mcp-server/src/workflow/handlers/exec.ts
+import { execFile as execFileCb } from 'node:child_process';
+export function execFileAsync(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        execFileCb(command, args, { cwd, encoding: 'utf8' }, (err, stdout, stderr) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve({ stdout: String(stdout), stderr: String(stderr) });
+        });
+    });
+}

package/dist/workflow/handlers/fs-utils.d.ts

@@ -0,0 +1 @@
+export declare function pathExists(target: string): Promise<boolean>;

package/dist/workflow/handlers/fs-utils.js

@@ -0,0 +1,11 @@
+// mcp-server/src/workflow/handlers/fs-utils.ts
+import { access } from 'node:fs/promises';
+export async function pathExists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/workflow/handlers/gh.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Thrown when the GitHub CLI binary is missing (spawn ENOENT etc.).
+ * Non-retryable: no amount of retrying installs gh.
+ */
+export declare class GhUnavailableError extends Error {
+    constructor(detail?: string);
+}
+export interface GhPrRef {
+    number: number;
+    url: string;
+}
+export interface GhAdapter {
+    findPrByBranch(branch: string): Promise<GhPrRef | null>;
+    createPr(args: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }): Promise<GhPrRef>;
+    mergePr(number: number, opts: {
+        deleteBranch: boolean;
+    }): Promise<void>;
+    addComment(number: number, body: string): Promise<void>;
+}
+/** Real adapter: shells out to `gh` with array args, cwd pinned to the repo root. */
+export declare class ExecFileGhAdapter implements GhAdapter {
+    private readonly repoRoot;
+    private readonly executable;
+    constructor(repoRoot: string, executable?: string);
+    private gh;
+    findPrByBranch(branch: string): Promise<GhPrRef | null>;
+    createPr(args: {
+        head: string;
+        base: string;
+        title: string;
+        body: string;
+    }): Promise<GhPrRef>;
+    mergePr(number: number, opts: {
+        deleteBranch: boolean;
+    }): Promise<void>;
+    addComment(number: number, body: string): Promise<void>;
+}

package/dist/workflow/handlers/gh.js

@@ -0,0 +1,57 @@
+// mcp-server/src/workflow/handlers/gh.ts
+import { execFileAsync } from './exec.js';
+/**
+ * Thrown when the GitHub CLI binary is missing (spawn ENOENT etc.).
+ * Non-retryable: no amount of retrying installs gh.
+ */
+export class GhUnavailableError extends Error {
+    constructor(detail) {
+        super(`GitHub CLI (gh) is unavailable${detail ? `: ${detail}` : ''}. ` +
+            'Please install gh (https://cli.github.com/) and authenticate with `gh auth login`.');
+        this.name = 'GhUnavailableError';
+    }
+}
+/** Real adapter: shells out to `gh` with array args, cwd pinned to the repo root. */
+export class ExecFileGhAdapter {
+    repoRoot;
+    executable;
+    constructor(repoRoot, executable = 'gh') {
+        this.repoRoot = repoRoot;
+        this.executable = executable;
+    }
+    async gh(...args) {
+        try {
+            return await execFileAsync(this.executable, args, this.repoRoot);
+        }
+        catch (err) {
+            const error = err;
+            if (error.code === 'ENOENT') {
+                throw new GhUnavailableError(error.message);
+            }
+            const stderr = error.stderr ?? error.message;
+            throw new Error(`gh ${args.join(' ')} failed: ${stderr}`);
+        }
+    }
+    async findPrByBranch(branch) {
+        const { stdout } = await this.gh('pr', 'list', '--head', branch, '--state', 'open', '--json', 'number,url');
+        const parsed = JSON.parse(stdout);
+        return parsed.length > 0 ? parsed[0] : null;
+    }
+    async createPr(args) {
+        await this.gh('pr', 'create', '--head', args.head, '--base', args.base, '--title', args.title, '--body', args.body);
+        const ref = await this.findPrByBranch(args.head);
+        if (!ref) {
+            throw new Error(`gh pr create did not produce a findable PR for ${args.head}`);
+        }
+        return ref;
+    }
+    async mergePr(number, opts) {
+        const args = ['pr', 'merge', String(number), '--merge'];
+        if (opts.deleteBranch)
+            args.push('--delete-branch');
+        await this.gh(...args);
+    }
+    async addComment(number, body) {
+        await this.gh('pr', 'comment', String(number), '--body', body);
+    }
+}

package/dist/workflow/handlers/git.d.ts

@@ -0,0 +1,12 @@
+export declare function git(repoRoot: string, ...args: string[]): Promise<string>;
+export declare function gitOk(repoRoot: string, ...args: string[]): Promise<boolean>;
+export declare function currentBranch(repoRoot: string): Promise<string>;
+export declare function branchExists(repoRoot: string, branch: string): Promise<boolean>;
+export declare function hasCommits(repoRoot: string): Promise<boolean>;
+export declare function workingTreeDirty(repoRoot: string): Promise<boolean>;
+/**
+ * Pathspec commit: commits ONLY expectedRelPaths (and paths under them),
+ * never touching anything else the user may have staged. Returns false when
+ * none of expectedRelPaths intersect the staged index (no_changes semantics).
+ */
+export declare function commitStagedIfAny(repoRoot: string, message: string, expectedRelPaths: string[]): Promise<boolean>;

package/dist/workflow/handlers/git.js

@@ -0,0 +1,59 @@
+// mcp-server/src/workflow/handlers/git.ts
+//
+// All git usage goes through execFile with ARRAY args and cwd pinned to the
+// repo root — no shell strings. Git handlers never push, never --force,
+// never touch .git/hooks, never --no-verify.
+import { execFileAsync } from './exec.js';
+export async function git(repoRoot, ...args) {
+    try {
+        const { stdout } = await execFileAsync('git', args, repoRoot);
+        return stdout;
+    }
+    catch (err) {
+        const error = err;
+        const detail = (error.stderr ?? error.message ?? '').toString().trim();
+        throw new Error(`git ${args.join(' ')} failed: ${detail}`);
+    }
+}
+export async function gitOk(repoRoot, ...args) {
+    try {
+        await execFileAsync('git', args, repoRoot);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function currentBranch(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['symbolic-ref', '--short', 'HEAD'], repoRoot);
+        return stdout.trim();
+    }
+    catch {
+        return '';
+    }
+}
+export async function branchExists(repoRoot, branch) {
+    return gitOk(repoRoot, 'rev-parse', '--verify', '--quiet', `refs/heads/${branch}`);
+}
+export async function hasCommits(repoRoot) {
+    return gitOk(repoRoot, 'rev-parse', '--verify', '--quiet', 'HEAD');
+}
+export async function workingTreeDirty(repoRoot) {
+    const { stdout } = await execFileAsync('git', ['status', '--porcelain'], repoRoot);
+    return stdout.trim().length > 0;
+}
+/**
+ * Pathspec commit: commits ONLY expectedRelPaths (and paths under them),
+ * never touching anything else the user may have staged. Returns false when
+ * none of expectedRelPaths intersect the staged index (no_changes semantics).
+ */
+export async function commitStagedIfAny(repoRoot, message, expectedRelPaths) {
+    const { stdout } = await execFileAsync('git', ['diff', '--cached', '--name-only'], repoRoot);
+    const staged = stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+    const intersects = staged.some((p) => expectedRelPaths.some((exp) => p === exp || p.startsWith(`${exp}/`)));
+    if (!intersects)
+        return false;
+    await git(repoRoot, 'commit', '-m', message, '--', ...expectedRelPaths);
+    return true;
+}

package/dist/workflow/handlers/index.d.ts

@@ -0,0 +1,12 @@
+import type { WorkflowState } from '../types.js';
+import type { GhAdapter } from './gh.js';
+export interface ActionResult {
+    context_updates?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export type ActionHandler = (params: Record<string, unknown>, state: WorkflowState) => Promise<ActionResult>;
+export interface HandlerDeps {
+    repoRoot: string;
+    gh: GhAdapter;
+}
+export declare function buildActionHandlers(deps: HandlerDeps): Record<string, ActionHandler>;

package/dist/workflow/handlers/index.js

@@ -0,0 +1,20 @@
+import { createSpecDirHandler } from './create-spec-dir.js';
+import { createFeatureBranchHandler } from './create-feature-branch.js';
+import { createPrHandler } from './create-pr.js';
+import { mergePrHandler } from './merge-pr.js';
+import { updateCurrentIndexHandler } from './update-current-index.js';
+import { closeIntentHandler } from './close-intent.js';
+import { notifyBlockedHandler } from './notify-blocked.js';
+import { noopHandler } from './noop.js';
+export function buildActionHandlers(deps) {
+    return {
+        'create-spec-dir': createSpecDirHandler(deps),
+        'create-feature-branch': createFeatureBranchHandler(deps),
+        'create-pr': createPrHandler(deps),
+        'merge-pr': mergePrHandler(deps),
+        'update-current-index': updateCurrentIndexHandler(deps),
+        'close-intent': closeIntentHandler(deps),
+        'notify-blocked': notifyBlockedHandler(deps),
+        noop: noopHandler,
+    };
+}

package/dist/workflow/handlers/merge-pr.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function mergePrHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/merge-pr.js

@@ -0,0 +1,13 @@
+export function mergePrHandler(deps) {
+    return async (params, state) => {
+        const raw = state.context.pr_number;
+        if (raw === undefined || raw === null || raw === '') {
+            throw new Error('pr_number not found in workflow context; run create-pr before merge-pr ' +
+                `(workflow ${state.workflow_id}).`);
+        }
+        const prNumber = Number(raw);
+        // require_approvals is enforced by the platform (branch protection), not by us.
+        await deps.gh.mergePr(prNumber, { deleteBranch: params.delete_branch === true });
+        return { merged: true, pr_number: prNumber };
+    };
+}

package/dist/workflow/handlers/noop.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler } from './index.js';
+export declare const noopHandler: ActionHandler;

package/dist/workflow/handlers/noop.js

@@ -0,0 +1 @@
+export const noopHandler = async () => ({});

package/dist/workflow/handlers/notify-blocked.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function notifyBlockedHandler(_deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/notify-blocked.js

@@ -0,0 +1,12 @@
+export function notifyBlockedHandler(_deps) {
+    return async (params, state) => {
+        const notify = params.notify ?? [];
+        console.error(JSON.stringify({
+            type: 'workflow.blocked',
+            workflow_id: state.workflow_id,
+            stage: state.current_stage,
+            notify,
+        }));
+        return { notified: notify };
+    };
+}

package/dist/workflow/handlers/update-current-index.d.ts

@@ -0,0 +1,2 @@
+import type { ActionHandler, HandlerDeps } from './index.js';
+export declare function updateCurrentIndexHandler(deps: HandlerDeps): ActionHandler;

package/dist/workflow/handlers/update-current-index.js

@@ -0,0 +1,73 @@
+// mcp-server/src/workflow/handlers/update-current-index.ts
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { commitStagedIfAny, git } from './git.js';
+import { resolveUnder, validateContextVars } from './contain.js';
+import { pathExists } from './fs-utils.js';
+const PREAMBLE = '# Spec Index\n\n> 活规格索引：每个工作流一个章节，由工作流状态机（update-current-index）自动维护。\n';
+export function updateCurrentIndexHandler(deps) {
+    return async (params, state) => {
+        validateContextVars(state.context);
+        const domain = String(state.context.domain ?? 'default');
+        const relPath = path.posix.join('specs', '_current', `${domain}.md`);
+        const absPath = resolveUnder(deps.repoRoot, relPath);
+        await mkdir(path.dirname(absPath), { recursive: true });
+        const existing = (await pathExists(absPath)) ? await readFile(absPath, 'utf8') : null;
+        const section = renderSection(state);
+        const updated = existing === null
+            ? PREAMBLE + '\n' + section
+            : replaceSection(existing, state.workflow_id, section);
+        if (updated !== existing) {
+            await writeFile(absPath, updated, 'utf8');
+        }
+        if (params.git_commit === true) {
+            const status = await git(deps.repoRoot, 'status', '--porcelain');
+            if (status.trim()) {
+                await git(deps.repoRoot, 'add', '--', relPath);
+                await commitStagedIfAny(deps.repoRoot, `chore: update current index for ${state.workflow_id}`, [relPath]);
+            }
+        }
+        return { context_updates: { current_index: relPath }, target: relPath };
+    };
+}
+/**
+ * Section content is derived ONLY from the persisted state (no Date.now()) so
+ * re-running with the same state rewrites byte-identical content.
+ */
+function renderSection(state) {
+    const date = String(state.context.date ?? '');
+    const slug = String(state.context.slug ?? '');
+    const lines = [
+        `## [${state.workflow_id}] ${state.title}`,
+        '',
+        `- Status: ${state.status}`,
+        `- Current Stage: ${state.current_stage}`,
+        `- Spec: specs/${date}-${slug}/`,
+        `- Intent: intent/${date}-${slug}.md`,
+        `- Last Active: ${state.last_active}`,
+        '',
+    ];
+    return lines.join('\n');
+}
+/** Replaces (or appends) the `## [{workflow_id}] ...` section, preserving all
+ *  other sections and their order byte-for-byte. */
+function replaceSection(content, workflowId, section) {
+    const lines = content.split('\n');
+    const headerRe = new RegExp(`^## \\[${escapeRegExp(workflowId)}\\]`);
+    const start = lines.findIndex((line) => headerRe.test(line));
+    if (start === -1) {
+        const base = content.endsWith('\n') ? content : `${content}\n`;
+        return base + section;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^## \[/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    return [...lines.slice(0, start), ...section.split('\n'), ...lines.slice(end)].join('\n');
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}