Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion plan/Plan-001-semantic-data-schemas/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ hard failure — a skip that was hiding a broken locator lookup for `configurati
- [x] **TC-061** (FR-005-AC-2, FR-005-CON-2): table and `sysml` skeletons extract to identical normalized fields with the recorded forms.
- [x] **TC-062** (FR-005-AC-3): under the skeleton bundle index every skeleton extracts with zero errors and zero unresolved tokens.
- [x] **TC-063** (FR-005-AC-4): availability states per skeleton match the type's declared set.
- [x] **TC-064** (FR-005-AC-5): every negative fixture fails with its `expect:` code and its `detail:` substring, and the ten named cases exist.
- [x] **TC-064** (FR-005-AC-5): every negative fixture fails with its `expect:` code and its `detail:` substring, and the named cases exist.
- [x] **TC-068** (FR-005-AC-9): the sli/slo skeletons extract a unit-bearing field and the incident skeleton an identity and a `Timestamp` field.
- [x] **TC-070** (FR-005-CON-2): a Properties section holding both a table and a fence is refused at the second form.
- [x] **TC-071** (FR-005-AC-10): with the engine absent the semantic rows fail rather than skip, naming the provisioning path.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ that pin what the schemas and the engine refuse.

## Subtasks

- [x] **Typed `## Properties`.** The six types that require `fields` author one table with the header exactly `Field | Type | Multiplicity | Constraints`; `alert` and `runbook` carry no such section because their models forbid `fields`.
- [x] **Typed `## Properties`.** The six types that declare `fields` author one table with the header exactly `Field | Type | Multiplicity | Constraints`; `alert` and `runbook` carry no such section because their models forbid `fields`.
- [x] **The item rules, authored.** `sli` and `slo` each carry a `Type` cell with a trailing bracketed unit; `incident` carries one `identity` row and one `Timestamp` row; `configuration` and `migration` carry neither an identity nor a `Timestamp` row.
- [x] **`## Invariants`.** Every skeleton, one `### <clauseId>` per clause, each owning exactly one ```ocl``` fence.
- [x] **`## Operations`.** `runbook` and `deployment`, one `### <name>` per operation with an optional param table, a `Returns:` line and `Pre:`/`Post:` lines naming clauses declared in the same artifact.
Expand Down
79 changes: 79 additions & 0 deletions reviews/plat-277-soo-pr29-code-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
---
id: SR-102
title: "Code review — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)"
type: SpecReview
analysis: code-review
scope: "agent-ix/spec-objects-operational; typespec/main.tsp, spec_objects_operational/schemas/*.json, tests/test_role_schemas.py, tests/test_skeletons_semantic.py, tests/fixtures/negative/"
review_set: subset
---
# Code review — spec-objects-operational PR #29 (PLAT-277 F1)

## Summary

Ticket: PLAT-277 (finding F1). Diff `origin/main...adaac81`: eight TypeSpec
models drop `required` on `fields` / `clauses` / `operations`, the eight
emitted schemas lose their `required` arrays, one negative fixture is deleted,
and the role-schema tests flip their absent-key assertions and gain TC-092.

Verified independently:

