dic-workflow-kit 1.1.2 → 1.1.4

package/README.md

@@ -1,43 +1,132 @@
-# Design-Implementation Consistency Workflow Kit
+# QIHENG — Design Integrity Control Plane
 
-Version: `1.1.2`
+Version: `1.1.4`
 
-[Changelog](CHANGELOG.md)
+[中文](README.zh-CN.md) · [Operating contract](INSTRUCTION.md) · [Ontology](docs/ONTOLOGY.md) · [FAQ](docs/FAQ.md) · [Changelog](CHANGELOG.md)
 
-Design-Implementation Consistency Workflow Kit, or DIC Workflow Kit, is a portable agentic workflow package for checking and repairing whether implementation matches design intent.
+**Every design promise, proven in code.**
 
-It is designed for teams that use OpenSpec, design documents, API contracts, schemas, or product requirements before asking Coding Agents to implement code. The kit turns that process into an auditable workflow: read source truth, map design to implementation, inspect gaps, plan small repairs, validate evidence, and produce final consistency reports.
+QIHENG (契衡) is a portable design integrity control plane for proving that code still matches
+authoritative design intent. It supports Codex, Claude Code, OpenCode, MiMo Code,
+and BitFun, with OpenSpec, design documents, API contracts, schemas, product
+requirements, or Gherkin features as design sources.
 
-The kit is not tied to one contest, one repository, one language stack, or one agent host. It can be installed into OpenCode, referenced by Claude Code, used from Codex, or adapted by another coding-agent runner.
+## What makes it different
 
-> The differentiator is not the number of agents. DIC Workflow Kit uses design intent, typed handoffs, project profiles, validation evidence, and residual-risk reporting to prove that implementation remains aligned with its design contract.
+- **An executable Harness, not a checklist.** A cryptographic Candidate
+  Passport, typed gate graph, dependency closure, explicit applicability, and
+  content-addressed evidence compute delivery readiness.
+- **A shared ontology, not isolated Agent summaries.** Requirements, scenarios,
+  implementation units, gaps, repairs, validations, and evidence form one
+  traceable semantic graph.
+- **Governed mutations.** Role-bounded Actions and action-specific patches are
+  recorded in an append-only, SHA-256-linked Ledger before reconciliation.
+- **Evidence that fails closed.** Source, implementation, and evidence artifacts
+  are content-addressed; changed or missing bytes block PASS.
+- **Validation causality.** A green result binds the exact DesignSource and
+  ImplementationUnit hashes it consumed, so an old log cannot approve new code.
+- **Portable final proof.** Reports and Attestations bind the terminal decision
+  to the snapshot revision, Ledger, artifacts, invariants, and residual risks.
+- **Executive visibility without evidence loss.** The Assurance Cockpit shows
+  one decision, coverage, Digital Thread, risk blockers, and drill-down IDs
+  derived directly from machine state.
+
+The differentiator is therefore not the number of Agents. It is the governed,
+inspectable evidence chain between design, implementation, validation, and the
+final decision.
+
+QIHENG groups roles by evidence responsibility, not by headcount:
+
+- **Lens** establishes authority, obligations, semantic conflicts, and impact.
+- **Forge** inspects, repairs, and validates source-backed gaps.
+- **Tribunal** challenges high-risk claims, audits proof freshness, and makes
+  candidate-bound consistency and admission decisions.
+
+The orchestrator assembles the smallest applicable panel for the current risk.
+Adding more Agents without a distinct hypothesis, artifact, consumer, and
+decision right does not add assurance.
+
+## Three-minute quick start
+
+Requires Node.js 20 or later.
+
+```text
+npx dic-workflow-kit@1.1.4 install
+```
+
+The published package names remain `dic-workflow-kit` and
+`@tonyclaw/dic-workflow-kit` for compatibility. A global install exposes the
+preferred `qiheng` command as well as the legacy `dic-workflow-kit` command.
+
+Restart the Coding Agent in the target repository, then ask:
+
+```text
+Use QIHENG with quality-review-orchestrator to audit this delivery.
+Treat the imported Spec/change as the entry. Check the Spec and applicable
+design gates before implementation, inspect and repair design-implementation
+inconsistency after implementation, re-run gates invalidated by each repair,
+then apply the frozen-candidate pre-commit gate. Report consistency, quality,
+admission, and residual risk separately.
+Do not modify code unless I explicitly approve it.
+```
+
+Start with `reports/final-consistency-report.md`, `reports/FINAL_RESULT.json`,
+and `reports/ontology-report.md`. A valid terminal result is `PASS`, `PARTIAL`,
+`BLOCKED`, or `FAIL`; green tests alone do not imply PASS.
+
+After the project profile exists, operate the executable Harness:
+
+```text
+qiheng harness-init --root .
+qiheng harness-check --root . --json
+qiheng harness-report --root .
+```
+
+The generated `reports/harness-report.md` is the executive-facing Assurance
+Cockpit: one decision, a cryptographic candidate passport, assurance coverage,
+a visual design-to-delivery Digital Thread, gate decisions, and exact blockers.
+
+## Documentation
+
+| Document | Purpose |
+| --- | --- |
+| [Operating contract](INSTRUCTION.md) | Full workflow, evidence, handoff, and terminal-state rules |
+| [Ontology model](docs/ONTOLOGY.md) | Objects, links, Actions, Ledger, gates, and Attestations |
+| [Delivery Assurance Harness](docs/HARNESS.md) | Candidate passport, executable gate graph, Digital Thread, evidence recording, and executive cockpit |
+| [FAQ](docs/FAQ.md) | Multi-Agent communication, mounted knowledge, BDD, and defense questions |
+| [Code-evidence guide](docs/答辩引导-项目特点与代码证据.md) | Project claims mapped to implementation evidence |
+| [Release guide](docs/RELEASING.md) | Maintainer-only dual npm release procedure |
+| [Changelog](CHANGELOG.md) | Version history |
 
 ## 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, MiMo Code, and BitFun.
