artifact-chain-assistant 0.8.0

package/adapters/claude/templates/extended/ops/runbook/starter.md

@@ -0,0 +1,101 @@
+---
+id: {RUN_ID}
+title: {运维手册标题}
+status: draft
+related_features: []
+related_decisions: []
+---
+
+# {RUN_ID}: {运维手册标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这个运维手册的适用场景、目标受众和覆盖范围}
+
+## 适用场景
+
+- **触发条件**：{什么情况下使用此手册}
+- **前置条件**：{执行前必须满足的条件}
+- **负责人**：{主要负责人和备份}
+
+## 操作流程
+
+### 步骤 1：{步骤标题}
+
+**目的**：{步骤目的}
+
+**操作**：
+```bash
+{操作命令}
+```
+
+**预期结果**：{结果描述}
+
+**验证方法**：{如何验证操作成功}
+
+### 步骤 2：{步骤标题}
+
+{同上结构}
+
+## 告警与监控
+
+### 关键指标
+
+| 指标 | 阈值 | 告警方式 |
+|------|------|---------|
+| {指标1} | {阈值} | {告警方式} |
+| {指标2} | {阈值} | {告警方式} |
+
+### 告警处理
+
+| 告警 | 原因 | 处理步骤 |
+|------|------|---------|
+| {告警1} | {原因} | {步骤} |
+| {告警2} | {原因} | {步骤} |
+
+## 回滚流程
+
+### 回滚触发条件
+
+{描述什么情况下需要回滚}
+
+### 回滚步骤
+
+1. {回滚步骤 1}
+2. {回滚步骤 2}
+
+### 回滚验证
+
+{如何验证回滚成功}
+
+## 故障排查
+
+### 常见问题
+
+**问题 1**：{问题描述}
+
+**症状**：{症状描述}
+**原因**：{原因分析}
+**解决方案**：{解决步骤}
+
+### 日志位置
+
+| 服务 | 日志路径 | 关键字段 |
+|------|---------|---------|
+| {服务1} | {路径} | {字段} |
+
+## 联系人
+
+| 角色 | 姓名 | 联系方式 |
+|------|------|---------|
+| 主要负责人 | {姓名} | {联系方式} |
+| 备份负责人 | {姓名} | {联系方式} |
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始版本 | {作者} |

package/adapters/claude/templates/extended/ops/security_review/review-checklist.md

@@ -0,0 +1,56 @@
+# Security Review 审查清单
+
+<!-- 本清单是插件通用基线，项目本地审查规则可覆盖 -->
+
+## 结构完整性
+
+- [ ] `id` 字段存在且符合项目 ID 模式（如 `SEC-{nnn}`）
+- [ ] `title` 清晰描述审查范围
+- [ ] `scope` 已明确界定
+- [ ] 审查类型已标注
+
+## 威胁模型
+
+- [ ] 攻击面已全面识别
+- [ ] 信任边界已明确
+- [ ] 资产分类与敏感级别合理
+- [ ] 数据流图完整
+
+## 发现项质量
+
+- [ ] 发现项按严重度分类（高/中/低）
+- [ ] 每项有清晰的影响描述
+- [ ] 修复状态已跟踪
+- [ ] 误报已排除
+
+## 安全控制覆盖
+
+- [ ] 认证与授权已审查
+- [ ] 数据保护（传输 + 静态）已审查
+- [ ] 输入验证已审查
+- [ ] 依赖安全已扫描
+
+## 合规映射
+
+- [ ] 相关合规标准已识别
+- [ ] 合规状态已明确
+- [ ] 不合规项有修复计划
+
+## 修复跟踪
+
+- [ ] 高严重度发现项有修复方案
+- [ ] 修复责任人已指定
+- [ ] 修复截止日期合理
+- [ ] 修复后回归验证计划存在
+
+## 追溯性
+
+- [ ] 关联功能特性存在
+- [ ] 关联决策存在
+- [ ] 审查可追溯到变更原因
+
+## 周期性
+
+- [ ] 审查周期已设定
+- [ ] 上次审查日期已记录
+- [ ] 下次审查日期已计划

package/adapters/claude/templates/extended/ops/security_review/starter.md

