artifact-graph 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## Unreleased
 
+## 0.7.0
+
+### Added
+
+- **Contract kernel**: new deterministic contract kernel providing contract identity, a contract
+  registry, canonical IR normalization, revision digests, and policy compatibility checks. Exposed
+  through the new `artifact-graph contract` CLI subcommand group and public library exports.
+
+### Changed
+
+- **Version-lock changed-only collects untracked paths**: `version-lock refresh --changed-only`
+  (worktree and staged modes) now also collects untracked files, so newly added artifacts can no
+  longer silently bypass lock refresh.
+- **Organization migration to `ifoohoo`**: the public repository transferred to the `ifoohoo`
+  GitHub organization (`ifoohoo/artifact-graph`, name unchanged). Copyright is now held by
+  广州市风荷科技有限公司 (Guangzhou Fenghe Technology Co., Ltd.) together with the project
+  contributors; the NOTICE file states that the organization transfer is an administrative hosting
+  change, not a copyright assignment. Package metadata, installation docs, and repository
+  references were updated accordingly; the npm package name `artifact-graph` is unchanged.
+
 ## 0.6.1
 
 ### Fixed

package/INSTALL.md

@@ -21,13 +21,13 @@ npm install --save-dev artifact-graph
 ### From GitHub
 
 ```bash
-npm install --save-dev github:mzdbxqh/artifact-graph
+npm install --save-dev github:ifoohoo/artifact-graph
 ```
 
 Or with pnpm:
 
 ```bash
-pnpm add -D github:mzdbxqh/artifact-graph
+pnpm add -D github:ifoohoo/artifact-graph
 ```
 
 After installation, verify the CLI is available:
@@ -171,5 +171,5 @@ packet validation (`validatePacket`) correctly allows `requiredBaseline.total=0`
 
 ## Related Project
 
