From 9c31bd4f3b81ef34f9369aab0ed6d4c394257cd1 Mon Sep 17 00:00:00 2001 From: transitrix Date: Thu, 24 Sep 2026 18:24:53 +0400 Subject: [PATCH] docs: define versioned diagnostic identities and compatibility --- CHANGELOG.md | 8 ++ migrations/6.0-to-7.0/README.md | 97 +++++++++++++++++++ notations/CONTRACT.md | 29 ++++++ notations/elements/14-codex.md | 2 +- notations/elements/15-requirement.md | 11 +++ notations/elements/24-action.md | 42 +++++++- notations/views/diagrams/02-dgca.md | 5 + notations/views/diagrams/05-capability-map.md | 11 +++ notations/views/diagrams/09-products.md | 5 + notations/views/diagrams/10-applications.md | 11 +++ notations/views/diagrams/18-action-card.md | 5 + notations/views/reports/11-scenarios.md | 11 +++ notations/vocabulary.yaml | 40 ++++++++ scripts/check-notations.mjs | 6 +- scripts/check-notations.test.mjs | 15 +++ 15 files changed, 292 insertions(+), 6 deletions(-) create mode 100644 migrations/6.0-to-7.0/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 777f8b86..8676f438 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,14 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Version ## [Unreleased] +### Changed + +- Define versioned diagnostic identities for canonical ACTIONs, schema shapes, + supported view forms and assertion-gap reports. Preserve schedule-view codes + and retired CODEX identities. The new ACTION numeric lower bounds target the + next major release, **7.0.0**, with a [compatibility and migration contract](migrations/6.0-to-7.0/); + current release pins are unchanged. + ## [6.0.0] — Unreleased Bump category: **MAJOR**. Knowledge supersession now enforces errors on admitted diff --git a/migrations/6.0-to-7.0/README.md b/migrations/6.0-to-7.0/README.md new file mode 100644 index 00000000..3808fa22 --- /dev/null +++ b/migrations/6.0-to-7.0/README.md @@ -0,0 +1,97 @@ +# Diagnostic compatibility — methodology 6.0 → 7.0 + +This migration contract is for catalogue maintainers and validator implementers. +The target **7.0.0** is unreleased; this document does not change the current +release or any manifest pin. It defines the next-major boundary for the ACTION +numeric restrictions in [24-action.md](../../notations/elements/24-action.md) +§6–6.1. Adding diagnostic identities for already-invalid structures does not +itself change their validity. Rejecting previously accepted numbers does. + +## Compatibility and migration + +Through 6.x, ACTION `score` is an integer without a published lower bound; +cost and effort fields are numbers without a published lower bound. From 7.0.0, +negative `duration`, `duration_days`, `labor_cost`, `resources_cost`, `effort`, +and `score` produce `ACTION-011` errors. Zero remains valid, fractions remain +valid for the number fields, and fractional scores remain schema errors. +`sort` is not covered. Existing `duration_days` inputs remain supported; neither +that alias nor the accepted `Strategic Initiative` value is removed here. + +Before upgrading: + +1. Preserve the catalogue revision and original diagnostic output, including + the validator version. Check the six named fields on canonical and supported + inline ACTION records. Do not apply the check to every numeric field. +2. Review each negative value with its author. Correct genuine data errors from + evidence. If a negative score or cost intentionally conveys a signed measure, + preserve that meaning in an appropriately named `extensions` field and remove + or replace the canonical value only after review. Do not clamp, take absolute + values, or silently discard the source value. +3. Reconcile `duration_days` with `duration` in the declared schedule units. + Where both are supplied, preserve the original values in the review record, + choose the intended canonical duration, and remove the redundant alias only + after confirming equivalence. No automatic conversion is safe without units. +4. Validate against the target contract, review visible warnings and unsupported + forms, and update the manifest only when adopting a released 7.0.0 validator + and methodology. The per-file `spec_version` is informational, not a switch + enabling new errors in an older catalogue. + +## Historical emissions and normalisation + +The following profile covers **canonical ACTION emissions in Studio source +revision `4b39c67b790d92c542286934c5275d8e2f4d8f47`**, not +alternative meanings for the schedule-view codes. A historical record must +retain its original fields. Only a record with the named source revision and +canonical ACTION element context may acquire the indicated successor as an +additional normalised field. Other versions require their own explicit mapping. + +| Legacy canonical ACTION emission | Successor | Severity | Meaning | +|---|---|---|---| +| `ACT-005` | `ACTION-007` | warning | Unresolved parent or predecessor | +| `ACT-006` | `ACTION-008` | error | Predecessor cycle | +| `ACT-007` | `ACTION-009` | error | Self predecessor | +| `ACT-008` | `ACTION-010` | error | Invalid/reversed planned dates | +| `ACT-009` | `ACTION-011` | error | Negative value in the six named numeric fields | + +For a schedule view, `ACT-005` remains an **error** for an unresolved scoped GOAL; +`ACT-006` an invalid type filter; `ACT-007` invalid/duplicate working days; +`ACT-008` invalid holiday dates; and `ACT-009` the missing schedule-anchor +**warning**. Their complete table, including scheduling advisories, remains in +[07-action.md §6](../../notations/views/diagrams/07-action.md#6-validation-rules). +`ACTION-006` stays reserved and inactive. + +`CODEX-003` remains retired: its historical codex v0.1 meaning was typed-ID +resolution inside `applies_to`. It must not be globally aliased to `CODEX-002`. +A tool's incorrect use of it for missing jurisdiction/effective date is corrected +to `CODEX-002` only when the stored context identifies that missing-field check. + +## Positive and rejecting examples + +Each row is a mutation of an otherwise valid document in the named form; +“passes” means this rule does not fire, not that all catalogue checks pass. +Consumers can use these pairs to check diagnostic meaning independently of code +spelling. All errors must identify the affected field; warnings remain visible. + +| Rule | Positive example | Rejecting / advisory example | +|---|---|---| +| `ACTION-007` | Omitted root parent; predecessor resolves in catalogue | `parent: ACTION-MISSING-1` with no such ACTION → warning | +| `ACTION-008` | ACTION-1 precedes ACTION-2 only | ACTION-1 and ACTION-2 each name the other as predecessor → error | +| `ACTION-009` | ACTION-1 has `predecessors: []` | ACTION-1 has `predecessors: [ACTION-1]` → error | +| `ACTION-010` | Both dates `2026-09-24`; either date absent | `2026-02-30`, or end `2026-09-23` before start `2026-09-24` → error | +| `ACTION-011` | Each of the six fields separately set to `0`; number fields `0.5`; score `2` | Each field separately set to `-1` → error in 7.0.0; negative score/cost not newly rejected on 6.x pins | +| `SCHEMA_INVALID` | ACTION `score: 2`, `predecessors: []` | `score: 2.5`, `score: "2"`, or `predecessors: {}` → error with notation and field/type context | +| `CODEX-002` | REGULATION has jurisdiction and effective date | Omit either required field → error; never retired `CODEX-003` | +| `AC-001` | Object `action_card` with a nonempty `id` | Remove `action_card` or its `id` → error | +| `APP-002` | Inline `applications_catalogue` has required metadata and `applications: []` | Remove catalogue or replace applications array with an object → error | +| `CMAP-002` | Inline `capability_map` has required metadata and `capabilities: []` | Remove map or replace capabilities array with an object → error | +| `FGCA-004` | Inline nonempty factors/goals/actions; changes off; projection with valid `view_config` and no arrays | Inline `goals: []` → error; no inline-array requirement on a projection | +| `PMAP-002` | Inline catalogue with required metadata and `products: []`; valid projection without catalogue | Inline products collection is an object → error | +| `SCN-002` | Projection `view` with nonempty `id` and `name`, no inline scenarios | Omit `view.name` → error | +| `GAP-REQ-NO-ASSERT` | ASSERTION.about targets the REQUIREMENT | No targeting ASSERTION, even with a VERIFICATION → advisory warning, not noncompliance | + +The gap report may also observe absent targeting assertions for CONSTRAINTs, +but must state that ASSERTION does not support those targets in v1. It must not +require creating an invalid assertion. Shape rows describe only their owning +supported forms. Any unsupported form remains explicitly unvalidated, with +`NOTATION-SKIP-001` and strict-mode failure under CONTRACT §18; neither migration +nor code normalisation can turn it into a clean validation result. diff --git a/notations/CONTRACT.md b/notations/CONTRACT.md index 3878bfba..f21608b2 100644 --- a/notations/CONTRACT.md +++ b/notations/CONTRACT.md @@ -1325,3 +1325,32 @@ notation is unsupported by that tool version. Require the latter's path and Missing headers, parse failures, and read failures must remain visible in the accounting. These checks exercise the validator; a specification inventory alone is not evidence that the implementation conforms. + + +### 18.6 Shared schema diagnostics + +| Rule | Severity | Description | +|---|---|---| +| `SCHEMA_INVALID` | error | A parsed value violates the selected notation and supported form's schema shape or type: for example, a mapping is expected but a list is supplied, a collection member has the wrong type, or a required schema field is missing without a more specific rule. Include file path, notation, form, field path (with array index where relevant), expected shape/type and actual shape/type. | + +Use a specific published code when one covers the same defect; do not emit a +second generic finding for that defect. Independent findings remain visible. +An invalid YAML document is a parse failure, not a successful schema validation. +Select the document form before validating it: a projection does not inherit +legacy inline collections or headers. An unsupported form is unvalidated under +§18.2, with `NOTATION-SKIP-001`; it is never a clean result merely because the +validator cannot check it. A missing implementation does not redefine the schema. + +For example, `predecessors: {id: ACTION-1}` in an ACTION fails with field +`predecessors`, expected array, actual object; `predecessors: []` passes that +shape check. Neither example establishes the result of unrelated rules. + +### 18.7 Versioned diagnostic identity + +A stored diagnostic retains its original code, meaning, severity, notation, +form, methodology version and emitting tool version. A consumer may show a +normalised successor alongside it, but MUST NOT rewrite the original history. +An alias requires that complete scope: `ACT-005` alone is never an alias for +`ACTION-007`, because the schedule-view `ACT-005` remains a goal-resolution +error. See the [6.0 → 7.0 migration contract](../migrations/6.0-to-7.0/) for the +canonical-element corrections and their compatibility boundary. diff --git a/notations/elements/14-codex.md b/notations/elements/14-codex.md index d1362c68..abdd68e5 100644 --- a/notations/elements/14-codex.md +++ b/notations/elements/14-codex.md @@ -379,7 +379,7 @@ One artefact per file, named by its canonical ID. Examples: | `CODEX-005` | info | A `type: REGULATION` artefact does not declare `monitoring_needed:`. The field SHOULD be explicit so downstream consumers (and scanner agents) know whether the source is static or live — see §3.4. Info severity, not warning, because some legacy artefacts predate the field; new REGULATION artefacts SHOULD set it. | | `CODEX-006` | info | A `type: PRINCIPLE` artefact does not declare `established_by` (§4.1). Info severity — a record without one is admissible; the absence is a review finding for whoever admits it, not a defect the validator blocks on. | -Rule code `CODEX-003` was retired alongside `applies_to`; the code is reserved and is not reassigned. +Rule code `CODEX-003` was retired alongside `applies_to`; the code is reserved and is not reassigned. Missing `jurisdiction` or `effective_date` where §6 requires them is always `CODEX-002` (error), never `CODEX-003`. For example, a REGULATION with both fields passes this required-field check; omitting either fails. A PRINCIPLE does not require either field. --- diff --git a/notations/elements/15-requirement.md b/notations/elements/15-requirement.md index 843ece7a..6495a53b 100644 --- a/notations/elements/15-requirement.md +++ b/notations/elements/15-requirement.md @@ -316,6 +316,7 @@ A `REQUIREMENT` records *what the design must do*; a `NEED` ([`ELEMENT_PRIMITIVE | `REQ-005` | error | `level` is present but its value is not one of `stakeholder \| system \| software` (§2.5). | | `REQ-006` | error | `kind` is present but its value is not one of `functional \| quality` (§2.6). | | `REQ-SERVES-001` | error | `serves` is present but does not resolve to an admitted `NEED` in canon ([`ELEMENT_PRIMITIVES.md`](../ELEMENT_PRIMITIVES.md) §7.28). | +| `GAP-REQ-NO-ASSERT` | warning | In a gap report, a REQUIREMENT or CONSTRAINT has no targeting ASSERTION (`about` equals its ID) in the declared catalogue. Advisory absence of a recorded claim only: not missing VERIFICATION, not evidence of noncompliance. A targeting assertion suppresses this observation regardless of its claimed result; its own validity is checked separately. | | `REQ-COVERAGE-001` | warning | A REQUIREMENT has no ASSERTION targeting it — no file under `canon/assertions/` carries `about: `. Surfaces a compliance gap: the obligation exists in the model but the organisation makes no recorded claim about whether any subject satisfies it. The rule is `warning` rather than `error` because a newly admitted REQUIREMENT legitimately has no assertion yet. Cross-cutting — fires on the REQUIREMENT but is computed by scanning the assertions catalogue. | | `REQ-VERIF-COVERAGE-001` | warning | A REQUIREMENT has no admitted `VERIFICATION` targeting it — no file under `canon/verifications/` carries `verifies: ` ([27-verification.md](27-verification.md) §2). The engineering verification analogue of `REQ-COVERAGE-001`: the ASSERTION and VERIFICATION catalogues are independent ([27-verification.md](27-verification.md) §4), so a REQUIREMENT may carry compliance coverage with no verification evidence, or vice versa. `warning`, not `error`, for the same reason as `REQ-COVERAGE-001` — a newly admitted REQUIREMENT legitimately has no verification yet, and a purely compliance-origin REQUIREMENT may never accrue one. Cross-cutting — fires on the REQUIREMENT but is computed by scanning the verifications catalogue. | | `REQ-VERIF-COVERAGE-002` | warning | A REQUIREMENT has one or more admitted `VERIFICATION`s targeting it, but none has reached `outcome: pass` or `outcome: fail` — every verification against it is still `not_yet_run` or `inconclusive` ([27-verification.md](27-verification.md) §3). The trace link exists but has not closed. Distinct from, and mutually exclusive with, `REQ-VERIF-COVERAGE-001` by construction. Cross-cutting, same computation basis. | @@ -325,6 +326,16 @@ The shared lifecycle (`LIFECYCLE-001..004`, [CONTRACT.md](../CONTRACT.md) §7.3) --- + +`GAP-REQ-NO-ASSERT` is a report observation, not an expansion of ASSERTION's +permitted target types. CONSTRAINT coverage by ASSERTION remains unsupported +in v1; the report must disclose that limitation rather than require an invalid +assertion to silence the warning. REQUIREMENT assertion coverage and verification +coverage are independent. A REQUIREMENT with only a VERIFICATION still receives +this warning; one with a targeting ASSERTION does not. Preserve the existing +`REQ-COVERAGE-001` history and report context; do not globally rename it. + + ## 5. Evolution **Landed (2026-08-27, STANDARD codex TYPE):** diff --git a/notations/elements/24-action.md b/notations/elements/24-action.md index 43e79328..2b555533 100644 --- a/notations/elements/24-action.md +++ b/notations/elements/24-action.md @@ -1,8 +1,8 @@ --- title: "Action — implementation-layer work package" -version: "0.1" +version: "0.2" author: "Valerii Korobeinikov" -last_updated: "2026-06-25" +last_updated: "2026-09-24" status: "draft" --- @@ -179,11 +179,49 @@ One action per file, named by its canonical ID. Examples: `ACTION-PLATFORM-LAUNC | `ACTION-003` | warning | `parent` is present and both the parent and child have `type` values, but the child's level is not lower than the parent's (e.g. an `Initiative` whose `parent` is a `Project`). | | `ACTION-004` | error | `type` is not `Project` and the action is referenced as the project anchor in an Action Card ([views/18-action-card.md](../views/diagrams/18-action-card.md)) — action-card binding rule PC-002. | | `ACTION-005` | warning | Deprecated alias detected: `notation: activity`, `id` matching `ACTIVITY-…`, field `activity_type`, or path prefix `activities/`. Migrate to `action` / `ACTION-…` / `type` / `actions/`. | +| `ACTION-007` | warning | A non-null `parent` or an entry in `predecessors` does not resolve to an ACTION in the declared catalogue. Identify the field and unresolved ID. An omitted parent on a root is valid. | +| `ACTION-008` | error | The resolved ACTION predecessor graph contains a directed cycle. Report the participating IDs; do not treat an unresolved reference as a cycle. | +| `ACTION-009` | error | An ACTION lists its own ID in `predecessors`. This is also a one-node cycle; report the specific self-reference. | +| `ACTION-010` | error | A supplied, non-null `start_date` or `end_date` is not a valid calendar date in `YYYY-MM-DD` form, or `end_date` precedes `start_date`. Equal dates are valid. Lifecycle dates remain governed by the shared lifecycle rules. | +| `ACTION-011` | error | From methodology **7.0.0**, a supplied numeric value in exactly `duration`, `duration_days`, `labor_cost`, `resources_cost`, `effort`, or `score` is negative. Zero is valid. See §6.1 for aliases, types and compatibility; `sort` and extension values are excluded. | + The shared header (`HDR-001..004`, [CONTRACT.md](../CONTRACT.md) §2) and primitive-lifecycle (`LIFECYCLE-001..004`, [CONTRACT.md](../CONTRACT.md) §7.3) rules apply to ACTION files in addition to the ACTION-* rules above. --- +## 6.1 Numeric compatibility and diagnostic identity + +The nonnegative restriction is effective at methodology **7.0.0**, selected by +`transitrix.yaml`, not by this document's informational `spec_version`. +Versions through 6.x described costs and effort as numbers and `score` as an +integer without a lower bound. Rejecting an admitted negative value is therefore +a **breaking change**, even if a validator previously rejected it. The new code +is not permission to backport that restriction to a 6.x catalogue. + +- `duration`, `labor_cost`, `resources_cost`, and `effort` remain numbers; finite + fractions are allowed. Optional values may be absent. The documented + `duration: null` means unspecified, not zero. +- `duration_days` remains the supported legacy alias for a duration in days. + It has the same number/null semantics. `duration` takes precedence for + scheduling when both exist; `duration_days` is not reinterpreted in another + unit. Validate both supplied values; a negative alias cannot be hidden by a + positive canonical field. Migration must reconcile differing values/units. +- `score` remains an **integer**: `0` and `2` are valid, `2.5` is a type error + (`SCHEMA_INVALID`), and `-1` is `ACTION-011` from 7.0.0. `sort` remains an + integer with no new sign restriction. Cost, effort and score do not acquire + nullable semantics; a supplied null is a schema type error. +- Numeric strings, booleans, collections and non-finite numbers are type errors + (`SCHEMA_INVALID`), not negative-number findings. No coercion is implied. + +These element diagnostics apply to canonical ACTIONs and the corresponding +supported inline ACTION records. They never replace the schedule-view `ACT-*` +rules. `ACTION-006` remains reserved for the proposed Initiative alias warning; +this revision does not activate it. See the [diagnostic migration contract](../../migrations/6.0-to-7.0/) +for scoped historical mappings and positive/rejecting examples. + +--- + ## 7. Evolution - **Actions tree view** — a tree rendering of the `parent`-linked Initiative → Programme → Project → Task hierarchy, analogous to the Goals tree ([views/04-goals.md](../views/diagrams/04-goals.md)). Specified in `views/23-actions-tree.md`; Studio implementation tracked separately. diff --git a/notations/views/diagrams/02-dgca.md b/notations/views/diagrams/02-dgca.md index 8716a5ee..348f0e16 100644 --- a/notations/views/diagrams/02-dgca.md +++ b/notations/views/diagrams/02-dgca.md @@ -436,6 +436,7 @@ If the selected goal set happens to be closed, the caption is omitted (no empty | Rule | Severity | Description | |---|---|---| +| `FGCA-004` | error | Inline DGCA collection/header shape failure: `factors`, `goals`, or `actions` is absent, not an array, or empty; likewise `changes` unless `view_config.layers.changes: off`. This is the inline collection diagnostic corresponding to `DGCA-004`; emit one finding per defect. In projection form (only `view_config`, no element arrays), none of these arrays is required; validate the configuration object under `DGCA-004`. | | `DGCA-001` | error | document root is not an object, or `notation` field missing / does not equal `dgca`. | | `DGCA-002` | error | `id` missing or empty. | | `DGCA-003` | error | `name` missing or empty. | @@ -487,3 +488,7 @@ The rules below apply when validating the **canonical element files** (`canon/el - Canonical ID grammar and TYPE registry: [`IDS_AND_REFERENCES.md`](../../IDS_AND_REFERENCES.md) - Family selection across DGCA / Goals / Actions: `notations/README.md` § Family selection - Methodology, notation kit §2 (DGCA): `method/04-notations.md` + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/views/diagrams/05-capability-map.md b/notations/views/diagrams/05-capability-map.md index ebf526d3..2fd4b914 100644 --- a/notations/views/diagrams/05-capability-map.md +++ b/notations/views/diagrams/05-capability-map.md @@ -346,3 +346,14 @@ Migration: adopters with existing inline values move each value into a single-en - Methodology, notation kit §3 (capabilities and maturity): `method/04-notations.md` - DSM: `docs/docs/concepts/bcm-explained.md` — BCM concept and addressing rules - DSM assignment: `assignments/06_0_1_capabilities.md` — detailed requirements (addressing, validation, sets) + + +## Validation rules + +| Rule | Severity | Description | +|---|---|---| +| `CMAP-002` | error | In the supported inline map form, `capability_map` is absent or not an object, its required `id`, `name`, or `assessment_date` is absent or empty, or `capability_map.capabilities` is absent or not an array. An empty array is valid; item type/shape failures use `SCHEMA_INVALID`. | + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/views/diagrams/09-products.md b/notations/views/diagrams/09-products.md index 5f49eee4..10b503c8 100644 --- a/notations/views/diagrams/09-products.md +++ b/notations/views/diagrams/09-products.md @@ -270,6 +270,7 @@ view_config: | Rule | Severity | Description | |---|---|---| +| `PMAP-002` | error | In inline form, `products_catalogue` is absent or not an object, its required `id`, `name`, or `updated_at` is absent or empty, or `products_catalogue.products` is absent or not an array. An empty array is valid. In projection form, `products_catalogue` and its fields are not required; `view_config` must be an object and the projection rules below apply. | | `PROD-001` | error | `notation` missing or does not equal `products`. | | `PROD-002` | error | `id` missing or does not match `PROD-[-]`. | | `PROD-003` | error | `name` missing or empty. | @@ -307,3 +308,7 @@ Capabilities Map → what capabilities are required - Capabilities map: `notations/05-capability-map.md` - ID grammar and TYPE registry: `notations/IDS_AND_REFERENCES.md` - Methodology, notation kit: `method/04-notations.md` + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/views/diagrams/10-applications.md b/notations/views/diagrams/10-applications.md index d7569745..1a5cb924 100644 --- a/notations/views/diagrams/10-applications.md +++ b/notations/views/diagrams/10-applications.md @@ -260,3 +260,14 @@ ArchiMate → formal model of application layer elements and rel - ArchiMate vocabulary and ID grammar: `notations/IDS_AND_REFERENCES.md` - Products catalogue: `notations/09-products.md` - Methodology, notation kit: `method/04-notations.md` + + +## Validation rules + +| Rule | Severity | Description | +|---|---|---| +| `APP-002` | error | In the supported inline catalogue form, `applications_catalogue` is absent or not an object, its required `id`, `name`, or `updated_at` is absent or empty, or `applications_catalogue.applications` is absent or not an array. An empty array is valid; item type/shape failures use `SCHEMA_INVALID`. | + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/views/diagrams/18-action-card.md b/notations/views/diagrams/18-action-card.md index 1f9bd941..2955c7ae 100644 --- a/notations/views/diagrams/18-action-card.md +++ b/notations/views/diagrams/18-action-card.md @@ -205,6 +205,7 @@ A validator that cannot find the ID after exhausting both paths MUST raise `PC-0 | Rule | Severity | Description | |---|---|---| +| `AC-001` | error | The document root or `action_card` is not an object, or required `action_card.id` is absent or empty. Applies to the card form in §4.1; missing or unresolved `action_card.project` retains `PC-001`. | | `PC-001` | error | `action_card.project` is missing, malformed, or does not resolve to an admitted ACTION element after exhausting the canonical resolution scope (§6.1). The validator MUST search `canon/elements/**` recursively and then `views/actions/**` before raising this error. The diagnostic MUST disclose the paths searched (e.g. `canon/elements/`, `views/actions/`) and include an actionable hint naming the expected file pattern (`canon/elements/05_implementation/actions/ACTION--.yaml`). | | `PC-002` | error | The ACTION referenced by `action_card.project` carries an explicit non-project scale marker. In the element model all action scales share one ACTION TYPE (§1), so a missing/unmarked value is accepted; only an explicit non-project marker is flagged. The canonical project-identification rule is under revision (tracked separately). | | `PC-003` | error | A `milestone.delivers_changes[]` entry references a `CHANGE-…` that is not in the project Action's own `delivers_changes:`. The milestone cannot deliver a change the project isn't committed to. | @@ -249,3 +250,7 @@ Pending design work (separate epics): - Schedule milestones — distinct from action-card milestones: [07-action.md](./07-action.md) §5.9. - Motivation chain the card pulls: [02-dgca.md](./02-dgca.md) (DGCA). - Zone model, admission record, primitive lifecycle: [CONTRACT.md](../../CONTRACT.md) §5–7. + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/views/reports/11-scenarios.md b/notations/views/reports/11-scenarios.md index 59749bf6..98ecbef9 100644 --- a/notations/views/reports/11-scenarios.md +++ b/notations/views/reports/11-scenarios.md @@ -195,3 +195,14 @@ The example files under [`../examples/scenarios/`](../../examples/scenarios) (`o - Reconstruction invariant (why view documents are not content homes): [ELEMENT_PRIMITIVES.md](../../ELEMENT_PRIMITIVES.md) §1.1. - Named view-config convention (where this view's saved configs live, how they're named, listed, and re-run): [REPORT_VIEW_CONFIG.md](../REPORT_VIEW_CONFIG.md). - Architecture decision — reports are rendered from declarative view-configs, with a thin skill on top. + + +## Validation rules + +| Rule | Severity | Description | +|---|---|---| +| `SCN-002` | error | In the supported projection form, `view` is absent or not an object, or required `view.id` or `view.name` is absent or empty. Inline scenario collections are not required; scenario content is resolved from canon. Other configuration type failures use `SCHEMA_INVALID`. | + +Schema shape/type failures follow [CONTRACT.md](../../CONTRACT.md) §18.6. +Positive/rejecting cases and version compatibility are in the +[diagnostic migration contract](../../../migrations/6.0-to-7.0/). diff --git a/notations/vocabulary.yaml b/notations/vocabulary.yaml index 82c4fca6..460f6ebb 100644 --- a/notations/vocabulary.yaml +++ b/notations/vocabulary.yaml @@ -1648,3 +1648,43 @@ rule_codes: ZONE-003: severity: error spec: notations/CONTRACT.md + + ACTION-007: + severity: warning + spec: notations/elements/24-action.md + ACTION-008: + severity: error + spec: notations/elements/24-action.md + ACTION-009: + severity: error + spec: notations/elements/24-action.md + ACTION-010: + severity: error + spec: notations/elements/24-action.md + ACTION-011: + severity: error + spec: notations/elements/24-action.md + AC-001: + severity: error + spec: notations/views/diagrams/18-action-card.md + APP-002: + severity: error + spec: notations/views/diagrams/10-applications.md + CMAP-002: + severity: error + spec: notations/views/diagrams/05-capability-map.md + FGCA-004: + severity: error + spec: notations/views/diagrams/02-dgca.md + PMAP-002: + severity: error + spec: notations/views/diagrams/09-products.md + SCN-002: + severity: error + spec: notations/views/reports/11-scenarios.md + SCHEMA_INVALID: + severity: error + spec: notations/CONTRACT.md + GAP-REQ-NO-ASSERT: + severity: warning + spec: notations/elements/15-requirement.md diff --git a/scripts/check-notations.mjs b/scripts/check-notations.mjs index 1acee5f6..79b840d3 100644 --- a/scripts/check-notations.mjs +++ b/scripts/check-notations.mjs @@ -1111,7 +1111,7 @@ async function checkVocabularyValueVocabularies(failures) { // An expired `review_by` is itself a VOC4 failure, so a deferred item cannot // sit forever unnoticed. -const RULE_ROW_RE = /^\|\s*`([A-Z][A-Z0-9-]*)`\s*\|\s*(error|warning|info|deprecation)\s*\|/; +const RULE_ROW_RE = /^\|\s*`([A-Z][A-Z0-9_-]*)`\s*\|\s*(error|warning|info|deprecation)\s*\|/; // Pure — no I/O. Parses the `rule_codes:` block of vocabulary.yaml into // Map. Throws on a block that isn't found or doesn't @@ -1126,7 +1126,7 @@ export function parseVocabularyRuleCodes(text) { for (let i = startIdx + 1; i < lines.length; i++) { const line = lines[i]; if (/^\S/.test(line)) break; // dedent to column 0 — block ended - const codeM = line.match(/^ ([A-Z][A-Z0-9-]*):\s*$/); + const codeM = line.match(/^ ([A-Z][A-Z0-9_-]*):\s*$/); if (codeM) { current = { severity: null, spec: null }; out.set(codeM[1], current); @@ -1163,7 +1163,7 @@ export function parseVocabularyDeferredRuleCodes(text) { const line = lines[i]; if (line.length > 0 && !/^\s/.test(line)) break; // dedent to column 0 — block ended if (/^ \S/.test(line)) break; // dedent to "deferred:"'s own key level — rule_codes sub-block ended - const codeM = line.match(/^ ([A-Z][A-Z0-9-]*):\s*$/); + const codeM = line.match(/^ ([A-Z][A-Z0-9_-]*):\s*$/); if (codeM) { current = { reviewBy: null }; out.set(codeM[1], current); diff --git a/scripts/check-notations.test.mjs b/scripts/check-notations.test.mjs index 9aed8056..676f70b2 100644 --- a/scripts/check-notations.test.mjs +++ b/scripts/check-notations.test.mjs @@ -854,3 +854,18 @@ test('derivePresetMembershipFindings — negative: a module preset with no spec assert.equal(findings.length, 1); assert.match(findings[0], /no matching row/); }); + + +test('parseVocabularyRuleCodes — shared underscore diagnostic and advisory identity', () => { + const out = parseVocabularyRuleCodes(`rule_codes: + SCHEMA_INVALID: + severity: error + spec: notations/CONTRACT.md + GAP-REQ-NO-ASSERT: + severity: warning + spec: notations/elements/15-requirement.md +`); + assert.equal(out.get('SCHEMA_INVALID').severity, 'error'); + assert.equal(out.get('GAP-REQ-NO-ASSERT').severity, 'warning'); + assert.throws(() => parseVocabularyRuleCodes('rule_codes:\n schema_invalid:\n severity: error\n'), /unrecognised/); +});