+Both `dic-workflow-kit` and `@tonyclaw/dic-workflow-kit` publish the same version
+and runtime payload. The package contains all 19 Skills and all thirteen
+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.2 install
+npx dic-workflow-kit@1.1.4 install
 ```
 
 Select another host explicitly:
 
 ```text
-npx dic-workflow-kit@1.1.2 install --host claude-code
-npx dic-workflow-kit@1.1.2 install --host opencode
-npx dic-workflow-kit@1.1.2 install --host mimo-code
-npx dic-workflow-kit@1.1.2 install --host bitfun
+npx dic-workflow-kit@1.1.4 install --host claude-code
+npx dic-workflow-kit@1.1.4 install --host opencode
+npx dic-workflow-kit@1.1.4 install --host mimo-code
+npx dic-workflow-kit@1.1.4 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.2 install --host claude-code --scope project
-npx dic-workflow-kit@1.1.2 install --host opencode --scope project
-npx dic-workflow-kit@1.1.2 install --host mimo-code --scope project
-npx dic-workflow-kit@1.1.2 install --host bitfun --scope project
+npx dic-workflow-kit@1.1.4 install --host claude-code --scope project
+npx dic-workflow-kit@1.1.4 install --host opencode --scope project
+npx dic-workflow-kit@1.1.4 install --host mimo-code --scope project
+npx dic-workflow-kit@1.1.4 install --host bitfun --scope project
 ```
 
 The host mappings are:
@@ -57,19 +146,36 @@ For BitFun, the installer emits its native custom-agent schema. Inspection and p
 You can also install the CLI globally:
 
 ```text
-npm install --global @tonyclaw/dic-workflow-kit@1.1.2
-dic-workflow-kit install --host opencode
+npm install --global @tonyclaw/dic-workflow-kit@1.1.4
+qiheng install --host opencode
 ```
 
 The same CLI can also be installed directly from the repository:
 
 ```text
 npm install --global git+ssh://git@gitcode.com/TonyClaw/DICWorkflowKit.git
-dic-workflow-kit install
+qiheng 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
+qiheng doctor --host bitfun --scope project
+qiheng doctor --host opencode
+```
+
+Remove only files managed by this installation:
+
+```text
+qiheng 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
@@ -85,17 +191,18 @@ cd /path/to/your-project
 This prompt works across all five hosts:
 
 ```text
-Use DIC Workflow Kit to check design-implementation consistency in this project.
-First identify authoritative design sources and protected paths, then build the
-project profile. Map source-backed obligations to implementation, inspect gaps,
-plan repairs only where design evidence exists, run project-declared validation,
-and report the final consistency status and residual risks.
+Use QIHENG with quality-review-orchestrator to review this project.
+Treat the imported Spec/change as the entry. Select risk-applicable gates,
+check design before implementation, repair source-backed consistency gaps after
+implementation, invalidate and re-run affected gates, then decide pre-commit
+admission for the frozen candidate. Report consistency, quality, admission, and
+residual risk separately.
 ```
 
 For an audit that must not modify code:
 
 ```text
-Use DIC Workflow Kit to audit this project without modifying files.
+Use QIHENG to audit this project without modifying files.
 Report design obligations, implementation gaps, evidence locations,
 recommended repairs, and residual risks.
 ```