-Use [`artifact-chain-assistant`](https://github.com/mzdbxqh/artifact-chain-assistant) for Codex and
+Use [`artifact-chain-assistant`](https://github.com/ifoohoo/artifact-chain-assistant) for Codex and
 Claude Code skills that guide artifact-chain intake, setup, and maintenance.

package/LICENSE

@@ -171,7 +171,7 @@ recommend that a file or class name and description of purpose be included on
 the same "printed page" as the copyright notice for easier identification
 within third-party archives.
 
-Copyright 2026 xqh
+Copyright 2026 广州市风荷科技有限公司 (Guangzhou Fenghe Technology Co., Ltd.)
 
 Licensed under the Apache License, Version 2.0 (the "License");
 you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,4 +1,18 @@
-artifact-graph
-Copyright 2026 xqh
+# Notice
 
-This product includes software developed for the artifact-chain project.
+artifact-graph is an open-source project released under the Apache License 2.0.
+
+## Maintenance
+
+artifact-graph is maintained by 广州市风荷科技有限公司 (Guangzhou Fenghe
+Technology Co., Ltd.), together with the artifact-graph contributors. Copyright
+in the project is held by the artifact-graph contributors and 广州市风荷科技
+有限公司 as stated in the LICENSE file. The transfer of the public GitHub
+repository to the `ifoohoo` organization is an administrative change of the
+hosting location and maintenance identity; it does not by itself constitute a
+copyright assignment or transfer.
+
+## Third-Party Dependencies
+
+This project is built on Node.js and the npm ecosystem. See `package.json`
+for the full list of dependencies.

package/README.md

@@ -17,7 +17,7 @@ pnpm add -D artifact-graph
 Or install from GitHub:
 
 ```bash
-npm install --save-dev github:mzdbxqh/artifact-graph
+npm install --save-dev github:ifoohoo/artifact-graph
 ```
 
 Node.js `>=22.0.0` is required. For pnpm 10+, see [INSTALL.md](INSTALL.md) for the native build
@@ -65,7 +65,7 @@ cross-object field values, so callers must also run the semantic validator; stab
 
 ## Related Project
 
-Use [`artifact-chain-assistant`](https://github.com/mzdbxqh/artifact-chain-assistant) for Codex and
+Use [`artifact-chain-assistant`](https://github.com/ifoohoo/artifact-chain-assistant) for Codex and
 Claude Code skills that guide artifact-chain intake, setup, and maintenance.
 
 ## License

package/README.zh-CN.md

@@ -2,10 +2,10 @@
 
 [English](README.md)
 
-`artifact-graph` 是面向 AI 编程工作流的 Git-native Markdown 制品图扫描和校验工具。
+`artifact-graph` 是一个 Git 原生的 Markdown 制品图扫描与校验工具，面向 AI 编程工作流。
 
-它帮助项目把需求、场景、设计、源码、测试和 version-lock 元数据连接起来，在 AI agent
-声称实现完成之前，用确定性本地命令检查上下文和追溯关系。
+它把项目里的需求、场景、设计、源码、测试和 version-lock 元数据连成一张图，
+供 AI agent 在宣称实现完成之前，用确定性的本地命令检查上下文和追溯关系。
 
 ## 安装
 
@@ -16,7 +16,7 @@ pnpm add -D artifact-graph
 或从 GitHub 安装：
 
 ```bash
-npm install --save-dev github:mzdbxqh/artifact-graph
+npm install --save-dev github:ifoohoo/artifact-graph
 ```
 
 需要 Node.js `>=22.0.0`。pnpm 10+ 需要配置原生构建白名单，详见 [INSTALL.md](INSTALL.md)。
@@ -46,24 +46,24 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
 - 用 `artifact-graph validate` 校验制品之间的链接。
 - 用 `artifact-graph validate-review-result --file <path>` 校验 Review Result Protocol v1.0 文档。
 - 用 `artifact-graph context` 或 `artifact-graph packet` 构建实现上下文。
-- 用 `artifact-graph version-lock refresh` 和 `audit` 维护追溯新鲜度。
+- 用 `artifact-graph version-lock refresh` 和 `audit` 保持追溯关系及时更新。
 - 用 `artifact-graph hooks install-git --hook all` 安装可选 Git hooks。
 
 ## Review Result Protocol
 
-包内发布 `schemas/review-result.schema.json` 和等价的 TypeScript 类型与 validateReviewResult 校验 API。该协议不绑定具体
-项目，覆盖 review、repair、批次证据、findings、metrics 与 fail-closed decision；非法字段
-会返回稳定的 JSON path 诊断。协议拒绝未知顶层字段，`attempt` 仅允许 1–3；成功接受必须包含
-`producer`，`PASS`/`PASS_WITH_RESIDUAL_MINOR` 不能伴随 open `block` finding。独立 repair
-re-review 可记录 `acceptance.reviewer` 与 `acceptance.source_result`，validator 会拒绝 repair
-producer 自行接受。
-JSON Schema 无法比较跨对象字段值，因此调用方还必须运行 semantic validator；稳定身份是
-`executor + name`，`skill` 只是附加元数据，不能用于证明独立性。
+包内发布了 `schemas/review-result.schema.json`，以及配套的 TypeScript 类型和 `validateReviewResult`
+校验 API。该协议与具体项目无关，覆盖 review、repair、批次证据、findings、metrics 和
+fail-closed decision；非法字段和语义违规都会以稳定的 JSON path 报告。协议拒绝未知顶层字段；
+`attempt` 取值仅限 1–3；成功接受必须带 `producer`；`PASS`/`PASS_WITH_RESIDUAL_MINOR` 不允许
+存在未关闭的 `block` finding。独立的 repair 复审可以记录 `acceptance.reviewer` 和
+`acceptance.source_result`，validator 会拒绝 repair producer 自我接受。
+JSON Schema 无法比较跨对象的字段值，因此调用方还必须运行语义 validator；稳定身份由
+`executor + name` 构成，`skill` 只是附加元数据，不能用来证明独立性。
 
 ## 相关项目
 
-如果需要 Codex / Claude Code 的技能、初始化引导和维护流程，请使用
-[`artifact-chain-assistant`](https://github.com/mzdbxqh/artifact-chain-assistant)。
+如果需要 Codex / Claude Code 技能来引导制品链的接入、初始化和日常维护，请使用
+[`artifact-chain-assistant`](https://github.com/ifoohoo/artifact-chain-assistant)。
 
 ## 开源协议
 

package/contracts/e2e-test/schema.json

@@ -0,0 +1,315 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "artifact.e2e-test@1",
+  "title": "Artifact Contract: E2E Test Specification",
+  "description": "Minimal schema for E2E test specification artifacts",
+  "version": "1.0.0",
+  "contractIdentity": {
+    "major": "artifact.e2e-test@1",
+    "authority": "artifact",
+    "namespace": "artifact",
+    "revisionDigest": "sha256:374b99424519e42b40b621774fb602d62dfa23f48f792095f717bbabbe9e3f2a",
+    "relationRules": {
+      "derives_from": {
+        "allowedTargetTypes": ["scenario", "design", "decision"],
+        "min": 1,
+        "max": 10,
+        "anchorPolicy": "optional"
+      },
+      "verifies": {
+        "allowedTargetTypes": ["feature", "scenario"],
+        "min": 1,
+        "max": 5,
+        "anchorPolicy": "required"
+      },
+      "implemented_by": {
+        "allowedTargetTypes": ["code"],
+        "min": 0,
+        "max": 5,
+        "anchorPolicy": "optional"
+      },
+      "references": {
+        "allowedTargetTypes": ["feature", "scenario", "decision", "design", "e2e_test", "test"],
+        "min": 0,
+        "max": 20,
+        "anchorPolicy": "optional"
+      },
+      "covers": {
+        "allowedTargetTypes": ["feature", "scenario"],
+        "min": 0,
+        "max": 10,
+        "anchorPolicy": "optional"
+      }
+    },
+    "semanticMarkers": {
+      "scope": {
+        "jsonPointer": "/scope",
+        "markdownMarker": "scope",
+        "required": true
+      },
+      "system_boundary": {
+        "jsonPointer": "/system_boundary",
+        "markdownMarker": "system-boundary",
+        "required": true
+      },
+      "coverage": {
+        "jsonPointer": "/coverage",
+        "markdownMarker": "coverage",
+        "required": true
+      },
+      "environment_data": {
+        "jsonPointer": "/environment_data",
+        "markdownMarker": "environment-data",
+        "required": true
+      },
+      "test_cases": {
+        "jsonPointer": "/test_cases",
+        "markdownMarker": "test-cases",
+        "required": true
+      },
+      "evidence_contract": {
+        "jsonPointer": "/evidence_contract",
+        "markdownMarker": "evidence-contract",
+        "required": true
+      }
+    }
+  },
+  "type": "object",
+  "required": ["metadata", "scope", "system_boundary", "coverage", "environment_data", "relations", "test_cases", "evidence_contract"],
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "required": ["id", "title", "status"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9._-]+:(TC-\\d+[a-z]?|FILE)$"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": ["planned", "active", "done", "deprecated"]
+        },
+        "test_batch": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "scope": {
+      "type": "object",
+      "required": ["business_goal", "actors"],
+      "properties": {
+        "business_goal": {
+          "type": "string",
+          "minLength": 1
+        },
+        "actors": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "system_boundaries": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "non_goals": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "system_boundary": {
+      "type": "object",
+      "required": ["components"],
+      "properties": {
+        "components": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "external_dependencies": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "trust_boundaries": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "coverage": {
+      "type": "object",
+      "required": [],
+      "properties": {
+        "ac_coverage": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "related_scenarios": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "related_features": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "related_decisions": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "environment_data": {
+      "type": "object",
+      "properties": {
+        "topology": {
+          "type": "string"
+        },
+        "fixtures": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "identities": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "isolation_strategy": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "relations": {
+      "type": "array",
+      "description": "Machine-readable relation declarations: kind, target type/id, optional anchor, and contract-level cardinality rules",
+      "minItems": 2,
+      "items": {
+        "type": "object",
+        "required": ["kind", "target_type", "target_id"],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "enum": ["derives_from", "verifies", "implemented_by", "references", "covers"]
+          },
+          "target_type": {
+            "type": "string",
+            "enum": ["feature", "scenario", "decision", "design", "e2e_test", "test", "code"]
+          },
+          "target_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "anchor": {
+            "type": "string",
+            "description": "Optional anchor point (e.g., section marker, line reference)"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "test_cases": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/testCase"
+      },
+      "minItems": 1
+    },
+    "evidence_contract": {
+      "type": "object",
+      "required": ["required_artifacts"],
+      "properties": {
+        "required_artifacts": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "runner_binding": {
+          "type": "string"
+        },
+        "proof_requirements": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "definitions": {
+    "testCase": {
+      "type": "object",
+      "required": ["case_id", "goal", "preconditions", "actions", "oracles", "cleanup", "priority", "trace_targets"],
+      "properties": {
+        "case_id": {
+          "type": "string",
+          "pattern": "^TC-\\d+[a-z]?$"
+        },
+        "goal": {
+          "type": "string",
+          "minLength": 1
+        },
+        "preconditions": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "actions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["step", "action"],
+            "properties": {
+              "step": { "type": "integer", "minimum": 1 },
+              "action": { "type": "string", "minLength": 1 },
+              "expected_result": { "type": "string" }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "oracles": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["observable", "criterion"],
+            "properties": {
+              "observable": { "type": "string", "minLength": 1 },
+              "criterion": { "type": "string", "minLength": 1 },
+              "timeout_ms": { "type": "integer", "minimum": 0 }
+            },
+            "additionalProperties": false
+          },
+          "minItems": 1
+        },
+        "cleanup": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["critical", "high", "medium", "low"]
+        },
+        "trace_targets": {
+          "type": "array",
+          "items": { "type": "string" },
+          "minItems": 1
+        },
+        "path_class": {
+          "type": "string",
+          "enum": ["happy", "error", "recovery", "edge", "security", "performance"]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}