Standards, principles, testing strategy and architecture¶
Since 2.0 (#56) the harness carries the team's engineering standards into the run: language
standards packs, engineering principles, a testing strategy (TDD or BDD when the team works that
way) and the project's architecture. Every setting is optional; a project.yaml without it keeps
the 1.0.0 behaviour and its configuration digest. harness init writes them (see
the file harness init writes) and
harness config validate shows the effective values under engineering.
The cost rule of the whole wave: tools verify, models judge only what tools cannot.
- The implement request carries only the standards cards that apply to the files the call works
on, compact (id, rule, exceptions), capped by
standards.maxCards, selected deterministically and cached by the digest of the packs and the paths. - The cards no tool verifies and the principles checklist ride on the existing review call: no extra agent call.
- The architecture survey of an existing project is one read-only call per project, cached in
.harness/architecture.mdand reused by every run; new-project options are one call, only for a new project. - TDD evidence is measured by running the tests, BDD scenarios by the project's BDD runner.
scripts/measure_agent_tokens.py measures it: see token cost.
Standards packs¶
Fifteen packs ship with the package (src/governed_harness/resources/standards/PACK/):
python, javascript, typescript, node, react, angular, vue, java, kotlin, go,
rust, swift, csharp, php and ruby. Each has two files:
cards.yaml: short rule cards with an id (python.no-mutable-defaults), the rule, its rationale, explicit exceptions, the files it applies to (appliesToglobs) and what verifies it (verifiedBy: tool rule ids such asruff:B006oreslint:eqeqeq, orreview);tools.yaml: how the language is detected (marker files, extensions, manifest dependencies), its test and BDD runners, the BDD frameworks it recognizes and its tools (Checkstyle, PMD and SpotBugs; ktlint and detekt; ESLint, typescript-eslint, eslint-plugin-react and react-hooks, angular-eslint and eslint-plugin-vue, Prettier; golangci-lint; Clippy and rustfmt; SwiftLint; the .NET analyzers anddotnet format; PHPStan and PHP CS Fixer; RuboCop; Ruff, Mypy, Bandit and Vulture) with the configuration files that show a repository uses them, the command with machine-readable output, its parser and a recommended configuration.
| Key | Absent | init |
Effect |
|---|---|---|---|
packs |
[auto] |
[auto] |
auto: the packs of the detected languages (profile technologies, marker files, extensions, dependencies in package.json, pyproject.toml, pom.xml and other manifests); a pack brings the packs it extends (typescript and react bring javascript). Or pack ids. |
cards |
off |
auto |
The cards that apply to the files of a call go to the implement request (standards block); the cards verified by review and applying to the ChangeSet files go to the review call's checklist. |
maxCards |
12 |
12 |
Cap of the cards of one request. |
tools |
off |
detect |
Each pack tool whose configuration file is in the repository, and that no selected validator already runs (coveredBy), becomes an optional validator standards.PACK.TOOL with its parser. Detection only: the harness never installs a tool; a tool that is not installed is NOT_APPLICABLE. |
path |
.harness/standards |
none | Repository overrides: PATH/PACK/cards.yaml replaces cards with the same id, adds new ones and may list disabled ids; PATH/PACK/tools.yaml replaces tools by id; a directory with an id no pack has is a repository pack. |
disabled |
none | none | Card ids to drop. |
harness standards show lists the detected and effective packs, their tools and the validators
added for the repository; --lang PACK shows every card of one pack, --file PATH the cards an
implement call and the review checklist would get for those files. It works without a project.
The repository's own tool configuration takes precedence over the pack's recommendation: the pack only detects that the tool is configured and runs it. The parsers added for the packs' tools are Checkstyle XML, RuboCop JSON, Cargo JSON (Clippy) and MSBuild diagnostics (see located findings).
Engineering principles¶
verification.principles measures the traces some principles leave, deterministically, in
VERIFICATION (validator harness.principles):
| Rule | Proxy | Principle |
|---|---|---|
principles.dry.duplication |
A window of duplicationWindow normalized lines (default 6) the change adds that already exists in another file or elsewhere in the same file (tests are ignored). |
DRY |
principles.kiss.nesting |
An added line nested more than five levels deep (indentation, any language). | KISS |
principles.kiss.module-size |
A non-Python source file the change grows past verification.architecture.maxModuleLines (default 800); a file already past it is LOW. Python uses the #40 limits. |
KISS, Clean Code |
principles.composition.inheritance |
A class the change adds or edits whose inheritance chain in the workspace is deeper than maxInheritanceDepth (default 3): Python AST, extends and class X : Y declarations, Ruby <. |
Composition over inheritance |
principles.yagni.unused-public |
A public function or class (Python) or export (JavaScript, TypeScript) the change adds that no other file, test included, names; always LOW. | YAGNI |
principles.boy-scout.reformat-only |
A file whose every change is whitespace or layout: an unrelated cleanup. Cleanup inside a file the change edits for the task is allowed. | Boy Scout (bounded) |
Dependency direction and layers are the architecture's layer rules below (separation of concerns,
dependency inversion); naming and signatures are verified by the linters of the packs. Under
mode: enforce the check is mandatory and its findings have severity (default MEDIUM: shown,
not blocking under the default findingBlockSeverities; HIGH makes them block and enter the
correction loop); under warn they are LOW. unusedPublic, boyScout and checklist can be
turned off one by one.
With checklist (default on) the review call (review.agentReview) also receives the principles
checklist (single responsibility, open-closed, Liskov substitution, interface segregation,
dependency inversion, DRY, KISS, YAGNI, least astonishment, composition, Boy Scout), each with a
rule id (principles.srp and so on) the reviewer uses for its findings.
Testing strategy¶
testing.strategy |
What happens |
|---|---|
auto (init) |
Follow the repository: feature files or a BDD framework (behave, pytest-bdd, Cucumber, SpecFlow or Reqnroll, Karate, Behat, godog, Kotest...) give bdd, tests give conventional; nothing known is asked in INTENT under intake.projectSetup, and a person's answer is kept for the project. |
conventional |
The earlier behaviour. |
tdd |
The implement request asks for test-first work, and VERIFICATION records the evidence (validator harness.tdd, artifact tdd-evidence): red, the tests the change adds or changes run on the workspace with the changed sources reverted to the baseline and must fail there (tdd.not-red, HIGH, when they pass; tdd.no-tests, HIGH, when code changes without a test); green, every mandatory validator passes; refactor, the principles, architecture and layer checks pass with everything green. The red run uses testing.testCommand with the test files, else the pack's runner (python -m pytest -q FILES, bundle exec rspec FILES, the whole suite where the runner takes no files). |
bdd |
The acceptance call of SPECIFICATION writes the criteria as Gherkin feature files under featuresDirectory (default features) instead of pytest files; SPECIFICATION waits for a person (harness acceptance decide); the approved files are frozen and the BDD runner (bddCommand, else the pack's: python -m behave, npx cucumber-js, mvn -q test, bundle exec cucumber...) runs before the change and must fail (the steps are not defined); the implement request asks for the step definitions; every VERIFICATION checks the frozen files and runs the runner. |
Architecture¶
| Key | Absent | init |
Effect |
|---|---|---|---|
mode |
off |
agent |
agent: one read-only architecture call per project (a survey of an existing project in DISCOVERY, options for a new project in INTENT). |
style |
none | none | ddd, hexagonal, clean, layered, modular-monolith, microservices, mvvm, mvi or custom; a configured style or layers skip the call. |
layers |
none | none | Each layer: name, paths (globs) and/or modules (dotted prefixes). |
allow |
none | none | The layers each layer may depend on; a layer may always use itself, and a layer without an entry may use no other layer. |
enforce |
enforce |
enforce |
Layer violations are HIGH (enforce) or LOW (warn). |
refresh |
manual |
manual |
auto also surveys again when the source directory layout changed materially (fewer than 80 % of the directories in common). |
agent |
the run's provider | none | Provider, model and effort of the architecture call. |
layerCheck |
full |
differential |
differential: the layer check judges only the layers a changed file did not import on the baseline; full: every import of a changed file. |
baselineConflicts |
enforce |
allow |
allow: the dependencies the code already has and a survey's rules forbid are listed in the proposal and stay allowed in the rules a person approves; enforce: the rules as inferred. |
catalogue |
off |
experts |
experts: a new project chooses among the ten styles of the catalogue (layered, hexagonal, clean, ddd, modular-monolith, microservices, mvvm, mvi, event-driven, cqrs) with a recommendation report, and an expert for the chosen style rides with every later request. See architectures (Spanish). |
documentation |
off |
project |
project: the survey of an existing project writes persistent documents in .harness/reverse-engineering that later requests point to. See reverse engineering (Spanish). |
Existing project. DISCOVERY surveys it once: the call reads the layout and a few files and
answers the style, a short Markdown description and the layer rules it can infer. The answer is
stored in .harness/architecture.md and .harness/architecture.json and reused by every later
run (event architecture.survey.reused, no call). When rules were inferred, DISCOVERY waits for a
person, bound to their digest:
harness architecture show
harness architecture decide --run RUN --decision APPROVE --digest DIGEST --rationale "..."
harness architecture refresh marks the survey stale; the next run surveys again.
A survey can infer a rule the project itself breaks (in the 2.0.0 pilot, "encoding may depend on
no other layer" for a module that imports from .exc import BadData). Under
baselineConflicts: allow the harness checks the inferred rules against the source files before
it proposes them. Each dependency between two layers that the rules forbid and the code already
has is a conflict: the proposal lists it under baselineConflicts (the two layers, the number of
imports and up to five examples with path and line), the message of the blocked run and the
architecture entry of harness inbox name it, and the proposal carries the rules that will be
in force under enforced: the inferred rules with those dependencies added to allow. The digest
a person approves covers the inferred rules, the conflicts and the enforced rules. To keep a rule
as it was inferred, reject the proposal and configure layers and allow by hand.
New project. INTENT asks the call for two to four options with their trade-offs (benefits,
costs, fit) and one recommendation. A person chooses, bound to the digest of the options; the
choice is recorded as an ADR (an artifact with its digest and .harness/adr/ADR-0001-architecture.md)
and its layers become the rules:
harness architecture decide --run RUN --option hex --digest DIGEST --rationale "..."
Enforcement. The rules in force (configured layers, else the approved survey or ADR) are the forbidden-dependency
check of issue #40 generalized to every language (validator harness.layers, rule
architecture.layer-violation): the imports of each changed file are read per language (Python
AST; JavaScript and TypeScript import/require with relative paths resolved; Java, Kotlin and
Scala import; C# using; PHP use; Go import paths; Rust use crate::; Swift import; Ruby
require) and resolved to a layer by path glob, module prefix or declared package. The implement
request carries the layers and what each may depend on, and harness check runs the same check.
Under layerCheck: differential the check compares each changed file with its baseline text, as
the validators' ratchet does: a layer the file already imported before the change is a dependency
the change did not add and is not judged, whatever the rules say; an import that reaches a layer
the file did not depend on before is judged, and a new file is judged whole. It applies to
configured layers, an approved survey and an ADR alike. Without the key every import of a changed
file is judged, so a change is blamed for an import the baseline already had.
New and existing projects¶
A project is new when its Git repository has no commit, or when it has no source file beyond
scaffolding (tests, configuration, documentation, source files that define nothing, and an entry
point of at most 15 lines); otherwise it is existing. harness project show reports the
decision and why, with the packs, the testing strategy, the architecture and the forge, without
an agent call.
Under intake.projectSetup: ask INTENT asks (rule P1, targets project:architecture,
project:testing, project:standards), once per project:
- a new project: the testing strategy and the standards packs, unless the configuration sets them;
the architecture too when
architecture.modeis notagent(withagent, the call proposes options instead); - an existing project: only what detection could not establish (no tests, no detected language).
The person answers with harness task clarify like any clarification; the answers become the
project's setup record (harness project show, projectSetup), which later runs read instead of
asking again, and each answer lands in the task as a constraint (Project setup (testing): tdd).
Token cost¶
scripts/measure_agent_tokens.py runs the quickstart's Python project twice with the same two
tasks through a fixture command provider that calls no model and reports, as usage, an estimate
of the tokens it received (the request's JSON length divided by four; a rule of thumb, not a
tokenizer). The harness records that usage (harness budget show). Measured with the
harness of this branch (macOS arm64, Python 3.12.11), the totals per run and the calls by kind
(estimated input tokens):
| Configuration | Run | Agent calls | Recorded tokens | Implement | Review | Architecture |
|---|---|---|---|---|---|---|
| before (agent-results defaults, no wave 6 keys) | first task | 4 | 4670 | 1851 | 1076 | none |
| before | second task | 4 | 4735 | 1909 | 1079 | none |
after (harness init with wave 6) |
first task | 5 | 6359 | 2350 | 1421 | 814 |
| after | second task | 4 | 5575 | 2407 | 1423 | none |
The first run of a project pays one architecture survey; every later run reuses it. The
implement request grows with the nine cards that apply to src/sample/pricing.py and its test
(about 500 estimated tokens) and the review request with the checklist (about 345); the
principles, layer, TDD and BDD checks are tools and add no agent call. Re-run the script after
changing a pack or the checklist.