okstra 0.228.0 → 0.228.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -89,6 +89,15 @@ remains readable and is not retrofitted. Snapshot publication and reference chec
89
89
  are covered by `tests/run/test_project_qa_command_gate.py` and
90
90
  `tests/application/test_host_orchestration_render.py`.
91
91
 
92
+ QA declarations retain the optional `language` selector for the verifier's existing
93
+ diff-language skip policy. An absent selector remains absent and means always run.
94
+ Present selectors must be non-empty identifiers using letters, digits, `.`, `_`,
95
+ `+`, `#` or `-`, beginning with a letter or digit. The shared QA metadata validator
96
+ checks their shape during declaration loading and snapshot reading.
97
+ Changing a selector cannot replace a published snapshot. Frozen selectors remain
98
+ visible after current project settings change. The declaration immutability,
99
+ allowed-field and projection tests in `test_project_qa_command_gate.py` cover this.
100
+
92
101
  These declarations do not prove that a command ran. Preparation does not require
93
102
  future inspection scripts to exist, and execution receipts are a separate contract.
94
103
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.228.0",
3
+ "version": "0.228.2",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.228.0",
3
- "builtAt": "2026-11-01T10:19:02.762Z",
2
+ "package": "0.228.2",
3
+ "builtAt": "2026-11-01T13:01:12.678Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -20,7 +20,7 @@ Good:
20
20
  const sum = (arr) => arr.reduce((acc, x) => acc + x, 0);
21
21
  ```
22
22
 
23
- Caveat: do not extract until the duplication is real (rule of three). Premature abstraction is also a code smell. The caveat does not cover a literal copy: a new block byte-identical to one already in the repository — test helpers included — reuses or moves the existing one.
23
+ Caveat: extract when two current callers implement the same capability and would change together. Similar syntax alone does not establish a shared capability; keep independent decisions separate. Do not add an abstraction for a hypothetical second caller. A literal copy of an existing capability — test helpers included — reuses or moves the existing implementation.
24
24
 
25
25
  Two more forms of duplication that hide from symbol-level grep:
26
26
 
@@ -33,14 +33,16 @@ The simplest solution that meets the requirement wins. Cleverness has a maintena
33
33
 
34
34
  Bad:
35
35
  ```javascript
36
- if (data !== null || data !== undefined || data !== '') { ... }
36
+ const canSubmit = isReady ? true : false;
37
37
  ```
38
38
 
39
39
  Good:
40
40
  ```javascript
41
- if (data) { ... }
41
+ const canSubmit = isReady;
42
42
  ```
43
43
 
44
+ Here `isReady` is already a boolean, so both versions preserve the same value. Do not replace explicit null, undefined, or empty-string checks with a truthiness check unless rejecting `0`, `false`, and `NaN` is also intended.
45
+
44
46
  ## SOLID
45
47
 
46
48
  - **S**ingle Responsibility — one reason to change per class / module.
@@ -95,8 +97,8 @@ The name must describe what the function actually does. Misleading names break r
95
97
 
96
98
  Flag and rename:
97
99
 
98
- - `get*` / `fetch*` / `find*` that also mutate state, throw, or write logs / audits.
99
- - `is*` / `has*` / `can*` that throw instead of returning a boolean.
100
+ - `get*` / `fetch*` / `find*` that also perform caller-visible state changes their read-oriented names do not disclose. Documented lookup failures and diagnostic logging do not by themselves make a read name misleading.
101
+ - `is*` / `has*` / `can*` that use an exception for an ordinary negative answer instead of returning `false`. An operational failure may still propagate under a documented failure contract.
100
102
  - `find*` that *creates* the entity when missing → `findOrCreate*` or `ensure*`.
101
103
  - Names that describe the implementation, not the intent: `loopOverUsers` → `notifyActiveUsers`, `runQuery` → `listOverdueInvoices`.
102
104
  - Names that say the opposite of what they do under some branch: `enableFoo` that disables when a flag is off, with no hint in the name.
@@ -129,9 +131,9 @@ The test: grep the identifier across the file. If two occurrences carry differen
129
131
 
130
132
  ## Functions do one thing
131
133
 
132
- If the name contains "and", or you must scroll to read it, split it.
134
+ A name containing "and" or a body requiring scrolling is a reason to inspect responsibilities, not proof that a split is needed. Split when the body mixes independent responsibilities or levels of abstraction; apply the 50-line cap below separately.
133
135
 
134
- Bad:
136
+ A short orchestrator may call several already-named steps at the same abstraction level:
135
137
  ```javascript