@@ -0,0 +1,125 @@
+---
+id: {SEC_ID}
+title: {安全审查标题}
+status: draft
+scope: {审查范围}
+related_features: []
+related_decisions: []
+---
+
+# {SEC_ID}: {安全审查标题}
+
+<!-- 本模板是插件 starter 指导，项目本地模板可完全覆盖 -->
+<!-- 插件模板是入门指导，项目本地模板是权威 -->
+
+## 概述
+
+{描述这次安全审查的背景、审查范围和目标}
+
+## 审查信息
+
+- **审查范围**：{scope}
+- **审查类型**：代码审查 / 架构审查 / 渗透测试 / 合规审查
+- **审查日期**：{YYYY-MM-DD}
+- **审查人员**：{审查人员}
+- **审核截止日期**：{YYYY-MM-DD}
+
+## 威胁模型
+
+### 攻击面分析
+
+| 攻击面 | 入口点 | 数据流 | 信任边界 |
+|--------|--------|--------|---------|
+| {攻击面1} | {入口} | {数据流描述} | {边界} |
+| {攻击面2} | {入口} | {数据流描述} | {边界} |
+
+### 资产分类
+
+| 资产 | 敏感级别 | 存储位置 | 访问控制 |
+|------|---------|---------|---------|
+| {资产1} | 高/中/低 | {位置} | {控制方式} |
+| {资产2} | 高/中/低 | {位置} | {控制方式} |
+
+## 发现项
+
+### 高严重度
+
+| ID | 发现 | 影响 | 修复状态 |
+|----|------|------|---------|
+| {H-001} | {发现描述} | {影响描述} | 待修复 / 已修复 / 已接受 |
+
+### 中严重度
+
+| ID | 发现 | 影响 | 修复状态 |
+|----|------|------|---------|
+| {M-001} | {发现描述} | {影响描述} | 待修复 / 已修复 / 已接受 |
+
+### 低严重度
+
+| ID | 发现 | 影响 | 修复状态 |
+|----|------|------|---------|
+| {L-001} | {发现描述} | {影响描述} | 待修复 / 已修复 / 已接受 |
+
+## 安全控制清单
+
+### 认证与授权
+
+- [ ] 认证机制已审查
+- [ ] 授权策略已审查
+- [ ] 会话管理已审查
+- [ ] 密码策略已审查
+
+### 数据保护
+
+- [ ] 传输加密已审查（TLS 配置）
+- [ ] 静态加密已审查
+- [ ] 敏感数据脱敏已审查
+- [ ] 密钥管理已审查
+
+### 输入验证
+
+- [ ] SQL 注入防护已审查
+- [ ] XSS 防护已审查
+- [ ] CSRF 防护已审查
+- [ ] 文件上传安全已审查
+
+### 依赖安全
+
+- [ ] 依赖漏洞扫描已完成
+- [ ] 已知漏洞已修复或接受
+- [ ] 依赖版本锁定已确认
+
+## 合规映射
+
+| 合规要求 | 对应控制 | 状态 |
+|---------|---------|------|
+| {要求1} | {控制措施} | 合规 / 不合规 / 不适用 |
+| {要求2} | {控制措施} | 合规 / 不合规 / 不适用 |
+
+## 修复跟踪
+
+| 发现 ID | 修复方案 | 负责人 | 截止日期 | 状态 |
+|---------|---------|--------|---------|------|
+| {H-001} | {修复方案} | {负责人} | {日期} | 待修复 / 已修复 |
+
+## 结论
+
+### 审查结论
+
+{总结审查结论：通过 / 有条件通过 / 不通过}
+
+### 附带条件
+
+{如有条件通过，列出必须满足的条件}
+
+## 关联制品
+
+- 功能特性：{related_features}
+- 决策：{related_decisions}
+- 设计文档：{related_designs}
+
+## 变更日志
+
+| 日期 | 变更 | 作者 |
+|------|------|------|
+| {YYYY-MM-DD} | 初始版本 | {作者} |

package/adapters/codex/.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "artifact-chain-assistant",
+  "version": "0.8.0",
+  "description": "Artifact-chain intake, review/repair/batch/audit workflows, diagnostics, and version-lock maintenance helpers.",
+  "author": {
+    "name": "Artifact Graph Maintainers"
+  },
+  "license": "Apache-2.0",
+  "keywords": ["artifact-graph", "traceability", "codex", "claude-code"],
+  "skills": "./skills/",
+  "hooks": {},
+  "interface": {
+    "displayName": "Artifact Chain Assistant",
+    "shortDescription": "Artifact-chain context, review workflows, and version-lock maintenance.",
+    "longDescription": "Reusable skills for artifact-graph projects, including intake routing, generic artifact review/repair/batch/audit workflows, diagnostics, and version-lock refresh guidance.",
+    "developerName": "Artifact Graph Maintainers",
+    "category": "Productivity",
+    "capabilities": ["Write"],
+    "defaultPrompt": [
+      "Check where this artifact-chain task should start.",
+      "Review a design-spec artifact for traceability and completeness.",
+      "Run a batch review on multiple artifacts.",
+      "Refresh version locks for my staged changes.",
+      "Run artifact-chain doctor for this project."
+    ]
+  }
+}

package/adapters/codex/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](templates/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