@andares/pi-toolkits 0.9.8 → 0.11.0

package/src/features/init/templates/memory-readme.md

@@ -0,0 +1,99 @@
+# Agent memory framework v{{frameworkVersion}}
+
+This repository keeps agent memory in a fixed shape so that every session can find
+a fact in one place instead of re-deriving it, and so the memory does not grow into
+an unreadable pile. Read this file **before writing memory**; it is the rulebook,
+while `AGENTS.md` at the repository root is the entry point and index.
+
+## Where things live
+
+| Location | Answers | Lifetime |
+| --- | --- | --- |
+| `specs/PLAN.md` | What are we going to do, what is still open | rewritten as work moves |
+| `specs/<unit>.md` | One unit of work: requirement, approach, acceptance | written before work, status updated at close |
+| `.agents/memory/` | What is known, decided, and why | long-lived; append and compact only |
+| `.agents/implementations/` | What was changed, when, with what evidence | one record per change, never rewritten |
+| `.agents/prompts/` | The operator's own words (optional) | read-only input |
+
+## Memory files
+
+| File | Owns | Never holds |
+| --- | --- | --- |
+| `FINISHED.md` | Closed work: summary + evidence pointer + historical appendix | spec bodies, progress lists |
+| `FUTURE.md` | Deferred, rejected, waiting-for-a-trigger | schedule promises |
+| `ARCHITECTURE.md` | Layering, version baseline, decision records, investigation archive | visual specs, progress |
+| `DESIGN.md` | Visual single source of truth: tokens, palette, spacing, component looks | implementation details |
+| `TERMS.md` | Glossary and the rules that tell look-alike terms apart | visual specs |
+| `REVIEW.md` | Review ledger: judgement, trade-off, destination | a second copy of a spec |
+| `DEBUGGING.md` | Runtime diagnosis runbook | code facts |
+| `FUNCTION-<MODULE>.md` | One module's functional rules | copies of another module's rules |
+
+No file is created before it has content. Files not listed here are not memory.
+
+## Write rules
+
+1. **One fact, one home.** Detail lives in the file that owns it; everywhere else
+   is a pointer (`path#section`). If you are about to restate a fact, write a
+   pointer instead.
+2. **AGENTS.md holds only what every session needs**: invariants, commands,
+   routing, the index. Anything that can be looked up does not belong there.
+3. **Record conclusions and constraints, not narration.** No chat transcripts, no
+   "first I did X, then Y".
+4. **Append and compact; never rewrite history to look better.** Change records
+   are written once. The single exception: a directory move may update the path
+   strings inside them, and that must be listed in the migration report.
+5. **Date every stale-able claim** (versions, measurements, "currently"). An
+   unmeasured claim is `inference` or `TBD`, never a fact.
+6. **Keep the operator's decisions verbatim** (quote + date + who). They are the
+   most expensive thing to reconstruct.
+7. **Progress lives in the todo tool.** No second progress table in any document.
+8. **Specs precede work; records follow it.** Close a spec honestly (status line);
+   never delete it — archive it and leave a link when superseded.
+9. **Compress before you append.** Over budget means compact first, then add.
+10. **No secrets, credentials, or personal paths** in memory. Evidence you would
+    not publish does not belong here.
+
+## Budgets
+
+| What | Limit | Why |
+| --- | --- | --- |
+| `AGENTS.md` | soft {{softBudget}} chars, hard {{hardBudget}} | paid on **every** request |
+| one memory file | {{memoryBudget}} chars | navigability, not tokens |
+| change records | {{implementationsBudget}} files | roll up and archive past this |
+
+The audit reports overruns. Overrunning is not an emergency; growing without a
+compaction plan is.
+
+## Compaction recipes
+
+| File | How to shrink it |
+| --- | --- |
+| `specs/PLAN.md` | Move closed items to `FINISHED.md` as a 3-8 line summary + pointer |
+| `FINISHED.md` | Keep milestone summaries + pointers; move whole eras to `.agents/memory/archive/<year>/` |
+| `FUTURE.md` | Every entry needs a trigger; adopted → `specs/PLAN.md` + one-line pointer; unreachable → mark dropped with a date |
+| `ARCHITECTURE.md` | Decisions are append-only (context / decision / consequence / date); supersede, do not delete |
+| `FUNCTION-<MODULE>.md` | Split by sub-domain past budget; move dating measurements into a measurement appendix |
+| `REVIEW.md` | One section per round; the overview table is the only summary; fold old rounds into an appendix |
+| change records | Roll up per milestone into `FINISHED.md`, then move originals to `.agents/implementations/archive/<year>/` |
+
+## Audit
+
+`/ask-init check` (or the `framework_audit` tool during an init run) reports:
+
+- structure: missing files, index ↔ file mismatches, `AGENTS.override.md` shadowing
+- paths: references to `memory` or `implementations` without the `.agents/` prefix (a move would break them)
+- duplication: the same section heading in two files (one fact, two homes)
+- order: sections appended after the historical appendix
+- budgets: `AGENTS.md` and memory-file sizes
+- state: `PLAN.md` ↔ specs drift, stale `todos/`, `FUTURE.md` entries with no trigger
+- evidence: `FINISHED.md` entries without a change-record pointer
+
+Codes are stable (`E-…`, `W-…`, `I-…`), so reports can be compared across runs.
+
+## Upgrading the framework
+
+`.agents/framework/state.toml` records the framework version. When this file's
+version is newer than the state file, `/ask-init` plans an upgrade: deterministic
+steps run in code, prose changes are handed to the model as tasks. A project whose
+state version is newer than the installed tool is never migrated — upgrade the
+tool instead.

