@andares/pi-toolkits 0.10.0 → 0.11.0

package/src/features/init/render.ts

@@ -0,0 +1,131 @@
+/**
+ * init feature — markdown fragments shared by the plan, the scaffold and the
+ * work order. Kept language-aware: the framework's own text is English, but
+ * anything written into a project follows that project's language.
+ */
+import {
+	MEMORY_DIR,
+	MEMORY_FILES,
+	PLAN_FILE,
+	SPECS_DIR,
+	type MemoryRole,
+	type ProjectLanguage,
+} from "./spec.js";
+import type { Facts, RootInfo } from "./types.js";
+
+const READ_WHEN: Record<MemoryRole, { zh: string; en: string }> = {
+	contract: { zh: "写记忆之前", en: "before writing memory" },
+	finished: { zh: "收口工作、查历史证据", en: "closing work, tracing evidence" },
+	future: { zh: "决定延期/放弃之前", en: "before deferring or rejecting work" },
+	architecture: { zh: "改分层、选型、跨模块改动前", en: "layering, versions, cross-module changes" },
+	design: { zh: "动界面视觉之前", en: "before touching visual design" },
+	terms: { zh: "命名、文案、界面术语之前", en: "naming, copy, UI terminology" },
+	review: { zh: "周期性评审、方向修正", en: "periodic review, direction changes" },
+	debugging: { zh: "排查运行期问题", en: "diagnosing runtime problems" },
+	function: { zh: "改这个模块的功能之前", en: "before changing that module" },
+};
+
+const INDEX_TITLES: Record<ProjectLanguage, { plan: string; memory: string; none: string }> = {
+	zh: { plan: "计划", memory: "记忆", none: "_（尚未出现）_" },
+	en: { plan: "Plan", memory: "Memory", none: "_(none yet)_" },
+};
+
+/** Rows for the plan table of the AGENTS.md index. */
+export function planIndexRows(language: ProjectLanguage): string[] {
+	if (language === "zh") {
+		return [
+			`| \`${PLAN_FILE}\` | 路线级计划与未决问题 | 开工前 |`,
+			`| \`${SPECS_DIR}/<unit>.md\` | 单工作单元：需求原文 / 方案 / 验收清单 | 做这个单元时 |`,
+		];
+	}
+	return [
+		`| \`${PLAN_FILE}\` | Route-level plan and open questions | before starting work |`,
+		`| \`${SPECS_DIR}/<unit>.md\` | One unit of work: requirement / approach / acceptance | when doing that unit |`,
+	];
+}
+
+/** Rows for the memory table: files that exist now plus the core ones created now. */
+export function memoryIndexRows(
+	facts: Facts,
+	language: ProjectLanguage,
+	created: ReadonlySet<string>,
+): string[] {
+	const rows: string[] = [];
+	for (const spec of MEMORY_FILES) {
+		const rel = `${MEMORY_DIR}/${spec.file}`;
+		const present = facts.memory.some((doc) => doc.rel === rel);
+		const legacyPresent = facts.legacyMemory.some(
+			(doc) => doc.rel === `memory/${spec.file}`,
+		);
+		const willExist = present || legacyPresent || created.has(rel);
+		if (!willExist) continue;
+		const label = spec.file.startsWith("FUNCTION-")
+			? `${MEMORY_DIR}/FUNCTION-<MODULE>.md`
+			: rel;
+		rows.push(
+			language === "zh"
+				? `| \`${label}\` | ${spec.owns} | ${READ_WHEN[spec.role].zh} |`
+				: `| \`${label}\` | ${spec.owns} | ${READ_WHEN[spec.role].en} |`,
+		);
+	}
+	if (created.has(`${MEMORY_DIR}/README.md`)) {
+		rows.unshift(
+			language === "zh"
+				? `| \`${MEMORY_DIR}/README.md\` | 框架契约：文件职责、写入规则、预算、压缩法 | 写记忆之前 |`
+				: `| \`${MEMORY_DIR}/README.md\` | Framework contract: roles, write rules, budgets, compaction | before writing memory |`,
+		);
+	}
+	return rows;
+}
+
+/** The AGENTS.md index body (two labelled tables). */
+export function indexBlock(
+	facts: Facts,
+	language: ProjectLanguage,
+	created: ReadonlySet<string>,
+): string {
+	const titles = INDEX_TITLES[language];
+	const planRows = planIndexRows(language);
+	const memoryRows = memoryIndexRows(facts, language, created);
+	const header =
+		language === "zh" ? "| 文件 | 拥有什么 | 何时读 |\n| --- | --- | --- |" : "| File | Owns | Read when |\n| --- | --- | --- |";
+	const parts = [
+		`### ${titles.plan}`,
+		"",
+		header,
+		...planRows,
+		"",
+		`### ${titles.memory}`,
+		"",
+		header,
+		...(memoryRows.length > 0 ? memoryRows : [titles.none]),
+	];
+	return parts.join("\n");
+}
+
+/** The workspace-roots section, or an empty string when there are no roots. */
+export function rootsBlock(roots: readonly RootInfo[], language: ProjectLanguage): string {
+	if (roots.length === 0) return "";
+	const title = language === "zh" ? "工作区根（多仓库）" : "Workspace roots";
+	const note =
+		language === "zh"
+			? "> 记忆只住在主仓；下列目录的 `AGENTS.md` 只写本仓职责与本仓命令（≤30 行），不复制规则。"
+			: "> Memory lives in the main repository only. A listed root's `AGENTS.md` states its role and commands (≤30 lines), never a copy of the rules.";
+	const header =
+		language === "zh"
+			? "| 根 | 路径 | 职责 | 它的记忆 |\n| --- | --- | --- | --- |"
+			: "| Root | Path | Role | Its memory |\n| --- | --- | --- | --- |";
+	const rows = roots.map((root) => {
+		const memory =
+			root.agentsMd === "independent"
+				? language === "zh"
+					? "独立项目（自带记忆，不接管）"
+					: "independent project (owns its memory)"
+				: language === "zh"
+					? `主仓 \`${MEMORY_DIR}/\``
+					: `main repo \`${MEMORY_DIR}/\``;
+		const role = root.role ?? (language === "zh" ? "待补充" : "to be filled in");
+		return `| ${root.label} | \`${root.path}\`${root.exists ? "" : " (missing)"} | ${role} | ${memory} |`;
+	});
+	return [`## ${title}`, "", note, "", header, ...rows, ""].join("\n");
+}