- Every relaxed key is fed only by a `required: false` locator in
`spec_objects_operational/manifest.yaml` (properties/invariants/operations
for all eight types, lines 93-331). No locator or construct is touched.
- Item rules (`minItems`, `contains`, the occurrence `allOf`) are unchanged in
every schema; only the `required` arrays are removed.
- Regeneration: fetched the real pinned `@agent-ix/semantic-core@0.3.2` from
GitHub Packages (sha512 equals `package-lock.json` integrity), ran `npm ci`,
then `node scripts/generate-schemas.mjs --check` (27 match) and a full
regenerate with clean `git status`, on both the PR head and `origin/main`.
The coder's 0.3.3-relabelled emission is therefore confirmed byte-for-byte
against the real toolchain.
- Tests (quire 0.54.0 wheel, the only one reachable): PR head 145 passed /
6 failed; `origin/main` 144 passed / 6 failed. The 6 failing tests are the
same set with identical error lines on both trees (incident skeleton
`semantic.record-invalid`, alert-with-properties detail mismatch, unhashable
dict, empty extraction). Pre-existing engine skew, not introduced here.
- FCD construct consistency (filament-core-data
`crates/extraction-frontend/src/constructs.rs` `shape()`): the construct a
type lowers to comes from its manifest `object_types[].construct` block
(`bundle.rs` `archetype.construct()`). `spec_objects_operational/manifest.yaml`
declares no `construct:` for any type, on `origin/main`, on the PR head, or
on any remote branch. For all eight types (configuration, migration, sli,
slo, alert, runbook, incident, deployment), `shape()` therefore takes its
"object type with no declaration keeps the record" path. No
`min_clauses` / `identity_field_required` / `occurrence_field_required` /
`min_operations` rule applies, so the relaxation does not let `quire validate`
pass a document that FCD lowering then refuses. Consistent for every type,
no finding. If a construct is added later with one of those rules, the
matching locator must become `required: true` at the same time.
- With quire 0.54.0, `runbook-no-operations` still fails with its
`at operations: [] has less than 1 item` detail, and the deleted
`migration-no-invariants` fixture no longer yields `semantic.record-invalid`.

## Verdict

**CONDITIONAL** — no high finding. Two mediums (stale schema descriptions,
TC-092 asserting different cases than its ACs) and one low ceremony item.

## Findings

| ID | Severity | Summary | Refs | Escape Cause |
|---|---|---|---|---|
| FND-001 | medium | The TypeSpec doc comments, which the emitter copies into each shipped schema's `description`, still state the removed rule: Migration "`clauses` is required because…", Slo "`clauses` is required because…", Alert "`clauses` is required and carries the condition", Runbook "`operations` is required". The file header (line 12, "type-specific required keys") and line 20 / 256 / 455 ("the only model that requires…") also describe a required set that no longer exists. Shipped `Migration.json`, `Slo.json`, `Alert.json`, `Runbook.json` now contradict their own `required`-free bodies. | typespec/main.tsp:12, typespec/main.tsp:291, typespec/main.tsp:352, typespec/main.tsp:383, typespec/main.tsp:401 | wrong-requirement |
| FND-002 | medium | TC-092 does not assert what its two tagged ACs say. FR-006-AC-2 names "an `Incident` without an occurrence field", but the test sends `{"fields": [OCCURRENCE]}` — an occurrence field with no identity — so it fails on the identity rule, not the occurrence rule. FR-006-AC-1's "a record lacking `fields`, `clauses` or `operations` validates" half is never exercised in TC-092: it only checks `schema.get("required")` is falsy; the validating calls live in TC-041..049 tagged to FR-004. | tests/test_role_schemas.py:488-501 | correct-requirement-no-evidence |
| FND-003 | low | Ceremony: `assert len(fixtures) >= 9` is a file count. It does not prove the nine named cases exist (any nine files pass), and the real checks — `seen == expected_codes` and the unique-`detail` assertion — already carry the value. The PR re-tuned the number from 10 to 9 instead of removing it. | tests/test_skeletons_semantic.py:155 | wrong-requirement |

## Dispositions

Round 1, fix commit e2ca621. Re-verified against the real pinned
`@agent-ix/semantic-core@0.3.2`: `schemas-check` passes (27 match) and a
full regenerate leaves the tree clean. With quire 0.54.0, the PR head gives
153 passed / 6 failed and origin/main 144 / 6. The failing set is the same
6 tests, and their errors are identical apart from a one-line shift in
`test_skeletons_semantic.py`.