@@ -103,7 +210,7 @@ recommended repairs, and residual risks.
 For an evidence-bounded repair:
 
 ```text
-Use DIC Workflow Kit to inspect and repair this project.
+Use QIHENG to inspect and repair this project.
 Repair only gaps traceable to authoritative design sources. Run relevant
 validation after each change; stop expanding changes when validation fails
 and record the blocker.
@@ -114,7 +221,7 @@ and record the blocker.
 Provide the Change ID explicitly to reduce search scope and avoid treating historical changes as current truth:
 
 ```text
-Use DIC Workflow Kit to check the OpenSpec Change
+Use QIHENG to check the OpenSpec Change
 2026-06-09-add-ts-local-skill-source.
 Start from its proposal, design, tasks, and delta specs. Cross-check the current
 stable specs, implementation, and tests. Produce an obligation matrix,
@@ -138,7 +245,7 @@ Use workflow-core, workflow-intake, workflow-profile, and
 knowledge-openspec to inspect the current OpenSpec change.
 ```
 
-You do not need to start all nine Subagents manually. The primary Agent should select roles according to evidence dependencies and require every delegation to produce an artifact consumed by a downstream step.
+You do not need to start all thirteen Subagents manually. The primary Agent should select roles according to evidence dependencies and require every delegation to produce an artifact consumed by a downstream step.
 
 ### 5. Read the results
 
@@ -150,39 +257,28 @@ Start with these outputs:
 | `reports/contract-obligations.md` | Human-readable design obligations with source anchors |
 | `reports/implementation-gaps.md` | Confirmed implementation gaps |
 | `reports/repair-plan.md` | Source-backed repair plan with stop conditions |
+| `reports/quality/` | Applicability plan, gate run history, invalidation reasons, and candidate-bound decisions |
 | `reports/final-consistency-report.md` | Final consistency conclusion and residual risks |
 | `reports/FINAL_RESULT.json` | Machine-readable terminal status |
 | `logs/trace/` | Intake, delegation, change, and validation evidence |
 
-Terminal status is always `PASS`, `PARTIAL`, `BLOCKED`, or `FAIL`. `PASS` means the evidence chain and validation gates are satisfied, not merely that visible tests happen to pass.
+DIC terminal status is `PASS`, `PARTIAL`, `BLOCKED`, or `FAIL`. Read it
+separately from specialist quality and repository admission. A DIC `PASS`
+means the consistency evidence chain is satisfied, not merely that visible
+tests happen to pass and not that the candidate is automatically admitted.
 
 ### Troubleshooting
 
 - **A Skill or Subagent is missing:** restart the Coding Agent and use `--dry-run` to confirm the resolved install root.
+- **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.
 
-### Dual npm release
-
-Every release publishes the same version and payload under both npm names:
-
-- `@tonyclaw/dic-workflow-kit`
-- `dic-workflow-kit`
-
-`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.2
-npm run release:plan
-npm run release:dual:dry-run
-npm run release:dual
-```
-
-npm cannot provide an atomic transaction across two package names. The coordinator therefore uses a convergent release: it completes all local checks first, publishes both packages from temporary staging directories, skips a package when the exact version already exists, and can be safely rerun to publish only the missing side after a partial failure.
-
-For a defense-oriented walkthrough of the project claims and their code evidence, see [答辩引导：项目特点与代码证据](docs/答辩引导-项目特点与代码证据.md).
+Maintainers: see [the dual npm release guide](docs/RELEASING.md).
 
 ## Why This Exists
 
@@ -190,7 +286,7 @@ Coding Agents are good at changing code, but they often optimize for local green
 
 > Does the implementation still match the design contract?
 
-DIC Workflow Kit answers that question with a repeatable workflow:
+QIHENG answers that question with a repeatable workflow:
 
 1. Identify authoritative design sources.
 2. Build a project profile.
@@ -208,85 +304,232 @@ DIC Workflow Kit answers that question with a repeatable workflow:
 | `skills/` | Installable Skills: workflow controls and reusable knowledge packs. |
 | `agents/` | Installable Agent prompts: bounded roles for evidence production and repair flow. |
 | `adapters/` | Optional adapters for OpenSpec, generic repos, contests, and stack-specific environments. |
-| `schemas/` | Stable JSON schemas for project profile, handoff, and final evidence artifacts. |
+| `runtime/` | Source implementation of ontology evaluation, Actions, Ledger, integrity checks, reports, and Attestations. |
+| `schemas/` | Stable JSON schemas for profiles, ontology state, Actions, handoffs, Attestations, and final results. |
 | `scripts/` | Portable Python standard-library helpers. |
+| `docs/` | Ontology reference, FAQ, release guide, presentations, and code-evidence walkthroughs. |
 | `examples/` | Small examples showing how to apply the kit to different project styles. |
 
-## Skills in Workflow Order
+## Skills by First Activation
 
-Skills are listed by the point at which they first participate in the default workflow. Knowledge Skills are conditional: load them only when repository evidence or the current stage requires them.
+This table is an index, not a mandatory serial pipeline. Skills are listed by
+their earliest normal activation point. Knowledge and specialist quality Skills
+are conditional, may run more than once, and become stale when their consumed
+artifacts or candidate bytes change.
 
 | Order | Skill | Type | Workflow Position | Core Role |
 | --- | --- | --- | --- | --- |
-| 00 | `workflow-core` | Workflow mechanism | Entire run | Defines source priority, evidence rules, typed handoffs, final statuses, and durable output contracts. |
-| 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. |
-| 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. |
-
-## Subagents in Execution Order
-
-Each Subagent appears in its default execution order. A stage may be skipped only with evidence, and a Subagent is useful only when its output is consumed by the next decision.
+| 00 | `quality-review-orchestrator` | Quality control | Imported Spec through pre-commit admission | Maintains the applicability plan, gate dependencies, invalidation, reruns, and distinct delivery outcomes. |
+| 01 | `workflow-core` | Workflow mechanism | Entire DIC run | Defines source priority, ontology, evidence rules, typed handoffs, final statuses, and durable outputs. |
+| 02 | `workflow-harness` | Executable control plane | Profile creation through admission | Freezes candidate identity, materializes the gate graph, records evidence-backed decisions, propagates invalidation, and computes readiness. |
+| 03 | `workflow-intake` | Workflow method | Before Subagents | Finds design sources, implementation roots, test roots, protected paths, validation commands, and adapter hints. |
+| 04 | `workflow-profile` | Workflow method | Before Subagents | Normalizes intake evidence into the project profile consumed by every downstream role. |
+| 05 | `knowledge-openspec` | Knowledge pack | During source reading, if OpenSpec is detected | Interprets proposals, designs, specs, scenarios, tasks, active changes, and archived capabilities. |
+| 06 | `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. |
+| 07 | `knowledge-change-impact` | Knowledge pack | After intake, drift, or repair | Traces semantic impact and invalidates only dependent evidence and gates. |
+| 08 | `quality-cross-spec-consistency` | Design quality gate | After authority discovery; before implementation | Audits direct related baselines and ranked semantic candidates for incompatible current rules. |
+| 09 | `quality-spec-review` | Design quality gate | After Spec import; before implementation | Checks specification completeness, consistency, testability, traceability, and unsupported claims; reruns after governing Spec changes. |
+| 10 | `quality-sr-ar-review` | Architecture quality gate | Before architecture-affecting implementation | Checks requirement-to-design coverage, ownership, interfaces, data/state, quality attributes, and realizability. |
+| 11 | `quality-ci-gate` | Delivery quality gate | PLAN before implementation; VERIFY before admission | Defines mandatory candidate checks, runtime/flake policy, evidence retention, and candidate-bound verification. |
+| 12 | `workflow-repair` | Workflow method | Post-implementation DIC loop | Controls source-backed consistency inspection, minimal repair, validation, and convergence. |
+| 13 | `knowledge-repair-distill` | Knowledge pack | During repair planning or when execution drifts | Supplies gap taxonomy, convergence guidance, model-steering hints, and validation gates. |
+| 14 | `quality-code-review` | Implementation quality gate | Whenever changed implementation risk applies | Reviews semantic contract impact, architecture, security, performance, reliability, and maintainability. |
+| 15 | `quality-dt-review` | Test quality gate | Whenever changed behavior or test risk applies | Checks requirement/risk coverage, negative paths, assertion strength, determinism, and mutation sensitivity. |
+| 16 | `quality-adversarial-challenge` | Independent challenge gate | After ordinary review for high-risk claims | Runs a minimal risk-selected challenge set and records reproducible counterexamples. |
+| 17 | `quality-evidence-audit` | Evidence integrity gate | Before final review and after candidate drift | Verifies that claims are current, reproducible, content-addressed, and candidate-bound. |
+| 18 | `quality-repository-gate` | Pre-commit admission gate | After DIC Attestation and affected-gate reruns | Freezes candidate identity and decides ADMIT, ADMIT WITH FOLLOW-UP, or REJECT from current evidence. |
+
+## Subagents in the DIC Consistency Loop
+
+These Subagents implement the post-implementation consistency loop. Their
+dependency order does not imply that the surrounding quality gates execute once
+or that unrelated work must be serialized.
 
 | Step | Subagent | Phase | Consumes | Produces |
 | --- | --- | --- | --- | --- |
