dsh-notes-board 0.1.1 → 0.3.0

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts

@@ -0,0 +1,56 @@
+/**
+ * Verify tree: lifecycle/class/filename/INDEX and internal relative markdown links.
+ * Run: npx tsx <skill-dir>/scripts/verify-agent-note-tree.ts
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { agentNoteRoot, walkAgentNoteTree } from "./agent-note-tree.ts";
+
+const { notes, errors } = walkAgentNoteTree();
+
+// Check relative markdown links inside active notes
+const LINK_REGEX = /\[([^\]]+)\]\(([^)]+)\)/g;
+
+for (const note of notes) {
+  const noteFullPath = resolve(agentNoteRoot, note.rel);
+  const content = readFileSync(noteFullPath, "utf8");
+  let match: RegExpExecArray | null;
+
+  while ((match = LINK_REGEX.exec(content)) !== null) {
+    let rawTarget = match[2]?.trim();
+    if (!rawTarget) continue;
+
+    // Support CommonMark angle bracket destinations: [text](<path>)
+    if (rawTarget.startsWith("<") && rawTarget.endsWith(">")) {
+      rawTarget = rawTarget.slice(1, -1).trim();
+    }
+
+    // Ignore web links, intra-page anchors and ellipsis placeholders
+    if (rawTarget.startsWith("http://") || rawTarget.startsWith("https://") || rawTarget.startsWith("#") || rawTarget.startsWith("mailto:") || rawTarget.includes("…")) {
+      continue;
+    }
+
+    // Strip anchor fragment if present
+    const fileTarget = rawTarget.split("#")[0];
+    if (!fileTarget) continue;
+
+    const resolvedTarget = resolve(dirname(noteFullPath), fileTarget);
+
+    // Only verify internal links within agentNoteRoot (boundary-aware: a
+    // sibling like .agents/notes-backup/ must not prefix-match)
+    if (!resolvedTarget.startsWith(agentNoteRoot + sep)) {
+      continue;
+    }
+
+    if (!existsSync(resolvedTarget)) {
+      errors.push(`link: ${note.rel} -> "${rawTarget}" target file does not exist`);
+    }
+  }
+}
+
+if (errors.length) {
+  for (const e of errors) console.error(e);
+  process.exit(1);
+}
+
+console.log(`ok: ${notes.length} note(s) tree and relative links verified`);

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts

@@ -0,0 +1,127 @@
+/**
+ * Verify frozen archived Agent Notes: exact head layout, manifest.json seals,
+ * append-only extension vs a git baseline (skipped gracefully without git).
+ * Usage:
+ *   npx tsx <skill-dir>/scripts/verify-archived-agent-notes.ts          # verify only
+ *   npx tsx <skill-dir>/scripts/verify-archived-agent-notes.ts --write  # verify, then seal unsealed files
+ * Env: AGENT_NOTE_ARCHIVE_BASE_REF (default HEAD) — git ref the manifest is compared against.
+ */
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { agentNoteRoot } from "./agent-note-tree.ts";
+
+const isWrite = process.argv.includes("--write");
+const errors: string[] = [];
+const warnings: string[] = [];
+const fail = (msg: string) => { errors.push(msg); };
+
+// --- collect archived files (skip accidental .zh.md)
+const archivedDir = join(agentNoteRoot, "archived");
+const files: string[] = [];
+function scan(dir: string) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) scan(full);
+    else if (entry.isFile() && entry.name.endsWith(".md") && !entry.name.endsWith(".zh.md")) {
+      const rel = relative(archivedDir, full).split("\\").join("/");
+      if (rel === "AGENTS.md" || rel === "manifest.json") continue;
+      files.push(rel);
+    }
+  }
+}
+if (existsSync(archivedDir)) scan(archivedDir);
+
+// --- head layout: L1 title / L2 blank / L3 Status / L4 Archived / L5 blank
+const TITLE_RE = /^# Agent Note[:：] ?\S/;
+const ARCHIVED_RE = /^Archived: \d{4}-\d{2}-\d{2}$/;
+for (const rel of files) {
+  const lines = readFileSync(join(archivedDir, rel), "utf8").replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").split("\n");
+  if (!TITLE_RE.test(lines[0] ?? "")) fail(`${rel} — line 1 must be \`# Agent Note: <title>\``);
+  if (lines[1] !== "") fail(`${rel} — line 2 must be blank`);
+  if (lines[2] !== "Status: implemented") fail(`${rel} — line 3 must be \`Status: implemented\``);
+  if (!ARCHIVED_RE.test(lines[3] ?? "")) fail(`${rel} — line 4 must be \`Archived: YYYY-MM-DD\` immediately below Status`);
+  if (lines[4] !== "") fail(`${rel} — line 5 must be blank after Archived`);
+}
+
+// --- manifest seals
+const manifestPath = join(archivedDir, "manifest.json");
+interface Manifest { version: 1; files: Record<string, string>; }
+let manifest: Manifest = { version: 1, files: {} };
+if (existsSync(manifestPath)) {
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch {
+    fail("archived/manifest.json exists but is not valid JSON");
+  }
+} else if (files.length > 0 && !isWrite) {
+  fail("archived/manifest.json missing — run with --write to seal existing archived notes");
+}
+
+const sealOf = (relFromRoot: string) =>
+  `sha256:${createHash("sha256").update(readFileSync(join(agentNoteRoot, relFromRoot))).digest("hex")}`;
+
+for (const rel of files) {
+  const key = `archived/${rel}`;
+  const entry = manifest.files[key];
+  if (!entry) {
+    if (isWrite) {
+      manifest.files[key] = sealOf(key);
+    } else {
+      fail(`${key} — missing seal in manifest.json (run with --write)`);
+    }
+  } else if (entry !== sealOf(key)) {
+    fail(`${key} — seal mismatch: archived note was modified after sealing (frozen notes must never change)`);
+  }
+}
+for (const key of Object.keys(manifest.files)) {
+  if (!existsSync(join(agentNoteRoot, key))) fail(`${key} — sealed entry has no file on disk`);
+}
+
+// --- append-only vs git baseline (skipped without git)
+const repoRoot = (() => {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: agentNoteRoot, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
+})();
+if (repoRoot) {
+  const baseRef = process.env.AGENT_NOTE_ARCHIVE_BASE_REF || "HEAD";
+  const manifestRel = relative(repoRoot, manifestPath).split("\\").join("/");
+  let baselineRaw: string | null = null;
+  try {
+    baselineRaw = execFileSync("git", ["show", `${baseRef}:${manifestRel}`], { cwd: repoRoot, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    // manifest absent at baseline — nothing to compare
+  }
+  if (baselineRaw !== null) {
+    try {
+      const baseline = JSON.parse(baselineRaw) as Manifest;
+      for (const [key, seal] of Object.entries(baseline.files ?? {})) {
+        if (manifest.files[key] !== seal) {
+          fail(`${key} — seal added/changed/removed relative to ${baseRef}; archived seals are append-only`);
+        }
+      }
+    } catch {
+      fail(`archived/manifest.json at ${baseRef} was not valid JSON`);
+    }
+  }
+} else {
+  warnings.push("not a git repository — append-only check skipped (seal hashes still verified against disk)");
+}
+
+if (errors.length) {
+  for (const e of errors) console.error(`archived: ${e}`);
+  process.exit(1);
+}
+
+if (isWrite) {
+  const sorted = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a.localeCompare(b)));
+  writeFileSync(manifestPath, JSON.stringify({ version: 1, files: sorted }, null, 2) + "\n", "utf8");
+}
+
+for (const w of warnings) console.warn(`warning: ${w}`);
+console.log(`ok: ${files.length} archived note(s) verified, ${Object.keys(manifest.files).length} seal(s) in manifest`);

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/templates/implemented.md

