@bossmissing/agent-meta 0.1.0

package/dist/templates/index.js

@@ -0,0 +1,445 @@
+/**
+ * Built-in templates. A project can override any of them by placing a file
+ * named `<key>.tmpl` under `templates/agent-meta/` (configurable via
+ * paths.templates). Only {{variable}} substitution is supported.
+ */
+const AGENTS_MD = `# AGENTS.md
+
+## Project Overview
+
+- Project type: {{project_type}}
+- Package manager: {{package_manager}}
+- Main application paths: {{main_paths}}
+
+## Important Documentation
+
+- Architecture: \`docs/architecture/\`
+- Domain rules: \`docs/domain/\`
+- API conventions: \`docs/api/\`
+- Engineering rules: \`docs/engineering/\`
+- Architecture decisions: \`docs/adr/\`
+- Product capability specs: \`openspec/specs/\`
+- Active changes: \`openspec/changes/\`
+
+## Working Rules
+
+- Read the nearest applicable \`AGENTS.md\` before modifying files.
+- Read related domain documentation before changing business behavior.
+- 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.
+
+## High-Risk Areas
+
+Before changing payment, order, commission, settlement, withdrawal, permissions, webhooks, inventory, or audit logging, read the applicable documentation under \`docs/domain/\`.
+
+## Definition of Done
+
+- Relevant tests pass.
+- Type checking and lint pass where configured.
+- Behavior changes include documentation or specification updates where applicable.
+- High-risk changes include rollback and failure-path consideration.
+`;
+const DOMAIN_README = `---
+title: {{domain_title}}
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# {{domain_title}}
+
+## 职责
+
+<!-- 描述该领域负责的业务能力。 -->
+
+## 非职责
+
+<!-- 明确该领域不负责什么，避免模块边界扩散。 -->
+
+## 核心对象
+
+| 对象 | 说明 |
+|---|---|
+|  |  |
+
+## 上游依赖
+
+<!-- 哪些模块、事件、服务会驱动该领域。 -->
+
+## 下游影响
+
+<!-- 该领域变化会影响哪些模块、数据、接口或用户角色。 -->
+
+## 关键规则入口
+
+- [业务规则](./rules.md)
+{{state_machine_link}}{{glossary_link}}
+
+## 关联 ADR
+
+<!-- 例如：../adr/0004-withdrawal-idempotency.md -->
+`;
+const DOMAIN_RULES = `---
+title: {{domain_title}}业务规则
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# {{domain_title}}业务规则
+
+## 术语
+
+<!-- 仅列出该领域特有术语；通用术语应放到 docs/domain/glossary.md。 -->
+
+## 不变量
+
+<!-- 无论何时都必须成立的规则。 -->
+
+-
+-
+-
+
+## 权限规则
+
+| 角色 | 可执行操作 | 限制 |
+|---|---|---|
+|  |  |  |
+
+## 边界条件
+
+<!-- 写清重复请求、失败重试、并发、撤销、退款、异常状态等行为。 -->
+
+## 审计与追踪
+
+<!-- 是否需要审计日志、操作人、时间、状态变更原因等。 -->
+
+## 禁止行为
+
+-
+-
+`;
+const DOMAIN_STATE_MACHINE = `---
+title: {{domain_title}}状态机
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# {{domain_title}}状态机
+
+## 状态列表
+
+| 状态 | 含义 | 是否终态 |
+|---|---|---|
+|  |  | 否 |
+
+## 状态流转
+
+\`\`\`mermaid
+stateDiagram-v2
+  [*] --> pending
+  pending --> completed
+  pending --> cancelled
+\`\`\`
+
+## 流转规则
+
+| 当前状态 | 触发事件 | 下一个状态 | 前置条件 | 副作用 |
+| ---- | ---- | ----- | ---- | --- |
+|      |      |       |      |     |
+
+## 幂等规则
+
+<!-- 对重复请求、重复事件、重复回调的处理规则。 -->
+`;
+const DOMAIN_GLOSSARY = `---
+title: {{domain_title}}术语表
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# {{domain_title}}术语表
+
+| 术语 | 定义 | 备注 |
+|---|---|---|
+|  |  |  |
+`;
+const DOMAIN_AGENTS = `# {{domain_title}} Module Rules
+
+## Scope
+
+This directory contains the {{domain_title}} domain.
+
+## Required Reading
+
+- \`README.md\`
+- \`rules.md\`
+{{state_machine_reading}}
+
+## Rules for Agents
+
+- Do not change domain behavior without updating the relevant domain documentation.
+- Do not introduce new states without updating \`state-machine.md\`.
+- Preserve existing audit and idempotency behavior.
+- Keep business rules out of controllers and UI components.
+- Add tests for normal, boundary, and retry scenarios.
+
+## Review Checklist
+
+- Are permissions affected?
+- Are money, inventory, or externally triggered callbacks affected?
+- Is retry or duplicate handling required?
+- Does this change require an ADR?
+`;
+const ADR = `---
+title: ADR-{{adr_number}}：{{title}}
+status: {{status}}
+date: {{date}}
+owners:
+  - {{owner}}
+supersedes: []
+superseded_by: []
+tags: []
+---
+
+# ADR-{{adr_number}}：{{title}}
+
+## 背景
+
+<!-- 当前问题是什么？为什么需要做决策？ -->
+
+## 决策
+
+<!-- 明确采用什么方案。必须能被以后的人理解和执行。 -->
+
+## 不采用的方案
+
+### 方案 A
+
+<!-- 为什么不选。 -->
+
+### 方案 B
+
+<!-- 为什么不选。 -->
+
+## 后果
+
+### 正向影响
+
+-
+
+### 代价与限制
+
+-
+
+### 后续约束
+
+-
+
+## 关联内容
+
+- Domain docs:
+- OpenSpec changes:
+- Related ADRs:
+- Related APIs:
+`;
+const ADR_0001 = `---
+title: ADR-{{adr_number}}：Repository conventions
+status: accepted
+date: {{date}}
+owners:
+  - {{owner}}
+supersedes: []
+superseded_by: []
+tags: [conventions]
+---
+
+# ADR-{{adr_number}}：Repository conventions
+
+## 背景
+
+项目接入 AI Agent 协作，需要统一仓库元数据结构：AGENTS.md、领域文档、ADR、frontmatter 与校验规则。
+
+## 决策
+
+采用 Agent Meta 约定：
+
+- 根 \`AGENTS.md\` 只保留操作性规则与文档入口，不复制领域规则。
+- 领域规则统一放在 \`docs/domain/<domain>/\`。
+- 长期架构决策记录在 \`docs/adr/\`，四位递增编号，不复用编号。
+- 受约束文档必须包含 frontmatter：title、status、owner、last_reviewed。
+- 通过 \`meta check\` 在本地与 CI 校验元数据完整性。
+
+## 不采用的方案
+
+### 单一大 AGENTS.md
+
+规则集中在单文件会不可维护，且 Agent 无法按目录感知局部规则。
+
+## 后果
+
+### 正向影响
+
+- 规则只写一次，可被机器校验。
+
+### 代价与限制
+
+- 需要维护文档 frontmatter 与审核时间。
+
+### 后续约束
+
+- 新领域必须通过 \`meta new-domain\` 创建。
+
+## 关联内容
+
+- Domain docs: docs/domain/
+- Related ADRs:
+`;
+const DOMAIN_INDEX_README = `---
+title: Domain Index
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: false
+applies_to: []
+---
+
+# Domain Index
+
+<!-- meta:domain-index:start -->
+<!-- Generated by \`meta sync --indexes\`. Do not edit between markers. -->
+<!-- meta:domain-index:end -->
+`;
+const ADR_INDEX_README = `---
+title: ADR Index
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: false
+applies_to: []
+---
+
+# ADR Index
+
+<!-- meta:adr-index:start -->
+<!-- Generated by \`meta sync --indexes\`. Do not edit between markers. -->
+<!-- meta:adr-index:end -->
+`;
+const GLOSSARY = `---
+title: 术语表
+status: active
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# 术语表
+
+<!-- 跨领域通用术语。领域特有术语放在各领域目录下。 -->
+
+| 术语 | 定义 | 备注 |
+|---|---|---|
+|  |  |  |
+`;
+const SYSTEM_OVERVIEW = `---
+title: 系统架构总览
+status: draft
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# 系统架构总览
+
+## 系统边界
+
+<!-- 系统包含哪些应用 / 服务。 -->
+
+## 模块划分
+
+<!-- 主要模块与职责。 -->
+
+## 关键依赖
+
+<!-- 数据库、消息队列、第三方服务。 -->
+`;
+const API_CONVENTIONS = `---
+title: API 约定
+status: draft
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# API 约定
+
+## 命名与版本
+
+## 错误码规范
+
+## 鉴权约定
+`;
+const ENGINEERING_TESTING = `---
+title: 测试规范
+status: draft
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# 测试规范
+
+## 必须覆盖的场景
+
+- 正常路径
+- 边界条件
+- 重试与幂等
+
+## 工具与命令
+`;
+const RUNBOOKS_README = `---
+title: Runbooks
+status: draft
+owner: {{owner}}
+last_reviewed: {{date}}
+source_of_truth: true
+applies_to: []
+---
+
+# Runbooks
+
+<!-- 运维手册与故障处理流程。 -->
+`;
+export const BUILTIN_TEMPLATES = {
+    "agents.md": AGENTS_MD,
+    "domain-readme.md": DOMAIN_README,
+    "domain-rules.md": DOMAIN_RULES,
+    "domain-state-machine.md": DOMAIN_STATE_MACHINE,
+    "domain-glossary.md": DOMAIN_GLOSSARY,
+    "domain-agents.md": DOMAIN_AGENTS,
+    "adr.md": ADR,
+    "adr-0001.md": ADR_0001,
+    "domain-index-readme.md": DOMAIN_INDEX_README,
+    "adr-index-readme.md": ADR_INDEX_README,
+    "glossary.md": GLOSSARY,
+    "system-overview.md": SYSTEM_OVERVIEW,
+    "api-conventions.md": API_CONVENTIONS,
+    "engineering-testing.md": ENGINEERING_TESTING,
+    "runbooks-readme.md": RUNBOOKS_README,
+};