package/src/features/init/spec.ts

@@ -0,0 +1,429 @@
+/**
+ * init feature — the agent-framework contract, as data.
+ *
+ * This file is the single source of truth for *where* the framework lives and
+ * *what it expects*. Everything else (detect / plan / apply / audit) reads it,
+ * so a layout change is one edit here plus a migration recipe.
+ *
+ * Layout principle (operator decision, 2026-10-26):
+ *   - purely agent-facing content lives under `.agents/` (hidden, less noise at
+ *     the repo root);
+ *   - content people read stays at the root (`specs/`, `design/`, `docs/`, `legal/`).
+ *
+ * The three-way split is deliberate:
+ *   `specs/`                    — the plan: what to do, how to accept it
+ *   `.agents/memory/`           — memory: what is known, decided, why
+ *   `.agents/implementations/`  — evidence: what was changed, when, with proof
+ *   `.agents/prompts/`          — input: the operator's own words (optional)
+ *
+ * `todos/` is retired: a requirement becomes a spec, and the verbatim wording
+ * goes into that spec's "requirement" section instead of a second directory.
+ */
+
+/** Bump when the contract changes in a way existing projects must migrate. */
+export const FRAMEWORK_VERSION = 1;
+
+/** Identity written into state and reports. */
+export const FRAMEWORK_ID = "agent-framework";
+
+/* -------------------------------------------------------------------------- */
+/* Paths                                                                       */
+/* -------------------------------------------------------------------------- */
+
+export const AGENTS_FILE = "AGENTS.md";
+export const CLAUDE_FILE = "CLAUDE.md";
+export const OVERRIDE_FILE = "AGENTS.override.md";
+
+/** Hidden home of everything that exists only for the agent. */
+export const AGENTS_DIR = ".agents";
+export const MEMORY_DIR = ".agents/memory";
+export const IMPLEMENTATIONS_DIR = ".agents/implementations";
+export const PROMPTS_DIR = ".agents/prompts";
+export const FRAMEWORK_DIR = ".agents/framework";
+
+export const STATE_FILE = ".agents/framework/state.toml";
+export const STATE_GITIGNORE = ".agents/framework/.gitignore";
+export const SNAPSHOTS_DIR = ".agents/framework/snapshots";
+export const PLANS_DIR = ".agents/framework/plans";
+export const REPORTS_DIR = ".agents/framework/reports";
+
+/** The plan home stays at the root: humans review it. */
+export const SPECS_DIR = "specs";
+export const PLAN_FILE = "specs/PLAN.md";
+
+/** The contract every agent reads before writing memory. */
+export const CONTRACT_FILE = ".agents/memory/README.md";
+/** A one-screen signpost for whoever opens `.agents/` first. */
+export const SIGNPOST_FILE = ".agents/README.md";
+/** Optional cascade of remembered decisions and functional specs. */
+export const FUNCTION_PREFIX = "FUNCTION-";
+
+/** Root-level plan/requirement files this framework supersedes. */
+export const LEGACY_DOC_NAMES = [
+	"TODO.md",
+	"TASKS.md",
+	"ROADMAP.md",
+	"NOTES.md",
+	"DEVNOTES.md",
+	"DEVELOPMENT.md",
+	"PLAN.md",
+];
+
+/** Directories that belong under `.agents/` in this framework. */
+export const DEPRECATED_ROOT_DIRS = ["memory", "implementations", "prompts"] as const;
+
+/** Retired entirely: requirement wording moves into `specs/<unit>.md`. */
+export const RETIRED_ROOT_DIRS = ["todos"] as const;
+
+/* -------------------------------------------------------------------------- */
+/* Budgets                                                                     */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * AGENTS.md is paid for on *every* request, so it is the one file with a hard
+ * budget. `memory/*.md` is read on demand: its budget is about navigability,
+ * not tokens.
+ */
+export const BUDGETS = {
+	/** Soft ceiling: the audit starts warning here. */
+	agentsMdSoftChars: 12_000,
+	/** Hard ceiling: the plan records the overflow as debt that must be paid. */
+	agentsMdHardChars: 20_000,
+	/** A memory file past this is hard to navigate; split or archive. */
+	memoryFileChars: 80_000,
+	/** Above this many change records, roll old ones up and archive them. */
+	implementationsFiles: 200,
+} as const;
+
+/* -------------------------------------------------------------------------- */
+/* Memory files                                                                */
+/* -------------------------------------------------------------------------- */
+
+export type MemoryRole =
+	| "contract"
+	| "finished"
+	| "future"
+	| "architecture"
+	| "design"
+	| "terms"
+	| "review"
+	| "debugging"
+	| "function";
+
+export interface MemoryFileSpec {
+	/** File name inside `.agents/memory/` (or `FUNCTION-*` pattern). */
+	readonly file: string;
+	readonly role: MemoryRole;
+	/** Always created (with a short seed) versus lazily on first use. */
+	readonly core: boolean;
+	/** One-line "owns what", used in plans, seeds and the index. */
+	readonly owns: string;
+	/** What must never be written there. */
+	readonly never: string;
+}
+
+export const MEMORY_FILES: readonly MemoryFileSpec[] = [
+	{
+		file: "FINISHED.md",
+		role: "finished",
+		core: true,
+		owns: "closed work: summary + evidence pointer + historical appendices",
+		never: "spec bodies, duplicated progress lists",
+	},
+	{
+		file: "FUTURE.md",
+		role: "future",
+		core: true,
+		owns: "deferred / rejected / waiting-for-a-trigger registry",
+		never: "schedule promises, half-plans that belong in specs/",
+	},
+	{
+		file: "ARCHITECTURE.md",
+		role: "architecture",
+		core: true,
+		owns: "layering, version baseline, decision records, investigation archive",
+		never: "visual specs, progress, functional behaviour owned by FUNCTION-*",
+	},
+	{
+		file: "DESIGN.md",
+		role: "design",
+		core: false,
+		owns: "visual single source of truth: tokens, palette, spacing, component looks",
+		never: "implementation details, component inventories",
+	},
+	{
+		file: "TERMS.md",
+		role: "terms",
+		core: false,
+		owns: "glossary and the discriminating rules behind each term",
+		never: "visual specs, API documentation",
+	},
+	{
+		file: "REVIEW.md",
+		role: "review",
+		core: false,
+		owns: "review ledger: judgement, trade-off, destination",
+		never: "a second copy of any spec",
+	},
+	{
+		file: "DEBUGGING.md",
+		role: "debugging",
+		core: false,
+		owns: "runtime diagnosis runbook (logs, crash dumps, live attach)",
+		never: "code facts that belong in ARCHITECTURE",
+	},
+	{
+		file: "FUNCTION-<MODULE>.md",
+		role: "function",
+		core: false,
+		owns: "one module's functional specification and its exact rules",
+		never: "copies of another module's rules",
+	},
+];
+
+/** Memory file names that are recognised when auditing an existing project. */
+export function isMemoryFileName(name: string): boolean {
+	if (MEMORY_FILES.some((spec) => spec.file === name)) return true;
+	return name.startsWith(FUNCTION_PREFIX) && name.endsWith(".md");
+}
+
+/* -------------------------------------------------------------------------- */
+/* Optional root modules                                                       */
+/* -------------------------------------------------------------------------- */
+
+export interface RootModuleSpec {
+	readonly dir: string;
+	/** What the directory is for, in one line (English: shipped text). */
+	readonly owns: string;
+}
+
+export const ROOT_MODULES: readonly RootModuleSpec[] = [
+	{ dir: "specs", owns: "plans and unit specs (the plan home)" },
+	{ dir: "design", owns: "design sources and their paired notes" },
+	{ dir: "docs", owns: "user- and contributor-facing documentation" },
+	{ dir: "legal", owns: "license originals, third-party notices and provenance" },
+];
+
+/* -------------------------------------------------------------------------- */
+/* Scan limits                                                                 */
+/* -------------------------------------------------------------------------- */
+
+export const SCAN = {
+	/** Files bigger than this are read for metadata only, never for content. */
+	maxFileBytes: 1_500_000,
+	/** Cap the tree walk so a runaway repo cannot stall the command. */
+	maxFiles: 20_000,
+	/** Depth for the generic walk. */
+	maxDepth: 6,
+	/** Directory names never descended into. */
+	ignoreDirs: new Set([
+		".git",
+		"node_modules",
+		"target",
+		"dist",
+		"build",
+		"out",
+		"release-out",
+		".venv",
+		"venv",
+		"__pycache__",
+		".cache",
+		".turbo",
+		".next",
+		"coverage",
+		".pytest_cache",
+		".mypy_cache",
+	]),
+	/** Text extensions counted for path references. */
+	refExtensions: new Set([
+		".md",
+		".mdx",
+		".ts",
+		".tsx",
+		".js",
+		".mjs",
+		".cjs",
+		".mts",
+		".cts",
+		".rs",
+		".toml",
+		".json",
+		".yml",
+		".yaml",
+		".txt",
+		".html",
+		".css",
+		".scss",
+		".py",
+		".sh",
+		".fish",
+		".pd",
+		".nix",
+		".go",
+		".java",
+		".kt",
+		".swift",
+		".c",
+		".h",
+		".cc",
+		".cpp",
+	]),
+} as const;
+
+/* -------------------------------------------------------------------------- */
+/* Audit vocabulary                                                            */
+/* -------------------------------------------------------------------------- */
+
+export const AUDIT_CODES = {
+	pathBareRef: "E-PATH-01",
+	stateUntracked: "E-STATE-01",
+	stateUncommitted: "W-STATE-01",
+	stateVersion: "E-STATE-02",
+	indexMismatch: "E-INDEX-01",
+	brokenLink: "E-LINK-01",
+	rootAgentDir: "W-ROOT-01",
+	rootEmptyFile: "W-ROOT-02",
+	rootMissing: "W-ROOT-03",
+	rootCardTooBig: "W-ROOT-04",
+	todosRemain: "W-TODO-01",
+	budgetAgents: "W-BUDGET-01",
+	budgetMemory: "W-BUDGET-02",
+	duplicateFact: "W-DUP-01",
+	appendixOrder: "W-ORDER-01",
+	coverageOpen: "W-COV-01",
+	futureNoTrigger: "W-META-01",
+	finishedNoEvidence: "W-EVID-01",
+	overrideContext: "W-OVERRIDE-01",
+	contractMissing: "E-CONTRACT-01",
+	scaffoldLeftover: "W-SCAFFOLD-01",
+	agentsSkills: "I-AGENTS-01",
+	notInstalled: "I-INSTALL-01",
+	planSpecDrift: "W-PLAN-01",
+} as const;
+
+export type AuditCode = (typeof AUDIT_CODES)[keyof typeof AUDIT_CODES];
+
+/* -------------------------------------------------------------------------- */
+/* Messages                                                                    */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Framework-owned text (contract, plan headers, audit codes) ships in English:
+ * it is read by models and published on npm. Text *written into a project*
+ * follows that project's language (`zh` when its docs are mostly CJK).
+ */
+export type ProjectLanguage = "zh" | "en";
+
+/** Seed bodies for core memory files, kept deliberately tiny. */
+export const SEEDS: Record<ProjectLanguage, Record<string, string>> = {
+	en: {
+		finished: [
+			"# Finished work",
+			"",
+			"> Closed work only: a summary, the evidence pointer, and the historical appendix.",
+			"> Never restate a spec here; link to it. Never keep an open item here.",
+			"",
+			"## Summary",
+			"",
+			"_Nothing closed yet._",
+			"",
+		].join("\n"),
+		future: [
+			"# Future and deferred",
+			"",
+			"> Every entry needs: what, why it waits, and the trigger that would bring it back.",
+			"> Adopted entries move to `specs/PLAN.md` and leave a one-line pointer behind.",
+			"",
+			"_Nothing registered yet._",
+			"",
+		].join("\n"),
+		architecture: [
+			"# Architecture",
+			"",
+			"> Layering, version baseline, decision records (context / decision / consequence / date)",
+			"> and the investigation archive. One fact, one home.",
+			"",
+			"## Layering",
+			"",
+			"_To be filled in by the init run (evidence only — read the code, do not guess)._",
+			"",
+			"## Decisions",
+			"",
+			"_No decisions recorded yet._",
+			"",
+		].join("\n"),
+	},
+	zh: {
+		finished: [
+			"# 已完成",
+			"",
+			"> 只放已收口的工作：摘要、证据指针、历史附录。",
+			"> 不在这里重述规格（给指针），也不留未完成项。",
+			"",
+			"## 摘要",
+			"",
+			"_还没有已收口的条目。_",
+			"",
+		].join("\n"),
+		future: [
+			"# 远期与延期",
+			"",
+			"> 每条必须写清：是什么、为什么等、什么条件会把它拉回来（触发条件）。",
+			"> 被采纳的条目移入 `specs/PLAN.md`，这里留一行指针。",
+			"",
+			"_还没有登记。_",
+			"",
+		].join("\n"),
+		architecture: [
+			"# 架构与决策",
+			"",
+			"> 分层、版本基线、决策记录（背景 / 决定 / 后果 / 日期）与调研存档。一个事实一个家。",
+			"",
+			"## 分层",
+			"",
+			"_由初始化那一轮填（只写读到的证据，不许猜）。_",
+			"",
+			"## 决策记录",
+			"",
+			"_还没有决策。_",
+			"",
+		].join("\n"),
+	},
+};
+
+/** Seed body for `specs/PLAN.md`. */
+export const PLAN_SEED: Record<ProjectLanguage, string> = {
+	en: [
+		"# Plan (open work)",
+		"",
+		"> Route-level plan and open questions only. A unit of work gets its own",
+		"> `specs/<unit>.md` before implementation starts; closed work moves to",
+		"> `.agents/memory/FINISHED.md` as a summary plus an evidence pointer.",
+		"> Progress itself lives in the todo tool — never here.",
+		"",
+		"## Route",
+		"",
+		"_No milestones recorded yet._",
+		"",
+		"## Open questions",
+		"",
+		"_None._",
+		"",
+	].join("\n"),
+	zh: [
+		"# 计划（未完成）",
+		"",
+		"> 只放路线级计划与未决问题。每个工作单元开工前单独写 `specs/<unit>.md`；",
+		"> 已收口的工作移入 `.agents/memory/FINISHED.md`，只留摘要与证据指针。",
+		"> 进度本身只在 todo 工具里——这里不写。",
+		"",
+		"## 路线",
+		"",
+		"_还没有里程碑。_",
+		"",
+		"## 未决问题",
+		"",
+		"_无。_",
+		"",
+	].join("\n"),
+};