| FND | outcome | reason |
|---|---|---|
| FND-001 | fixed | Doc comments in `typespec/main.tsp` (header, L20, L256, Migration, Slo, Alert, Runbook, Incident) now say optional / "when present"; the six affected schema descriptions were regenerated by the emitter. |
| FND-002 | fixed | TC-092 now asserts `{}` validates for all eight types and uses an identity-only Incident record, which fails for the missing occurrence field. Eight parametrized `validate_document` cases tagged TC-092 / FR-006-AC-1 remove the optional section from each skeleton. |
| FND-003 | fixed | `assert len(fixtures) >= 9` deleted. |
42 changes: 42 additions & 0 deletions reviews/plat-277-soo-pr29-gap-analysis.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
id: SR-103
title: "Gap analysis — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)"
type: SpecReview
analysis: gap-analysis
scope: "agent-ix/spec-objects-operational; spec/functional/FR-006-optional-sections-optional-keys.md, spec/functional/FR-004-role-schemas.md, spec/tests.md, tests/test_role_schemas.py"
review_set: subset
---
# Gap analysis — spec-objects-operational PR #29 (PLAT-277 F1)

## Summary

Ticket: PLAT-277 (finding F1). Planless; plan completion: not assessed.
`quoin matrix --repo . --json` (quoin 0.29.1) on the PR head: FR-006-AC-1 and
FR-006-AC-2 are tagged (both by
`test_a_record_lacking_an_optional_section_key_validates_and_the_key_stays_checked`);
FR-004-AC-10 is tagged by the renamed empty-record test; FR-004-CON-2 is gone
from spec and matrix. FR-006-CON-1 is untagged. No production code in the
diff lacks an owning requirement: the TypeSpec change is owned by FR-006 and
the regenerated schemas by FR-002.

## Verdict

**CONDITIONAL** — one medium (an untagged constraint that `spec/tests.md`
reports as covered), one low (no document-level evidence for the F1 outcome).

## Findings

| ID | Severity | Summary | Refs | Escape Cause |
|---|---|---|---|---|
| FND-001 | medium | FR-006-CON-1 is `untagged` in the computed matrix, yet `spec/tests.md` maps it to TC-092 and marks FR-006 ✅. The constraint also restates FR-006-AC-1's first half ("no shipped object-type schema lists a required key"), so either tag it or delete the redundant constraint. | spec/functional/FR-006-optional-sections-optional-keys.md:51, spec/tests.md:75, spec/tests.md:146 | correct-requirement-no-evidence |
| FND-002 | low | F1 is a document-level defect (a document without the optional section was refused as `semantic.record-invalid`), but every FR-006 test runs on hand-built records. Nothing asserts that `validate_document` accepts a document lacking `## Invariants` / `## Operations` / `## Properties`. Reviewer checked by hand with quire 0.54.0: a runbook without `## Operations` and the deleted migration fixture produce no `semantic.record-invalid`. The deleted fixture could have become that positive check. | tests/fixtures/negative/migration-no-invariants.md, tests/test_role_schemas.py:488 | correct-requirement-no-evidence |

## Dispositions

Round 1, fix commit e2ca621. `quoin matrix` reports no untagged criterion:
FR-006-AC-1 is tagged by 2 binders and FR-006-AC-2 by 1.

| FND | outcome | reason |
|---|---|---|
| FND-001 | fixed | FR-006-CON-1 deleted from FR-006 and from both `spec/tests.md` rows. |
| FND-002 | fixed | `test_a_document_without_the_optional_section_is_not_record_invalid` runs `validate_document` on each of the eight skeletons with its optional section removed; all 8 pass with quire 0.54.0. |
53 changes: 53 additions & 0 deletions reviews/plat-277-soo-pr29-spec-review.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
---
id: SR-104
title: "Spec review — spec-objects-operational PR #29 (PLAT-277 F1 optional record keys)"
type: SpecReview
analysis: base
scope: "agent-ix/spec-objects-operational; spec/functional/FR-004-role-schemas.md, spec/functional/FR-005-executable-skeletons.md, spec/functional/FR-006-optional-sections-optional-keys.md, spec/tests.md, spec/spec.md"
review_set: subset
---
# Spec review — spec-objects-operational PR #29 (PLAT-277 F1)

## Summary

Ticket: PLAT-277 (finding F1). Examined new FR-006 (statement, Behavior,
FR-006-CON-1, FR-006-AC-1, FR-006-AC-2), TC-092, the FR-004 table rows,
FR-004-AC-2..5, AC-9, AC-10, the removal of FR-004-CON-2, the FR-005
negative-fixture list, FR-005-AC-5 and the tests.md rows TC-041..049, TC-064.

