artifact-graph 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,91 @@
 
 ## Unreleased
 
+## 0.6.0
+
+### Added
+
+- **E2E coverage proof mechanism**: `validate --include e2e-coverage` now outputs executable_ref
+  coverage statistics (total TCs, with executable_ref, rate), status breakdown, chain_type breakdown,
+  uncovered scenarios, and uncovered features. JSON and human-readable formats supported.
+  - Configurable thresholds via `artifact-graph.config.yaml` `e2e` section:
+    `executable_ref_warning`, `executable_ref_error`, `report_uncovered_scenarios`,
+    `report_uncovered_features`, `scenario_waivers`, `feature_waivers`.
+  - Threshold violations produce `E2E_COVERAGE_WARNING` / `E2E_COVERAGE_ERROR` findings.
+
+- **TC status lifecycle validation**: TCs with invalid `status` values produce `E2E_INVALID_TC_STATUS`.
+  `waived` status requires non-empty `waived_reason` (`E2E_WAIVED_NO_REASON`).
+
+- **chain_type vocabulary validation**: Invalid chain_type produces `E2E_INVALID_CHAIN_TYPE`.
+  Deprecated aliases `core_only` → `core_e2e`, `frontend_only` → `mock_playwright` produce
+  `E2E_DEPRECATED_CHAIN_TYPE` migration warnings.
+
+- **ac_coverage_rate freetext detection**: Handwritten percentages produce
+  `E2E_AC_COVERAGE_RATE_FREETEXT` — this field must be computed, not manually entered.
+
+- **Deterministic checklist rules**:
+  - `E2E-UNIT-TEST-NOT-E2E`: executable_ref pointing to `.test.ts` instead of `.spec.ts`.
+  - Version-lock liveness: E2E spec files with no active `@e2e_test`/`@tc` annotations produce
+    `orphan_lock` liveness warnings.
+
+- **`generate-e2e-registry` command**: Deterministic, idempotent E2E registry generation from
+  Markdown test files. `--deterministic` flag sets `generated_at` to epoch for diff checks.
+  `--out <path>` writes output to file.
+
+- **E2E-TRACE-004 Markdown authority**: When a TC explicitly declares `chain_type: desktop_chain`,
+  conflicts with source-level `mock_playwright` annotations are downgraded to info (per
+  artifact-chain-spec §5.2: Markdown side is authoritative).
+
+### Changed
+
+- **`validate --format json`** output is now wrapped in `{ issues, e2eCoverage }` when
+  `--include e2e-coverage` is specified. Without `--include e2e-coverage`, output remains a raw
+  issues array (backward compatible).
+
+## 0.5.0
+
+### Added
+
+- **Universal baseline policy**: `resolveArtifactContext` now injects 19 always-present baseline
+  files (AGENTS.md, CLAUDE.md, artifact-chain-spec, blueprints, contracts, etc.) as required context
+  by default. `scanArtifacts` stores a normalized absolute `root` on the graph so that
+  `resolveArtifactContext` can fall back to `graph.root` when callers omit `opts.root`.
+  - Default: `context.universal_baseline` is `true` (all baseline files injected and verified).
+  - Explicit opt-out: set `context.universal_baseline: false` in `artifact-graph.config.yaml` to
+    skip baseline injection entirely for lightweight or partial projects.
+  - Config validation: `loadConfig` rejects non-boolean values (`0`, `""`, `"false"`, `1`, `"true"`)
+    with an explicit error.
+  - Fail-closed: when baseline is enabled but no project root is available, all 19 baseline items
+    appear in `missingDetails` with kind `missing-baseline`; the manifest writes
+    `baselinePolicy: true` so downstream packet validation cannot silently infer opt-out.
+  - Readability gate: baseline file checks now verify both `stat.isFile()` and read permission
+    (`access(R_OK)`), so unreadable files are reported in `missingDetails` rather than silently
+    skipped.
+- **`ArtifactGraph.root` field**: `ArtifactGraph` interface gains an optional `root?: string` field
+  populated by `scanArtifacts` with the normalized absolute project root. Consumers that construct
+  graph literals without this field remain backward-compatible.
+
+### Fixed
+
+- **CLI `--help`/`-h` safety for subcommands**: `artifact-graph hooks install-git --help/-h` and
+  `artifact-graph version-lock --help/-h` now exit 0 and print usage without executing command
+  side effects. Previously, `hooks install-git --help` would install hooks into the Git repository
+  instead of showing help. This prevents accidental hook installation when users pass `--help` to
+  verify CLI behavior. Regression tests verify that `--help`, `-h`, and positional `help` tokens
+  do not create or modify Git hooks.
+- **Review Result input hardening**: reject unknown top-level fields and attempts outside 1–3;
+  require producer identity for successful PASS decisions; reject PASS decisions with open block
+  findings; and reject repair self-acceptance using stable `executor + name` identity even when
+  `skill` metadata differs. This tightens Review Result v1.0 consumption compatibility, including
+  acceptance identity rules: migrate legacy top-level fields into protocol sections and run
+  `artifact-graph validate-review-result --file <result.json> --format json` before consumption.
+- **Canonical E2E code tag**: add `@e2e_test` as the canonical traceability tag; legacy `@tc`
+  remains an alias and emits the `E2E-TRACE-007` deprecation warning from generic code-comment scans.
+- **Traceability annotation false-positive fix**: reduce false positives in source/test traceability
+  comment validation for custom artifact types registered via `artifact-graph.config.yaml`.
+- **Pre-commit hook configuration detection**: improve pre-commit hook configuration detection to
+  handle non-standard Git hook directory layouts and `core.hooksPath` overrides.
+
 ## 0.4.1
 
 ### Changed