package/src/features/init/templates/signpost.md

@@ -0,0 +1,15 @@
+# `.agents/` — agent-facing material
+
+Everything in this directory exists for the agent, not for the application: it is
+committed (except the runtime folders ignored by `framework/.gitignore`) and
+reviewed by humans, but it is not part of the shipped product.
+
+| Directory | What it is |
+| --- | --- |
+| `.agents/memory/` | Long-lived memory: decisions, constraints, finished work, deferred ideas. Rules: `.agents/memory/README.md` |
+| `.agents/implementations/` | One record per change (what changed, why, evidence) |
+| `.agents/prompts/` | The operator's own words, verbatim (optional; often local-only) |
+| `.agents/framework/` | Tool state for `/ask-init`: `state.toml`, snapshots, plans, reports |
+
+The entry point every session reads is `AGENTS.md` in the repository root.
+Memory is not loaded automatically; it is read on demand from the index there.

package/src/features/init/templates/state-gitignore

@@ -0,0 +1,6 @@
+# Runtime state, not memory.
+# Snapshots are copies of what a migration touched; plans and reports are the
+# transient output of one run. None of it belongs in version control.
+snapshots/
+plans/
+reports/

package/src/features/init/templates.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { countBareRefs } from "./detect.js";
+import { renderTemplate, templateNames } from "./templates.js";
+
+const TOKENS: Record<string, string> = {
+	project: "demo",
+	date: "2026-10-26",
+	contract: "> Memory contract (agent-framework v1).",
+	docTitle: "project guide (AGENTS.md)",
+	softBudget: "12000",
+	hardBudget: "20000",
+	memoryBudget: "80000",
+	implementationsBudget: "200",
+	index: "| File | Owns | Read when |\n| --- | --- | --- |\n| `specs/PLAN.md` | route | before work |",
+	roots: "",
+	frameworkVersion: "1",
+	statePath: ".agents/framework/state.toml",
+	contractPath: ".agents/memory/README.md",
+	implementationsDir: ".agents/implementations",
+	h_what: "What this is",
+	h_rules: "Hard rules",
+	h_commands: "Commands",
+	h_layout: "Layout",
+	h_index: "Plan and memory index",
+	h_impact: "Change impact index",
+	h_roots: "Workspace roots",
+	h_terms: "Terms",
+	h_maintenance: "Framework maintenance",
+};
+
+describe("templates", () => {
+	it("renders every shipped template without leaving placeholders", () => {
+		for (const name of templateNames()) {
+			const text = renderTemplate(name, TOKENS, "en");
+			expect(text, name).not.toMatch(/\{\{/);
+			expect(text.length, name).toBeGreaterThan(20);
+		}
+	});
+
+	it("renders the localized seeds", () => {
+		expect(renderTemplate("seed-finished", TOKENS, "zh")).toContain("# 已完成");
+		expect(renderTemplate("plan", TOKENS, "zh")).toContain("# 计划");
+		expect(renderTemplate("seed-architecture", TOKENS, "en")).toContain("# Architecture");
+	});
+
+	it("keeps the shipped contract free of legacy path references", () => {
+		for (const name of ["memory-readme", "signpost", "agents-skeleton"]) {
+			const text = renderTemplate(name, TOKENS, "en");
+			expect(countBareRefs(text, "memory/"), name).toBe(0);
+			expect(countBareRefs(text, "implementations/"), name).toBe(0);
+		}
+	});
+
+	it("fails loudly instead of writing an unresolved placeholder", () => {
+		expect(() => renderTemplate("agents-skeleton", {}, "en")).toThrow(/no value for/);
+		expect(() => renderTemplate("nope", TOKENS, "en")).toThrow(/unknown template/);
+	});
+});

package/src/features/init/templates.ts

@@ -0,0 +1,79 @@
+/**
+ * init feature — template loading and substitution.
+ *
+ * Templates fall into two groups:
+ *  - files under `templates/` (shipped with the package, path-resolved from
+ *    `import.meta.url` so a global install works);
+ *  - seeds that live in code because they are localized (`SEEDS`, `PLAN_SEED`).
+ *
+ * A rendered template must never leak `{{token}}` syntax into a project, so the
+ * loader fails loudly on an unresolved placeholder instead of writing it.
+ */
+import { readFileSync } from "node:fs";
+import {
+	PLAN_SEED,
+	SEEDS,
+	type ProjectLanguage,
+} from "./spec.js";
+
+const FILE_TEMPLATES = new Set([
+	"agents-skeleton",
+	"memory-readme",
+	"signpost",
+	"state-gitignore",
+]);
+
+/** Templates whose content is not Markdown (written verbatim). */
+const RAW_TEMPLATES = new Set(["state-gitignore"]);
+
+const SEED_TEMPLATES = new Set([
+	"seed-finished",
+	"seed-future",
+	"seed-architecture",
+]);
+
+export function templateNames(): string[] {
+	return [...FILE_TEMPLATES, ...SEED_TEMPLATES, "plan"];
+}
+
+/** Collapse runs of blank lines left behind by empty optional sections. */
+function tidy(text: string): string {
+	return `${text.replace(/\n{3,}/g, "\n\n").replace(/[ \t]+\n/g, "\n").trimEnd()}\n`;
+}
+
+export function renderTemplate(
+	name: string,
+	tokens: Record<string, string>,
+	language: ProjectLanguage,
+): string {
+	let body: string;
+	if (name === "plan") {
+		body = PLAN_SEED[language];
+	} else if (name.startsWith("seed-")) {
+		const role = name.slice("seed-".length);
+		body = SEEDS[language][role] ?? "";
+		if (body.length === 0) throw new Error(`unknown seed template: ${name}`);
+	} else if (FILE_TEMPLATES.has(name)) {
+		// `.gitignore` content is not Markdown; keep it extension-less so Markdown
+		// linters do not read its `#` comments as headings.
+		const suffix = RAW_TEMPLATES.has(name) ? "" : ".md";
+		body = readFileSync(new URL(`./templates/${name}${suffix}`, import.meta.url), "utf8");
+	} else {
+		throw new Error(
+			`unknown template "${name}" (known: ${templateNames().join(", ")})`,
+		);
+	}
+
+	const rendered = body.replace(/\{\{\s*([\w.]+)\s*\}\}/g, (_match, key: string) => {
+		const value = tokens[key];
+		if (value === undefined) {
+			throw new Error(`template "${name}" has no value for {{${key}}}`);
+		}
+		return value;
+	});
+
+	if (/\{\{/.test(rendered)) {
+		throw new Error(`template "${name}" left a placeholder unresolved`);
+	}
+	return tidy(rendered);
+}

package/src/features/init/test-helpers.ts

@@ -0,0 +1,89 @@
+/**
+ * Test helpers for the init feature. Kept in `src/` (like the tests themselves)
+ * so the published package and the test run see the same files; nothing here is
+ * imported by the extension at runtime.
+ */
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+/** Create a throw-away project from a path → content map. */
+export function project(files: Record<string, string>): string {
+	const root = mkdtempSync(join(tmpdir(), "pi-init-"));
+	for (const [rel, content] of Object.entries(files)) {
+		const absolute = join(root, rel);
+		mkdirSync(dirname(absolute), { recursive: true });
+		writeFileSync(absolute, content, "utf8");
+	}
+	return root;
+}
+
+export function remove(root: string): void {
+	rmSync(root, { recursive: true, force: true });
+}
+
+/** `git init` + add + commit, for tests that need tracked files. */
+export function gitProject(files: Record<string, string>, message = "init"): string {
+	const root = project(files);
+	execFileSync("git", ["-C", root, "init", "-q"], { stdio: "ignore" });
+	execFileSync("git", ["-C", root, "add", "-A"], { stdio: "ignore" });
+	execFileSync(
+		"git",
+		[
+			"-C",
+			root,
+			"-c",
+			"user.email=test@example.com",
+			"-c",
+			"user.name=test",
+			"commit",
+			"-q",
+			"-m",
+			message,
+		],
+		{ stdio: "ignore" },
+	);
+	return root;
+}
+
+/** An installed-looking framework (state + contract + canonical dirs). */
+export function installedProject(extra: Record<string, string> = {}): string {
+	return project({
+		"AGENTS.md": [
+			"# demo — project guide",
+			"",
+			"> Memory contract (agent-framework v1): one fact, one home.",
+			"",
+			"## 1. What this is",
+			"",
+			"A demo project.",
+			"",
+			"## 5. Plan and memory index",
+			"",
+			"| File | Owns | Read when |",
+			"| --- | --- | --- |",
+			"| `specs/PLAN.md` | route | before work |",
+			"| `.agents/memory/FINISHED.md` | closed work | closing |",
+			"",
+		].join("\n"),
+		"specs/PLAN.md": "# Plan (open work)\n\n## Route\n\n_None._\n",
+		".agents/memory/README.md": "# Agent memory framework v1\n\nRules.\n",
+		".agents/memory/FINISHED.md": "# Finished work\n\n## Summary\n\n_None._\n",
+		".agents/memory/FUTURE.md": "# Future and deferred\n\n_None._\n",
+		".agents/memory/ARCHITECTURE.md": "# Architecture\n\n## Layering\n\n_None._\n",
+		".agents/implementations/2026-01-01_init.md":
+			"# init\n\n完成时间：2026-01-01 00:00:00\n\n## 范围\n\nInitial.\n",
+		".agents/framework/state.toml": [
+			"version = 1",
+			'tool = "0.0.0-test"',
+			'created = "2026-01-01T00:00:00+08:00"',
+			'updated = "2026-01-01T00:00:00+08:00"',
+			'profile = "core"',
+			"modules = []",
+			'lang = "en"',
+			"",
+		].join("\n"),
+		...extra,
+	});
+}

package/src/features/init/tool.ts

@@ -0,0 +1,72 @@
+/**
+ * init feature — the `framework_audit` tool.
+ *
+ * Registered inactive and activated for the duration of an init run, so the
+ * model can close its own loop: edit → audit → fix the `E-*` findings and the
+ * open coverage rows before reporting. Outside such a run it stays out of the
+ * tool list; the human entry point is `/ask-init check`.
+ *
+ * Read-only: it never writes, so it is safe to call at any point.
+ */
+import { Type } from "typebox";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { detect } from "./detect.js";
+import { audit, countFindings, renderFindings } from "./audit.js";
+import { FRAMEWORK_VERSION } from "./spec.js";
+
+export const FRAMEWORK_AUDIT_TOOL = "framework_audit";
+
+const PARAMS = Type.Object({});
+
+const DESCRIPTION = `Audit this repository's agent-memory framework (read-only).
+
+Checks the layout under .agents/ and specs/, budgets, duplicated section headings,
+appendix ordering, bare path references, plan/spec drift, stale zero-byte files and
+the migration coverage table. Findings carry stable codes: E-* must be fixed, W-* are
+warnings that should either be fixed or recorded in specs/PLAN.md, I-* are informational.
+
+Use it after writing or moving memory files, and before reporting an init/migration
+run as complete.`;
+
+const GUIDELINES = [
+	"After any init or migration edit, run `framework_audit` and fix every E-* finding and every OPEN coverage row before reporting completion.",
+];
+
+export function registerAuditTool(pi: ExtensionAPI): void {
+	pi.registerTool<typeof PARAMS, { errors: number; warnings: number; infos: number }>({
+		name: FRAMEWORK_AUDIT_TOOL,
+		label: "Framework audit",
+		description: DESCRIPTION,
+		promptSnippet: "Audit the agent-memory framework layout (read-only)",
+		promptGuidelines: GUIDELINES,
+		parameters: PARAMS,
+		defaultActive: false,
+		annotations: { readOnlyHint: true, idempotentHint: true },
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			try {
+				const facts = detect(ctx.cwd);
+				const findings = audit(facts);
+				const counts = countFindings(findings);
+				return {
+					content: [
+						{
+							type: "text" as const,
+							text: renderFindings(findings, {
+								root: ctx.cwd,
+								frameworkVersion: FRAMEWORK_VERSION,
+							}),
+						},
+					],
+					details: counts,
+				};
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return {
+					content: [{ type: "text" as const, text: `framework_audit: ${message}` }],
+					details: { errors: 1, warnings: 0, infos: 0 },
+					isError: true,
+				};
+			}
+		},
+	});
+}