-| 01 | `spec-reader` | Source truth | Project profile and authoritative design sources | Source-backed requirement brief, source anchors, protected paths, unresolved questions |
-| 02 | `profile-builder` | Project profile confirmation | Intake evidence and repository structure | `reports/project-profile.json` |
-| 03 | `contract-oracle` | Obligation mapping | Confirmed requirements, scenarios, and feedback hypotheses | Source-confirmed obligation queue |
-| 04 | `flow-auditor` | Flow completeness | Obligation queue and optional BDD scenarios | Lifecycle, transition, branch, side-effect, and integration-flow audit |
-| 05 | `impl-inspector` | Implementation inspection | Confirmed obligations and flow audit | Source-backed implementation gap report; no code edits |
-| 06 | `repair-planner` | Repair planning | Gap report, protected paths, and available validation commands | Small repair slices with source anchors, stop conditions, and fallback routes |
-| 07 | `code-repairer` | Code repair | Approved repair slices | Minimal code changes, changed-file evidence, and repair notes |
-| 08 | `validation-runner` | Validation | Project-declared commands and changed implementation | Evaluator-readable validation logs and summaries under `logs/trace/validation/` |
-| 09 | `final-reviewer` | Final gate | All prior evidence, changed files, validation, and output artifacts | Final consistency decision, residual risks, and result recommendation |
-
-## Default Workflow
+| 01 | `profile-builder` | Project profile confirmation | Intake evidence and repository structure | `reports/project-profile.json`, authority scope, and semantic candidates |
+| 02 | `spec-reader` | Source truth | Project profile and authoritative design sources | Source-backed requirement brief, source anchors, protected paths, unresolved questions |
+| 03 | `semantic-conflict-auditor` | Cross-Spec challenge | Direct related baselines, semantic candidates, and authority roots | Source-paired conflict and refinement findings; no edits |
+| 04 | `contract-oracle` | Obligation mapping | Confirmed requirements, scenarios, and conflict findings | Source-confirmed obligation queue |
+| 05 | `impact-analyst` | Change impact | Candidate change surface, obligations, repository and ontology dependencies | Invalidated decisions and minimal safe rerun plan |
+| 06 | `flow-auditor` | Flow completeness | Obligation queue and optional BDD scenarios | Lifecycle, transition, branch, side-effect, and integration-flow audit |
+| 07 | `impl-inspector` | Implementation inspection | Confirmed obligations and flow audit | Source-backed implementation gap report; no code edits |
+| 08 | `repair-planner` | Repair planning | Gap report, protected paths, and available validation commands | Small repair slices with source anchors, stop conditions, and fallback routes |
+| 09 | `code-repairer` | Code repair | Approved repair slices | Minimal code changes, changed-file evidence, and repair notes |
+| 10 | `validation-runner` | Validation | Project-declared commands and changed implementation | Evaluator-readable validation logs and summaries under `logs/trace/validation/` |
+| 11 | `adversarial-challenger` | Independent challenge | Frozen candidate, high-risk claims, policies, and evidence | Falsifiable challenges and reproducible counterexamples; no edits |
+| 12 | `evidence-auditor` | Evidence integrity | Candidate, claims, gate runs, validation, and content hashes | Claim-to-evidence matrix and stale or unsupported claim findings |
+| 13 | `final-reviewer` | DIC consistency gate | Current DIC evidence, conflicts, impact, validation, and output artifacts | Candidate-bound consistency decision and Attestation; not repository admission |
+
+## Default Gate Lifecycle
 
 ```text
-workflow-core
--> workflow-intake
--> workflow-profile
--> [knowledge-openspec, when detected]
--> spec-reader
--> profile-builder
--> contract-oracle
--> [knowledge-bdd, when behavior coverage is needed]
--> workflow-repair
--> flow-auditor
--> impl-inspector
--> [knowledge-repair-distill, when planning or drift requires it]
--> repair-planner
--> code-repairer
--> validation-runner
--> final-reviewer
+IMPORT SPEC
+-> Intake + Profile
+-> Cross-Spec Consistency
+-> Spec Review
+-> [SR/AR Review when architecture or realization is affected]
+-> CI Gate [PLAN]
+
+IMPLEMENT
+-> implementation from confirmed obligations
+-> [risk-applicable specialist gates]*
+
+DIC CONSISTENCY LOOP
+-> inspect design-implementation gaps
+-> [plan repair -> apply repair -> validate]*
+-> analyze impact and stale dependent evidence
+-> [invalidate and re-run affected gates]*
+
+PRE-COMMIT
+-> CI Gate [VERIFY frozen candidate]
+-> [Adversarial Challenge when material hypotheses apply]
+-> Evidence Audit [candidate-bound claim freshness]
+-> Final Reviewer [DIC consistency + Attestation]
+-> Repository Gate [ADMIT / ADMIT WITH FOLLOW-UP / REJECT]
 ```
 
