@bossmissing/agent-meta 0.1.0 → 0.3.0

package/dist/generators/hook-generator.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+import { detectPackageManager } from "../commands/init.js";
+/** The `meta check` invocation appropriate for the project's package manager. */
+export function metaCheckCommand(root) {
+    switch (detectPackageManager(root)) {
+        case "pnpm":
+            return "pnpm exec meta check";
+        case "yarn":
+            return "yarn exec meta check";
+        case "npm":
+            return "npx meta check";
+        default:
+            return "meta check";
+    }
+}
+const LEFTHOOK_FILENAMES = ["lefthook.yml", "lefthook.yaml"];
+/**
+ * Create lefthook.yml with a pre-commit meta-check command, or add the
+ * command to an existing file. An existing meta-check entry is never
+ * overwritten.
+ */
+export function generateLefthookConfig(root, dryRun) {
+    const existing = LEFTHOOK_FILENAMES.find((f) => fs.existsSync(path.join(root, f)));
+    const rel = existing ?? "lefthook.yml";
+    const abs = path.join(root, rel);
+    const run = metaCheckCommand(root);
+    let doc = {};
+    if (existing) {
+        try {
+            doc = YAML.parse(fs.readFileSync(abs, "utf8")) ?? {};
+        }
+        catch (e) {
+            throw new MetaError(`Cannot parse ${rel}: ${e.message}`, EXIT_CODES.CONFIG_UNPARSABLE);
+        }
+    }
+    if (typeof doc["pre-commit"] !== "object" || doc["pre-commit"] === null) {
+        doc["pre-commit"] = {};
+    }
+    const preCommit = doc["pre-commit"];
+    if (typeof preCommit["commands"] !== "object" || preCommit["commands"] === null) {
+        preCommit["commands"] = {};
+    }
+    const commands = preCommit["commands"];
+    const current = commands["meta-check"];
+    if (current) {
+        return { action: "unchanged", path: rel, command: current.run ?? "" };
+    }
+    commands["meta-check"] = { run };
+    if (!dryRun)
+        fs.writeFileSync(abs, YAML.stringify(doc), "utf8");
+    return { action: existing ? "updated" : "created", path: rel, command: run };
+}

package/dist/generators/index-generator.d.ts

@@ -1,6 +1,6 @@
 import type { MetaConfig } from "../schemas/config.schema.js";
 import type { FileWriter } from "../core/filesystem.js";
 export declare function buildDomainIndexTable(root: string, config: MetaConfig): string;
-export declare function buildAdrIndexTable(root: string, config: MetaConfig): string;
+export declare function buildAdrIndexTable(root: string, config: MetaConfig, relDir?: string): string;
 export declare function updateDomainIndex(writer: FileWriter, root: string, config: MetaConfig): void;
-export declare function updateAdrIndex(writer: FileWriter, root: string, config: MetaConfig): void;
+export declare function updateAdrIndex(writer: FileWriter, root: string, config: MetaConfig, relDir?: string): void;

package/dist/generators/index-generator.js

@@ -5,15 +5,22 @@ import { dateValueToString } from "../core/paths.js";
 import { listAdrFiles } from "./adr-generator.js";
 import { renderNamedTemplate } from "../core/templates.js";
 import { todayISO } from "../core/paths.js";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
 const DOMAIN_MARKERS = ["<!-- meta:domain-index:start -->", "<!-- meta:domain-index:end -->"];
 const ADR_MARKERS = ["<!-- meta:adr-index:start -->", "<!-- meta:adr-index:end -->"];