package/INSTALL.md

@@ -21,7 +21,7 @@ npm install --save-dev artifact-graph
 ### From GitHub
 
 ```bash
-npm install github:mzdbxqh/artifact-graph
+npm install --save-dev github:mzdbxqh/artifact-graph
 ```
 
 Or with pnpm:
@@ -33,47 +33,141 @@ pnpm add -D github:mzdbxqh/artifact-graph
 After installation, verify the CLI is available:
 
 ```bash
-artifact-graph --help
+# pnpm
+pnpm exec artifact-graph --help
+
+# npm
+npx artifact-graph --help
 ```
 
 ### pnpm Native Build Allowlist
 
-With pnpm 10+, the native `better-sqlite3` dependency must be allowed to build.
-Add or update `pnpm-workspace.yaml` in your project root:
+`artifact-graph` depends on `better-sqlite3`, which requires a native build. pnpm blocks postinstall
+scripts by default; you must explicitly allow the build. The configuration key depends on your pnpm
+version:
+
+**pnpm 10.26+** — add `allowBuilds` to `pnpm-workspace.yaml` in your project root:
 
 ```yaml
+# pnpm-workspace.yaml (pnpm 10.26+)
 allowBuilds:
   better-sqlite3: true
 ```
 
-Without this entry, `pnpm install` may skip the native build and `artifact-graph` will fail at
-runtime.
+**pnpm 10.0–10.25** — add `onlyBuiltDependencies` to your project `package.json`:
+
+```jsonc
+// package.json (pnpm 10.0–10.25)
+{
+  "pnpm": {
+    "onlyBuiltDependencies": ["better-sqlite3"]
+  }
+}
+```
+
+Without the correct entry for your pnpm version, `pnpm install` may skip the native build and
+`artifact-graph` will fail at runtime with a missing binding error.
 
 ## Quick Start
 
-From your project root:
+After installing as a dev dependency, use your package manager's exec to invoke the CLI. From your
+project root:
 
 ```bash
-artifact-graph init --root .
-artifact-graph validate --root . --warning-only
-artifact-graph version-lock refresh --changed-only --staged --format markdown
-artifact-graph version-lock audit --root . --strict-missing-lock
+# pnpm
+pnpm exec artifact-graph init --root .
+pnpm exec artifact-graph validate --root . --warning-only
+pnpm exec artifact-graph version-lock refresh --all --format markdown
+pnpm exec artifact-graph version-lock audit --root . --strict-missing-lock
+
+# npm
+npx artifact-graph init --root .
+npx artifact-graph validate --root . --warning-only
+npx artifact-graph version-lock refresh --all --format markdown
+npx artifact-graph version-lock audit --root . --strict-missing-lock
 ```
 