136
138
  function handleData() {
137
139
  fetchData();
@@ -140,7 +142,7 @@ function handleData() {
140
142
  }
141
143
  ```
142
144
 
143
- Good: each step is its own function with a clear name and signature.
145
+ The body above does not need further splitting: each step is already a separate function. The generic name `handleData` is a naming issue; choose a name for the overall operation based on the caller's purpose.
144
146
 
145
147
  ### Plain-English summary test
146
148
 
@@ -148,11 +150,11 @@ For every function you add or meaningfully modify, ask:
148
150
 
149
151
  > Can I summarize what this function does, line by line, as a short English sentence per line — and does the resulting summary read as prose?
150
152
 
151
- If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract.
153
+ If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract. A local readability helper can have one caller; the second-caller requirement applies to reuse-driven abstraction layers.
152
154
 
153
- ### Also flag and split
155
+ ### Inspect for readability problems
154
156
 
155
- - Nested conditionals 3+ levels deep — flatten with early returns or named predicates.
157
+ - Three nested control-flow blocks — inspect whether early returns or named predicates improve readability. Four or more require refactoring under "Limit nesting depth" below.
156
158
  - Mixed levels of abstraction — a high-level orchestrator suddenly doing string parsing, date arithmetic, or SQL assembly inline.
157
159
  - A reader has to track 5+ anonymous temporary values to understand the return.
158
160
  - A long `.map().filter().reduce()` chain where each stage does non-obvious work and no stage has a name.
@@ -170,7 +172,7 @@ Crossing the cap is an extraction signal, not a style nit. Before declaring a fu
170
172
  ### What's fine
171
173
 
172
174
  - Functions that read as a straight sequence of clear, already-named steps (each line is an English sentence).
173
- - Short functions (< ~10 lines) regardless of shape.
175
+ - Short functions (< ~10 lines) with a clear purpose and readable flow. Shortness does not exempt a function from the nesting-depth rule or other applicable checks.
174
176
  - Idiomatic framework patterns used clearly (a 30-line controller method obviously doing its job).
175
177
  - Guard clauses at the top — they *help* readability, they don't count against you.
176
178
 
@@ -228,6 +230,8 @@ Replacing a typed library error with a bare one throws away what the caller need
228
230
 
229
231
  These principles apply to every test file regardless of language or framework. The mechanical detection patterns (which mock library, which spy API) are in each `languages/*.md` Tests section.
230
232
 
233
+ Follow the testing-waiver policy in `overview.md` "Tests planned". An explicit waiver applies only to the named behavior or check, including its branch-test, branch-deletion, or resource-bound requirement. Record that scope as unverified. All checks outside the waiver and the quality rules for tests that are written or edited still apply.
234
+
231
235
  ### No self-mocking
232
236
 
233
237
  A unit test for class `Foo` must **not** stub, spy on, or replace methods on the instance of `Foo` being tested. Mocking injected collaborators (other services, repositories, adapters, ports, the clock) is fine and expected.
@@ -332,7 +336,7 @@ The failures the plan names are where the trace starts, not where it stops. Two
332
336
 
333
337
  A failure the test fakes cannot produce is not covered by a passing test. Name it as unverified rather than calling the path clean.
334
338
 
335
- **A finding names the input or state that produces the wrong result.** *"If the archive yields no entries, line 42 reports success and stores an empty result"* is a finding. Code that works as written is `clean`, however you would have written it differently: alternative structures, guards for states no caller can reach, extra tests for covered paths, and "consider extracting / renaming / memoizing" are improvements, not findings. A real failure that is small and cheap to fix is still a finding.
339
+ **An execution-error finding names the input or state that produces the wrong result.** *"If the archive yields no entries, line 42 reports success and stores an empty result"* is an execution-error finding. A design-violation finding instead identifies the applicable rule, the violating code, and its concrete design or maintenance consequence; it does not require a runtime failure. An alternative implementation or preferred name alone establishes neither kind. Guards for states no caller can reach and extra tests for already-covered behavior are optional improvements unless a separate applicable rule violation is demonstrated. A real failure that is small and cheap to fix is still a finding.
336
340
 
337
341
  ## Untrusted input and security
338
342
 
@@ -346,13 +350,13 @@ A size or count limit protects nothing if a costlier check still runs on the ove
346
350
 
347
351
  Input that reaches SQL, a shell command, a file path, a URL fetched server-side, a template, or a regular expression goes through a parameter, an allowlist, or an escaping API for that sink — never string concatenation or interpolation. A path from input is resolved and checked to stay under its root; a server-side fetch target is checked against an allowlist of hosts.
348
352
 
349
- ### Every new entry point checks who is calling and what they own
353
+ ### Every new entry point checks the caller's access rights
350
354
 
351
- A new route, handler, resolver, or job that reads or writes per-user data carries the project's authentication guard, and a lookup by an id from the input compares the caller's identity with the resource's owner before returning or changing it. An id the caller can choose is not proof of ownership.
355
+ A new route, handler, resolver, or job that reads or writes per-user data establishes the caller or execution identity through the project's authentication mechanism and checks permission for the requested operation before returning or changing the resource. Apply the project's access policy: ownership, shared access, tenant membership, or an authorized administrative role may establish permission. An id the caller can choose is not proof of access. An explicitly public operation follows the project's public-access policy rather than requiring a user identity.
352
356
 
353
- ### Secrets and personal data stay out of code, logs, and responses
357
+ ### Protect secrets and limit personal-data disclosure
354
358
 
355
- No secret, token, or credential in source or fixtures meant for production. Logs, error messages, and response bodies carry no secret, full token, password, or personal data — including inside an echoed request body or an upstream error passed through verbatim.
359
+ Keep real secrets, tokens, and credentials out of source and fixtures meant for production. Logs and error messages do not expose secrets, full tokens, passwords, or personal data through echoed request bodies or upstream errors passed through verbatim. A response may return personal data only when the operation's access policy authorizes the recipient and the fields are needed for its documented purpose. Credentials or tokens are returned only by operations explicitly designed to issue them to an authorized recipient; unrelated responses do not echo them.
356
360
 
357
361
  ### No execution of input
358
362
 
@@ -367,7 +371,7 @@ Good: `const LEGAL_AGE = 18; if (age > LEGAL_AGE)`
367
371
 
368
372
  ## Limit nesting depth
369
373
 
370
- Flatten with early returns / guard clauses. If you reach four nested blocks, refactor.
374
+ Count nested control-flow blocks within each function; the function, class, and module bodies do not count. At three levels, inspect readability rather than requiring a split solely for the count. At four or more, flatten with early returns or extract a named step before completion. Short functions follow the same threshold. Enforcement is the preflight self-check and code review.
371
375
 
372
376
  Bad:
373
377
  ```javascript
@@ -396,6 +400,8 @@ function process(user) {
396
400
 
397
401
  The code already says **what**. Comments record the hidden constraint, the bug being worked around, the surprising tradeoff. Never narrate the next line.
398
402
 
403
+ Interface documentation may describe caller-visible contracts that the signature cannot express: error versus ordinary negative results, missing-input behavior, side effects, or security constraints. This is not redundant narration of an implementation. Verify the documented behavior against implementations, callers, and relevant tests; do not infer it from the documentation alone. When the contract requires non-obvious work, explain its reason if that reason is established by evidence.
404
+
399
405
  Bad:
400
406
  ```javascript
401
407
  // increment i
@@ -5,9 +5,9 @@ These rules apply to every worker writing or editing project code (executor and
5
5
  ## Core principles
6
6
 
7
7
  1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
8
- 2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
9
- 3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
10
- 4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
8
+ 2. **KISS — simplest sufficient design** — Add reusable abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when current callers require them. For reuse-driven extraction, name the second caller now; otherwise inline. A local helper with one caller is appropriate when it names a distinct step in a mixed-level function or brings a body under the 50-line cap. Keep that helper local rather than introducing a reusable layer. Project-required architecture boundaries still apply. *Example violation: extracting a shared `formatUserName()` module used by exactly one call site, "in case we need it elsewhere".*
9
+ 3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier serves a current internal use, an established external contract, a runtime entry point, or an explicit user requirement. Cite the caller, contract, registration, or requirement; a hypothetical future consumer is not evidence.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
10
+ 4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; replace comments that merely narrate executable code with clearer names. Reserve implementation comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Interface documentation may state caller-visible contracts that names and types cannot express, such as error versus mismatch results or required work for missing inputs; verify those claims against implementations and callers. Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
11
11
  5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
12
12
  6. **Simplest conforming approach** — When choosing how to implement or fix something, pick the simplest, most direct solution path that still conforms to the project's architecture and established conventions. This is broader than KISS (#2): KISS bounds abstraction; this bounds the whole approach. Simplicity never licenses bending the structure or a convention — rule out non-conforming paths first, then take the plainest of what remains. Self-check: name the architecture/convention boundary the chosen approach respects; if a simpler path respects it too, take that one.
13
13
  7. **Fix at the cause, inside the change set** — An error surfacing during your work is fixed in the code that produced it — the files you are changing and the modules they directly call. A build/deploy/test failure is NOT a license to edit configuration or manifest files (`package.json`, lockfiles, `tsconfig`, CI config, build scripts) that were already passing before this change; a regression in something previously green almost always lives in the new code, not in long-stable config. If a config/manifest edit looks unavoidable, stop and confirm with the user first — state which file, why the current code can't carry the fix, and what was passing before. *Self-check: every file edited to resolve the error is in the current change set or a module it directly calls; no previously-passing config/manifest was touched to silence the failure without the user's explicit sign-off.* *Example violation: tests fail to import a new module, so you loosen `package.json`/`tsconfig` paths instead of fixing the import in the code you just wrote.*
@@ -50,10 +50,10 @@ If no Stage 1 language rule matches (an unlisted language), stop and ask the use
50
50
  - [ ] Language reference read for this turn.
51
51
  - [ ] `clean-code.md` principles applied: DRY, KISS, SOLID, YAGNI, meaningful naming (truthful + standalone + one identifier one meaning per file), single-purpose functions, plain-English summary test, 50-line cap, no magic numbers, shallow nesting, comments-explain-why.
52
52
  - [ ] **Mutation and state boundaries** (`clean-code.md`): decide on the direct identifier, not a status/flag proxy; capture before-state in one snapshot ahead of the mutating boundary; update only this work's owned fields on an existing row; re-read state before calling a zero-affected-rows write success or failure; put priority-between-inputs in a named domain function; keep error messages to what was observed.
53
- - [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; a new entry point carries the auth guard and an ownership check on input-chosen ids; no secrets or personal data in code, logs or responses; no eval or unsafe deserialization of input.
54
- - [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change.
53
+ - [ ] **Untrusted input and security** (`clean-code.md`), for every file that reads input from outside the process or acts on its behalf: a size/count bound rejects oversized input before any check or step that grows faster than the input; input reaches SQL, shell, paths, server-side fetches, templates and regexes only through parameters, allowlists or escaping; new entry points enforce the project's operation-specific access policy, including shared, administrative, and explicitly public access where applicable; protect secrets and limit personal-data disclosure as specified in `clean-code.md`, including authorized data responses and credential issuance; no eval or unsafe deserialization of input.
54
+ - [ ] Tests planned: which test(s) cover this change. New behaviour without a test is **incomplete** unless the user has explicitly opted out for this change and project rules permit it. Record the exact waived behavior or check and its unverified coverage. That waiver applies to the corresponding branch-test, branch-deletion, and resource-bound checks in this pack; it does not waive unrelated checks, weaken existing tests, or establish verified coverage.
55
55
  - [ ] **Existing tests surveyed (run this before planning any new test):** for every surface this change touches, `grep -rln` the candidate test files, list their test names, then READ the bodies of the ones that could overlap. A list of names does not tell you what a test asserts, and behavioural overlap does not collide on names — treat a clean name search as unfinished, not as a clear result. Record per surface: `extend <path:line>` / `new (nothing covers <behaviour>)` / `retire <path:line> (behaviour moved to <where>)`. A new test or test file with no survey line is unfinished work. The survey may change the design — moving the seam so existing tests keep passing beats adding parallel ones. Carry out a `retire` verdict in the same commit, on behavioural grounds only: the behaviour it asserted is gone, or a new test asserts it more strongly through the same seam. "Looks similar" / "touches the same file" is not grounds; without grounds the test stays, because a silent coverage loss costs more than one extra test.
56
- - [ ] **Testing discipline:** the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
56
+ - [ ] **Testing discipline:** apply the recorded testing waiver only to its stated scope. For tests written or edited, the test does not stub/spy methods on the SUT itself (collaborators are fine), and assertions are on outcomes (return values, state, events, boundary calls) — not on which internal helper was called. Each unwaived branch this change adds (`catch`, guard, early return, `else`) has a test that fails when the branch body is deleted; assertions land on the last write to a record, not an intermediate one; each test title names its unit and the single condition it isolates; no effect is claimed under its own mock; shared fixtures keep their ordinary defaults; the scenarios' setup values actually differ; every new test helper/mock is used by a test in this same change; no positional mock-argument access (`rg 'mock\.calls'`).
57
57
  - [ ] **Third-party wrapper (when this change wraps a library call):** the wrapper adds behaviour the library does not already provide — read the installed library source before keeping a recovery branch — no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
58
58
  - [ ] **Hexagonal overlay (if loaded):** no business logic inside any port body, adapter methods are I/O only (no post-fetch JS filtering on domain state, no `findValid*`/`findActive*` adapter names hiding rules), all domain objects declared under `domain/`, no changed domain file importing outward (ORM / framework / adapters / services), and a service dependency you add or modify goes through a port rather than a concrete adapter (advisory — record it with the port sketch; blocking when the project declares `architecture.style = hexagonal` in `.okstra/project.json` — fix before write, never record-and-pass).
59
59
  - [ ] **Existing code searched — by capability, not by name:** `grep` the identifier you are about to add AND the behaviour it performs (call sites, domain literals, error strings, the shape of the data it returns). A capability that already exists under a different name is the duplication this check exists to catch, and an identifier grep alone never finds it — name-level uniqueness is not evidence of absence. Record per new unit: the search terms used, the nearest existing implementation found, and the verdict `extend <path:line>` / `new (nothing covers <behaviour>)`. No survey line, no new unit.
@@ -83,11 +83,12 @@ def _keyed_values(text: str) -> dict[str, str]:
83
83
  values: dict[str, str] = {}
84
84
  if text == "-":
85
85
  return values
86
- for entry in text.split(";"):
86
+ # Reviewers write prose reasons; only a semicolon before the next `RULE=` separates assignments.
87
+ for entry in re.split(r";(?=\s*[A-Z][A-Z0-9]*=)", text):
87
88
  key, separator, value = entry.partition("=")
88
89
  key, value = key.strip(), value.strip()
89
90
  if not separator or not key or not value or key in values:
90
- raise ValueError("empty or duplicate rule assignment")
91
+ raise ValueError(f"empty or duplicate rule assignment: {entry.strip()!r}")
91
92
  values[key] = value
92
93
  return values
93
94
 
@@ -241,6 +241,12 @@ def validate_qa_commands(qa: object) -> list[str]:
241
241
 
242
242
  def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[str]:
243
243
  errors: list[str] = []
244
+ language = entry.get("language")
245
+ if "language" in entry and (
246
+ not isinstance(language, str)
247
+ or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._+#-]*", language)
248
+ ):
249
+ errors.append("language must be a non-empty language identifier")
244
250
  identifier = entry.get("id")
245
251
  if identifier is not None:
246
252
  if not isinstance(identifier, str) or not re.fullmatch(
@@ -25,7 +25,7 @@ from .verification_plan import (
25
25
  INPUT_ARTIFACT = "verification inputs"
26
26
  QA_INPUT_FIELDS = (
27
27
  "label", "cmd", "id", "procedurePath", "sourcePaths", "resourceKeys",
28
- "sourceBaselineDigest",
28
+ "sourceBaselineDigest", "language",
29
29
  )
30
30
 
31
31
 
@@ -63,11 +63,11 @@ Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`.
63
63
  | C-CR-0003 | - | T1=no state mutation; T2=non-test source; T3=non-test source; T4=no tests or new branches | - | src/orders/schema.py:1 |
64
64
  ```
65
65
 
66
- The example uses the base structural and state-and-tests catalogs. `Checked` means inspected and no actionable finding for those rules. A criterion includes all applicable subconditions in its references; one inapplicable subcondition does not make the entire criterion N/A. Explicitly list the IDs; `all`, counts and ID ranges are not verdicts. `N/A` assigns `rule=reason`; `Findings` assigns `rule=finding-id`. Separate assignments with semicolons and multiple finding IDs for one rule with commas. Use `-` for an empty field. Every expected rule appears exactly once across the three status fields. Never infer an omitted rule as clean.
66
+ The example uses the base structural and state-and-tests catalogs. `Checked` means inspected and no actionable finding for those rules. A criterion includes all applicable subconditions in its references; one inapplicable subcondition does not make the entire criterion N/A. Explicitly list the IDs; `all`, counts and ID ranges are not verdicts. `N/A` assigns `rule=reason`; `Findings` assigns `rule=finding-id`. Separate assignments with semicolons and multiple finding IDs for one rule with commas. Only a semicolon followed by the next `RULE=` starts a new assignment; a semicolon inside a reason stays part of that reason. Use `-` for an empty field. Every expected rule appears exactly once across the three status fields. Never infer an omitted rule as clean.
67
67
 
68
68
  Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by ` — ` and a short observation before any ` :: ` rule observations. Do not substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies that the file and line exist inside the project. Additional definitions and evidence remain in finding bodies.
69
69
 
70
- For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed workload and bound; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; use commas within an observation. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
70
+ For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed workload and bound; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; the same `RULE=` boundary applies, so a semicolon inside an observation stays part of it. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
71
71
 
72
72
  For example, `jobs/dispatch.py:18 :: G2=jobs/client.py:25 returned states preserve the dependency outcomes; G3=jobs/dispatch.py:9 validated batch limit bounds work before parsing; G5=jobs/dispatch.py:18 public typing and exception-chaining clauses hold` records three observations in one row. `checked`, `clean` and `no issues` alone are verdict labels, not observations. The checker rejects missing observations, notes for unchecked criteria, aliases and invalid source locations. It cannot establish whether a written observation is true.
73
73