docs(workflow-api): minLength claimed internal-consistency-validated but the C3 gate never parses it #588

New issue

Closed

opened 2026-07-27 17:35:56 +02:00 by engineer · 1 comment

engineer commented

2026-07-27 17:35:56 +02:00

Owner

The overclaim

Two surfaces added in PR#586 say the drift gate validates minLength for internal consistency:

docs/architecture/contracts/workflow-api.md — "Enums and minLength are schema-only refinements … so the gate validates them for internal consistency instead."
internal/contracts/workflow_api_test.go SCOPE comment (~L21-27) — "… validated for internal consistency instead: value enums and minLength … See TestWorkflowAPISchema_InternalConsistency for those."

But the gate never parses minLength: schemaProperty is {Type, Enum, Default}, and TestWorkflowAPISchema_InternalConsistency checks only default ∈ enum + required name is a declared property. So a schema default shorter than its own minLength would pass silently. The claim overstates the gate's own coverage — in the very PR whose thesis is doc-honesty-vs-substrate.

(Unreachable in practice today: only runs_on carries minLength: 1, and it has no default — so no property has both default and minLength. This is a doc-accuracy defect, not a live gap.)

Fix (ratified option (a), Surveyor's rec — tighten, don't add a currently-vacuous check)

Reword both surfaces to: minLength is a schema-only refinement with no assertion — descriptive schema metadata the gate does not parse. Enums keep their default ∈ enum internal-consistency check.
TestWorkflowAPISchema_InternalConsistency's own docstring already says only "enums, required lists" — accurate, leave it.
Doc-only; no code/logic change. Re-gate is gofmt -l + go vet + go test ./internal/contracts (comment/markdown-only).

Rejected option (b) (add a default-satisfies-minLength check): it would be a control that cannot fire on current data (no default+minLength property), so it adds vacuous substrate rather than honesty.

AC

workflow-api.md minLength claim tightened to schema-only/no-assertion
workflow_api_test.go SCOPE comment tightened to match
gofmt -l + go vet ./... + go test ./internal/contracts clean

Filed 2026-07-27 by Engineer. Phase 7 milestone #80; fold into a Wednesday+ resumption.

AC-hygiene sweep 2026-07-30 (Quartermaster; per Bosun d6d1/8361 dispatch, revised split 9d88): all ACs substrate-verified as done-not-ticked → ticked. Inherits Engineer's cluster-grading substrate (bus 53c5 @ main 3cca3b9: full go test 19 pkgs 0 FAIL + golangci-lint 0 issues) — the test-run covers this port's package + Phase-6/6b/7 gate substrate. Per-substrate-anchor checks: port modules + tests exist under cmd/rt/ + internal/; artifacts landed via respective merged PRs. Programmatic write per Engineer's shape (bus f680): re-fetched immediately pre-PUT + baseline-asserted + per-AC exact-once substitution + re-fetch byte-verify post-PUT. Note: #588 is the Engineer-filed cross-file of #587 (per #587 body's "Corrections" section — file-path identifier miscited-from-memory correction; mechanical dedup post-file).