+> Use `version-lock refresh --all` for the initial lock. The `--changed-only --staged` variant is for
+> pre-commit hooks on existing projects — not for first-time initialization.
+
 ## Smoke Test
 
 Run these commands to confirm the installation is working:
 
 ```bash
-artifact-graph --help
-artifact-graph doctor --format markdown
-artifact-graph validate --root . --warning-only
+# pnpm
+pnpm exec artifact-graph --help
+pnpm exec artifact-graph doctor --format markdown
+pnpm exec artifact-graph validate --root . --warning-only
+
+# npm
+npx artifact-graph --help
+npx artifact-graph doctor --format markdown
+npx artifact-graph validate --root . --warning-only
 ```
 
 If `artifact-graph doctor` cannot find the CLI or config, check that:
 
-1. `artifact-graph` is in `PATH` or `./node_modules/.bin/`.
-2. Your project has an `artifact-graph.config.yaml` (run `artifact-graph init --root .` to create one).
+1. `artifact-graph` is in `./node_modules/.bin/` (run `pnpm exec artifact-graph --help` or
+   `npx artifact-graph --help` to verify).
+2. Your project has an `artifact-graph.config.yaml` (run `pnpm exec artifact-graph init --root .` or
+   `npx artifact-graph init --root .` to create one).
+
+## Universal Baseline Policy
+
+Starting with 0.5.0, `artifact-graph context` and `artifact-graph packet` inject 19 always-present
+baseline files (AGENTS.md, CLAUDE.md, artifact-chain-spec, blueprints, contracts, domain artifacts,
+verification files, etc.) as required context by default. When any of these files is missing or
+unreadable, the context manifest reports them in `missingDetails` and the command exits non-zero.
+
+### Default behavior
+
+```yaml
+# artifact-graph.config.yaml
+# context.universal_baseline defaults to true — no explicit entry needed
+```
+
+With the default, all baseline files are verified against the project root. If a file is missing,
+is a directory, or is unreadable, it appears in the structured `missingDetails` with kind
+`missing-baseline`.
+
+### Explicit opt-out for lightweight projects
+
+If your project does not contain all 19 baseline files (e.g., a partial migration or a standalone
+library), explicitly disable baseline injection:
+
+```yaml
+# artifact-graph.config.yaml
+context:
+  universal_baseline: false
+```
+
+With `false`, `resolveArtifactContext` skips baseline injection entirely. No `baseline` category
+appears in the context manifest, and the manifest writes `baselinePolicy: false` so that
+packet validation (`validatePacket`) correctly allows `requiredBaseline.total=0`.
+
+### Config validation
+
+`loadConfig` rejects non-boolean values for `context.universal_baseline`:
+
+| Value | Result |
+|-------|--------|
+| `true` | Baseline enabled |
+| `false` | Baseline disabled |
+| `undefined` | Defaults to `true` |
+| `0`, `1` | **Error**: `Invalid context.universal_baseline` |
+| `""`, `"false"`, `"true"` | **Error**: `Invalid context.universal_baseline` |
+
+### Migration impact
+
+- **Existing projects with all baseline files present**: no change in behavior. The default
+  `true` policy was already implicit in 0.4.x context resolution.
+- **Projects missing baseline files**: add `context.universal_baseline: false` to suppress
+  baseline verification, or create the missing files. Without this, `context` and `packet`
+  commands will exit non-zero with structured missing evidence.
+- **Packet validation**: `validatePacket` (PKT-004) now requires an explicit `baselinePolicy`
+  field to allow `requiredBaseline.total=0`. Packets without `baselinePolicy` and with
+  `total=0, missing=[]` are rejected — this prevents silent opt-out inference.
 
 ## Related Project
 

package/README.md

@@ -17,7 +17,7 @@ pnpm add -D artifact-graph
 Or install from GitHub:
 
 ```bash
-npm install github:mzdbxqh/artifact-graph
+npm install --save-dev github:mzdbxqh/artifact-graph
 ```
 
 Node.js `>=22.0.0` is required. For pnpm 10+, see [INSTALL.md](INSTALL.md) for the native build
