@omne-harness/repo-toolchain 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# repo-toolchain
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[中文说明](README_ZH.md)
+
+`@omne-harness/repo-toolchain` is this repository's checker package. It is planned for npm and stays `private` until the first release. It provides the rule engine, commit attribution, the dependency graph, declaration compatibility, structure metrics, actual architecture extraction, the review page and the clean loop. After the root pins an exact version, local checks run the published version.
+
+Three unpublished tool members import this package through its subpaths. This package does not import them:
+
+- [dev-flow](../dev-flow/README.md): dispatch admission, task binding, Issue and board reads, the package template.
+- [product-checks](../product-checks/README.md): the product rules, acceptance coverage declarations and scenario status of this repository.
+- [test-runner](../test-runner/README.md): change-set plans, member tests, timing ledgers and differential mutation testing.
+
+## Repository roots and configuration
+
+- The checked repository is `OMNE_SUBJECT_ROOT`. When it is not set, it is the Git root of the current directory.
+- The runner repository is `OMNE_RUNNER_ROOT`. When it is not set, it is the checked repository. Dependency rules (`.dependency-cruiser.cjs`, `tsconfig.base.json`) and configuration come only from the runner repository, so a checked tree cannot change them.
+- Configuration is in [`repo-toolchain.config.json`](../../repo-toolchain.config.json) at the repository root, in the sections `loop`, `metrics` and `acceptanceLock`. A missing file, a missing section or an unknown section is an error. No defaults apply.
+- dependency-cruiser needs TypeScript to parse `.ts` files. With pnpm, add `typescript` to dependency-cruiser under `packageExtensions` in `pnpm-workspace.yaml`. If TypeScript is not found, the dependency check exits with an error. It does not pass with the `.ts` files left out.
+
+## Build and test
+
+```sh
+pnpm --filter @omne-harness/repo-toolchain build      # tsc, then prebuild the review page's third-party code into dist
+pnpm --filter @omne-harness/repo-toolchain typecheck
+pnpm --filter @omne-harness/repo-toolchain test
+pnpm run build:tools                                  # tool member CLIs read this package's dist; build it first (turbo caches it)
+```
+
+The build writes the React, @xyflow/react, antd and elkjs code that the review page inlines to `dist/report/flow/architecture/page-assets.json`. A run from `dist` reads that file. A run from the sources bundles at page generation. The published package therefore does not depend on these UI libraries.
+
+## Public entries
+
+The `exports` subpaths map to modules under `src`, for example `@omne-harness/repo-toolchain/core/task-context`. `.` exports the rule types, `collectSources`, `runRules(files, rules)` and the actual architecture API. `./architecture` exports the actual architecture API. `loop/run`, `loop/hook-measure` and `loop/sensors/*` exist for the tests of the other tool members in this repository and carry no public promise. The published manifest drops the `source` condition, which points at `src`.
+
+`make design-check` checks current design sources, domain objects, and generated inputs. `make loop-health` reports trends, test timings, and Git history.
+
+## Stop-hook revision reads
+
+The Stop hook recalculates the merge base with `primaryBranch` on each invocation.
+The global architecture reader resolves that base to a fixed commit and batches its selected source and intent blobs.
+They use byte lengths for UTF-8 content and preserve literal paths, empty files and read failures.
+No measurements persist across commits. Source ownership uses the longest member prefix and one inventory traversal.
+
+Synchronizing the primary branch can remove delivered changes from the current difference.
+For a task-wide report, run `make loop-status BASE=<task-start-commit>` with a fixed task anchor.
+That explicit base does not change the automatic hook's base. The internal 40-second limit and host error protocol remain unchanged.
+
+## Actual assembly observations
+
+The clean loop reads complete current and BASE sources through `sensors.architecture`.
+Global expectations belong to `docs/architecture/constraints.json`.
+Each version discovers its own current or historical input. Duplicate owners and invalid source references fail.
+Schema 2 source paths start at repository root. Referenced files and Markdown anchors are read at the same version.
+IC-1 and IC-5 use adopted roles and actual public exports. Directory names grant no exception.
+A missing current or BASE input remains unknown or no-data. Current deletion still reports its semantic change.
+Changes to cited Markdown also trigger the hook. See the [conformance contract](src/arch/CONFORMANCE.md).
+It reports static conformance separately from added, removed and changed assembly facts.
+Fact counts are neutral. They have no thresholds or trend comparison.
+
+Identity excludes source positions and uses JSON tuples, so delimiter names do not collide.
+Metadata changes retain contract, owner and shape values before and after the change.
+A dynamic injection remains unknown. A static fact that disappears does not prove runtime release.
+A missing current expectation produces no-data and fails the enabled strict sensor.
+No BASE means no difference reading. Neither case becomes zero.
+
+The extractor does not prove lifecycle, authorization, isolation or shared commits.
+Public services, member SPEC files and behavior verification own those obligations.
+Tests cover source moves, injection additions, metadata changes, collisions, unknowns and missing inputs.
+See [the full configuration and output description](README_ZH.md#实际装配与全局架构约束).