@longzai-intelligence-issues/ledger 0.0.1

package/src/__tests__/prompts/prompts.commands.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'bun:test';
+
+import { listPrompts, showPrompt } from '@/prompts/prompts.commands';
+
+describe('listPrompts', () => {
+  test('内置两模板在场且内容完整', () => {
+    const prompts = listPrompts({});
+
+    expect(prompts.map((entry) => entry.id)).toEqual(['issue-create-and-process', 'issue-process']);
+    expect(prompts.every((entry) => entry.source === 'builtin')).toBe(true);
+
+    /**
+     * create 模板关键节
+     */
+    const createPrompt = showPrompt('issue-create-and-process', {});
+
+    expect(createPrompt?.content).toContain('范围判定先于建档');
+    expect(createPrompt?.content).toContain('门禁取号');
+    expect(createPrompt?.content).toContain('【1】备选方案和分析');
+    expect(createPrompt?.content).toContain('verify-close');
+
+    /**
+     * process 模板关键节
+     */
+    const processPrompt = showPrompt('issue-process', {});
+
+    expect(processPrompt?.content).toContain('引用必须唯一定位');
+    expect(processPrompt?.content).toContain('终态拦截');
+  });
+
+  test('builtin 关闭时仅 extra', () => {
+    expect(listPrompts({ builtin: false })).toEqual([]);
+  });
+
+  test('extraDir 加载并按 id 覆盖内置', () => {
+    /**
+     * extra 目录（复用本测试文件目录下的临时文件不可行——直接以 fixtures 目录断言缺席容错）
+     */
+    const prompts = listPrompts({ extraDir: '/nonexistent/prompts-dir' });
+
+    expect(prompts).toHaveLength(2);
+  });
+
+  test('showPrompt 未命中返回 null', () => {
+    expect(showPrompt('ghost-prompt', {})).toBeNull();
+  });
+});

