artifact-chain-assistant 0.8.0

package/EXTENDED-ARTIFACT-CATALOG.md

@@ -0,0 +1,312 @@
+# Extended Artifact Catalog
+
+This document summarizes the extended artifact type catalog for `artifact-chain-assistant`. It
+covers type classification, recommended paths and ID patterns, template adoption rules, and the
+three-tier authority boundary between `artifact-graph`, the plugin, and target projects.
+
+For core artifact types (`feature`, `scenario`, `decision`, `design`, `test`, `e2e_test`), see the
+plugin README and INSTALL.md. This document covers opt-in types beyond the core set.
+
+## Three-Tier Authority Model
+
+| Layer | Scope | Responsibility for Extended Types |
+| --- | --- | --- |
+| **artifact-graph** | Deterministic graph capabilities | Reads type definitions from config; indexes artifacts; provides context/packet/validate. Does **not** ship default paths or ID patterns for extended types. Types without configured paths are not indexed. |
+| **artifact-chain-assistant** | General assistant guidance | Provides starter templates, profile suggestions, and generic review checklists. **Templates are guidance, not authority.** Project-local templates and review skills override plugin suggestions. |
+| **Target project** | Final working method | Decides which extended types to enable; maintains config, local templates, review skills, and ID rules. **Project-local overrides plugin suggestions.** Enables new types progressively as maturity grows. |
+
+## Extended Artifact Type Catalog
+
+Extended types are organized into four categories. Each type entry includes recommended paths, ID
+patterns, lifecycle rules, and review checkpoints. All recommended values are **guidance** — the
+project's `artifact-graph.config.yaml` is the final authority.
+
+### Contract Artifacts
+
+Contract artifacts record interface agreements at system boundaries. When requirements flow from
+features and scenarios into implementation, contracts are key upstream artifacts for context
+assembly.
+
+| Type | Recommended Path | Recommended ID Pattern | Lifecycle | Review Checkpoints |
+| --- | --- | --- | --- | --- |
+| `api_contract` | `artifacts/contracts/api/` | `API-{nnn}` or `{service}-API-{version}` | Create/update on API change; mark deprecated when API is retired | Consistency with implementation, error code coverage, version compatibility, request/response schema completeness |
+| `cli_contract` | `artifacts/contracts/cli/` | `CLI-{nnn}` or `{tool}-CLI-{version}` | Create/update on CLI interface change | Command signature, parameter types, exit codes, backward compatibility, help text accuracy |
+| `ui_contract` | `artifacts/contracts/ui/` | `UI-{nnn}` | Create/update on UI flow change | Interaction flows, state transitions, accessibility, error state coverage |
+| `ipc_contract` | `artifacts/contracts/ipc/` | `IPC-{nnn}` | Create/update on IPC channel change | Message format, error propagation, frontend/backend boundary, serialization compatibility |
+| `data_contract` | `artifacts/contracts/data/` | `DATA-{nnn}` | Create/update on data model/schema change | Field semantics, version compatibility, migration path, default value semantics |
+| `report_contract` | `artifacts/contracts/report/` | `RPT-{nnn}` | Create/update on report format change | Field semantics, aggregation logic, output format, time window semantics |
+| `integration_contract` | `artifacts/contracts/integration/` | `INT-{nnn}` | Create/update on external system integration change | Interface protocol, timeout, retry strategy, idempotency, error classification |
+| `batch_job_contract` | `artifacts/contracts/batch/` | `BATCH-{nnn}` | Create/update on batch job change | Input/output format, schedule expression, idempotency, error handling, replay strategy |
+
+### Domain and Data Artifacts
+
+Domain and data artifacts capture business concepts and technical data models. They are core
+artifacts for enterprise Java and DDD projects.
+
+| Type | Recommended Path | Recommended ID Pattern | Lifecycle | Review Checkpoints |
+| --- | --- | --- | --- | --- |
+| `domain_model` | `artifacts/domain/` | `DM-{nnn}` or entity name | Create/update on domain concept change | Aggregate boundaries, domain events, bounded context mapping, invariant definitions |
+| `database_migration` | `artifacts/migrations/` | `MIG-{nnn}` or timestamp (e.g., `20260709-001`) | Create on schema change; mark executed after deployment | Rollback path, data compatibility, performance impact, large table change strategy |
+
+### Deployment and Operations Artifacts
+
+Deployment and operations artifacts cover production environment changes, security, performance, and
+operational procedures. Enable only when the project has corresponding operational processes.
+
+| Type | Recommended Path | Recommended ID Pattern | Lifecycle | Review Checkpoints |
+| --- | --- | --- | --- | --- |
+| `deployment_manifest` | `artifacts/deploy/` | `DEP-{nnn}` or environment name (e.g., `DEP-prod`) | Create/update on deployment config change | Environment differences, rollback strategy, resource limits, health check configuration |
+| `security_review` | `artifacts/security/` | `SEC-{nnn}` | Create/update on security review cycle or major change | Threat model coverage, fix status tracking, compliance mapping, sensitive data handling |
+| `performance_budget` | `artifacts/performance/` | `PERF-{nnn}` | Create/update on performance target change | Metric baseline, threshold definition, regression detection strategy, measurement method |
+| `migration_plan` | `artifacts/migrations/plan/` | `MPLAN-{nnn}` | Create on migration start; update at each phase completion | Phase division, rollback point definition, data validation strategy, parallel run period |
+| `runbook` | `artifacts/runbooks/` | `RUN-{nnn}` | Create/update on operational procedure change | Step accuracy, alert correlation, responsible person, last execution date |
+
+### Release Governance Artifacts
+
+Release governance artifacts cover versioning strategy, publishing workflows, and open-source
+compliance. Enable only for parent repos, release governance repos, or multi-package monorepos that
+own the release process.
+
+| Type | Recommended Path | Recommended ID Pattern | Lifecycle | Review Checkpoints |
+| --- | --- | --- | --- | --- |
+| `release_policy` | `artifacts/governance/` | `RP-{nnn}` | Create/update on release policy change | Version semantics, release cadence, branch strategy, changelog standard, rollback plan |
+| `publish_skill` | `artifacts/governance/` | `PS-{nnn}` | Create/update on publish workflow change | Publish targets, quality gates, compliance checks, error handling, rollback plan |
+| `oss_compliance` | `artifacts/governance/` | `OSS-{nnn}` | Create/update on OSS compliance rule or release scope change | License policy, dependency audit, standard files, security disclosure, release exclusions |
+
+### Agent and Hook Artifacts
+
+Agent and hook artifacts cover AI-assisted workflows and CI/CD gates. Enable only when the project
+has corresponding files or processes.
+
+| Type | Recommended Path | Recommended ID Pattern | Lifecycle | Review Checkpoints |
+| --- | --- | --- | --- | --- |
+| `agent_skill` | `artifacts/skills/` | `SKILL-{nnn}` | Create/update on skill definition change | Input/output contract, tool dependencies, permission boundary, error handling |
+| `hook_policy` | `artifacts/policies/` | `HOOK-{nnn}` | Create/update on hook policy change | Trigger conditions, gate rules, bypass approval process, audit log |
+| `prompt_packet` | `artifacts/packets/` | `PP-{nnn}` | Create/update on prompt template or context assembly change | Context sources, prompt clarity, token budget, output contract, testability |
+
+## Bootstrap Trimming Strategy
+
+Bootstrap selects a **minimum viable profile** rather than enabling all known types.
+
+Rules:
+
+1. **Core set always enabled**: `feature`, `scenario`, `decision`, `design`, `test`, `e2e_test`.
+2. **Contracts by evidence**: Enable only when the project has corresponding interface files (e.g., OpenAPI spec, CLI entry, IPC channel definition).
+3. **Domain/data by project shape**: Enterprise Java/DDD projects may enable `domain_model`; projects with databases may enable `database_migration`.
+4. **Ops by operational process**: Enable only when the project has deployment configs, security review processes, or operational manuals.
+5. **Agent/hook by local files**: Enable only when the project has `skills/`, `policies/`, or hook config files.
+6. **Progressive expansion**: As project maturity grows, add new types in `artifact-graph.config.yaml`. Existing artifacts and traceability relationships are unaffected.
+
+After bootstrap, the enabled types, paths, and ID patterns are recorded in
+`artifact-graph.config.yaml`. Deferred types and their evidence conditions are documented in the
+project's artifact catalog so future expansion is a recorded decision.
+
+## Template Adoption
+
+### Template Source Rules
+
+1. **Plugin templates are onboarding guidance.** `artifact-chain-assistant` provides starter
+   templates for each extended type in `templates/extended/`, organized by category
+   (`contracts/`, `domain/`, `ops/`, `agent/`). Plugin templates do not determine the project's
+   artifact shape.
+2. **Project-local templates are authority.** When a project needs different section structures,
+   review standards, or naming rules, project-local templates override plugin templates.
+3. **Fallback when no template exists.** If a project enables an extended type but has no local
+   template, the assistant may reference the plugin starter but must note it has not been
+   customized.
+4. **Adoption flow.** Copy the starter template from `templates/extended/` to the project-local
+   `artifacts/templates/` or equivalent, then customize.
+
+### Template Lifecycle
+
+1. **Bootstrap phase**: Bootstrap skill references plugin starters to generate initial artifact
+   structure. Template source is recorded in `artifacts/README.md`.
+2. **Adoption phase**: Team reviews the starter, decides which sections to keep/modify/remove,
+   and copies to local. The customized version becomes authority.
+3. **Mature phase**: Project maintains a complete local template library. Plugin starters are
+   referenced only when onboarding new members or enabling new types.
+4. **Upgrade review**: When the plugin updates a starter, the project reviews the diff and
+   selectively merges useful changes while preserving local customizations.
+
+### Template Directory Layout
+
+```
+templates/
+  core/                          # Core artifact templates
+    feature/
+      starter.md                 # Drafting guidance template
+      review-checklist.md        # Generic review checklist
+    scenario/
+      starter.md
+      review-checklist.md
+    decision/
+      starter.md
+      review-checklist.md
+    design/
+      starter.md
+      review-checklist.md
+    test/
+      starter.md
+      review-checklist.md
+    e2e_test/
+      starter.md
+      review-checklist.md
+  extended/                      # Extended artifact templates (by category)
+    contracts/
+      api_contract/
+        starter.md
+        review-checklist.md
+      cli_contract/
+        starter.md
+        review-checklist.md
+      data_contract/
+        starter.md
+        review-checklist.md
+      ...                        # Other contract types follow the same structure
+    domain/
+      domain_model/
+        starter.md
+        review-checklist.md
+      database_migration/
+        starter.md
+        review-checklist.md
+    ops/
+      deployment_manifest/
+        starter.md
+        review-checklist.md
+      runbook/
+        starter.md
+        review-checklist.md
+      ...
+    governance/
+      release_policy/
+        starter.md
+        review-checklist.md
+      publish_skill/
+        starter.md
+        review-checklist.md
+      oss_compliance/
+        starter.md
+        review-checklist.md
+    agent/
+      agent_skill/
+        starter.md
+        review-checklist.md
+      hook_policy/
+        starter.md
+        review-checklist.md
+      prompt_packet/
+        starter.md
+        review-checklist.md
+```
+
+Each type's `starter.md` contains the artifact structure template and minimal filling guidance.
+`review-checklist.md` is the generic review checkpoint baseline. Both are **suggestions that can be
+fully overridden by project-local templates**.
+
+## Evidence-Based Enablement
+
+Bootstrap activates extended artifact types only when local files or directories exist:
+
+| Type | Enablement Evidence |
+| --- | --- |
+| `api_contract` | OpenAPI/Swagger spec, API documentation, or REST endpoint code exists |
+| `cli_contract` | CLI entry code or command definitions exist |
+| `data_contract` | Data model definitions or schema files exist |
+| `domain_model` | DDD aggregates, entities, or value objects exist in code |
+| `database_migration` | Database schema or migration scripts exist |
+| `security_review` | Security review process, security-related code, or Spring Security config exists |
+| `performance_budget` | Performance test scripts, monitoring config, or performance baseline docs exist |
+| `migration_plan` | Migration planning docs, architecture evolution plans, or system transition plans exist |
+| `runbook` | Operational procedures or runbook documents exist |
+| `deployment_manifest` | Deployment configs (K8s, Docker, etc.) exist |
+| `agent_skill` | Agent skill definition files exist |
+| `hook_policy` | CI/CD hook configurations exist |
+| `release_policy` | Release policy docs, versioning strategy, or release process files exist |
+| `publish_skill` | Publish workflow scripts, CI/CD publish pipelines, or registry configuration exists |
+| `prompt_packet` | Prompt template files, context assembly configs, or AI workflow definitions exist |
+| `oss_compliance` | License files, dependency audit configs, or OSS compliance process docs exist |
+
+**Rule**: Enable a type only when local evidence exists. Do not enable because the plugin provides a
+template.
+
+## artifact-graph Runtime Support for Custom Types
+
+Starting with `artifact-graph` 0.3.0, config-driven custom types have full runtime support.
+The extended catalog has two layers:
+
+1. **Implemented in artifact-chain-assistant**: starter templates, review checklists, bootstrap
+   recommendations, and evidence-based adoption guidance.
+2. **Implemented in artifact-graph 0.3.0+**: config-driven indexing, graph traversal, `context`,
+   `packet`, `validate`, `version-lock`, and `extraFields` for any registered custom type.
+
+### What the Runtime Provides for Custom Types
+
+Once a type is registered in `artifact-graph.config.yaml` with `paths` and optionally
+`idPatterns`, the runtime delivers:
+
+1. **Scanning and frontmatter parsing**: Read `types.{type}.paths` from config; scan matching
+   files; parse frontmatter for `id`, `title`, `status` and other standard fields. Types without
+   configured paths are not indexed.
+2. **Graph edges**: Custom types participate in graph traversal through `related_<type>`
+   frontmatter fields, `@<type> <ID>` traceability comments, and explicit relationship fields.
+3. **Target selector**: `--target <type>:<id>` works with `context`, `packet`, `packet-prompt`,
+   and `audit` for any type that has `target: true` in config. The ID may contain colons; only the
+   first colon separates type from ID. There is **no** dynamic `--{type}` flag; `--target` is the
+   universal entry point.
+4. **Extra fields**: Declare `extraFields` in config to index specific frontmatter fields (string,
+   number, boolean, enum). Undeclared fields remain in raw frontmatter but are not indexed.
+5. **Validation**: Custom types participate in ID pattern checks, dangling relation warnings, orphan
+   artifact warnings, and version-lock freshness checks.
+6. **Version-lock**: Custom type artifacts and their traceability edges are included in
+   version-lock refresh, audit, and bootstrap.
+
+### Capability Matrix
+
+| Capability | Core Types | Extended Types | Notes |
+| --- | --- | --- | --- |
+| File indexing and ID parsing | Implemented | Implemented via config `paths` + `idPatterns` | Types without configured paths are not indexed |
+| Graph traversal (upstream/downstream) | Implemented | Implemented via `related_<type>` fields and traceability comments | Strength depends on traceability annotation density |
+| context/packet assembly | Implemented (`--target <type>:<id>`) | Implemented (`--target <type>:<id>`) | `--target` is the universal entry; no dynamic `--{type}` flags |
+| validate | Implemented | Implemented | ID pattern checks, dangling relations, orphan warnings, lock freshness |
+| version-lock | Implemented | Implemented | Custom type edges included in refresh/audit/bootstrap |
+| Artifact content quality judgment | No | No | artifact-graph does not judge "good PRD" or "good contract" |
+| Built-in edge rules | No | No | All edge rules come from artifact content, not type metadata |
+
+### Known Limitations
+
+- **Content quality not judged**: artifact-graph validates structure and traceability, not whether
+  an artifact's content is well-written or complete.
+- **Sparse traceability annotations**: Custom artifacts without `related_*` frontmatter fields or
+  implementation traceability comments will produce weak graph relationships. Mitigation:
+  project-local review should require traceability fields.
+- **ID pattern collisions**: Multiple types using the same ID pattern can cause ambiguous graph
+  edges. Mitigation: use distinct ID prefixes per type (e.g., `API-`, `CLI-`).
+- **Path overlaps**: Multiple types whose path globs match the same files create duplicate graph
+  nodes. Mitigation: use mutually exclusive path globs.
+- **Loosely-coupled ops artifacts**: Some types (e.g., `runbook`, `deployment_manifest`) may have
+  naturally loose links to the core requirement chain. This is expected behavior, not a defect.
+
+## Project Shape Profiles
+
+Nine project profiles each map to a recommended starter set and a defer-until-ready list. Profiles
+are used only during bootstrap — they are not a runtime concept. The final selection is written to
+`artifact-graph.config.yaml`.
+
+| Profile | Recommended Extended Types | Deferred Types |
+| --- | --- | --- |
+| Docs/planning repo | None | All extended types |
+| TypeScript library or CLI | `cli_contract` | Other contracts, domain, ops |
+| API service | `api_contract`, `data_contract` | `domain_model`, `deployment_manifest`, `runbook`, `performance_budget` |
+| Enterprise Java/Spring/JVM | `api_contract`, `data_contract`, `integration_contract`, `batch_job_contract`, `domain_model`, `database_migration`, `security_review` | `deployment_manifest`, `runbook`, `performance_budget` |
+| Desktop or full-stack app | `ui_contract`, `ipc_contract`, `api_contract` | `deployment_manifest`, `runbook` |
+| Agent or plugin toolkit | `agent_skill`, `hook_policy`, `prompt_packet` | Other extended types |
+| Parent or release governance repo | `release_policy`, `publish_skill`, `oss_compliance` | Other extended types |
+| Existing mature artifact repo | As-needed based on existing files | Types without local evidence |
+| Small first-time project | None | All extended types |
+
+## Related Documents
+
+- [README](README.md) — Plugin overview with full feature list
+- [INSTALL.md](INSTALL.md) — Installation, bootstrap flow, and profile expansion guide
+- [ADOPTION-GUIDE](https://github.com/ifoohoo/artifact-chain-assistant/blob/main/templates/extended/ADOPTION-GUIDE.md) — Step-by-step template adoption and upgrade review guide

package/EXTENDED-ARTIFACT-CATALOG.zh-CN.md

@@ -0,0 +1,289 @@
+# 扩展制品目录
+
+[English](EXTENDED-ARTIFACT-CATALOG.md)
+
+本文档汇总 `artifact-chain-assistant` 的扩展制品类型目录，内容包括类型分类、推荐路径与 ID 模式、
+模板采用规则，以及 `artifact-graph`、插件与目标项目之间的三层权威边界。
+
+核心制品类型（`feature`、`scenario`、`decision`、`design`、`test`、`e2e_test`）见插件 README 和
+INSTALL.md。本文档只介绍核心集合之外的可选类型。
+
+## 三层权威模型
+
+| 层级 | 权威范围 | 对扩展制品的职责 |
+|------|---------|-----------------|
+| **artifact-graph** | 确定性图能力 | 从 config 读取类型定义，索引制品，提供 context/packet/validate。**不内置扩展类型的默认路径或 ID 模式。** 未配置路径的类型不会被索引。 |
+| **artifact-chain-assistant** | 通用助手指导 | 提供扩展制品的入门模板、profile 建议和通用审查清单。**模板是指导，不是权威。** 项目本地模板和审查技能覆盖插件建议。 |
+| **目标项目** | 最终工作法 | 决定启用哪些扩展类型，维护 config、本地模板、审查技能和 ID 规则。**项目本地覆盖插件建议。** 随成熟度提升逐步启用新类型。 |
+
+## 扩展制品类型目录
+
+扩展类型按四个类别组织。每类制品包含推荐路径、ID 模式、生命周期规则和审查要点。所有推荐值
+均为**指导**——项目的 `artifact-graph.config.yaml` 才是最终权威。
+
+### 一、契约类制品
+
+契约类制品记录系统边界上的接口约定。需求从功能、场景流向实现时，契约是上下文组装的关键上游制品。
+
+| 制品类型 | 推荐路径 | 推荐 ID 模式 | 生命周期 | 审查要点 |
+|---------|---------|-------------|---------|---------|
+| `api_contract` | `artifacts/contracts/api/` | `API-{nnn}` 或 `{service}-API-{version}` | API 变更时创建/更新；废弃 API 时标记 deprecated | 与实现代码一致、覆盖错误码、版本兼容、请求/响应 schema 完整性 |
+| `cli_contract` | `artifacts/contracts/cli/` | `CLI-{nnn}` 或 `{tool}-CLI-{version}` | CLI 接口变更时创建/更新 | 命令签名、参数类型、退出码、向后兼容、帮助文本准确性 |
+| `ui_contract` | `artifacts/contracts/ui/` | `UI-{nnn}` | UI 流程变更时创建/更新 | 交互流程、状态转换、可访问性、错误状态覆盖 |
+| `ipc_contract` | `artifacts/contracts/ipc/` | `IPC-{nnn}` | IPC 通道变更时创建/更新 | 消息格式、错误传播、前后端边界、序列化兼容 |
+| `data_contract` | `artifacts/contracts/data/` | `DATA-{nnn}` | 数据模型/schema 变更时创建/更新 | 字段含义、版本兼容、迁移路径、默认值语义 |
+| `report_contract` | `artifacts/contracts/report/` | `RPT-{nnn}` | 报告格式变更时创建/更新 | 字段含义、聚合逻辑、输出格式、时间窗口语义 |
+| `integration_contract` | `artifacts/contracts/integration/` | `INT-{nnn}` | 外部系统集成变更时创建/更新 | 接口协议、超时、重试策略、幂等性、错误分类 |
+| `batch_job_contract` | `artifacts/contracts/batch/` | `BATCH-{nnn}` | 批处理作业变更时创建/更新 | 输入/输出格式、调度表达式、幂等性、错误处理、重放策略 |
+
+### 二、领域与数据制品
+
+领域与数据制品记录业务概念和技术数据模型，是企业 Java 和 DDD 项目的核心制品。
+
+| 制品类型 | 推荐路径 | 推荐 ID 模式 | 生命周期 | 审查要点 |
+|---------|---------|-------------|---------|---------|
+| `domain_model` | `artifacts/domain/` | `DM-{nnn}` 或实体名 | 领域概念变更时创建/更新 | 聚合边界、领域事件、限界上下文映射、不变量定义 |
+| `database_migration` | `artifacts/migrations/` | `MIG-{nnn}` 或时间戳（如 `20260709-001`） | schema 变更时创建；上线后标记已执行 | 回滚路径、数据兼容性、性能影响、大表变更策略 |
+
+### 三、部署与运维制品
+
+部署与运维制品覆盖生产环境的变更、安全、性能和操作流程。项目具备对应运维流程时才启用。
+
+| 制品类型 | 推荐路径 | 推荐 ID 模式 | 生命周期 | 审查要点 |
+|---------|---------|-------------|---------|---------|
+| `deployment_manifest` | `artifacts/deploy/` | `DEP-{nnn}` 或环境名（如 `DEP-prod`） | 部署配置变更时创建/更新 | 环境差异、回滚策略、资源限制、健康检查配置 |
+| `security_review` | `artifacts/security/` | `SEC-{nnn}` | 安全审查周期或重大变更时创建/更新 | 威胁模型覆盖、修复状态跟踪、合规映射、敏感数据处理 |
+| `performance_budget` | `artifacts/performance/` | `PERF-{nnn}` | 性能目标变更时创建/更新 | 指标基线、阈值定义、回归检测策略、测量方法 |
+| `migration_plan` | `artifacts/migrations/plan/` | `MPLAN-{nnn}` | 迁移启动时创建；每阶段完成时更新 | 阶段划分、回滚点定义、数据验证策略、并行运行期 |
+| `runbook` | `artifacts/runbooks/` | `RUN-{nnn}` | 运维流程变更时创建/更新 | 步骤准确性、告警关联、责任人、最近执行日期 |
+
+### 四、发布治理制品
+
+发布治理制品覆盖版本策略、发布工作流和开源合规。仅父工程、发布治理仓库或自身负责发布流程的多包 monorepo 才启用。
+
+| 制品类型 | 推荐路径 | 推荐 ID 模式 | 生命周期 | 审查要点 |
+|---------|---------|-------------|---------|---------|
+| `release_policy` | `artifacts/governance/` | `RP-{nnn}` | 发布策略变更时创建/更新 | 版本语义、发布节奏、分支策略、变更日志规范、回滚计划 |
+| `publish_skill` | `artifacts/governance/` | `PS-{nnn}` | 发布工作流变更时创建/更新 | 发布目标、质量门禁、合规检查、错误处理、回滚计划 |
+| `oss_compliance` | `artifacts/governance/` | `OSS-{nnn}` | 开源合规规则或发布范围变更时创建/更新 | 许可证策略、依赖审计、标准文件、安全披露、发布排除规则 |
+
+### 五、Agent 与 Hook 制品
+
+Agent 与 Hook 制品覆盖 AI 辅助工作流和 CI/CD 门禁。项目存在对应文件或流程时才启用。
+
+| 制品类型 | 推荐路径 | 推荐 ID 模式 | 生命周期 | 审查要点 |
+|---------|---------|-------------|---------|---------|
+| `agent_skill` | `artifacts/skills/` | `SKILL-{nnn}` | 技能定义变更时创建/更新 | 输入/输出契约、工具依赖、权限边界、错误处理 |
+| `hook_policy` | `artifacts/policies/` | `HOOK-{nnn}` | hook 策略变更时创建/更新 | 触发条件、门禁规则、绕过审批流程、审计日志 |
+| `prompt_packet` | `artifacts/packets/` | `PP-{nnn}` | prompt 模板或上下文组装规则变更时创建/更新 | 上下文来源、prompt 清晰度、token 预算、输出契约、可测试性 |
+
+## Bootstrap 裁剪策略
+
+bootstrap 的职责是按项目形态选出**最小可用 profile**，而不是启用所有已知类型。
+
+裁剪规则：
+
+1. **基础集合始终启用**：`feature`、`scenario`、`decision`、`design`、`test`、`e2e_test`。
+2. **契约类按证据加入**：项目本地存在对应的接口文件（如 OpenAPI spec、CLI 入口、IPC 通道定义）才启用。
+3. **领域与数据类按项目形态加入**：企业 Java/DDD 项目可启用 `domain_model`；使用数据库的项目可启用 `database_migration`。
+4. **运维类按运维流程加入**：项目有部署配置、安全审查流程或运维手册，才启用对应类型。
+5. **Agent/Hook 类按本地文件加入**：项目存在 `skills/`、`policies/` 或 hook 配置文件才启用。
+6. **发布治理类按治理证据加入**：项目存在发布策略、发布脚本或开源合规流程时，才启用 `release_policy`、`publish_skill`、`oss_compliance`。
+7. **渐进扩展**：项目成熟度提升后，可按需在 `artifact-graph.config.yaml` 中新增类型，已有制品和追溯关系不受影响。
+
+bootstrap 执行后，启用的类型、路径和 ID 模式记录在 `artifact-graph.config.yaml` 中；延后启用的
+类型及其证据条件记录在项目制品目录中，让日后的扩展有据可查。
+
+## 模板采用
+
+### 模板来源规则
+
+1. **插件模板是入门指导**。`artifact-chain-assistant` 在 `templates/extended/` 下为每种扩展类型
+   提供 starter 模板，按类别组织（`contracts/`、`domain/`、`ops/`、`agent/`）。插件模板不决定
+   项目的制品形态。
+2. **项目本地模板是权威**。项目需要不同的章节结构、审查标准或命名规则时，本地模板覆盖插件模板。
+3. **无模板时的回退**。项目启用了某扩展类型但没有本地模板时，助手可以引用插件 starter，但必须
+   提示用户该模板尚未按项目定制。
+4. **采用流程**。把 starter 模板从 `templates/extended/` 复制到项目本地的 `artifacts/templates/`
+   或等价位置，定制后即成为项目权威。
+
+### 模板生命周期
+
+1. **Bootstrap 阶段**：bootstrap 技能引用插件 starter 模板生成初始制品结构，模板来源记录在
+   `artifacts/README.md` 中。
+2. **采用阶段**：团队审阅 starter 模板，决定各章节保留、修改还是删除，再复制到本地。定制后的
+   版本成为权威。
+3. **成熟阶段**：项目本地维护完整的模板库，只在新成员上手或启用新类型时才参考插件 starter。
+4. **升级评审**：插件更新 starter 时，项目审查 diff，有选择地合入有用变更，保留本地定制。
+
+### 模板目录布局
+
+```
+templates/
+  core/                          # 核心制品模板
+    feature/
+      starter.md                 # 起草指引模板
+      review-checklist.md        # 通用审查清单
+    scenario/
+      starter.md
+      review-checklist.md
+    decision/
+      starter.md
+      review-checklist.md
+    design/
+      starter.md
+      review-checklist.md
+    test/
+      starter.md
+      review-checklist.md
+    e2e_test/
+      starter.md
+      review-checklist.md
+  extended/                      # 扩展制品模板（按类别组织）
+    contracts/
+      api_contract/
+        starter.md
+        review-checklist.md
+      cli_contract/
+        starter.md
+        review-checklist.md
+      data_contract/
+        starter.md
+        review-checklist.md
+      ...                        # 其他契约类型同构
+    domain/
+      domain_model/
+        starter.md
+        review-checklist.md
+      database_migration/
+        starter.md
+        review-checklist.md
+    ops/
+      deployment_manifest/
+        starter.md
+        review-checklist.md
+      runbook/
+        starter.md
+        review-checklist.md
+      ...
+    governance/
+      release_policy/
+        starter.md
+        review-checklist.md
+      publish_skill/
+        starter.md
+        review-checklist.md
+      oss_compliance/
+        starter.md
+        review-checklist.md
+    agent/
+      agent_skill/
+        starter.md
+        review-checklist.md
+      hook_policy/
+        starter.md
+        review-checklist.md
+      prompt_packet/
+        starter.md
+        review-checklist.md
+```
+
+每个类型的 `starter.md` 包含制品结构模板和最基本的填写指引，`review-checklist.md` 是通用审查
+要点的基线。两者都只是建议，项目本地可以完全覆盖。
+
+## 按证据启用
+
+bootstrap 只在本地文件或目录确实存在时才启用扩展制品类型：
+
+| 制品类型 | 启用证据 |
+|---------|---------|
+| `api_contract` | 存在 OpenAPI/Swagger 规范、API 文档或 REST 端点代码 |
+| `cli_contract` | 存在 CLI 入口代码或命令定义 |
+| `data_contract` | 存在数据模型定义或 schema 文件 |
+| `domain_model` | 存在 DDD 聚合、实体或值对象代码 |
+| `database_migration` | 存在数据库 schema 或迁移脚本 |
+| `security_review` | 存在安全审查流程、安全相关代码或 Spring Security 配置 |
+| `performance_budget` | 存在性能测试脚本、监控配置或性能基线文档 |
+| `migration_plan` | 存在迁移规划文档、架构演进方案或系统过渡计划 |
+| `runbook` | 存在运维流程或操作手册 |
+| `deployment_manifest` | 存在部署配置（K8s、Docker 等） |
+| `agent_skill` | 存在 Agent 技能定义文件 |
+| `hook_policy` | 存在 CI/CD hook 配置 |
+| `prompt_packet` | 存在 prompt 模板文件、上下文组装配置或 AI 工作流定义 |
+| `release_policy` | 存在发布策略文档、版本策略或发布流程文件 |
+| `publish_skill` | 存在发布脚本、CI/CD 发布流水线或注册中心配置 |
+| `oss_compliance` | 存在许可证文件、依赖审计配置或开源合规流程文档 |
+
+**规则**：本地证据存在才启用对应类型，不要因为插件提供了模板就启用。
+
+## artifact-graph 对自定义类型的运行时支持
+
+从 `artifact-graph` 0.3.0 起，配置驱动的自定义类型获得了完整的运行时支持。扩展制品目录分为
+两个层次：
+
+1. **artifact-chain-assistant 已实现**：starter 模板、审查清单、bootstrap 推荐和按证据启用指导。
+2. **artifact-graph 0.3.0+ 已实现**：对任意注册的自定义类型，提供配置驱动的索引、图遍历、
+   `context`、`packet`、`validate`、`version-lock` 和 `extraFields` 支持。
+
+### 运行时为自定义类型提供的能力
+
+在 `artifact-graph.config.yaml` 中注册类型（`paths` 和可选的 `idPatterns`）后，运行时提供以下能力：
+
+1. **扫描与 frontmatter 解析**：读取 `types.{type}.paths`，扫描匹配文件，解析 frontmatter，提取
+   `id`、`title`、`status` 等标准字段。未配置路径的类型不会被索引。
+2. **图边建立**：自定义类型可通过 `related_<type>` frontmatter 字段、`@<type> <ID>` 追溯注释和
+   显式关系字段参与图遍历。
+3. **Target 选择器**：`--target <type>:<id>` 可用于 `context`、`packet`、`packet-prompt` 和 `audit`
+   命令，适用于 config 中标记了 `target: true` 的任意类型。ID 可以包含冒号，只有第一个冒号用于
+   分隔类型和 ID。注意：**没有**动态的 `--{type}` flag，`--target` 是通用入口。
+4. **额外字段**：在 config 中声明 `extraFields`，即可索引指定的 frontmatter 字段（string、number、
+   boolean、enum）。未声明的字段仍留在原始 frontmatter 中，但不会被索引。
+5. **验证**：自定义类型同样参与 ID 模式检查、悬空关系警告、孤立制品警告和版本锁新鲜度检查。
+6. **版本锁**：自定义类型的制品及其追溯边会纳入 version-lock 的 refresh、audit 和 bootstrap。
+
+### 能力矩阵
+
+| 能力 | 核心类型 | 扩展类型 | 说明 |
+|------|---------|---------|------|
+| 文件索引和 ID 解析 | 已实现 | 通过 config `paths` + `idPatterns` 实现 | 未配置路径的类型不会被索引 |
+| 图遍历（上游/下游） | 已实现 | 通过 `related_<type>` 字段和追溯注释实现 | 强度取决于追溯注释密度 |
+| context/packet 组装 | 已实现（`--target <type>:<id>`） | 已实现（`--target <type>:<id>`） | `--target` 是通用入口；没有动态 `--{type}` flag |
+| validate | 已实现 | 已实现 | ID 模式检查、悬空关系、孤立制品、锁新鲜度 |
+| version-lock | 已实现 | 已实现 | 自定义类型边纳入 refresh/audit/bootstrap |
+| 制品内容质量判断 | 不做 | 不做 | artifact-graph 不判断"好 PRD"或"好契约" |
+| 内置边规则 | 不做 | 不做 | 所有边规则来自制品内容，不来自类型元数据 |
+
+### 已知限制
+
+- **不判断内容质量**：artifact-graph 验证的是结构和追溯性，不判断制品内容写得好不好、完不完整。
+- **追溯注释稀疏**：自定义制品缺少 `related_*` frontmatter 字段，或实现文件缺少追溯注释时，图
+  遍历得到的关系会比较弱。缓解办法：项目本地审查中强制要求追溯字段。
+- **ID 模式冲突**：多个类型使用相同的 ID 模式，可能产生有歧义的图边。缓解办法：每个类型使用
+  不同的 ID 前缀（如 `API-`、`CLI-`）。
+- **路径重叠**：多个类型的路径 glob 匹配到相同文件，会产生重复的图节点。缓解办法：使用互斥的
+  路径 glob。
+- **运维制品关联本就松散**：某些类型（如 `runbook`、`deployment_manifest`）与核心需求链的联系
+  天然较弱。这是预期行为，不是缺陷。
+
+## 项目形态 Profile
+
+九种项目形态各自对应一套推荐的 starter 集合和延后启用列表。Profile 只在 bootstrap 阶段使用，
+不是运行时概念；最终选择会写入 `artifact-graph.config.yaml`。
+
+| 项目形态 | 推荐启用的扩展类型 | 延后启用的类型 |
+|---------|------------------|-------------|
+| 文档/规划仓库 | 无 | 所有扩展类型 |
+| TypeScript 库或 CLI | `cli_contract` | 其他契约、领域、运维 |
+| API 服务 | `api_contract`、`data_contract` | `domain_model`、`deployment_manifest`、`runbook`、`performance_budget` |
+| 企业级 Java/Spring/JVM | `api_contract`、`data_contract`、`integration_contract`、`batch_job_contract`、`domain_model`、`database_migration`、`security_review` | `deployment_manifest`、`runbook`、`performance_budget` |
+| 桌面/全栈应用 | `ui_contract`、`ipc_contract`、`api_contract` | `deployment_manifest`、`runbook` |
+| Agent/插件工具包 | `agent_skill`、`hook_policy`、`prompt_packet` | 其他扩展类型 |
+| Parent/发布治理仓库 | `release_policy`、`publish_skill`、`oss_compliance` | 其他扩展类型 |
+| 已有成熟制品仓库 | 按现有文件按需启用 | 无本地证据的类型 |
+| 首次尝试的小型项目 | 无 | 所有扩展类型 |
+
+## 相关文档
+
+- [README](README.md) — 插件概览与完整功能列表
+- [INSTALL.md](INSTALL.md) — 安装、bootstrap 流程和 profile 扩展指南
+- [ADOPTION-GUIDE](https://github.com/ifoohoo/artifact-chain-assistant/blob/main/templates/extended/ADOPTION-GUIDE.md) — 模板采用和升级评审的分步指南