@@ -0,0 +1,32 @@
+# Agent Note: <标题>
+
+Status: implemented
+
+<!--
+  【维护提醒】
+  1. 现行法律契约：代码重构、改名或路径变更时，同批就地更新事实。禁止把 Decision 改写成另一个决定。
+  2. 时态纪律：严禁 ## Proposal / ## Plan / ## Acceptance criteria 等计划态标题；Decision 用现在时（门禁只拒标题）。
+  3. 归档契约：只插 Archived: YYYY-MM-DD 紧邻 Status: implemented。互链写在新笔记，不写进归档篇。
+-->
+
+## Problem
+
+<动机：脱离方案也能独立成立。说明触发原因：什么破了、什么要变、不做会怎样>
+
+## Decision
+
+<已落地事实，全篇使用现在时描述。可插入 Package 拓扑 / 契约 / Schema 等业务自由小节>
+
+## Alternatives considered
+
+- **<备选 A>** — <先写其最强论据，再写为何被否>
+- **<备选 B>** — <先写其最强论据，再写为何被否。不做/复用仅当当时真的权衡过才写，不要编>
+
+## Consequences
+
+- **收益**：<带来了什么确定性提升，无基线不写相对量词>
+- **代价与已知上限**：<牺牲了什么，什么信号发生时必须重访该决定>
+
+## Verification
+
+<可选，现在时事实：如何证明该决定在当前代码库中依然生效。落到可确认表面——路径、量级、执行命令>

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/templates/proposed.md