@@ -26,12 +26,22 @@ allowlist setup.
 ## Quick Start
 
 ```bash
-artifact-graph init --root .
-artifact-graph validate --root . --warning-only
-artifact-graph version-lock refresh --changed-only --staged --format markdown
-artifact-graph version-lock audit --root . --strict-missing-lock
+# pnpm
+pnpm exec artifact-graph init --root .
+pnpm exec artifact-graph validate --root . --warning-only
+pnpm exec artifact-graph version-lock refresh --all --format markdown
+pnpm exec artifact-graph version-lock audit --root . --strict-missing-lock
+
+# npm
+npx artifact-graph init --root .
+npx artifact-graph validate --root . --warning-only
+npx artifact-graph version-lock refresh --all --format markdown
+npx artifact-graph version-lock audit --root . --strict-missing-lock
 ```
 
+> Use `version-lock refresh --all` for the initial lock. The `--changed-only --staged` variant is for
+> pre-commit hooks on existing projects — not for first-time initialization.
+
 ## Common Workflows
 
 - Generate or inspect project artifact graph configuration with `artifact-graph init`.
@@ -45,7 +55,13 @@ artifact-graph version-lock audit --root . --strict-missing-lock
 
 The package publishes `schemas/review-result.schema.json` and a matching TypeScript types + validateReviewResult validator API.
 The protocol is project-neutral and supports review, repair, batch evidence, findings, metrics, and
-fail-closed decisions. Invalid fields are reported with stable JSON paths.
+fail-closed decisions. Unknown top-level fields are rejected; `attempt` is limited to 1–3;
+successful acceptance requires `producer`; and `PASS`/`PASS_WITH_RESIDUAL_MINOR` cannot contain an
+open `block` finding. Independent repair re-review can record `acceptance.reviewer` and
+`acceptance.source_result`; the validator rejects self-acceptance by the repair producer. Invalid
+fields and semantic violations are reported with stable JSON paths. JSON Schema cannot compare
+cross-object field values, so callers must also run the semantic validator; stable identity is
+`executor + name`, while `skill` is only metadata and cannot establish independence.
 
 ## Related Project
 

package/README.zh-CN.md

@@ -16,7 +16,7 @@ pnpm add -D artifact-graph
 或从 GitHub 安装：
 
 ```bash
-npm install github:mzdbxqh/artifact-graph
+npm install --save-dev github:mzdbxqh/artifact-graph
 ```
 
 需要 Node.js `>=22.0.0`。pnpm 10+ 需要配置原生构建白名单，详见 [INSTALL.md](INSTALL.md)。
@@ -24,12 +24,22 @@ npm install github:mzdbxqh/artifact-graph
 ## 快速开始
 
 ```bash
-artifact-graph init --root .
-artifact-graph validate --root . --warning-only
-artifact-graph version-lock refresh --changed-only --staged --format markdown
-artifact-graph version-lock audit --root . --strict-missing-lock
+# pnpm
+pnpm exec artifact-graph init --root .
+pnpm exec artifact-graph validate --root . --warning-only
+pnpm exec artifact-graph version-lock refresh --all --format markdown
+pnpm exec artifact-graph version-lock audit --root . --strict-missing-lock
+
+# npm
+npx artifact-graph init --root .
+npx artifact-graph validate --root . --warning-only
+npx artifact-graph version-lock refresh --all --format markdown
+npx artifact-graph version-lock audit --root . --strict-missing-lock
 ```
 
+> 首次初始化版本锁使用 `version-lock refresh --all`。`--changed-only --staged` 适用于
+> 已有项目的 pre-commit hook，不适用于首次初始化。
+
 ## 常见工作流
 
 - 用 `artifact-graph init` 生成或检查项目制品图配置。
@@ -43,7 +53,12 @@ artifact-graph version-lock audit --root . --strict-missing-lock
 
 包内发布 `schemas/review-result.schema.json` 和等价的 TypeScript 类型与 validateReviewResult 校验 API。该协议不绑定具体
 项目，覆盖 review、repair、批次证据、findings、metrics 与 fail-closed decision；非法字段
-会返回稳定的 JSON path 诊断。
+会返回稳定的 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` 只是附加元数据，不能用于证明独立性。
 
 ## 相关项目