package/src/features/init/templates/agents-skeleton.md

@@ -0,0 +1,44 @@
+# {{project}} — {{docTitle}}
+
+{{contract}}
+
+> Created {{date}} by `/ask-init` (agent-framework v{{frameworkVersion}}).
+<!-- TODO(ask-init): remove this line after reviewing the guide. -->
+
+## {{h_what}}
+
+<!-- TODO(ask-init): one short paragraph: what this project is, who it serves, what it is not. Evidence only. -->
+
+## {{h_rules}}
+
+<!-- TODO(ask-init): numbered invariants. Each ≤2 lines; a rule that needs detail points at the file that owns it. Never invent a rule: derive it from a manifest, a script, a CI gate, or an explicit decision. -->
+
+## {{h_commands}}
+
+<!-- TODO(ask-init): copy-pasteable install / build / test / lint / run / release commands, read from manifests and CI. Mark anything unverified. -->
+
+## {{h_layout}}
+
+<!-- TODO(ask-init): top-level tree with one line per entry, including .agents/ and specs/. -->
+
+## {{h_index}}
+
+{{index}}
+
+{{roots}}
+
+## {{h_impact}}
+
+<!-- TODO(ask-init): change → code location → what else must be updated in the same change. Start with the areas the survey actually found. -->
+
+## {{h_terms}}
+
+<!-- TODO(ask-init): only terms that get confused; the full glossary belongs in .agents/memory/TERMS.md. -->
+
+## {{h_maintenance}}
+
+- framework: agent-framework v{{frameworkVersion}} (`{{statePath}}`)
+- budgets: AGENTS.md soft {{softBudget}} / hard {{hardBudget}} characters; one memory file {{memoryBudget}}
+- audit: `/ask-init check`
+- before writing memory: read `{{contractPath}}`
+- records: one file per change in `{{implementationsDir}}/`, first line carries the exact time