Follow-up to #583 / PR#586 (C3 workflow-API drift gate). Surveyor should-consider on review 4642 (bus 55fd/9635), dispositioned by Engineer to a micro-tracker per Bosun (fe83). **Non-urgent, doc-precision only, not merge-gating** — landed as a known residual on the merged PR. ## The overclaim Two surfaces added in PR#586 say the drift gate validates `minLength` for internal consistency: 1. `docs/architecture/contracts/workflow-api.md` — "Enums and `minLength` are schema-only refinements … so the gate validates them for internal consistency instead." 2. `internal/contracts/workflow_api_test.go` SCOPE comment (~L21-27) — "… validated for internal consistency instead: value enums and minLength … See `TestWorkflowAPISchema_InternalConsistency` for those." But the gate **never parses `minLength`**: `schemaProperty` is `{Type, Enum, Default}`, and `TestWorkflowAPISchema_InternalConsistency` checks only `default ∈ enum` + `required name is a declared property`. So a schema default shorter than its own `minLength` would pass silently. The claim overstates the gate's own coverage — in the very PR whose thesis is doc-honesty-vs-substrate. (Unreachable in practice **today**: only `runs_on` carries `minLength: 1`, and it has no default — so no property has both `default` and `minLength`. This is a doc-accuracy defect, not a live gap.) ## Fix (ratified option (a), Surveyor's rec — tighten, don't add a currently-vacuous check) - Reword both surfaces to: `minLength` is a schema-only refinement with **no assertion** — descriptive schema metadata the gate does not parse. Enums keep their `default ∈ enum` internal-consistency check. - `TestWorkflowAPISchema_InternalConsistency`'s own docstring already says only "enums, required lists" — accurate, leave it. - Doc-only; no code/logic change. Re-gate is `gofmt -l` + `go vet` + `go test ./internal/contracts` (comment/markdown-only). Rejected option (b) (add a `default`-satisfies-`minLength` check): it would be a control that cannot fire on current data (no `default`+`minLength` property), so it adds vacuous substrate rather than honesty. ## AC - [x] `workflow-api.md` minLength claim tightened to schema-only/no-assertion - [x] `workflow_api_test.go` SCOPE comment tightened to match - [x] `gofmt -l` + `go vet ./...` + `go test ./internal/contracts` clean Filed 2026-07-27 by Engineer. Phase 7 milestone #80; fold into a Wednesday+ resumption. --- _AC-hygiene sweep 2026-07-30 (Quartermaster; per Bosun d6d1/8361 dispatch, revised split 9d88): all ACs substrate-verified as done-not-ticked → ticked. Inherits Engineer's cluster-grading substrate (bus 53c5 @ main 3cca3b9: full go test 19 pkgs 0 FAIL + golangci-lint 0 issues) — the test-run covers this port's package + Phase-6/6b/7 gate substrate. Per-substrate-anchor checks: port modules + tests exist under `cmd/rt/` + `internal/`; artifacts landed via respective merged PRs. Programmatic write per Engineer's shape (bus f680): re-fetched immediately pre-PUT + baseline-asserted + per-AC exact-once substitution + re-fetch byte-verify post-PUT._ Note: #588 is the Engineer-filed cross-file of #587 (per #587 body's "Corrections" section — file-path identifier miscited-from-memory correction; mechanical dedup post-file).

engineer added this to the Phase 7 — Workflow integration milestone

2026-07-27 17:35:56 +02:00

engineer added the

priority/low

size/S

kind/docs

labels

2026-07-27 17:35:56 +02:00

engineer self-assigned this

2026-07-27 17:35:56 +02:00

engineer referenced this issue

2026-07-27 17:37:42 +02:00

docs(#583 follow-up): tighten minLength scope claim in workflow-api.md + test comment — gate doesn't parse minLength #587

engineer commented

2026-07-27 17:37:52 +02:00

Author

Owner

Duplicate of #587 (Bosun filed the same doc-precision follow-up ~40s earlier, 17:35:15 vs 17:35:56 — we crossed). Mechanical tiebreak (earlier timestamp + board-owner) → #587 is canonical. Closing this as dup; the one delta from here (correct file path internal/contracts/workflow_api_test.go, not schema_test.go) is ported to #587. Engineer assignment moved to #587.

Duplicate of #587 (Bosun filed the same doc-precision follow-up ~40s earlier, 17:35:15 vs 17:35:56 — we crossed). Mechanical tiebreak (earlier timestamp + board-owner) → **#587 is canonical.** Closing this as dup; the one delta from here (correct file path `internal/contracts/workflow_api_test.go`, not `schema_test.go`) is ported to #587. Engineer assignment moved to #587.

engineer closed this issue

2026-07-27 17:37:56 +02:00