FR-006's statement is a sound, testable rule and matches the manifest: every
`properties` / `invariants` / `operations` locator for all eight types is
`required: false`. Its Behavior keeps item rules on present keys and leaves
locators unchanged, and the diff honours both. Removing FR-004-CON-2 is
correct; it is not left dangling in tests or matrix. `quire validate` on the
three FRs is clean; `spec/tests.md` fails only on the pre-existing
`Coverage Status` column name, unchanged by this PR.

## Verdict

**CONDITIONAL** — no high finding. Two mediums: FR-005 and the FR-004 table
still describe a required set that FR-006 abolished. One low wording drift.

## Findings

| ID | Severity | Summary | Refs | Escape Cause |
|---|---|---|---|---|
| FND-001 | medium | FR-005 still keys obligations on "types that require `fields`" / "require `operations`". Line 49 (which skeletons author `## Properties`), line 61 (which author `## Operations`) and FR-005-AC-4 ("`fields` `available` for the six types that require `fields`") now denote the empty set, so read literally they impose nothing. The PR updated the Invariants bullet (line 58) but not these. The same wording is in plan Task-005 line 46. Restate them as "the six types that admit `fields`" / "the types whose skeleton authors `operations`". | spec/functional/FR-005-executable-skeletons.md:49, spec/functional/FR-005-executable-skeletons.md:61, spec/functional/FR-005-executable-skeletons.md:91 | wrong-requirement |
| FND-002 | medium | In the FR-004 table, every row now reads Required keys "none (FR-006)", but `fields` / `clauses` / `operations` were not added to the Optional keys column. The table no longer lists the full key set each type admits; for example Deployment's row omits `fields` and `operations`. The prose still says "`Deployment` requires an identity field" (line 61) and "`Incident` is the only model that requires occurrence identity" (lines 65, 100). Under FR-006 those hold only when `fields` is present, and the spec does not say so. Two readers could disagree on whether an `Incident` with no `## Properties` must be refused. | spec/functional/FR-004-role-schemas.md:61, spec/functional/FR-004-role-schemas.md:65, spec/functional/FR-004-role-schemas.md:70-77, spec/functional/FR-004-role-schemas.md:100 | wrong-requirement |
| FND-003 | low | AC/TC wording drift. TC-041, TC-045, TC-046 and TC-047 (and their tests) now assert that an absent key validates, but FR-004-AC-2, AC-6, AC-7 and AC-8 do not say so. FR-004-AC-4 gained "a record without `fields` validates", but the TC-043 row did not. Plan.md line 157 still says "the ten named cases". | spec/functional/FR-004-role-schemas.md:122-128, spec/tests.md:118-122 | wrong-requirement |

## Dispositions

Round 1, fix commit e2ca621.

| FND | outcome | reason |
|---|---|---|
| FND-001 | still-open | FR-005 L49, FR-005-AC-4 and Task-005 L46 now say "declares `fields`", but FR-005 L61 still reads "Each skeleton whose type requires `operations` (`runbook`, `deployment`)", which is the empty set after FR-006. One-word fix: "declares `operations`". |
| FND-002 | fixed | The Optional keys column now lists `fields` / `clauses` / `operations` for every admitting type. The Item rules header now states that each rule applies only when its key is present, and FR-004-AC-8 states that an Incident without `fields` validates. |
| FND-003 | fixed | FR-004-AC-2, AC-6, AC-7 and AC-8 now state that an absent key validates, the TC-043 row gained "no `fields` validates", and plan.md drops "ten". |

Round 2, head d74cd82.

| FND | outcome | reason |
|---|---|---|
| FND-001 | fixed | FR-005 L61 now reads "Each skeleton whose type declares `operations`", and L52 now reads "`Incident` demands when `fields` is present". A scan of spec/, plan/ and typespec/ for "require(s) `fields`/`operations`/`clauses`", "types that require" and "whose type requires" finds nothing left. |
Loading
Loading