package/dist/validators/adr-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare const VALID_ADR_STATUSES: string[];
+export declare function validateAdrs(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/adr-validator.js

@@ -0,0 +1,182 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseDocFile, sectionHasContent, hasSection } from "../core/frontmatter.js";
+import { dateValueToString } from "../core/paths.js";
+import { listAdrFiles, ADR_FILE_RE } from "../generators/adr-generator.js";
+export const VALID_ADR_STATUSES = ["proposed", "accepted", "deprecated", "superseded", "rejected"];
+const SECTION_ALIASES = {
+    background: ["背景", "background", "context"],
+    decision: ["决策", "decision"],
+    consequences: ["后果", "consequences"],
+};
+export function validateAdrs(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    const adrDirAbs = path.join(root, config.paths.adr_docs);
+    if (!fs.existsSync(adrDirAbs))
+        return { issues, checkedFiles: 0 };
+    const entries = fs.readdirSync(adrDirAbs).filter((f) => f.endsWith(".md"));
+    const adrFiles = listAdrFiles(adrDirAbs);
+    const relDir = config.paths.adr_docs;
+    // Filename format (README.md and index files are exempt).
+    for (const f of entries) {
+        if (f.toLowerCase() === "readme.md")
+            continue;
+        if (!ADR_FILE_RE.test(f)) {
+            issues.push({
+                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.",
+            });
+        }
+    }
+    // Duplicate numbers / slugs.
+    const byNumber = new Map();
+    const bySlug = new Map();
+    for (const info of adrFiles) {
+        byNumber.set(info.number, [...(byNumber.get(info.number) ?? []), path.basename(info.file)]);
+        bySlug.set(info.slug, [...(bySlug.get(info.slug) ?? []), path.basename(info.file)]);
+    }
+    for (const [num, files] of byNumber) {
+        if (files.length > 1) {
+            issues.push({
+                code: "ADR_DUPLICATE_NUMBER",
+                severity: "error",
+                file: path.join(relDir, files[1]),
+                message: `Duplicate ADR number ${String(num).padStart(config.defaults.adr_padding, "0")}: ${files.join(", ")}`,
+                suggestion: "Renumber one of the ADRs; numbers must be unique and never reused.",
+            });
+        }
+    }
+    for (const [slug, files] of bySlug) {
+        if (files.length > 1) {
+            issues.push({
+                code: "ADR_DUPLICATE_SLUG",
+                severity: "error",
+                file: path.join(relDir, files[1]),
+                message: `Duplicate ADR slug '${slug}': ${files.join(", ")}`,
+            });
+        }
+    }
+    const existingBasenames = new Set(entries);
+    for (const info of adrFiles) {
+        const rel = path.join(relDir, path.basename(info.file));
+        const doc = parseDocFile(info.file);
+        if (doc.parseError || !doc.hasFrontmatter) {
+            issues.push({
+                code: "DOC_FRONTMATTER_INVALID",
+                severity: "error",
+                file: rel,
+                message: doc.parseError
+                    ? `Frontmatter YAML cannot be parsed: ${doc.parseError}`
+                    : "ADR is missing YAML frontmatter",
+            });
+            continue;
+        }
+        const data = doc.data;
+        // Title must contain the same number as the filename.
+        const title = typeof data["title"] === "string" ? data["title"] : "";
+        if (!title) {
+            issues.push({
+                code: "DOC_REQUIRED_FIELD_MISSING",
+                severity: "error",
+                file: rel,
+                message: "ADR frontmatter is missing 'title'",
+            });
+        }
+        else {
+            const numMatch = /(\d{4,})/.exec(title);
+            if (!numMatch || parseInt(numMatch[1], 10) !== info.number) {
+                issues.push({
+                    code: "ADR_TITLE_NUMBER_MISMATCH",
+                    severity: "error",
+                    file: rel,
+                    message: `Title number does not match filename number ${info.numberStr}`,
+                    suggestion: `Use a title like "ADR-${info.numberStr}：...".`,
+                });
+            }
+        }
+        const status = data["status"];
+        if (typeof status !== "string" || !VALID_ADR_STATUSES.includes(status)) {
+            issues.push({
+                code: "ADR_STATUS_INVALID",
+                severity: "error",
+                file: rel,
+                message: `Invalid ADR status '${String(status)}'`,
+                suggestion: `Use one of: ${VALID_ADR_STATUSES.join(", ")}.`,
+            });
+        }
+        if (!dateValueToString(data["date"])) {
+            issues.push({
+                code: "ADR_DATE_INVALID",
+                severity: "error",
+                file: rel,
+                message: "'date' is missing or not a valid YYYY-MM-DD date",
+            });
+        }
+        const owners = data["owners"];
+        if (!Array.isArray(owners) || owners.length === 0) {
+            issues.push({
+                code: "ADR_OWNERS_EMPTY",
+                severity: "error",
+                file: rel,
+                message: "'owners' must be a non-empty array",
+            });
+        }
+        // Required sections with non-empty content.
+        for (const [key, aliases] of Object.entries(SECTION_ALIASES)) {
+            if (!hasSection(doc.content, aliases)) {
+                issues.push({
+                    code: `ADR_MISSING_${key.toUpperCase()}`,
+                    severity: "error",
+                    file: rel,
+                    message: `Missing required section: ${aliases[0]}`,
+                    suggestion: `Add a "## ${aliases[0]}" section.`,
+                });
+            }
+            else if (!sectionHasContent(doc.content, aliases)) {
+                issues.push({
+                    code: `ADR_MISSING_${key.toUpperCase()}`,
+                    severity: "error",
+                    file: rel,
+                    message: `Section "${aliases[0]}" is empty`,
+                    suggestion: `Fill in the "## ${aliases[0]}" section.`,
+                });
+            }
+        }
+        // supersedes / superseded_by references must exist.
+        for (const field of ["supersedes", "superseded_by"]) {
+            const refs = data[field];
+            if (!Array.isArray(refs))
+                continue;
+            for (const ref of refs) {
+                if (typeof ref !== "string" || ref.trim() === "")
+                    continue;
+                const base = path.basename(ref);
+                if (!existingBasenames.has(base)) {
+                    issues.push({
+                        code: "ADR_REFERENCE_NOT_FOUND",
+                        severity: "error",
+                        file: rel,
+                        message: `'${field}' references a file that does not exist: ${ref}`,
+                    });
+                }
+            }
+        }
+        if (status === "superseded") {
+            const sb = data["superseded_by"];
+            if (!Array.isArray(sb) || sb.filter((s) => typeof s === "string" && s.trim()).length === 0) {
+                issues.push({
+                    code: "ADR_SUPERSEDED_WITHOUT_LINK",
+                    severity: "warning",
+                    file: rel,
+                    message: "ADR is marked 'superseded' but 'superseded_by' is empty",
+                    suggestion: "Point 'superseded_by' at the replacing ADR file.",
+                });
+            }
+        }
+    }
+    return { issues, checkedFiles: adrFiles.length };
+}