@@ -0,0 +1,38 @@
+# Agent Note: <标题>
+
+Status: proposed
+
+<!--
+  【维护提醒】
+  1. 落地转 implemented 时的重写契约：## Proposal 改为现在时的 ## Decision；
+     ## Acceptance criteria / ## Risks 折进 ## Consequences（或现在时的 ## Testing / ## Verification）。
+  2. 前提消失或不再推进 → 转 Status: rejected — <原因>，严禁归档 proposed。
+  3. Alternatives 必填：只记录真实考虑过的对手方案；「不做/复用」仅当当时真的权衡过才写。
+-->
+
+## Problem
+
+<动机，脱离方案也能独立成立；写清背景、约束与失败条件>
+
+## Proposal
+
+<拟议改动，可用将来时；含关键设计、迁移步骤与开放问题>
+
+## Alternatives considered
+
+必填。只写当时真的权衡过的选项（没有过的不要编）。「不做 / 复用现状」可以是其中一档，但不是必填档。
+
+每档一个候选，或 `### Why not <X>?` 子节：
+
+- **<备选 A>** — <为何没选，先写它的最强论据再写否掉理由，一段一备选>
+- **<备选 B>** — <同上>
+
+需要结构化对比多个选项时，用标准 × 选项矩阵（Fit / 运维复杂度 / 团队技能 / 成本 / 锁定风险 / 实施时间）逐格打 ✓/⚠️/✗。被否项必带"为何否"。
+
+## Acceptance criteria
+
+<什么可观察状态算完成；含验证表面与门禁>
+
+## Risks
+
+<可能出什么问题、已知取舍与回滚条件>

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/templates/rejected.md

@@ -0,0 +1,27 @@
+# Agent Note: <标题>
+
+Status: rejected — <一句话原因>
+
+<!--
+  【维护提醒】
+  1. 冻结不动：不改写为对立面，不随代码演进更新事实；结论就在 Status 行。
+  2. 仅在"防止重犯"期间保留：被否方案依赖的旧技术/API 已彻底移除、后人绝无可能
+     再提时，把这一篇删掉。
+  3. 价值被新笔记吸收时，按 references/archiving.md 的合并删除流程处理。
+-->
+
+## Problem
+
+<动机>
+
+## Proposal
+
+<曾拟议的方案，冻结保留>
+
+## Alternatives considered
+
+- **<备选>** — <为何当时考虑/为何最终否掉>
+
+## Risks
+
+<为何否掉、若重提需满足什么条件>

package/vendor/write-notes-like-deepseek/skills/write-notes-like-deepseek/templates/verify-notes.yml

@@ -0,0 +1,38 @@
+# 复制到宿主仓库 .github/workflows/verify-notes.yml 后启用。
+# 默认项目级安装路径；使用其他路径时请同步修改下方命令。
+name: Verify Agent Notes
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Verify note tree, format, and archive seals
+        env:
+          # HEAD is a no-op on a clean checkout. Compare against the pre-change
+          # commit: PR base, or the previous tip of the pushed branch.
+          # A new-branch push sends before=0000…; git show fails and the script
+          # skips append-only (seal-vs-disk still runs).
+          AGENT_NOTE_ARCHIVE_BASE_REF: ${{ github.event.pull_request.base.sha || github.event.before }}
+        run: |
+          npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-tree.ts
+          npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-agent-note-format.ts
+          npx tsx .agents/skills/write-notes-like-deepseek/scripts/verify-archived-agent-notes.ts