artifact-graph 0.9.4 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## Unreleased
+
+## 0.11.0
+
+### Added
+
+- Added configuration-driven relation semantics and current/planned/history graph views, including
+  partial-replacement section annotations and protection against planned replacements invalidating
+  the current baseline.
+- Added read-only `impact` and `coverage` reports. Coverage exposes graph and scan boundaries plus
+  raw behavior/release references without inferring successful verification or publication.
+
+### Fixed
+
+- Clarified source annotation syntax, scan scope, missing-lock counting and release-coverage
+  limits in the installation guide and README. CLI help and Markdown version-lock audits now
+  explain that passing a strict audit, including a zero-lock result, does not prove full
+  implementation coverage. Lock semantics, JSON output and exit-code policies are unchanged.
+
+### Changed
+
+- Version lockstep with `artifact-chain-assistant` 0.11.0.
+
+## 0.10.0
+
+### Added
+
+- Added transactional `refactor-id` support for renaming artifact identifiers across configured
+  artifacts, source annotations, and tests. The command reports version-lock impact without
+  changing the lock, preserves unrelated bytes and file modes, detects conflicts before writing,
+  and rolls back the whole transaction if a write fails.
+- Added structured native-binding diagnostics for the CLI and Node library, including the selected
+  installation, probe source, failure stage, stable cause, and actionable remediation.
+
+### Fixed
+
+- `doctor`, `scan`, and `query` now classify `better-sqlite3` failures against the installation
+  that actually provides the running CLI. A target project's dependencies can no longer change
+  `MISSING`, `BUILD_DISABLED`, ABI mismatch, or load-error classification.
+- CommonJS `require`, ESM import, and packed CLI use are covered by the release consumer matrix and
+  remain loadable when lifecycle scripts are disabled. SQLite-dependent `doctor`, `scan`, and
+  `query` operations then fail with the documented structured diagnostic instead of an unrelated
+  loader error.
+
 ## 0.9.4
 
 ### Changed

package/INSTALL.md

@@ -90,6 +90,218 @@ 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.
 