package/dist/validators/agents-validator.d.ts

@@ -0,0 +1,3 @@
+import type { ValidatorContext, ValidatorResult } from "./context.js";
+export declare function findLocalAgentsFiles(root: string, rootAgents: string): string[];
+export declare function validateAgents(ctx: ValidatorContext): ValidatorResult;

package/dist/validators/agents-validator.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import fg from "fast-glob";
+import { compareAgentsRules } from "../analyzers/duplicate-rule-analyzer.js";
+export function findLocalAgentsFiles(root, rootAgents) {
+    return fg
+        .sync("**/AGENTS.md", {
+        cwd: root,
+        ignore: ["node_modules/**", ".git/**", "dist/**", "templates/**"],
+    })
+        .filter((rel) => rel !== rootAgents)
+        .sort();
+}
+export function validateAgents(ctx) {
+    const issues = [];
+    const { root, config } = ctx;
+    const rootAgentsRel = config.paths.root_agents;
+    const rootAgentsAbs = path.join(root, rootAgentsRel);
+    let rootContent = null;
+    let checkedFiles = 0;
+    if (!fs.existsSync(rootAgentsAbs)) {
+        issues.push({
+            code: "ROOT_AGENTS_MISSING",
+            severity: "error",
+            file: rootAgentsRel,
+            message: `Root ${rootAgentsRel} is missing`,
+            suggestion: "Run `meta init` to generate it.",
+        });
+    }
+    else {
+        checkedFiles++;
+        rootContent = fs.readFileSync(rootAgentsAbs, "utf8");
+        const lines = rootContent.split(/\r?\n/).length;
+        if (lines > config.defaults.agents_max_lines) {
+            issues.push({
+                code: "AGENTS_TOO_LONG",
+                severity: "warning",
+                file: rootAgentsRel,
+                message: `Root AGENTS.md is ${lines} lines (recommended max: ${config.defaults.agents_max_lines})`,
+                suggestion: "Move detailed rules into docs/domain/, docs/architecture/ or docs/engineering/ and keep only references here.",
+            });
+        }
+    }
+    for (const rel of findLocalAgentsFiles(root, rootAgentsRel)) {
+        checkedFiles++;
+        const content = fs.readFileSync(path.join(root, rel), "utf8");
+        const lines = content.split(/\r?\n/).length;
+        if (lines > config.defaults.local_agents_max_lines) {
+            issues.push({
+                code: "AGENTS_TOO_LONG",
+                severity: "warning",
+                file: rel,
+                message: `Local AGENTS.md is ${lines} lines (recommended max: ${config.defaults.local_agents_max_lines})`,
+                suggestion: "Move detailed rules into the domain documentation.",
+            });
+        }
+        if (rootContent) {
+            const { duplicates, conflicts } = compareAgentsRules(rootContent, content);
+            for (const dup of duplicates) {
+                issues.push({
+                    code: "AGENTS_DUPLICATE_RULE",
+                    severity: "warning",
+                    file: rel,
+                    line: dup.localLine,
+                    message: `Rule duplicates root AGENTS.md (line ${dup.rootLine}): "${dup.rule}"`,
+                    suggestion: "Keep the detailed rule in domain docs and retain only a reference in AGENTS.md.",
+                });
+            }
+            for (const c of conflicts) {
+                issues.push({
+                    code: "AGENTS_POTENTIAL_CONFLICT",
+                    severity: "warning",
+                    file: rel,
+                    line: c.localLine,
+                    message: `Rule may conflict with root AGENTS.md (line ${c.rootLine}): local "${c.localRule}" vs root "${c.rootRule}"`,
+                    suggestion: "Resolve the contradiction or scope the local rule explicitly.",
+                });
+            }
+        }
+    }
+    return { issues, checkedFiles };
+}