dic-workflow-kit 1.1.3 → 1.1.4

package/README.md

@@ -1,43 +1,132 @@
-# Design-Implementation Consistency Workflow Kit
+# QIHENG — Design Integrity Control Plane
 
-Version: `1.1.3`
+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.3 install
+npx dic-workflow-kit@1.1.4 install
 ```
 
 Select another host explicitly:
 
 ```text
-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
+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.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
+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,15 +146,15 @@ 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.3
-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.
@@ -75,14 +164,14 @@ Use `--dry-run` to preview the resolved destination, `--install-root <path>` for
 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
+qiheng doctor --host bitfun --scope project
+qiheng doctor --host opencode
 ```
 
 Remove only files managed by this installation:
 
 ```text
-dic-workflow-kit uninstall --host bitfun --scope project
+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.
@@ -102,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.
 ```
@@ -120,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.
@@ -131,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,
@@ -155,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
 
@@ -167,11 +257,15 @@ 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
 
@@ -184,25 +278,7 @@ Terminal status is always `PASS`, `PARTIAL`, `BLOCKED`, or `FAIL`. `PASS` means
 - **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.3
-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
 
@@ -210,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.
@@ -228,85 +304,102 @@ 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 | 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. |
-
-## 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:
-
-```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
-```
+`*` 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.
 
-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.
+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
 
@@ -326,24 +419,27 @@ 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:
+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
-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 .
+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 .
 ```
 
 `action-record` writes an append-only, SHA-256-addressed audit entry to
@@ -508,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.