+## Code Traceability And Coverage Boundaries
+
+Version locks track declared relationships and changes to their file contents. A successful
+`version-lock audit --strict-missing-lock` does **not** prove that every release file has an
+artifact link or that every artifact has an implementation. Read this section before using
+the audit as a release acceptance check.
+
+### Declare a source-to-artifact link
+
+Use a standalone line comment in source files whose language accepts `//`:
+
+```ts
+// @feature A1
+// @scenario S-01 @feature A1
+// @decision D-TOOL-01
+```
+
+The syntax is `@<registered-type-or-alias> <artifact-ID>`. The tag selects the type; the value
+is the ID, not `feature:A1`, a Markdown link, or a file path. Separate multiple IDs with spaces
+or commas, or repeat the tag. Each ID must match the configured type's `idPatterns`. Custom
+types and their explicit aliases are supported when registered in the project configuration.
+Keep explanatory prose on a separate line. Split mappings that combine multiple scenarios
+and multiple features into separate lines so their correspondence is unambiguous.
+
+For a Markdown implementation such as a skill, use a standalone, single-line HTML comment:
+
+```markdown
+<!-- @feature A1 -->
+```
+
+Place the comment outside fenced examples so it declares the file's own responsibility.
+The scanner is a text parser, not a language compiler. It recognizes standalone `//` and
+single-line `<!-- ... -->` forms. It does not support native Python/shell `#` comments, SQL
+`--` comments, or `/* ... */`/JSDoc traceability blocks. Trailing `//` comments after code are
+invalid. Do not put invalid-language `//` comments into Python files to work around this limit.
+JavaScript, TypeScript and Java are examples of languages that can use the `//` form;
+this is not a promise of complete language-specific syntax parsing.
+
+### Configure the files to scan
+
+Source annotations are parsed through `types.test.paths`, including implementation files.
+The historical name `test` does not mean that every matching file becomes a test node.
+Merge paths appropriate to the project into its existing `artifact-graph.config.yaml`:
+
+```yaml
+types:
+  test:
+    paths:
+      - "src/**/*.ts"
+      - "src/**/*.tsx"
+      - "tests/**/*.ts"
+      - "skills/**/*.md"
+idPatterns:
+  test: '^.+\.(ts|tsx|md)$'
+```
+
+These are example source paths, not a replacement for the project's artifact type definitions.
+The built-in default only matches `heimdall/packages/**/*.test.ts`; ordinary `src/` and
+`skills/` trees require configuration. Directory walking skips `node_modules`, `dist`, `.git`
+and `.artifact-graph`. Scanning does not derive scope from a release manifest or `.gitignore`.
+If types overlap, the most specific path definition claims the file; check the
+`ARTIFACT_PATH_OVERLAP` diagnostic rather than assuming both parsers run.
+
+Files named `*.test.*`, `*.spec.*`, `*Test.java` or `*Tests.java`, and files under `test/`,
+`tests/` or `__tests__/`, are classified as tests and create `verifies` locks. Other annotated
+files create implementation nodes and `implements` locks. A plain file with no recognized
+annotation produces no source node. A skill Markdown file claimed by a custom artifact type
+is an artifact node, not automatically a code implementation; confirm `sourceKind` in the
+version index before choosing an implementation-lock policy.
+
+### Establish and check the locks
+
+After declaring real links and verifying their targets, run:
+
+```bash
+pnpm exec artifact-graph version-index --root . --format json
+pnpm exec artifact-graph validate --root . --format json
+pnpm exec artifact-graph version-lock refresh --root . --all --format markdown
+pnpm exec artifact-graph version-lock audit --root . --strict-missing-lock --format json
+```
+
+Inspect the index for the intended source nodes and edges. `validate` checks annotation/link
+errors; `refresh --all` records current hashes for discovered relationships; `audit` checks
+those locks. These commands do not execute the source or prove that an implementation meets
+its requirements. Use a separate, existing project test gate for behavioral verification.
+Do not automatically refresh immediately before the acceptance audit merely to clear stale
+hashes: first review the changes and run the relevant tests.
+
+To lock just one declared relationship, use:
+
+```bash
+pnpm exec artifact-graph version-lock update --root . --target feature:A1 --source skills/example/SKILL.md
+```
+
+`update` requires both `--target` and `--source`; there is no `update --all` operation.
+`bootstrap` can establish an initial baseline, but `refresh --all` is the recommended
+incremental entry. Do not use `bootstrap --force` in routine maintenance or hooks.
+
+### What missing_lock counts
+
+`missing_lock` is reported per discovered, lockable relationship without a corresponding lock:
+
+- Source-to-artifact `implements`/`verifies` relationships are checked against `locks`.
+- Artifact-to-artifact relationships are checked against `artifactRelations` too.
+- With runners configured, tests in discovery scope but inactive in every matching runner
+  are excluded from automatic lock creation and missing-lock counting. Unscoped tests remain
+  lockable. Without runner configuration, the legacy fallback treats non-E2E test paths as
+  active; E2E paths need a recognized `// @e2e_test` or `// @tc` annotation to be active.
+  These liveness rules are not a general release-file exemption mechanism.
+
+Missing locks are warnings by default; `--strict-missing-lock` makes them blocking without
+changing the population being checked. Do not combine a required acceptance check with
+`--warning-only`, which suppresses its nonzero exit status.
+
+An artifact with no relationships does not produce `missing_lock` just because it has no
+implementation. An artifact without incoming implementation links can still have outgoing
+artifact relationships that require relation locks. `totalLocks: 0` only counts implementation
+and verification locks; inspect `totalArtifactRelationLocks` separately. With no lockable
+relationships and no existing locks, even the strict audit can pass with zero locks.
+
+### Release coverage and exemptions
+
+The `coverage` command reports graph health, scan mapping, declared behavior references, and an
+optional caller-supplied release-file mapping. It is a boundary report, not a release-payload gate:
+
+```bash
+pnpm exec artifact-graph coverage --root . --format json
+pnpm exec artifact-graph coverage --root . --release-input release-files.txt --format json
+```
+
+Behavior verification is reported as `not-evaluated`; implementation, verification, and evidence
+edges remain raw declaration references. With a release input list, mapped and unmapped paths are
+reported but release status remains `unknown` and evidence remains empty. Without a list, release
+status is `not-requested`. The command never turns a file list into proof that a version was
+published. Graph health accounts for validation and lock issues. Scan coverage reports both files
+inside configured scan paths and files actually mapped to nodes or edge sources; changed-path
+classification is marked unavailable outside a Git worktree. There is no general artifact/file exemption marker for `missing_lock`; E2E coverage
+waivers concern a different check and must not be used as implementation-lock exemptions.
+
+For a policy requiring every release code file to link upward and every required artifact to
+have an implementation or approved exemption, keep two separate checks:
+
+1. Use the existing release process's authoritative payload list to compare expected source
+   files with the version index and implementation locks. Compare the required artifact set
+   with incoming implementation locks and the project's explicitly approved exceptions.
+2. Use `validate` and strict version-lock audit for declared links and their freshness, plus
+   the project's behavioral tests. These checks cannot replace the coverage comparison.
+
+The acceptance decision remains a project/release-policy responsibility. `coverage` can compare
+the caller's existing inventory with graph mapping, but does not own that inventory or approve its
+exceptions. Reuse existing release inventory and approval records; do not maintain a second
+payload manifest or invent an artifact-graph exemption field. If no authoritative execution or
+release result exists, keep the corresponding fact unknown rather than accepting the mapping or
+lock audit as proof.
+
+### Time views and read-only impact
+
+Projects may map their own status words into `current`, `planned`, and `history` with
+`statusViews`. Explicit views are available on graph queries and context assembly; omitting
+`--view` preserves the earlier unfiltered behavior:
+
+```yaml
+statusViews:
+  active: current
+  accepted: current
+  planned: planned
+  open: planned
+  done: history
+  deprecated: history
+```
+
+```bash
+pnpm exec artifact-graph query --from feature:A1 --view current --format json
+pnpm exec artifact-graph context --target feature:A1 --view current --format json
+pnpm exec artifact-graph packet --target feature:A1 --view current --format json
+```
+
+When a project configures `supersedes`, a full replacement moves its target to history only while
+the replacing artifact maps to `current`. A planned or uncategorized replacement cannot invalidate
+the current baseline. A partial replacement keeps the old artifact in its own view and reports the
+replaced sections when the replacing artifact is current.
+
+Use `impact` when selecting work or tests without refreshing locks:
+
+```bash
+pnpm exec artifact-graph impact --root . --worktree --format json
+pnpm exec artifact-graph impact --root . --staged --format json
+pnpm exec artifact-graph impact --root . --base main --format json
+pnpm exec artifact-graph impact --root . --paths src/a.ts,src/b.ts --format json
+```
+
+The report separates directly mapped nodes, related nodes and edges, graph-control files, files in
+configured scan scope that did not resolve to a node, and paths outside scan scope. Generating the
+report does not refresh locks or write graph state.
+
+Exclude tooling such as non-shipped `scripts/check-*.py` from the release coverage denominator
+using the release inventory. Omitting those files from annotation scan paths is a scan-scope
+decision, not a machine-validated exemption. Shipped compatibility forwarding shells still
+belong in the payload comparison: link them to the artifact describing compatibility behavior,
+or record an exception in the project's existing approval process. An ADR that is intentionally
+documentation-only need not be assigned a fabricated implementation link.
+
+### Store locks per project
+
+Commit `artifacts/traceability-version-lock.json` with the project and review its diff; do not
+gitignore it. The lock stores project-relative paths and content hashes so another checkout
+can audit the same baseline. Generated caches such as `.artifact-graph/` are separate.
+Use each project's own `--root` and lock file even when projects share one CLI installation.
+If a project uses `--lock-path`, pass the same project-relative path to every lock command and
+its hooks/CI; the flag is an invocation option, not a persistent setting. Keep one authoritative
+lock per effective project graph, rather than sharing a lock across unrelated roots.
+
 ## Cleaning Up Orphan Locks
 
 After deleting or splitting an artifact (or removing a traceability edge), the affected version