package/src/__tests__/template/issue-template.renderer.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, test } from 'bun:test';
+
+import { parseCriteriaBlock, parseIssueDoc } from '@/parser/registry.parser';
+import {
+  renderCriteriaBlockExample,
+  renderIssueTemplate,
+  renderIssueTemplateSkeleton,
+  renderRegistryReadmeStub,
+} from '@/template/issue-template.renderer';
+
+/**
+ * instance 模式渲染入参（含沿革与阻塞）
+ */
+const SAMPLE_VALUES = {
+  number: '0035',
+  slug: 'runs-list-grace',
+  title: '宽限期趟数合成兜底缺失',
+  priority: 'P2' as const,
+  scopeTitle: 'issues 项目域',
+  date: '2026-09-14',
+  source: '用户裁定（2026-09-14，会话正文）',
+  historyRefs: [{ number: '0034', slug: 'prior-case' }],
+  blockedByRefs: [{ number: '0036', slug: 'blocker-case' }, { number: '0037' }],
+};
+
+describe('renderIssueTemplateSkeleton', () => {
+  test('骨架头部七键齐全且次序规范', () => {
+    const skeleton = renderIssueTemplateSkeleton();
+
+    expect(skeleton.startsWith('# <NNNN> - ')).toBe(true);
+    expect(skeleton.indexOf('**优先级**')).toBeLessThan(skeleton.indexOf('**状态**'));
+    expect(skeleton.indexOf('**状态**')).toBeLessThan(skeleton.indexOf('**立案日期**'));
+    expect(skeleton.indexOf('**立案日期**')).toBeLessThan(skeleton.indexOf('**所属域**'));
+    expect(skeleton.indexOf('**所属域**')).toBeLessThan(skeleton.indexOf('**来源**'));
+    expect(skeleton.indexOf('**来源**')).toBeLessThan(skeleton.indexOf('**沿革**'));
+    expect(skeleton.indexOf('**沿革**')).toBeLessThan(skeleton.indexOf('**阻塞**'));
+  });
+
+  test('骨架正文四段齐全且次序规范', () => {
+    const skeleton = renderIssueTemplateSkeleton();
+
+    expect(skeleton.indexOf('## 一、问题动机')).toBeLessThan(skeleton.indexOf('## 二、现状与证据'));
+    expect(skeleton.indexOf('## 二、现状与证据')).toBeLessThan(skeleton.indexOf('## 三、处置方向'));
+    expect(skeleton.indexOf('## 三、处置方向')).toBeLessThan(
+      skeleton.indexOf('## 四、处置结果/验证口径'),
+    );
+  });
+
+  test('骨架本身可被解析器读档（建档态 red）', () => {
+    const record = parseIssueDoc('0700-format-sample.md', renderIssueTemplateSkeleton(), 0);
+
+    expect(record?.status).toBe('red');
+  });
+});
+
+describe('renderIssueTemplate', () => {
+  test('实例渲染回环：落盘名解析 + 状态 red + 标题提取', () => {
+    const content = renderIssueTemplate(SAMPLE_VALUES);
+
+    const record = parseIssueDoc(`${SAMPLE_VALUES.number}-${SAMPLE_VALUES.slug}.md`, content, 0);
+
+    expect(record?.id).toBe('0035');
+    expect(record?.slug).toBe('runs-list-grace');
+    expect(record?.title).toBe('0035 - 宽限期趟数合成兜底缺失');
+    expect(record?.status).toBe('red');
+    expect(record?.pendingReason).toBeNull();
+  });
+
+  test('实例渲染沿革阻塞引用回环（链接与纯编号两形态）', () => {
+    const record = parseIssueDoc(
+      `${SAMPLE_VALUES.number}-${SAMPLE_VALUES.slug}.md`,
+      renderIssueTemplate(SAMPLE_VALUES),
+      0,
+    );
+
+    expect(record?.historyRefs).toEqual([{ number: '0034', slug: 'prior-case' }]);
+    expect(record?.blockedByRefs).toEqual([
+      { number: '0036', slug: 'blocker-case' },
+      { number: '0037', slug: null },
+    ]);
+  });
+
+  test('可选引用缺席时省略对应元信息行', () => {
+    const content = renderIssueTemplate({
+      ...SAMPLE_VALUES,
+      historyRefs: undefined,
+      blockedByRefs: undefined,
+    });
+
+    expect(content.includes('**沿革**')).toBe(false);
+    expect(content.includes('**阻塞**')).toBe(false);
+  });
+
+  test('实例骨架与骨架正文四段共享占位文本（结构零漂移）', () => {
+    const instance = renderIssueTemplate(SAMPLE_VALUES);
+
+    for (const heading of [
+      '## 一、问题动机',
+      '## 二、现状与证据',
+      '## 三、处置方向',
+      '## 四、处置结果/验证口径',
+    ]) {
+      expect(instance.includes(heading)).toBe(true);
+    }
+
+    expect(instance.includes('> <问题原文逐字记录，禁止转述改写>')).toBe(true);
+  });
+});
+
+describe('renderCriteriaBlockExample', () => {
+  test('示例块本身通过解析器机检（照抄即合法）', () => {
+    const parsed = parseCriteriaBlock(renderCriteriaBlockExample());
+
+    expect(parsed.summary).toContain('示例');
+    expect(parsed.criteria).toHaveLength(1);
+    expect(parsed.criteria[0]?.channel).toBe('test');
+  });
+});
+
+describe('renderRegistryReadmeStub', () => {
+  test('存根包含 scope 名、建档入口与指南链接', () => {
+    const stub = renderRegistryReadmeStub(
+      'issues 项目域',
+      '../../docs/guides/issue-file-format.md',
+    );
+
+    expect(stub.includes('# issues 项目域 issue 注册表')).toBe(true);
+    expect(stub.includes('lzi-issues create')).toBe(true);
+    expect(stub.includes('../../docs/guides/issue-file-format.md')).toBe(true);
+    expect(stub.includes('🔴 待处理')).toBe(true);
+    expect(stub.includes('⚪ 已冻结')).toBe(true);
+  });
+});

package/src/close/evidence-reader.utils.ts