-The same flow can be read as four evidence gates:
+`*` means zero or more risk-driven iterations. This is a gate graph with
+feedback loops, not a fixed one-pass Agent chain. A skipped gate needs an
+applicability reason. A changed Spec, architecture, implementation, test,
+fixture, pipeline, policy, or candidate invalidates dependent decisions, which
+must be re-run from the earliest affected boundary.
+
+Keep three outcomes distinct: DIC `consistencyStatus`, specialist
+`qualityStatus`, and repository `admissionStatus`. DIC `PASS` proves
+design-implementation consistency; it does not by itself prove every quality
+domain or grant `ADMIT`. Retain the applicability plan, gate run history,
+invalidation reasons, and decisions under `reports/quality/`.
+
+## 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. These ontology commands expect the workflow to have already
+created `reports/ontology-snapshot.json`, `reports/project-profile.json`, and,
+for Ledger operations, `reports/ontology-actions.jsonl`. They are integrity and
+governance commands, not a replacement for the initial Agent-driven intake:
 
 ```text
-DISCOVER
-workflow-intake
--> workflow-profile
-
-UNDERSTAND
--> spec-reader
--> profile-builder
--> contract-oracle
-
-INSPECT + REPAIR
--> flow-auditor
--> impl-inspector
--> repair-planner
--> code-repairer
-
-VERIFY
--> validation-runner
--> final-reviewer
+qiheng ontology-check --root . --status PASS
+qiheng action-check --root . --action reports/actions/repair.json
+qiheng action-record --root . --action reports/actions/repair.json
+qiheng ontology-reconcile --root .
+qiheng ontology-ledger-check --root . --json
+qiheng ontology-evidence-check --root . --json
+qiheng ontology-validation-check --root . --json
+qiheng ontology-implementation-check --root . --json
+qiheng ontology-query --root . --query impact --id <object-id>
+qiheng ontology-drift --root .
+qiheng ontology-plan --root . --json
+qiheng ontology-explain --root . --id <object-id> --json
+qiheng ontology-report --root . --status PASS
+qiheng ontology-attest --root . --status PASS --summary "Verified"
+qiheng ontology-attestation-check --root .
 ```
 
-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.
+`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
 
@@ -322,6 +565,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
@@ -330,7 +577,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.
 
@@ -345,4 +604,8 @@ Adapters can change or extend this contract. For example, a contest adapter may
 
 ## Status
 
-This repository currently contains the first generalized scaffold extracted from a contest-specific design-implementation repair workflow. It is intended to become the reusable upstream kit for future OpenSpec and design-first Coding Agent workflows.
+QIHENG is a released, cross-host workflow package with safe
+installation lifecycle management, OpenSpec and BDD intake, ontology-governed
+Actions, content-addressed validation, tamper-evident Ledgers, generated reports,
+and final Attestations. New work should preserve these contracts while extending
+adapters, storage backends, and CI trust anchors.