dic-workflow-kit 1.1.1 → 1.1.3

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dic-workflow-kit",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "Design-implementation consistency workflow with OpenSpec obligations, BDD knowledge, Skills, and Subagents.",
   "author": {
     "name": "TonyClaw"

package/CHANGELOG.md

@@ -4,6 +4,86 @@ All notable changes to DIC Workflow Kit are documented in this file.
 
 The project follows [Semantic Versioning](https://semver.org/). Both npm packages, `dic-workflow-kit` and `@tonyclaw/dic-workflow-kit`, always use the same version and runtime payload.
 
+## [Unreleased]
+
+## [1.1.3] - 2026-07-28
+
+### Added
+
+- Added a portable ontology snapshot schema for typed objects, links, lifecycle, provenance, and invariant results.
+- Added an auditable ontology action schema with role, scope, precondition, postcondition, evidence, and rollback fields.
+- Added automatic OpenSpec-to-ontology snapshot generation and an `ontology-check` source helper command.
+- Added computed PASS gates for source coverage, implementation disposition, validation coverage, and open blocking gaps.
+- Added bundled `ontology-check`, `action-check`, and `action-record` runtime commands without publishing runtime source.
+- Added append-only, SHA-256-addressed action audit records with idempotency and collision rejection.
+- Added generic-project ontology initialization with candidate design sources.
+- Added action-specific ontology patches for controlled object, link, and lifecycle effects.
+- Added hash-verified, idempotent `ontology-reconcile` ledger replay with invariant-safe snapshot replacement.
+- Added `ontology-query` views for uncovered obligations, open gaps, unevidenced validations, and bounded impact analysis.
+- Added `ontology-drift` for content-hash change detection and incremental impact roots.
+- Added canonical snapshot revisions and an integrity invariant for detecting direct semantic edits.
+- Added optimistic concurrency protection for snapshot replacement during reconciliation.
+- Added `ontology-plan` to map design-source drift and impact neighborhoods to minimal Agent-stage reruns.
+- Added first-class English and Chinese Gherkin ingestion for Feature, Background, Scenario, Scenario Outline, Examples, tags, and source anchors.
+- Added `ontology-explain` for object provenance, direct relations, and bounded evidence-chain inspection.
+- Added a BDD adapter and strengthened the `knowledge-bdd` operating contract.
+- Added `ontology-report` for a generated, high-density Markdown view of current semantic state.
+- Added content-addressed ontology attestations bound to snapshot revision, action ledger, source hashes, and gate results.
+- Added `ontology-attestation-check` to reject stale or tampered final evidence.
+- Added sequence-numbered v2 action-ledger hash chains with v1-prefix compatibility.
+- Added Snapshot-revision binding for newly recorded actions and optional authored `expectedSnapshotRevision` checks.
+- Added `ontology-ledger-check` for chain head, record counts, and full-ledger digest inspection.
+- Added external Attestation anchoring through `ontology-attestation-check --expected-hash`.
+- Added `ontology-evidence-check` for content-addressed validation artifact verification.
+- Added Evidence artifact hashes to final Attestations and generated ontology reports.
+- Added `ObserveImplementation` to distinguish existing-code observation from repair output.
+- Added `ontology-implementation-check` for content-addressed implementation verification.
+- Added Validation input causality: each run binds its consumed DesignSource and ImplementationUnit hashes.
+- Added `ontology-validation-check`; stale or incomplete validation inputs now block PASS and invalidate Attestations.
+- Added ImplementationUnit hashes to final Attestations and generated ontology reports.
+- Added an installation manifest with SHA-256 hashes for every managed file.
+- Added `doctor` to verify installed files and Codex marketplace registration.
+- Added safe `uninstall` for every supported host.
+- Added `--json` output for installation lifecycle automation.
+- Added collision, tamper detection, forced recovery, and Codex unregister tests.
+
+### Changed
+
+- Moved Skill version markers into standards-compliant `metadata.version` while preserving release synchronization and legacy-install recognition.
+- Reframed Subagent responsibilities as bounded ontology reads, proposals, actions, and evidence attachments.
+- Added the ontology snapshot to the required workflow evidence and final artifacts.
+- Added role/action, target type, terminal condition, evidence, and protected-path enforcement.
+- Completed actions now require a non-empty, action-authorized ontology patch instead of direct snapshot edits.
+- PASS now rejects changed, missing, or out-of-project tracked design sources.
+- PASS now also rejects untracked design sources that lack a recorded content hash.
+- Final review now treats prose as a generated ontology view and requires attestation verification before publication.
+- New actions must be reconciled before another action can be recorded, preventing ambiguous multi-action base revisions.
+- `VERIFIED_BY` now counts only current Validation objects whose status is `PASS`.
+- `AttachEvidence` now requires a real project-relative artifact, SHA-256 provenance, and the `ContentAddressed` interface.
+- PASS now rejects missing, changed, untracked, inactive, or out-of-project required Evidence artifacts.
+- Ontology commands now separate the workflow evidence root from `snapshot.projectRoot`.
+- Content checks now resolve real paths and reject symlink escapes and non-file artifacts.
+- `IMPLEMENTED_BY` now counts only current ImplementationUnit objects.
+- `ObserveImplementation` and `ApplyRepair` now require real, content-addressed implementation files.
+- PASS now rejects missing, changed, untracked, inactive, invalid, or out-of-project required implementation artifacts.
+- `ontology-plan` now selects different minimal recovery stages for design, implementation, and Evidence drift.
+- Install now refuses to overwrite unmanaged or locally modified files unless `--force` is explicitly supplied.
+- Uninstall now refuses to remove modified managed files unless `--force` is explicitly supplied.
+- Install treats symbolic links and non-file targets as conflicts to prevent writes escaping managed roots.
+- Codex uninstall preserves all unrelated personal marketplace entries.
+
+## [1.1.2] - 2026-07-28
+
+### Added
+
+- Added native BitFun installation for user and project scopes.
+- Added BitFun-specific Subagent frontmatter conversion using its `schema_version: 1` custom-agent contract.
+- Added isolated BitFun installation, directory mapping, and least-privilege runtime-tool permission tests.
+
+### Changed
+
+- Extended version synchronization to keep BitFun adapter installation examples aligned with each release.
+
 ## [1.1.1] - 2026-07-27
 
 ### Added

package/INSTRUCTION.md

@@ -14,6 +14,111 @@ This instruction is generic. It must not assume a contest, language, framework,
 - Do not edit protected design sources unless explicitly instructed.
 - Write intermediate evidence under `logs/trace/`.
 - Write final evidence under `reports/` and `result/`.
+- Treat `reports/ontology-snapshot.json` as the machine-readable semantic state.
+- Change semantic state through typed, evidence-backed actions rather than untracked prose.
+
+When workflow evidence is stored outside the repository, use the workflow root
+to locate `reports/` and the Snapshot `projectRoot` to resolve design,
+implementation, and Evidence paths. Do not conflate these roots.
+
+## Ontology Contract
+
+The workflow models design consistency as typed objects and links:
+
+```text
+Change -> PROPOSES -> Requirement
+Requirement -> DERIVED_FROM -> DesignSource
+Scenario -> REFINES -> Requirement
+Requirement -> IMPLEMENTED_BY -> ImplementationUnit
+Requirement/Scenario -> VERIFIED_BY -> Validation
+Gap -> VIOLATES -> Requirement
+RepairAction -> RESOLVES -> Gap
+Validation -> PRODUCES -> Evidence
+```
+
+Every object must have a stable ID, lifecycle, properties, and provenance. Every
+link endpoint must resolve. Reports are views over this semantic state; they are
+not independent sources of truth.
+
+Agents may only perform actions within their role:
+
+- readers propose or confirm source-backed objects
+- inspectors add observed implementation and gap links
+- planners propose repair actions without editing code
+- repairers execute approved, path-bounded actions
+- validators attach validation and evidence objects
+- final reviewers evaluate invariants and transition final status
+
+Before executing or recording a mutation, validate it with the installed runtime:
+
+```text
+dic-workflow-kit action-check --root <project> --action <action.json>
+dic-workflow-kit action-record --root <project> --action <action.json>
+dic-workflow-kit ontology-reconcile --root <project>
+dic-workflow-kit ontology-ledger-check --root <project>
+dic-workflow-kit ontology-evidence-check --root <project>
+dic-workflow-kit ontology-validation-check --root <project>
+dic-workflow-kit ontology-implementation-check --root <project>
+```
+
+`action-record` appends an immutable, content-hashed entry to
+`reports/ontology-actions.jsonl`. Reusing an action ID with different content is
+an error. `ontology-reconcile` replays authorized `ontologyPatch` effects and
+atomically replaces the snapshot only when structural invariants still pass.
+Use `ontology-check --status PASS` before producing a terminal PASS.
+
+Set `expectedSnapshotRevision` on authored actions. Newly recorded ledger
+entries bind the current Snapshot revision and form a sequence-numbered hash
+chain. Reconcile before recording the next action; otherwise recording fails.
+
+A completed action must declare `parameters.ontologyPatch`. Its permitted
+object types, link types, and lifecycle transitions are derived from the action
+type. Agents must not edit `ontology-snapshot.json` directly to bypass these
+rules.
+
+Useful machine-readable queries:
+
+```text
+dic-workflow-kit ontology-query --root <project> --query uncovered
+dic-workflow-kit ontology-query --root <project> --query gaps
+dic-workflow-kit ontology-query --root <project> --query unevidenced
+dic-workflow-kit ontology-query --root <project> --query impact --id <object-id>
+dic-workflow-kit ontology-drift --root <project>
+dic-workflow-kit ontology-plan --root <project> --json
+dic-workflow-kit ontology-explain --root <project> --id <object-id> --json
+dic-workflow-kit ontology-report --root <project> --status <status>
+```
+
+Snapshots carry a canonical `snapshotRevision`. Direct semantic edits invalidate
+the revision and must fail structural review. Reconciliation uses optimistic
+concurrency and refuses to replace a snapshot that changed after replay began.
+
+A PASS gate includes source-drift evaluation. A changed, missing, or
+out-of-project tracked source blocks PASS even when older implementation and
+validation links are still present.
+
+A `VERIFIED_BY` relation counts only when its Validation has a current lifecycle
+and `properties.status: PASS`. The Validation must record `executedAt` and bind
+every consumed DesignSource and ImplementationUnit as
+`properties.inputs[] = { objectId, contentHash }`; otherwise an earlier run
+could incorrectly approve newer design or code. Every Evidence produced by such a Validation
+must reference a project-relative artifact, record its SHA-256
+`provenance.contentHash`, and implement `ContentAddressed`.
+
+An `IMPLEMENTED_BY` relation counts only when its ImplementationUnit has a
+current lifecycle. The implementation must reference a project-relative regular
+file, record its SHA-256 `provenance.contentHash`, and implement
+`ContentAddressed`. Use `ObserveImplementation` for existing code and
+`ApplyRepair` for approved repair output.
+
+The portable schemas are:
+
+```text
+schemas/ontology-snapshot.schema.json
+schemas/ontology-action.schema.json
+schemas/ontology-action-record.schema.json
+schemas/ontology-attestation.schema.json
+```
 
 ## Default Stages
 
@@ -39,6 +144,10 @@ At minimum, produce:
 reports/project-profile.json
 reports/contract-obligations.json
 reports/contract-obligations.md
+reports/ontology-snapshot.json
+reports/ontology-actions.jsonl
+reports/ontology-report.md
+reports/ontology-attestation.json
 reports/final-consistency-report.md
 reports/FINAL_RESULT.json
 result/output.md
@@ -70,6 +179,13 @@ If OpenSpec files are present, use `knowledge-openspec` before repair planning.
 - archived specs do not override current specs
 - implementation does not silently exceed or contradict the accepted design
 
+## BDD Rule
+
+If `.feature` files are present, use `knowledge-bdd`. Preserve Feature,
+Background, Scenario, Scenario Outline, Examples, tags, normalized steps, and
+source lines. BDD acceptance contracts become ontology obligations, but they do
+not become validation evidence until current executable checks are recorded.
+
 ## Final Status
 
 Use one of:
@@ -80,3 +196,30 @@ Use one of:
 - `FAIL`
 
 Do not use `SUCCESS`, `DONE`, or informal status labels in final machine-readable output.
+
+`PASS` is valid only when ontology invariants pass. At minimum:
+
+- every active obligation has a source
+- every active scenario refines a requirement
+- every active requirement has an implementation disposition
+- every required ImplementationUnit exists and matches its recorded SHA-256
+- every active obligation is linked to validation
+- every referenced Validation is current and successful
+- every referenced Validation binds the current design and implementation hashes
+- every required Evidence artifact exists and matches its recorded SHA-256
+- no blocking gap remains open
+
+Before publishing any terminal status, generate the ontology report, create a
+content-addressed attestation, and verify it against the current snapshot,
+action ledger, design sources, and gate:
+
+```text
+dic-workflow-kit ontology-report --root <project> --status <status>
+dic-workflow-kit ontology-attest --root <project> --status <status> --summary "<summary>"
+dic-workflow-kit ontology-attestation-check --root <project>
+```
+
+If the final verification fails, the result is stale and must not be published.
+Persist the emitted Attestation `contentHash` in external CI or release
+metadata when available, then verify it with
+`ontology-attestation-check --expected-hash <sha256>`.

package/README.md

@@ -1,6 +1,6 @@
 # Design-Implementation Consistency Workflow Kit
 
-Version: `1.1.1`
+Version: `1.1.3`
 
 [Changelog](CHANGELOG.md)
 
@@ -14,28 +14,30 @@ The kit is not tied to one contest, one repository, one language stack, or one a
 
 ## Install with npm
 
-The npm package contains all seven Skills and all nine Subagents and installs them with host-native directory layouts for Codex, Claude Code, OpenCode, and MiMo Code.
+The npm package contains all seven Skills and all nine Subagents and installs them with host-native directory layouts for Codex, Claude Code, OpenCode, MiMo Code, and BitFun.
 
 Codex remains the default, so the original command is backward compatible:
 
 ```text
-npx dic-workflow-kit@1.1.1 install
+npx dic-workflow-kit@1.1.3 install
 ```
 
 Select another host explicitly:
 
 ```text
-npx dic-workflow-kit@1.1.1 install --host claude-code
-npx dic-workflow-kit@1.1.1 install --host opencode
-npx dic-workflow-kit@1.1.1 install --host mimo-code
+npx dic-workflow-kit@1.1.3 install --host claude-code
+npx dic-workflow-kit@1.1.3 install --host opencode
+npx dic-workflow-kit@1.1.3 install --host mimo-code
+npx dic-workflow-kit@1.1.3 install --host bitfun
 ```
 
 User scope is the default. To install into the current repository instead, use `--scope project`:
 
 ```text
-npx dic-workflow-kit@1.1.1 install --host claude-code --scope project
-npx dic-workflow-kit@1.1.1 install --host opencode --scope project
-npx dic-workflow-kit@1.1.1 install --host mimo-code --scope project
+npx dic-workflow-kit@1.1.3 install --host claude-code --scope project
+npx dic-workflow-kit@1.1.3 install --host opencode --scope project
+npx dic-workflow-kit@1.1.3 install --host mimo-code --scope project
+npx dic-workflow-kit@1.1.3 install --host bitfun --scope project
 ```
 
 The host mappings are:
@@ -46,13 +48,16 @@ The host mappings are:
 | Claude Code | `~/.claude/{skills,agents}` | `.claude/{skills,agents}` |
 | OpenCode | `~/.config/opencode/{skills,agents}` | `.opencode/{skills,agents}` |
 | MiMo Code | platform config root under `mimocode/{skills,agents}` | `.mimocode/{skills,agents}` |
+| BitFun | platform-native BitFun data/config roots | `.bitfun/{skills,agents}` |
 
-On Windows, MiMo Code's user root resolves to `%LOCALAPPDATA%\mimocode`; `MIMOCODE_HOME` and `XDG_CONFIG_HOME` are honored where applicable. The installer adapts Subagent frontmatter per host while keeping `agents/` in the package as the single source of truth.
+On Windows, MiMo Code's user root resolves to `%LOCALAPPDATA%\mimocode`; `MIMOCODE_HOME` and `XDG_CONFIG_HOME` are honored where applicable. BitFun user Skills resolve to the platform data directory (`BitFun/skills`) and its Subagents resolve to the BitFun config root (`bitfun/agents`); project installation uses BitFun's native `.bitfun` directory. The installer adapts Subagent frontmatter per host while keeping `agents/` in the package as the single source of truth.
+
+For BitFun, the installer emits its native custom-agent schema. Inspection and planning roles stay read-only; only `code-repairer` and `validation-runner` receive the write and command tools required by their runtime responsibilities.
 
 You can also install the CLI globally:
 
 ```text
-npm install --global @tonyclaw/dic-workflow-kit@1.1.1
+npm install --global @tonyclaw/dic-workflow-kit@1.1.3
 dic-workflow-kit install --host opencode
 ```
 
@@ -65,11 +70,28 @@ dic-workflow-kit install
 
 Use `--dry-run` to preview the resolved destination, `--install-root <path>` for an isolated host root, or the backward-compatible Codex-only `--marketplace-root <path>`. The Codex installer preserves unrelated marketplace entries and replaces only the entry with the same plugin name. Restart or reload the target coding-agent session after its first Skills/agents directory is created.
 
+### Verify, upgrade, and uninstall
+
+Every successful installation writes `.dic-workflow-kit-install.json` with the package version, resolved host roots, managed files, and SHA-256 hashes. Use `doctor` to verify that no managed file is missing or modified:
+
+```text
+dic-workflow-kit doctor --host bitfun --scope project
+dic-workflow-kit doctor --host opencode
+```
+
+Remove only files managed by this installation:
+
+```text
+dic-workflow-kit uninstall --host bitfun --scope project
+```
+
+Install refuses to overwrite an unmanaged or locally modified file. Uninstall likewise refuses to remove a modified managed file. Review the reported paths first; use `--force` only when those changes may be discarded. Use `--json` with `install`, `doctor`, or `uninstall` for machine-readable CI output.
+
 ## How to use it
 
 ### 1. Start the Coding Agent in your project root
 
-After installation, enter the repository you want to inspect and restart Codex, Claude Code, OpenCode, or MiMo Code. An existing session may not discover a newly created Skills/agents directory immediately.
+After installation, enter the repository you want to inspect and restart Codex, Claude Code, OpenCode, MiMo Code, or BitFun. An existing session may not discover a newly created Skills/agents directory immediately.
 
 ```text
 cd /path/to/your-project
@@ -77,7 +99,7 @@ cd /path/to/your-project
 
 ### 2. Start the workflow with a prompt
 
-This prompt works across all four hosts:
+This prompt works across all five hosts:
 
 ```text
 Use DIC Workflow Kit to check design-implementation consistency in this project.
@@ -154,7 +176,10 @@ Terminal status is always `PASS`, `PARTIAL`, `BLOCKED`, or `FAIL`. `PASS` means
 ### Troubleshooting
 
 - **A Skill or Subagent is missing:** restart the Coding Agent and use `--dry-run` to confirm the resolved install root.
-- **Only this repository should use the kit:** add `--scope project` for Claude Code, OpenCode, or MiMo Code.
+- **Check installation integrity:** run `doctor` with the same host, scope, and root options used for installation.
+- **Install reports a collision:** inspect the reported file; preserve or rename user-owned content before considering `--force`.
+- **Uninstall refuses a modified file:** keep the file by leaving the installation in place, or use `--force` only after backing up the modification.
+- **Only this repository should use the kit:** add `--scope project` for Claude Code, OpenCode, MiMo Code, or BitFun.
 - **The project does not use OpenSpec:** use design documents, APIs, schemas, READMEs, or product requirements as authoritative design sources.
 - **A validation tool is unavailable:** record the missing command and environment evidence, and finish as `BLOCKED` or `PARTIAL`; do not claim success.
 - **Do green tests prove consistency:** no. Requirements, branches, state transitions, side effects, and integration flows must also match the design.
@@ -169,7 +194,7 @@ Every release publishes the same version and payload under both npm names:
 `package.json` is the canonical version source. Set a new version once; the helper propagates it to the Codex plugin manifest, workflow runtime, all Skills, all Subagents, and both READMEs:
 
 ```text
-npm run release:set-version -- 1.1.1
+npm run release:set-version -- 1.1.3
 npm run release:plan
 npm run release:dual:dry-run
 npm run release:dual
@@ -217,7 +242,7 @@ Skills are listed by the point at which they first participate in the default wo
 | 01 | `workflow-intake` | Workflow method | Before Subagents | Finds design sources, implementation roots, test roots, protected paths, validation commands, and adapter hints. |
 | 02 | `workflow-profile` | Workflow method | Before Subagents | Normalizes intake evidence into the project profile consumed by every downstream role. |
 | 03 | `knowledge-openspec` | Knowledge pack | During source reading, if OpenSpec is detected | Interprets proposals, designs, specs, scenarios, tasks, active changes, and archived capabilities. |
-| 04 | `knowledge-bdd` | Knowledge pack | After obligations are confirmed, when behavior coverage is needed | Derives Given-When-Then acceptance scenarios from confirmed design rules and flow contracts. |
+| 04 | `knowledge-bdd` | Knowledge pack | When `.feature` files or behavioral coverage are in scope | Interprets mounted Gherkin contracts or derives source-bounded Given-When-Then scenarios. |
 | 05 | `workflow-repair` | Workflow method | Audit through final review | Controls source-backed inspection, repair planning, minimal code changes, validation loops, and evidence updates. |
 | 06 | `knowledge-repair-distill` | Knowledge pack | During repair planning or when execution drifts | Supplies gap taxonomy, convergence guidance, model-steering hints, and validation gates. |
 
@@ -283,6 +308,133 @@ VERIFY
 
 This chain is intentionally evidence-first. Skills provide workflow controls or stage-specific knowledge; Subagents consume bounded inputs and produce typed evidence. A workflow with fewer strong handoffs is better than a decorative chain of agents with no consumed evidence.
 
+## Ontology-Driven Consistency
+
+DIC models the run as a portable semantic graph, not a collection of unrelated
+agent summaries. `reports/ontology-snapshot.json` contains typed objects
+(`DesignSource`, `Requirement`, `Scenario`, `ImplementationUnit`, `Gap`,
+`RepairAction`, `Validation`, and `Evidence`) and explicit links between them.
+
+Each object has a stable ID, lifecycle, and source provenance. Agents operate
+through bounded actions defined by `schemas/ontology-action.schema.json`. The
+final reviewer computes PASS from graph invariants: active obligations must be
+source-backed, requirements must have implementation dispositions, obligations
+must have current validation evidence, and blocking gaps must be closed.
+
+This is file-backed by design. It works across Coding Agent hosts without
+requiring a graph database; SQLite or a graph service can be added later as an
+index without changing the semantic contract.
+
+The published, bundled CLI validates and records actions without publishing the
+runtime source:
+
+```text
+dic-workflow-kit ontology-check --root . --status PASS
+dic-workflow-kit action-check --root . --action reports/actions/repair.json
+dic-workflow-kit action-record --root . --action reports/actions/repair.json
+dic-workflow-kit ontology-reconcile --root .
+dic-workflow-kit ontology-ledger-check --root . --json
+dic-workflow-kit ontology-evidence-check --root . --json
+dic-workflow-kit ontology-validation-check --root . --json
+dic-workflow-kit ontology-implementation-check --root . --json
+dic-workflow-kit ontology-query --root . --query impact --id <object-id>
+dic-workflow-kit ontology-drift --root .
+dic-workflow-kit ontology-plan --root . --json
+dic-workflow-kit ontology-explain --root . --id <object-id> --json
+dic-workflow-kit ontology-report --root . --status PASS
+dic-workflow-kit ontology-attest --root . --status PASS --summary "Verified"
+dic-workflow-kit ontology-attestation-check --root .
+```
+
+`action-record` writes an append-only, SHA-256-addressed audit entry to
+`reports/ontology-actions.jsonl`. It rejects unauthorized Agent roles, missing
+targets, invalid target types, incomplete terminal conditions, missing evidence,
+protected-path overlap, and action-ID collisions.
+
+New records use the v2 ledger format: each record has a sequence number,
+previous-record hash, base Snapshot revision, action hash, and full-record hash.
+This detects reordering, insertion, mutation, and stale-state recording while
+retaining read compatibility with a contiguous v1 prefix. Run
+`ontology-ledger-check` to inspect the chain head and complete-file hash.
+
+Completed actions carry a declarative `ontologyPatch`. Action-specific rules
+restrict which objects, links, and lifecycle transitions can be produced.
+`ontology-reconcile` verifies ledger hashes, skips previously applied actions,
+replays remaining patches, recomputes invariants, and replaces the snapshot only
+after the complete candidate state is valid.
+
+`ontology-query` provides four initial operational views:
+
+- `uncovered`: active obligations missing implementation or validation
+- `gaps`: unresolved Gap objects
+- `unevidenced`: validations without durable evidence
+- `impact --id`: the bounded dependency neighborhood of a changed source,
+  requirement, implementation unit, validation, gap, or repair
+
+`ontology-evidence-check` verifies that every Evidence object required by a
+current Validation points to a real project-relative file whose bytes match its
+recorded SHA-256. A `VERIFIED_BY` link counts toward PASS only when the target
+Validation is current and reports `properties.status: PASS`.
+
+`ontology-validation-check` closes the “old green log, new code” loophole.
+Each Validation records `executedAt` and binds every consumed DesignSource and
+ImplementationUnit through `{ objectId, contentHash }`. Missing or stale inputs
+block PASS and invalidate the final Attestation.
+
+`ontology-implementation-check` verifies every required ImplementationUnit
+against its project-relative file and recorded SHA-256. Existing code is
+recorded through `ObserveImplementation`; `ApplyRepair` is reserved for
+implementation created or changed by an approved repair.
+
+`ontology-drift` compares current design-source content with the SHA-256
+provenance recorded in the snapshot. Changed or missing sources return a
+non-zero status and their IDs can be passed directly to the impact query.
+
+`ontology-plan` combines source drift, implementation drift, Evidence drift,
+and impact traversal into a minimal rerun plan. Design changes restart intake
+and contract confirmation; implementation drift restarts inspection and
+validation; Evidence-only drift restarts validation and final review.
+
+Every generated or reconciled snapshot has a canonical `snapshotRevision`.
+Direct semantic edits invalidate it. Reconciliation also checks that the
+on-disk snapshot did not change while replay was running, preventing a stale
+writer from silently overwriting newer semantic state. Source drift is included
+in the PASS gate, so old green evidence cannot approve a changed design.
+
+`ontology-explain` returns an object's properties, provenance, direct
+relations, and bounded evidence chains. It shows exactly which design source,
+implementation unit, gap, repair, validation, and evidence support a claim.
+
+`ontology-report` generates a high-density Markdown view directly from the
+snapshot. `ontology-attest` creates a content-addressed terminal decision bound
+to the snapshot revision, action-ledger hash, tracked source hashes, Evidence
+artifact hashes, ImplementationUnit hashes, and gate results.
+`ontology-attestation-check` recomputes those bindings so a source,
+implementation file, evidence file, ledger, snapshot, or attestation edit makes
+the artifact fail closed.
+Store the emitted `contentHash` in CI or release metadata and supply it through
+`--expected-hash` to add an external trust anchor; a self-contained digest alone
+provides integrity, not authenticity.
+
+## BDD as an Ontology Source
+
+The source helper detects `.feature` files under conventional feature, BDD,
+spec, and test roots. English and common Chinese Gherkin keywords are supported.
+
+- Feature becomes a Requirement.
+- Scenario and Scenario Outline become Scenario objects.
+- Background clauses are inherited by every scenario.
+- Examples tables, tags, source lines, and source hashes are preserved.
+- `DERIVED_FROM` connects obligations to the feature file.
+- `REFINES` connects each scenario to its Feature requirement.
+
+Parsing a scenario does not prove it passed. Validation and durable evidence
+must still be attached through `RunValidation` and `AttachEvidence`.
+
+For an explicitly selected OpenSpec Change, only referenced Feature files are
+mounted. Other detected files remain discoverable without silently widening the
+Change's obligation scope.
+
 ## OpenSpec Focus
 
 For OpenSpec projects, the kit treats these as first-class design sources:
@@ -317,6 +469,10 @@ By default, a run should produce artifacts relative to the selected submission/w
 reports/project-profile.json
 reports/contract-obligations.json
 reports/contract-obligations.md
+reports/ontology-snapshot.json
+reports/ontology-actions.jsonl
+reports/ontology-report.md
+reports/ontology-attestation.json
 reports/implementation-gaps.md
 reports/repair-plan.md
 reports/final-consistency-report.md
@@ -325,7 +481,19 @@ result/output.md
 logs/trace/
 ```
 
-For an explicit OpenSpec Change, `init` generates both obligation artifacts automatically. Requirements and Scenarios receive stable IDs, source line references, authority labels, parent relationships, and structured Given/When/Then clauses. Active changes use delta specs as authority; archived changes use the promoted current baseline so historical text cannot override current design truth.
+For an explicit OpenSpec Change, `init` generates the obligation artifacts and
+ontology snapshot automatically. Requirements and Scenarios receive stable IDs,
+source line references, authority labels, provenance hashes, parent
+relationships, and structured Given/When/Then clauses. Active changes use delta
+specs as authority; archived changes use the promoted current baseline so
+historical text cannot override current design truth.
+
+From a source checkout, evaluate the ontology structure or a requested PASS gate:
+
+```text
+python scripts/dic_workflow.py --root /path/to/evidence ontology-check
+python scripts/dic_workflow.py --root /path/to/evidence ontology-check --status PASS
+```
 
 Adapters can change or extend this contract. For example, a contest adapter may require a fixed `result/output.md`, while an internal CI adapter may publish JSON evidence to an artifact store.