@@ -0,0 +1,201 @@
+/**
+ * 绿证据锚点判读（证据收口缺省模式的判定核）
+ *
+ * 处置段定位（标题行起至下一 `## ` 或文末，跨内嵌围栏）；段内围栏里行整体跳过
+ * （判据声明非执行结果），围栏外逐行按优先级归类锚点：certificate > exit-zero >
+ * all-green > adjudicated；零锚点拒收。挂起词拦截按状态行全文判定。
+ */
+
+import { DISPOSITION_TITLE_KEYWORD, PENDING_REASON_PATTERN } from '@/parser/format.utils';
+
+/**
+ * 锚点类别
+ */
+export type EvidenceAnchorKind = 'certificate' | 'exit-zero' | 'all-green' | 'adjudicated';
+
+/**
+ * 绿证据锚点
+ */
+export type EvidenceAnchor = {
+  /**
+   * 锚点类别
+   */
+  kind: EvidenceAnchorKind;
+
+  /**
+   * 锚点原文行
+   */
+  line: string;
+};
+
+/**
+ * 证据判读结果
+ */
+export type EvidenceReadResult = {
+  /**
+   * 锚点列表（按判读优先级序）
+   */
+  anchors: EvidenceAnchor[];
+
+  /**
+   * 处置段文本（定位失败为空串）
+   */
+  dispositionText: string;
+};
+
+/**
+ * 证书指纹锚点模式（64 位 hex）
+ */
+const CERTIFICATE_PATTERN = /证书指纹\s+([0-9a-f]{64})/;
+
+/**
+ * 退出码零锚点模式（两形态）
+ */
+const EXIT_ZERO_PATTERN = /退出码\s*0(?!\d)|EXIT\s*=\s*0(?!\d)/i;
+
+/**
+ * 全绿族词语锚点模式
+ */
+const ALL_GREEN_PATTERN = /(?<![未待])全(?:绿|过|部通过)/;
+
+/**
+ * 经裁定自验锚点模式
+ */
+const ADJUDICATED_PATTERN = /用户[^。\n]{0,30}自验/;
+
+/**
+ * 定位处置段文本（跨内嵌围栏）
+ *
+ * @param raw - 文档全文
+ * @returns 处置段文本（含标题行；缺席为空串）
+ */
+export function locateDispositionText(raw: string): string {
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 处置段标题行下标
+   */
+  const startIndex = lines.findIndex(
+    (line) => line.startsWith('## ') && line.includes(DISPOSITION_TITLE_KEYWORD),
+  );
+
+  if (startIndex === -1) {
+    return '';
+  }
+
+  /**
+   * 段末行下标（下一 `## ` 标题或文末）
+   */
+  let endIndex = lines.length;
+
+  for (let index = startIndex + 1; index < lines.length; index += 1) {
+    if ((lines[index] ?? '').startsWith('## ')) {
+      endIndex = index;
+
+      break;
+    }
+  }
+
+  return lines.slice(startIndex, endIndex).join('\n');
+}
+
+/**
+ * 判读处置段围栏外锚点
+ *
+ * @param dispositionText - 处置段文本
+ * @returns 锚点列表（优先级降序归类，首个命中类别只取一次）
+ */
+export function readEvidenceAnchors(dispositionText: string): EvidenceAnchor[] {
+  /**
+   * 锚点收集器
+   */
+  const anchors: EvidenceAnchor[] = [];
+
+  /**
+   * 已命中类别集合（每类别只取首个）
+   */
+  const hitKinds = new Set<EvidenceAnchorKind>();
+
+  /**
+   * 围栏深度（处置段内围栏里行整体跳过）
+   */
+  let fenceDepth = 0;
+
+  for (const line of dispositionText.split(/\r?\n/)) {
+    if (line.trim().startsWith('```')) {
+      fenceDepth = fenceDepth === 0 ? 1 : 0;
+
+      continue;
+    }
+
+    if (fenceDepth > 0) {
+      continue;
+    }
+
+    /**
+     * 候选锚点（类别 + 模式）
+     */
+    const candidates: ReadonlyArray<{ kind: EvidenceAnchorKind; pattern: RegExp }> = [
+      { kind: 'certificate', pattern: CERTIFICATE_PATTERN },
+      { kind: 'exit-zero', pattern: EXIT_ZERO_PATTERN },
+      { kind: 'all-green', pattern: ALL_GREEN_PATTERN },
+      { kind: 'adjudicated', pattern: ADJUDICATED_PATTERN },
+    ];
+
+    for (const candidate of candidates) {
+      if (!hitKinds.has(candidate.kind) && candidate.pattern.test(line)) {
+        anchors.push({ kind: candidate.kind, line });
+        hitKinds.add(candidate.kind);
+      }
+    }
+  }
+
+  return anchors;
+}
+
+/**
+ * 证据判读组合入口
+ *
+ * @param raw - 文档全文
+ * @returns 判读结果
+ */
+export function readEvidence(raw: string): EvidenceReadResult {
+  /**
+   * 处置段文本
+   */
+  const dispositionText = locateDispositionText(raw);
+
+  return { anchors: readEvidenceAnchors(dispositionText), dispositionText };
+}
+
+/**
+ * 挂起词拦截判定（状态行含任一挂起词即拒绝收口——诚实黄灯维持）
+ *
+ * @param statusLine - 状态行全文
+ * @param pendingWords - 挂起词表
+ * @returns 命中的挂起词；未命中为 null
+ */
+export function findPendingWord(
+  statusLine: string,
+  pendingWords: readonly string[],
+): string | null {
+  return pendingWords.find((word) => statusLine.includes(word)) ?? null;
+}
+
+/**
+ * 挂起原因提取（冻结/收口报文引用；复用解析器括注口径）
+ *
+ * @param statusLine - 状态行全文
+ * @returns 挂起原因；无括注为 null
+ */
+export function readPendingReason(statusLine: string): string | null {
+  /**
+   * 括注命中
+   */
+  const match = PENDING_REASON_PATTERN.exec(statusLine);
+
+  return match === null ? null : (match[1] ?? '').trim();
+}