package/README.md

@@ -63,10 +63,32 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
 
 ## Common Workflows
 
+### Code traceability starts with scan scope
+
+Declare links with standalone `// @feature A1` source comments or `<!-- @feature A1 -->`
+in skill Markdown. Include those files in `types.test.paths`, which also handles implementation
+sources; the default does not scan every `src/` or `skills/` tree. Native Python `#` comments
+are not supported.
+
+> `version-lock audit --strict-missing-lock` checks locks for discovered relationships. Files
+> without annotations and artifacts without relationships can remain invisible to missing-lock
+> checks; even zero locks can pass. It does not prove complete release-file or artifact coverage.
+
+See [Code Traceability And Coverage Boundaries](INSTALL.md#code-traceability-and-coverage-boundaries)
+for syntax, scan configuration, classification, exemptions and project isolation. Inspect the
+index before `refresh --all`; there is no `version-lock update --all` operation.
+
+### Daily commands
+
 - Generate or inspect project artifact graph configuration with `artifact-graph init`.
 - Validate artifact links with `artifact-graph validate`.
 - Validate Review Result Protocol v1.0 documents with `artifact-graph validate-review-result --file <path>`.
 - Build implementation context with `artifact-graph context` or `artifact-graph packet`.
+- Add `--view current|planned|history|all` to `query`, `context`, or `packet` when a project maps
+  statuses through `statusViews`. The default stays compatible with the unfiltered graph.
+- Inspect change impact without refreshing locks with `artifact-graph impact --worktree`.
+- Report graph health, scan mapping, and the limits of behavior/release evidence with
+  `artifact-graph coverage`. The command does not infer successful verification or publication.
 - Keep traceability freshness with `artifact-graph version-lock refresh` and `audit`.
 - Version lock covers both implementation/verification edges (`locks`) and artifact-to-artifact
   relations (`artifactRelations`). Old 1.0 lock files without `artifactRelations` are treated as

package/README.zh-CN.md

@@ -60,10 +60,32 @@ npx artifact-graph version-lock audit --root . --strict-missing-lock
 
 ## 常见工作流
 
+### 代码与制品追溯：先确认扫描范围
+
+源码可用独占一行的 `// @feature A1` 声明实现关系；技能 Markdown 可用
+`<!-- @feature A1 -->`。`A1` 是制品 ID，命令行的 `feature:A1` 写法不能直接放在注释值中。
+文件必须纳入 `types.test.paths`；该字段也用于实现文件，默认不会扫描所有 `src/` 或 `skills/`。
+Python 的 `#` 注释目前不受支持。
+
+> `version-lock audit --strict-missing-lock` 只检查已发现关系的锁与新鲜度。
+> 没有注释的文件、没有关系的制品可能不产生缺锁问题；零锁也可能审计通过。
+> 它不能证明“每个发布文件都有制品来源、每个制品都有实现或豁免”。
+
+详细语法、扫描配置、`implements`（实现）与 `verifies`（验证）的分类、豁免边界及多项目隔离，
+见 [代码追溯接入说明](INSTALL.md#code-traceability-and-coverage-boundaries)。先确认索引中确有预期节点和关系，
+再运行 `refresh --all` 建立锁；不存在 `version-lock update --all` 操作。
+
+### 日常命令
+
 - 用 `artifact-graph init` 生成或检查项目制品图配置。
 - 用 `artifact-graph validate` 校验制品之间的链接。
 - 用 `artifact-graph validate-review-result --file <path>` 校验 Review Result Protocol v1.0 文档。
 - 用 `artifact-graph context` 或 `artifact-graph packet` 构建实现上下文。
+- 项目通过 `statusViews` 映射状态后，可在 `query`、`context` 或 `packet` 上增加
+  `--view current|planned|history|all`；不传参数时仍返回兼容旧版的未过滤图。
+- 用 `artifact-graph impact --worktree` 只读查看变更影响，不刷新版本锁。
+- 用 `artifact-graph coverage` 报告图健康、扫描映射以及行为与发布证据的评估边界；
+  该命令不推断验证成功或已经发布。
 - 用 `artifact-graph version-lock refresh` 和 `audit` 保持追溯关系及时更新。
 - 版本锁覆盖实现/验证边（`locks`）和制品间关系（`artifactRelations`）。旧版 1.0 锁文件缺少
   `artifactRelations` 时视为空数组；首次启用时执行一次 `refresh --all` 建立完整关系基线。