-function replaceBetweenMarkers(content, [start, end], body) {
+function replaceBetweenMarkers(content, [start, end], body, relPath) {
     const startIdx = content.indexOf(start);
     const endIdx = content.indexOf(end);
-    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+    if (startIdx === -1 && endIdx === -1) {
         // No markers: append a managed section at the end.
         return `${content.trimEnd()}\n\n${start}\n${body}\n${end}\n`;
     }
+    if (startIdx === -1 || endIdx === -1 || endIdx < startIdx) {
+        // Exactly one marker (or reversed order): regenerating here could swallow
+        // user content between the orphan marker and a freshly appended section.
+        throw new MetaError(`Index markers in ${relPath} are malformed: expected '${start}' followed by '${end}'. ` +
+            `Restore both markers (in order), or remove both to let the index be re-appended.`, EXIT_CODES.CHECK_FAILED);
+    }
     return (content.slice(0, startIdx + start.length) + "\n" + body + "\n" + content.slice(endIdx));
 }
 function frontmatterStr(data, key) {
@@ -52,8 +59,8 @@ export function buildDomainIndexTable(root, config) {
         ...rows,
     ].join("\n");
 }
-export function buildAdrIndexTable(root, config) {
-    const adrDir = path.join(root, config.paths.adr_docs);
+export function buildAdrIndexTable(root, config, relDir = config.paths.adr_docs) {
+    const adrDir = path.join(root, relDir);
     const rows = listAdrFiles(adrDir).map((info) => {
         const doc = parseDocFile(info.file);
         const title = frontmatterStr(doc.data, "title") || info.slug;
@@ -74,14 +81,14 @@ function updateIndexFile(writer, relPath, markers, table, templateName, root, co
             date: todayISO(),
         });
     }
-    const updated = replaceBetweenMarkers(content, markers, table);
+    const updated = replaceBetweenMarkers(content, markers, table, relPath);
     writer.write(relPath, updated, { overwrite: true });
 }
 export function updateDomainIndex(writer, root, config) {
     const rel = path.join(config.paths.domain_docs, "README.md");
     updateIndexFile(writer, rel, DOMAIN_MARKERS, buildDomainIndexTable(root, config), "domain-index-readme.md", root, config);
 }
-export function updateAdrIndex(writer, root, config) {
-    const rel = path.join(config.paths.adr_docs, "README.md");
-    updateIndexFile(writer, rel, ADR_MARKERS, buildAdrIndexTable(root, config), "adr-index-readme.md", root, config);
+export function updateAdrIndex(writer, root, config, relDir = config.paths.adr_docs) {
+    const rel = path.join(relDir, "README.md");
+    updateIndexFile(writer, rel, ADR_MARKERS, buildAdrIndexTable(root, config, relDir), "adr-index-readme.md", root, config);
 }

package/dist/generators/mcp-generator.d.ts

@@ -0,0 +1,9 @@
+import type { FileWriter } from "../core/filesystem.js";
+import { type McpPack } from "../core/mcp-packs.js";
+/**
+ * Install a tool pack into the target repository:
+ * - merge the MCP server into `.mcp.json` (existing servers are never touched)
+ * - merge plugin settings into `.claude/settings.json` (existing values always win)
+ * - copy the pack's skills into `.claude/skills/` (existing files are skipped)
+ */
+export declare function installMcpPack(writer: FileWriter, root: string, pack: McpPack): void;

package/dist/generators/mcp-generator.js

@@ -0,0 +1,68 @@
+import fs from "node:fs";
+import path from "node:path";
+import { EXIT_CODES, MetaError } from "../core/errors.js";
+import { listPackSkillFiles } from "../core/mcp-packs.js";
+const MCP_JSON = ".mcp.json";
+const CLAUDE_SETTINGS = ".claude/settings.json";
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Deep-merge source into target, adding missing keys only — existing values always win. */
+function mergeMissing(target, source) {
+    let changed = false;
+    for (const [key, value] of Object.entries(source)) {
+        if (!(key in target)) {
+            target[key] = value;
+            changed = true;
+        }
+        else if (isPlainObject(target[key]) && isPlainObject(value)) {
+            changed = mergeMissing(target[key], value) || changed;
+        }
+        // Existing non-object values are kept as-is.
+    }
+    return changed;
+}
+function readJson(root, rel) {
+    const abs = path.join(root, rel);
+    if (!fs.existsSync(abs))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(abs, "utf8")) ?? {};
+    }
+    catch (e) {
+        throw new MetaError(`Cannot parse ${rel}: ${e.message}`, EXIT_CODES.CONFIG_UNPARSABLE);
+    }
+}
+/**
+ * Install a tool pack into the target repository:
+ * - merge the MCP server into `.mcp.json` (existing servers are never touched)
+ * - merge plugin settings into `.claude/settings.json` (existing values always win)
+ * - copy the pack's skills into `.claude/skills/` (existing files are skipped)
+ */
+export function installMcpPack(writer, root, pack) {
+    if (pack.server) {
+        const doc = readJson(root, MCP_JSON);
+        if (!isPlainObject(doc.mcpServers))
+            doc.mcpServers = {};
+        const servers = doc.mcpServers;
+        if (servers[pack.name]) {
+            writer.actions.push({ type: "skip", path: MCP_JSON });
+        }
+        else {
+            servers[pack.name] = pack.server;
+            writer.write(MCP_JSON, JSON.stringify(doc, null, 2) + "\n", { overwrite: true });
+        }
+    }
+    if (pack.settings) {
+        const doc = readJson(root, CLAUDE_SETTINGS);
+        if (mergeMissing(doc, pack.settings)) {
+            writer.write(CLAUDE_SETTINGS, JSON.stringify(doc, null, 2) + "\n", { overwrite: true });
+        }
+        else {
+            writer.actions.push({ type: "skip", path: CLAUDE_SETTINGS });
+        }
+    }
+    for (const [rel, srcAbs] of listPackSkillFiles(pack)) {
+        writer.write(path.join(".claude", "skills", rel), fs.readFileSync(srcAbs, "utf8"));
+    }
+}

package/dist/schemas/config.schema.d.ts

@@ -38,20 +38,14 @@ export declare const configSchema: z.ZodObject<{
         templates?: string | undefined;
     }>>;
     defaults: z.ZodDefault<z.ZodObject<{
-        doc_status: z.ZodDefault<z.ZodString>;
-        review_interval_days: z.ZodDefault<z.ZodNumber>;
         adr_padding: z.ZodDefault<z.ZodNumber>;
         agents_max_lines: z.ZodDefault<z.ZodNumber>;
         local_agents_max_lines: z.ZodDefault<z.ZodNumber>;
     }, "strip", z.ZodTypeAny, {
-        doc_status: string;
-        review_interval_days: number;
         adr_padding: number;
         agents_max_lines: number;
         local_agents_max_lines: number;
     }, {
-        doc_status?: string | undefined;
-        review_interval_days?: number | undefined;
         adr_padding?: number | undefined;
         agents_max_lines?: number | undefined;
         local_agents_max_lines?: number | undefined;
@@ -141,8 +135,6 @@ export declare const configSchema: z.ZodObject<{
         templates: string;
     };
     defaults: {
-        doc_status: string;
-        review_interval_days: number;
         adr_padding: number;
         agents_max_lines: number;
         local_agents_max_lines: number;
@@ -184,8 +176,6 @@ export declare const configSchema: z.ZodObject<{
         templates?: string | undefined;
     } | undefined;
     defaults?: {
-        doc_status?: string | undefined;
-        review_interval_days?: number | undefined;
         adr_padding?: number | undefined;
         agents_max_lines?: number | undefined;
         local_agents_max_lines?: number | undefined;

package/dist/schemas/config.schema.js

@@ -33,8 +33,6 @@ export const configSchema = z.object({
         .default({}),
     defaults: z
         .object({
-        doc_status: z.string().default("active"),
-        review_interval_days: z.number().default(180),
         adr_padding: z.number().int().min(1).default(4),
         agents_max_lines: z.number().default(180),
         local_agents_max_lines: z.number().default(120),

package/dist/templates/index.d.ts

@@ -4,9 +4,9 @@
  * paths.templates). Only {{variable}} substitution is supported.
  */
 export declare const BUILTIN_TEMPLATES: {
-    readonly "agents.md": "# AGENTS.md\n\n## Project Overview\n\n- Project type: {{project_type}}\n- Package manager: {{package_manager}}\n- Main application paths: {{main_paths}}\n\n## Important Documentation\n\n- Architecture: `docs/architecture/`\n- Domain rules: `docs/domain/`\n- API conventions: `docs/api/`\n- Engineering rules: `docs/engineering/`\n- Architecture decisions: `docs/adr/`\n- Product capability specs: `openspec/specs/`\n- Active changes: `openspec/changes/`\n\n## Working Rules\n\n- Read the nearest applicable `AGENTS.md` before modifying files.\n- Read related domain documentation before changing business behavior.\n- Do not duplicate domain rules in this file.\n- Update OpenSpec specs when externally observable behavior changes.\n- Add or update tests for behavior changes.\n- Do not mix unrelated refactors into a feature change.\n\n## High-Risk Areas\n\nBefore changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under `docs/domain/`.\n\n## Definition of Done\n\n- Relevant tests pass.\n- Type checking and lint pass where configured.\n- Behavior changes include documentation or specification updates where applicable.\n- High-risk changes include rollback and failure-path consideration.\n";
+    readonly "agents.md": "# AGENTS.md\n\n## Project Overview\n\n- Project type: {{project_type}}\n- Package manager: {{package_manager}}\n- Main application paths: {{main_paths}}\n\n## Important Documentation\n\n- Architecture: `docs/architecture/`\n- Domain rules: `docs/domain/`\n- API conventions: `docs/api/`\n- Engineering rules: `docs/engineering/`\n- Architecture decisions: `docs/adr/`\n- Product capability specs: `openspec/specs/`\n- Active changes: `openspec/changes/`\n\n## Working Rules\n\n- Read the nearest applicable `AGENTS.md` before modifying files.\n- Read related domain documentation before changing business behavior.\n- Do not modify third-party or vendored code (`node_modules/`, `vendor/`, `third_party/`, `patches/`). Wrap or extend it instead; if patching is unavoidable, record an ADR first.\n- Do not use user-level (global) skills, plugins, or MCP tools unless the human explicitly asks for them. Prefer tools, scripts, and skills defined inside this repository.\n- Never violate declared hard constraints (`docs/domain/*/rules.md` 硬限制 sections and `docs/engineering/constraints.md`). If a limit is not declared, ask the human instead of assuming it is negotiable.\n- If you are guessing, fabricating, or cannot verify a conclusion, stop and ask the human.\n- Do not duplicate domain rules in this file.\n- Update OpenSpec specs when externally observable behavior changes.\n- Add or update tests for behavior changes.\n- Do not mix unrelated refactors into a feature change.\n{{extra_rules}}\n## High-Risk Areas\n\nBefore changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under `docs/domain/`. Hard constraints for these areas are declared in each domain's `rules.md` under 硬限制（不可违反）.\n\n## Definition of Done\n\n- Relevant tests pass.\n- Type checking and lint pass where configured.\n- A human has reviewed the change.\n- All declared hard constraints hold.\n- Behavior changes include documentation or specification updates where applicable.\n- High-risk changes include rollback and failure-path consideration.\n";
     readonly "domain-readme.md": "---\ntitle: {{domain_title}}\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}\n\n## 职责\n\n<!-- 描述该领域负责的业务能力。 -->\n\n## 非职责\n\n<!-- 明确该领域不负责什么，避免模块边界扩散。 -->\n\n## 核心对象\n\n| 对象 | 说明 |\n|---|---|\n|  |  |\n\n## 上游依赖\n\n<!-- 哪些模块、事件、服务会驱动该领域。 -->\n\n## 下游影响\n\n<!-- 该领域变化会影响哪些模块、数据、接口或用户角色。 -->\n\n## 关键规则入口\n\n- [业务规则](./rules.md)\n{{state_machine_link}}{{glossary_link}}\n\n## 关联 ADR\n\n<!-- 例如：../adr/0004-withdrawal-idempotency.md -->\n";
-    readonly "domain-rules.md": "---\ntitle: {{domain_title}}业务规则\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}业务规则\n\n## 术语\n\n<!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->\n\n## 不变量\n\n<!-- 无论何时都必须成立的规则。 -->\n\n-\n-\n-\n\n## 权限规则\n\n| 角色 | 可执行操作 | 限制 |\n|---|---|---|\n|  |  |  |\n\n## 边界条件\n\n<!-- 写清重复请求、失败重试、并发、撤销、退款、异常状态等行为。 -->\n\n## 审计与追踪\n\n<!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->\n\n## 禁止行为\n\n-\n-\n";
+    readonly "domain-rules.md": "---\ntitle: {{domain_title}}业务规则\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}业务规则\n\n## 术语\n\n<!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->\n\n## 硬限制（不可违反）\n\n<!-- 安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->\n<!-- 没写在这里的限制，AI 会当成可协商的。 -->\n\n-\n-\n-\n\n## 软限制（可权衡）\n\n<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->\n\n-\n\n## 权限规则\n\n| 角色 | 可执行操作 | 限制 |\n|---|---|---|\n|  |  |  |\n\n## 边界条件\n\n<!-- 写清重复请求、失败重试、并发、撤销、退款、异常状态等行为。 -->\n\n## 审计与追踪\n\n<!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->\n";
     readonly "domain-state-machine.md": "---\ntitle: {{domain_title}}状态机\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}状态机\n\n## 状态列表\n\n| 状态 | 含义 | 是否终态 |\n|---|---|---|\n|  |  | 否 |\n\n## 状态流转\n\n```mermaid\nstateDiagram-v2\n  [*] --> pending\n  pending --> completed\n  pending --> cancelled\n```\n\n## 流转规则\n\n| 当前状态 | 触发事件 | 下一个状态 | 前置条件 | 副作用 |\n| ---- | ---- | ----- | ---- | --- |\n|      |      |       |      |     |\n\n## 幂等规则\n\n<!-- 对重复请求、重复事件、重复回调的处理规则。 -->\n";
     readonly "domain-glossary.md": "---\ntitle: {{domain_title}}术语表\nstatus: active\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# {{domain_title}}术语表\n\n| 术语 | 定义 | 备注 |\n|---|---|---|\n|  |  |  |\n";
     readonly "domain-agents.md": "# {{domain_title}} Module Rules\n\n## Scope\n\nThis directory contains the {{domain_title}} domain.\n\n## Required Reading\n\n- `README.md`\n- `rules.md`\n{{state_machine_reading}}\n\n## Rules for Agents\n\n- Do not change domain behavior without updating the relevant domain documentation.\n- Do not introduce new states without updating `state-machine.md`.\n- Preserve existing audit and idempotency behavior.\n- Keep business rules out of controllers and UI components.\n- Add tests for normal, boundary, and retry scenarios.\n\n## Review Checklist\n\n- Are permissions affected?\n- Are money, inventory, or externally triggered callbacks affected?\n- Is retry or duplicate handling required?\n- Does this change require an ADR?\n";
@@ -18,6 +18,11 @@ export declare const BUILTIN_TEMPLATES: {
     readonly "system-overview.md": "---\ntitle: 系统架构总览\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 系统架构总览\n\n## 系统边界\n\n<!-- 系统包含哪些应用 / 服务。 -->\n\n## 模块划分\n\n<!-- 主要模块与职责。 -->\n\n## 关键依赖\n\n<!-- 数据库、消息队列、第三方服务。 -->\n";
     readonly "api-conventions.md": "---\ntitle: API 约定\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# API 约定\n\n## 命名与版本\n\n## 错误码规范\n\n## 鉴权约定\n";
     readonly "engineering-testing.md": "---\ntitle: 测试规范\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 测试规范\n\n## 必须覆盖的场景\n\n- 正常路径\n- 边界条件\n- 重试与幂等\n\n## 工具与命令\n";
+    readonly "engineering-constraints.md": "---\ntitle: 项目级硬限制\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# 项目级硬限制\n\n<!-- 跨领域的硬限制放这里；单个领域的硬限制放 docs/domain/<domain>/rules.md。 -->\n\n## 硬限制（不可违反）\n\n<!-- 类别参考：安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->\n<!-- 没写在这里的限制，AI 会当成可协商的。 -->\n\n-\n-\n\n## 软限制（可权衡）\n\n<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->\n\n-\n";
     readonly "runbooks-readme.md": "---\ntitle: Runbooks\nstatus: draft\nowner: {{owner}}\nlast_reviewed: {{date}}\nsource_of_truth: true\napplies_to: []\n---\n\n# Runbooks\n\n<!-- 运维手册与故障处理流程。 -->\n";
+    readonly "change-proposal.md": "# {{change_title}}\n\n## Why\n\n<!-- 为什么要做这个变更？解决什么问题？ -->\n\n## What Changes\n\n<!-- 变更内容概述：新增/修改/移除哪些能力。 -->\n\n## Impact\n\n- Affected domains: {{domain}}\n- Affected specs:\n- Affected code:\n";
+    readonly "change-design.md": "# {{change_title}} — Design\n\n## Context\n\n<!-- 现状与约束。 -->\n\n## Goals / Non-Goals\n\n- Goals:\n- Non-Goals:\n\n## Decisions\n\n<!-- 关键技术决策；长期决策请沉淀为 ADR（meta new-adr）。 -->\n\n## Hard Constraints（硬限制核对）\n\n<!-- 列出本变更涉及的已声明硬限制与核对结论。 -->\n<!-- 来源：docs/domain/<domain>/rules.md 硬限制章节、docs/engineering/constraints.md。 -->\n\n| 硬限制 | 来源 | 核对结论 |\n|---|---|---|\n|  |  |  |\n\n## Risks / Trade-offs\n\n<!-- 风险与权衡。 -->\n";
+    readonly "change-tasks.md": "# {{change_title}} — Tasks\n\n## 1. Implementation\n\n- [ ] 1.1\n- [ ] 1.2\n\n## 2. Validation\n\n- [ ] 2.1 Tests updated\n- [ ] 2.2 `meta check` passes\n";
+    readonly "change-risk-review.md": "# {{change_title}} — Risk Review\n\n- Related domain: {{domain}}\n- Date: {{date}}\n\n## Checklist\n\n- [ ] Money representation（金额表示与精度）\n- [ ] Idempotency（幂等）\n- [ ] Retry behavior（重试行为）\n- [ ] Callback deduplication（回调去重）\n- [ ] Audit logging（审计日志）\n- [ ] Permission boundaries（权限边界）\n- [ ] Rollback plan（回滚方案）\n- [ ] Declared hard constraints checked（已声明的硬限制全部核对）\n\n## Notes\n\n<!-- 每项勾选前写清结论或“不适用”的原因。 -->\n";
 };
 export type TemplateName = keyof typeof BUILTIN_TEMPLATES;

package/dist/templates/index.js

@@ -25,19 +25,25 @@ const AGENTS_MD = `# AGENTS.md
 
 - Read the nearest applicable \`AGENTS.md\` before modifying files.
 - Read related domain documentation before changing business behavior.
+- Do not modify third-party or vendored code (\`node_modules/\`, \`vendor/\`, \`third_party/\`, \`patches/\`). Wrap or extend it instead; if patching is unavoidable, record an ADR first.
+- Do not use user-level (global) skills, plugins, or MCP tools unless the human explicitly asks for them. Prefer tools, scripts, and skills defined inside this repository.
+- Never violate declared hard constraints (\`docs/domain/*/rules.md\` 硬限制 sections and \`docs/engineering/constraints.md\`). If a limit is not declared, ask the human instead of assuming it is negotiable.
+- If you are guessing, fabricating, or cannot verify a conclusion, stop and ask the human.
 - Do not duplicate domain rules in this file.
 - Update OpenSpec specs when externally observable behavior changes.
 - Add or update tests for behavior changes.
 - Do not mix unrelated refactors into a feature change.
-
+{{extra_rules}}
 ## High-Risk Areas
 
-Before changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under \`docs/domain/\`.
+Before changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under \`docs/domain/\`. Hard constraints for these areas are declared in each domain's \`rules.md\` under 硬限制（不可违反）.
 
 ## Definition of Done
 
 - Relevant tests pass.
 - Type checking and lint pass where configured.
+- A human has reviewed the change.
+- All declared hard constraints hold.
 - Behavior changes include documentation or specification updates where applicable.
 - High-risk changes include rollback and failure-path consideration.
 `;
@@ -98,14 +104,21 @@ applies_to: []
 
 <!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->
 
-## 不变量
+## 硬限制（不可违反）
 
-<!-- 无论何时都必须成立的规则。 -->
+<!-- 安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->
+<!-- 没写在这里的限制，AI 会当成可协商的。 -->
 
 -
 -
 -
 
+## 软限制（可权衡）
+
+<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->
+
+-
+
 ## 权限规则
 
 | 角色 | 可执行操作 | 限制 |
@@ -119,11 +132,6 @@ applies_to: []
 ## 审计与追踪
 
 <!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->
-
-## 禁止行为
-
--
--
 `;
 const DOMAIN_STATE_MACHINE = `---
 title: {{domain_title}}状态机
@@ -413,6 +421,109 @@ applies_to: []
 
 ## 工具与命令
 `;
+const CHANGE_PROPOSAL = `# {{change_title}}
+
+## Why
+
+<!-- 为什么要做这个变更？解决什么问题？ -->
+
+## What Changes
+
+<!-- 变更内容概述：新增/修改/移除哪些能力。 -->
+
+## Impact
+
+- Affected domains: {{domain}}
+- Affected specs:
+- Affected code:
+`;
+const CHANGE_DESIGN = `# {{change_title}} — Design
+
+## Context
+
+<!-- 现状与约束。 -->
+
+## Goals / Non-Goals
+
+- Goals:
+- Non-Goals:
+
+## Decisions
+
+<!-- 关键技术决策；长期决策请沉淀为 ADR（meta new-adr）。 -->
+
+## Hard Constraints（硬限制核对）
+
+<!-- 列出本变更涉及的已声明硬限制与核对结论。 -->
+<!-- 来源：docs/domain/<domain>/rules.md 硬限制章节、docs/engineering/constraints.md。 -->
+
+| 硬限制 | 来源 | 核对结论 |
+|---|---|---|
+|  |  |  |
+
+## Risks / Trade-offs
+
+<!-- 风险与权衡。 -->
+`;
+const CHANGE_TASKS = `# {{change_title}} — Tasks
+
+## 1. Implementation
+
+- [ ] 1.1
+- [ ] 1.2
+
+## 2. Validation
+
+- [ ] 2.1 Tests updated
+- [ ] 2.2 \`meta check\` passes
+`;
+const CHANGE_RISK_REVIEW = `# {{change_title}} — Risk Review
+
+- Related domain: {{domain}}
+- Date: {{date}}
+
+## Checklist
+
+- [ ] Money representation（金额表示与精度）
+- [ ] Idempotency（幂等）
+- [ ] Retry behavior（重试行为）
+- [ ] Callback deduplication（回调去重）
+- [ ] Audit logging（审计日志）
+- [ ] Permission boundaries（权限边界）
+- [ ] Rollback plan（回滚方案）
+- [ ] Declared hard constraints checked（已声明的硬限制全部核对）
+
+## Notes
+
+<!-- 每项勾选前写清结论或“不适用”的原因。 -->
+`;
+const ENGINEERING_CONSTRAINTS = `---
+title: 项目级硬限制
+status: draft
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# 项目级硬限制
+
+<!-- 跨领域的硬限制放这里；单个领域的硬限制放 docs/domain/<domain>/rules.md。 -->
+
+## 硬限制（不可违反）
+
+<!-- 类别参考：安全、数据一致性、API 契约、性能预算、兼容性、合规。 -->
+<!-- 没写在这里的限制，AI 会当成可协商的。 -->
+
+-
+-
+
+## 软限制（可权衡）
+
+<!-- 代码风格偏好、非关键路径的实现细节、可后续优化的部分。 -->
+
+-
+`;
 const RUNBOOKS_README = `---
 title: Runbooks
 status: draft
@@ -441,5 +552,10 @@ export const BUILTIN_TEMPLATES = {
     "system-overview.md": SYSTEM_OVERVIEW,
     "api-conventions.md": API_CONVENTIONS,
     "engineering-testing.md": ENGINEERING_TESTING,
+    "engineering-constraints.md": ENGINEERING_CONSTRAINTS,
     "runbooks-readme.md": RUNBOOKS_README,
+    "change-proposal.md": CHANGE_PROPOSAL,
+    "change-design.md": CHANGE_DESIGN,
+    "change-tasks.md": CHANGE_TASKS,
+    "change-risk-review.md": CHANGE_RISK_REVIEW,
 };

package/dist/validators/adr-validator.js

@@ -27,8 +27,8 @@ export function validateAdrs(ctx) {
                 code: "ADR_FILENAME_INVALID",
                 severity: "error",
                 file: path.join(relDir, f),
-                message: `ADR filename must match NNNN-slug.md (padding: ${config.defaults.adr_padding})`,
-                suggestion: "Rename the file, e.g. 0002-my-decision.md.",
+                message: "ADR filename must match <number>-slug.md",
+                suggestion: `Rename the file, e.g. ${"2".padStart(config.defaults.adr_padding, "0")}-my-decision.md.`,
             });
         }
     }
@@ -87,8 +87,8 @@ export function validateAdrs(ctx) {
             });
         }
         else {
-            const numMatch = /(\d{4,})/.exec(title);
-            if (!numMatch || parseInt(numMatch[1], 10) !== info.number) {
+            const titleNumbers = title.match(/\d+/g) ?? [];
+            if (!titleNumbers.some((s) => parseInt(s, 10) === info.number)) {
                 issues.push({
                     code: "ADR_TITLE_NUMBER_MISMATCH",
                     severity: "error",

package/dist/validators/domain-validator.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { parseDocFile, hasSection } from "../core/frontmatter.js";
+import { parseDocFile, hasSection, sectionHasContent, HARD_CONSTRAINT_HEADINGS, } from "../core/frontmatter.js";
 import { matchRiskKeywords } from "../core/risk.js";
 export function listDomainDirs(root, domainDocs) {
     const abs = path.join(root, domainDocs);
@@ -99,6 +99,20 @@ export function validateDomains(ctx) {
             }
         }
         if (riskHits.length > 0) {
+            // Hard constraints must be declared; undeclared limits get treated as
+            // negotiable by AI agents.
+            if (fs.existsSync(rulesAbs)) {
+                const rules = parseDocFile(rulesAbs);
+                if (!sectionHasContent(rules.content, HARD_CONSTRAINT_HEADINGS)) {
+                    issues.push({
+                        code: "HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS",
+                        severity: "warning",
+                        file: path.join(relDir, "rules.md"),
+                        message: `High-risk domain '${domain}' declares no hard constraints`,
+                        suggestion: 'Fill the "## 硬限制（不可违反）" section in rules.md (security, data consistency, API contracts, performance budgets, compatibility, compliance).',
+                    });
+                }
+            }
             if (!fs.existsSync(rulesAbs)) {
                 issues.push({
                     code: "HIGH_RISK_DOMAIN_MISSING_RULES",
@@ -126,6 +140,21 @@ export function validateDomains(ctx) {
                     suggestion: `Run \`meta new-domain ${domain} --force --with-state-machine\`.`,
                 });
             }
+            // High-risk domains should link the ADRs backing their key decisions.
+            const docs = [readmeAbs, rulesAbs].filter((abs) => fs.existsSync(abs));
+            const referencesAdr = docs.some((abs) => {
+                const body = fs.readFileSync(abs, "utf8").replace(/<!--[\s\S]*?-->/g, "");
+                return /adr\//i.test(body) || /ADR-\d/.test(body);
+            });
+            if (docs.length > 0 && !referencesAdr) {
+                issues.push({
+                    code: "DOMAIN_NO_ADR_REFERENCE",
+                    severity: "warning",
+                    file: relDir,
+                    message: `High-risk domain '${domain}' does not reference any ADR`,
+                    suggestion: `Record key decisions with \`meta new-adr ${domain}-idempotency\` and link them from the domain README.`,
+                });
+            }
         }
     }
     return { issues, checkedFiles };

package/dist/validators/openspec-validator.js

@@ -1,5 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
+import { matchRiskKeywords } from "../core/risk.js";
+import { listDomainDirs } from "./domain-validator.js";
 export function validateOpenSpec(ctx) {
     const issues = [];
     const { root, config } = ctx;
@@ -53,24 +55,51 @@ export function validateOpenSpec(ctx) {
             });
         }
     }
-    // Each change directory should contain at least a proposal or tasks file.
+    // Each change directory must contain the core change files.
     const changesAbs = path.join(openspecAbs, "changes");
     if (fs.existsSync(changesAbs)) {
         for (const entry of fs.readdirSync(changesAbs, { withFileTypes: true })) {
             if (!entry.isDirectory())
                 continue;
+            // OpenSpec keeps completed changes under changes/archive/.
+            if (entry.name === "archive")
+                continue;
             checkedFiles++;
             const changeDir = path.join(changesAbs, entry.name);
-            const hasCore = ["proposal.md", "tasks.md", "design.md"].some((f) => fs.existsSync(path.join(changeDir, f)));
-            if (!hasCore) {
+            const missing = ["proposal.md", "tasks.md"].filter((f) => !fs.existsSync(path.join(changeDir, f)));
+            if (missing.length > 0) {
                 issues.push({
                     code: "OPENSPEC_CHANGE_INCOMPLETE",
                     severity: "warning",
                     file: path.join(openspecRel, "changes", entry.name),
-                    message: "Change directory has none of proposal.md / design.md / tasks.md",
+                    message: `Change directory is missing: ${missing.join(", ")}`,
+                    suggestion: `Run \`meta new-change ${entry.name}\` to create the missing files.`,
                 });
             }
         }
     }
+    // High-risk domain docs should reference OpenSpec specs or changes.
+    for (const domain of listDomainDirs(root, config.paths.domain_docs)) {
+        const riskHits = matchRiskKeywords(domain, config.risk_keywords);
+        if (riskHits.length === 0)
+            continue;
+        const domainRel = path.join(config.paths.domain_docs, domain);
+        const docs = ["README.md", "rules.md"]
+            .map((f) => path.join(root, domainRel, f))
+            .filter((abs) => fs.existsSync(abs));
+        if (docs.length === 0)
+            continue;
+        checkedFiles += docs.length;
+        const referencesOpenspec = docs.some((abs) => /openspec/i.test(fs.readFileSync(abs, "utf8").replace(/<!--[\s\S]*?-->/g, "")));
+        if (!referencesOpenspec) {
+            issues.push({
+                code: "HIGH_RISK_DOMAIN_NO_OPENSPEC_REFERENCE",
+                severity: "warning",
+                file: domainRel,
+                message: `High-risk domain '${domain}' does not reference any OpenSpec specs or changes`,
+                suggestion: `Link the relevant openspec/specs/ or openspec/changes/ entries from ${domainRel}/README.md.`,
+            });
+        }
+    }
     return { issues, checkedFiles };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bossmissing/agent-meta",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Agent Meta CLI - manage AI agent collaboration metadata (AGENTS.md, domain docs, ADRs, frontmatter checks)",
   "keywords": [
     "cli",
@@ -22,6 +22,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "assets",
     "README.md",
     "LICENSE"
   ],
@@ -32,14 +33,6 @@
   "engines": {
     "node": ">=20"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "dev": "tsx src/cli.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "pnpm build"
-  },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
     "commander": "^12.1.0",
@@ -55,10 +48,11 @@
     "typescript": "^5.5.0",
     "vitest": "^2.1.0"
   },
-  "packageManager": "pnpm@10.0.0",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   }
-}
+}