package/src/close/green-flip.commands.ts

@@ -0,0 +1,199 @@
+/**
+ * 翻绿回填内核（green-flip）
+ *
+ * 状态行改写保留前缀粗体/冒号原形态（读/写口径统一）；处置段回填证据锚点块
+ * （两种收口形态标题）。守卫分诊：replace 原样返回且正则仍命中（已绿且概要
+ * 逐字一致）→ 幂等零变更；正则零命中 → 抛错拒绝（防「处置段在场而状态行未
+ * 翻」假绿）。
+ */
+
+import { STATUS_LINE_PREFIX_SOURCE } from '@/parser/format.utils';
+
+/**
+ * 翻绿入参
+ */
+export type GreenFlipInput = {
+  /**
+   * 文档全文
+   */
+  raw: string;
+
+  /**
+   * 收口概要（状态行括注与证据块首行）
+   */
+  summary: string;
+
+  /**
+   * 证据锚点块全文（含标题行；空串表示只翻状态行）
+   */
+  evidenceBlock: string;
+};
+
+/**
+ * 翻绿结果
+ */
+export type GreenFlipResult = {
+  /**
+   * 翻绿产物全文（幂等时与原文一致）
+   */
+  content: string;
+
+  /**
+   * 幂等标记（原文已为目标形态）
+   */
+  idempotent: boolean;
+};
+
+/**
+ * 状态行改写正则（由前缀源动态构造——读/写单一真源）
+ */
+const STATUS_LINE_REWRITE_PATTERN = new RegExp(
+  `(${STATUS_LINE_PREFIX_SOURCE}\\s*)(🔴|🟡|🟢)[^\\n]*`,
+);
+
+/**
+ * 目标状态行文本（概要 + 锚点指引）
+ */
+const GREEN_STATUS_SUFFIX = '——判据证据锚点见处置段）';
+
+/**
+ * 执行翻绿回填
+ *
+ * @param input - 翻绿入参
+ * @returns 翻绿结果
+ * @throws {@link Error} 状态行零命中（缺状态行的文档不得走翻绿路径）
+ */
+export function applyGreenFlip(input: GreenFlipInput): GreenFlipResult {
+  /**
+   * 目标状态行全文
+   */
+  const targetStatusLine = `🟢 已处置（${input.summary}${GREEN_STATUS_SUFFIX}`;
+
+  /**
+   * 状态行改写产物
+   */
+  const rewritten = input.raw.replace(STATUS_LINE_REWRITE_PATTERN, `$1${targetStatusLine}`);
+
+  if (rewritten === input.raw) {
+    /**
+     * 守卫分诊：正则仍命中说明原文已含目标态（幂等）；零命中说明无状态行
+     */
+    if (STATUS_LINE_REWRITE_PATTERN.test(input.raw)) {
+      return { content: input.raw, idempotent: true };
+    }
+
+    throw new Error('状态行零命中——缺状态行的文档不得走翻绿路径（先补状态行）');
+  }
+
+  return {
+    content: appendEvidenceBlock(rewritten, input.evidenceBlock),
+    idempotent: false,
+  };
+}
+
+/**
+ * 回填证据锚点块到处置段（有段则段末追加，缺段则文末补段）
+ *
+ * @param raw - 文档全文（状态行已翻绿）
+ * @param evidenceBlock - 证据锚点块全文
+ * @returns 回填产物
+ */
+function appendEvidenceBlock(raw: string, evidenceBlock: string): string {
+  if (evidenceBlock.trim() === '') {
+    return raw;
+  }
+
+  /**
+   * 文档行数组
+   */
+  const lines = raw.split(/\r?\n/);
+
+  /**
+   * 处置段标题行下标
+   */
+  const dispositionIndex = lines.findIndex(
+    (line) => line.startsWith('## ') && line.includes('处置结果'),
+  );
+
+  if (dispositionIndex === -1) {
+    return `${raw.replace(/\n+$/, '')}\n\n## 四、处置结果/验证口径\n\n${evidenceBlock}\n`;
+  }
+
+  /**
+   * 段末行下标（下一 `## ` 标题或文末）
+   */
+  let endIndex = lines.length;
+
+  for (let index = dispositionIndex + 1; index < lines.length; index += 1) {
+    if ((lines[index] ?? '').startsWith('## ')) {
+      endIndex = index;
+
+      break;
+    }
+  }
+
+  /**
+   * 段内既有内容（剥尾部空行）
+   */
+  const sectionBody = lines
+    .slice(dispositionIndex + 1, endIndex)
+    .join('\n')
+    .replace(/\n+$/, '');
+
+  /**
+   * 头部行（处置段标题之前的全部行——标题、元信息、动机等段落原样保留）
+   */
+  const head = lines.slice(0, dispositionIndex).join('\n').replace(/\n+$/, '');
+
+  /**
+   * 段后余文
+   */
+  const rest = lines.slice(endIndex).join('\n');
+
+  /**
+   * 回填段（标题 + 既有内容 + 证据块）
+   */
+  const section = [lines[dispositionIndex] ?? '', '', sectionBody, '', evidenceBlock]
+    .filter((part) => part !== '')
+    .join('\n');
+
+  return `${head}\n\n${section}\n\n${rest.replace(/^\n+/, '')}`.replace(/\n+$/, '\n');
+}
+
+/**
+ * 零执行证据收口证据块渲染
+ *
+ * @param anchorLines - 锚点原文行列表
+ * @param decisionRef - 收口依据（如「docs/decisions/0005」）
+ * @returns 证据锚点块全文
+ */
+export function renderEvidenceCloseBlock(
+  anchorLines: readonly string[],
+  decisionRef: string,
+): string {
+  return [
+    `证据锚点（末次通过零执行收口，${decisionRef}）：`,
+    ...anchorLines.map((line) => `- ${line}`),
+  ].join('\n');
+}
+
+/**
+ * 证书化真跑证据块渲染（逐判据证书指纹行）
+ *
+ * @param summary - 收口概要
+ * @param evidenceLines - 逐判据证据行（已含证书指纹与退出码）
+ * @param caseRef - 收口先例指针
+ * @returns 证据锚点块全文
+ */
+export function renderRerunEvidenceBlock(
+  summary: string,
+  evidenceLines: readonly string[],
+  caseRef: string,
+): string {
+  return [
+    `${summary}`,
+    '',
+    `判据执行证据（证书化收口，${caseRef}）：`,
+    ...evidenceLines.map((line) => `- ${line}`),
+  ].join('\n');
+}