Define and validate core capability management stages and system coverage

.github/workflows/capability-contract-test.yml

@@ -0,0 +1,28 @@
+name: Capability core contract
+on:
+  pull_request:
+    paths:
+      - 'tools/lint.py'
+      - 'tools/tests/test_capability_contract.py'
+      - 'notations/schemas/**'
+      - 'notations/vocabulary.yaml'
+      - 'notations/views/diagrams/05-capability-map.md'
+      - 'notations/views/diagrams/10-applications.md'
+      - 'notations/examples/capability-map/**'
+      - 'tests/fixtures/capability-management-cycle/**'
+      - '.github/workflows/capability-contract-test.yml'
+  workflow_dispatch:
+permissions:
+  contents: read
+
+jobs:
+  contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: pip install pyyaml
+      - name: Check positive, negative and compatibility cases
+        run: python -m unittest discover -s tools/tests -p test_capability_contract.py

CONTRIBUTING.md

@@ -32,7 +32,7 @@ For each issue, include the file path or section reference, what you observed, a
 4. **Run the relevant validators locally, before opening the PR.** This repo's own gate is not a single command — `.validators/lint.py` is what an *adopter* repo runs against its `canon/`; this repo has no `canon/` of its own to validate. What CI actually runs here, by what you touched:
    - Any `notations/**` spec or example, or `transitrix/skills/onboard/templates/**` — `node scripts/check-notations.mjs` (mechanical invariants: example extensions, `notation:` headers, internal link resolution, version-pin consistency).
    - A single view notation file (`*.transitrix.yaml`) — `npx @transitrix/cli validate <file>` (`npx.cmd` on Windows PowerShell with a restricted execution policy).
-   - `tools/lint.py` itself — the encoding regression test in `.github/workflows/lint-encoding-test.yml`.
+   - `tools/lint.py` itself — the encoding regression test in `.github/workflows/lint-encoding-test.yml`; for capability-map contracts also run `python -m unittest discover -s tools/tests -p test_capability_contract.py` (schema/vocabulary parity, native fixtures and negative controls).
    - A Claude Code Skill under `transitrix/skills/<name>/` — see "Adding or changing a Skill" below.
    - Anything else — check `.github/workflows/` for a job whose `paths:` trigger matches the files you touched; most packages and skills carry their own targeted test workflow.
 5. **Update related docs.** If your change affects naming, layout, or rules, update the relevant file(s) under `method/` (naming: `method/03-modelling.md`; layout: `method/02-repository.md`), `method/00-glossary.md`, and `README.md` as needed.

guides/capability-map-compatibility.md

@@ -0,0 +1,45 @@
+# Capability-map compatibility checks
+
+This change corrects the core methodology. It adds optional native fields rather
+than requiring a renderer-specific extension. No existing methodology version
+pin changes until a release is prepared under CONTRACT §10.
+
+| Surface | Checked on 2026-10-23 | Limit |
+| --- | --- | --- |
+| Published additive JSON Schema | Draft-07 AJV with date-format assertions: nine fixture fragments accepted; four malformed controls refused | Validate the selected definition, not the full organisation envelope |
+| `tools/lint.py` | Positive/negative integration cases, legacy omission, published schema/vocabulary parity and existing capability examples | New fields, mapping references, local keys, dates and view selections; no history reconstruction or renderer geometry |
+| CLI `@transitrix/cli@2.11.0`, file scope | Native capability-map example returns zero errors and six `NOTATION-SKIP-001` warnings for unavailable maturity sidecars | The result says the file remains unvalidated; it is not full compatibility proof |
+| CLI negative control | The same file with `management_cycle_stage: ESG` and `view_config.display.depth: 99` still returns zero errors | Released CLI does not enforce these new core contracts; run the reference linter and do not silently treat this acceptance as validation |
+| DSM / Studio / standalone renderer | Not adopted by this source change | Separate consumer implementation and release evidence required |
+
+The reference validator preserves its existing single-file installation shape:
+
+```sh
+python tools/lint.py
+python -m unittest discover -s tools/tests -p test_capability_contract.py
+python tools/tests/test_lint_encoding.py
+```
+
+The complete synthetic source model lives in
+`tests/fixtures/capability-management-cycle/`. From that directory, run
+`python ../../../tools/lint.py`. The view example is checked against that fixture
+for drift. Past, present and future dates are accepted as selections; validating
+a date does not establish that evidence exists for it.
+
+The new validator rejects malformed **new** native fields. Existing source data
+without them remains valid; it is not classified from names, H/V orientation,
+parent stages, tags or maturity. Existing direct application coverage fields
+retain their previous validation boundary; new technical mappings always check
+canonical CAPABILITY targets before display filtering. Common free-form tags
+are not narrowed to ESG, MDM and Support.
+
+For proposals that placed these values under `extensions`, move
+`extensions.management_cycle_stage` to the defined native field explicitly.
+Reconcile conflicts before moving and retain the source history. Do not infer
+stages from a legacy renderer's `layer`: canonical architectural `layer` remains
+`business`. Native APPLICATION technical entry `key` projects to standalone
+renderer `id`; source and adapter endpoint conventions require explicit date
+conversion. This is a mapping boundary, not a new global technical TYPE.
+
+CLI/DSM/Studio adoption, whole-source temporal assessment, source-to-renderer
+projection and product release remain separate from this methodology PR.

guides/modelling-capabilities.md

@@ -1,7 +1,7 @@
 ---
 title: Modelling capabilities
 status: active
-last_reviewed: 2026-09-14
+last_reviewed: 2026-10-23
 audience: public
 license: MIT
 ---
@@ -31,3 +31,34 @@ attribute_versions:
 ```
 
 Before accepting the map, check IDs and references, admission and lifecycle, sidecar placement, and the evidence behind each assessment. Confirm the view displays the selected date's values. A rendered diagram alone does not establish model validity. Full sidecar rules and migration guidance are in the specification's attribute-history section.
+
+## Management cycle, tags and system coverage
+
+Use the capability element's optional `management_cycle_stage` to state its
+management role. The five definitions and order live in
+[capability-map §6a](../notations/views/diagrams/05-capability-map.md#6a-management-cycle-stage-and-tags).
+Strategic includes strategic planning; Planning is tactical/operational. Keep
+architectural `layer: business`. ESG, MDM and Support are ordinary tags, not stages
+or automatic horizontal capabilities. Classify explicitly and never inherit.
+
+Record a system's direct `capabilities` on its APPLICATION element. Where the
+source identifies technical abilities, record them as the application's native
+`technical_capabilities` inventory, with unique local keys and explicit targets,
+per [the applications contract](../notations/views/diagrams/10-applications.md#6a-technical-capabilities-and-business-coverage).
+Neither field belongs in an `extensions` bag or solely inside a view. Missing
+mapping means not specified. Do not infer mappings from containment or names.
+
+Choose stage grouping, tag filters, selected systems and date in the map's
+[declared view_config](../notations/views/diagrams/05-capability-map.md#163-view_config-defaults).
+Retain observation date, model-validity date, revision and target intent when
+comparing snapshots. A red geometric intersection is an investigation aid, not
+a finding of redundant functionality. Confirm source evidence before drawing
+that conclusion.
+
+These core-contract corrections are prepared for review. Current standalone
+rendering uses a documented JSON projection; this is not proof of native CLI,
+DSM or Studio adoption. Verify consumer support before migrating source files.
+
+The core additive schemas and whole-model checks are described in the
+[capability-map compatibility guide](capability-map-compatibility.md). They ship
+with the methodology source; released consumers require separate adoption.

notations/ELEMENT_PRIMITIVES.md

@@ -450,6 +450,7 @@ Inline shape (catalogue entry): [views/09-products.md](./views/diagrams/09-produ
 | `type` | yes | string | `application` \| `integration` \| `platform` \| `data_store`. |
 | `domain` | no | string | Business domain. |
 | `capabilities` | no | list | `CAPABILITY-…` IDs supported. |
+| `technical_capabilities` | no | list | Application-owned technical abilities and explicit business-capability mappings; field shape and containment boundary in [applications catalogue §6a](views/diagrams/10-applications.md#6a-technical-capabilities-and-business-coverage). |
 | `products` | no | list | `PRODUCT-…` IDs supported. |
 | `description` | recommended | string | Short description. |
 | `owner_role` | no | string | `ROLE-…`. **Time-varying** — sidecar ([CONTRACT.md](CONTRACT.md) §9), not inline. |

notations/examples/capability-map/management-cycle.capability-map.transitrix.yaml

@@ -0,0 +1,82 @@
+# Complete canonical sources: tests/fixtures/capability-management-cycle/
+notation: capability-map
+spec_version: '0.5'
+name: Management cycle and system coverage
+capability_map:
+  id: CAPABILITY_MAP-CYCLE-1
+  name: Management cycle and system coverage
+  assessment_date: '2026-10-23'
+  capabilities:
+  - id: CAPABILITY-V1
+    name: Order Management
+    type: domain
+    valid_from: '2026-01-01'
+    valid_to: null
+    children:
+    - id: CAPABILITY-V1.1
+      name: Order strategy
+      type: domain
+      valid_from: '2026-01-01'
+      valid_to: null
+      management_cycle_stage: Strategic
+    - id: CAPABILITY-V1.2
+      name: Order improvement learning
+      type: domain
+      valid_from: '2026-01-01'
+      valid_to: null
+      management_cycle_stage: Learning
+    - id: CAPABILITY-V1.3
+      name: Fulfilment planning
+      type: domain
+      valid_from: '2026-01-01'
+      valid_to: null
+      management_cycle_stage: Planning
+      children:
+      - id: CAPABILITY-V1.3.1
+        name: Pick and pack
+        type: domain
+        valid_from: '2026-01-01'
+        valid_to: null
+        management_cycle_stage: Execution
+  - id: CAPABILITY-H1
+    name: Order assurance
+    type: supporting
+    valid_from: '2026-01-01'
+    valid_to: null
+    management_cycle_stage: Assurance
+    tags:
+    - ESG
+    - MDM
+    - Support
+view_config:
+  valid_at: null
+  scenario: null
+  management_cycle:
+    group: true
+    order:
+    - Strategic
+    - Learning
+    - Planning
+    - Execution
+    - Assurance
+  tags:
+    filter:
+    - ESG
+    - MDM
+    - Support
+    show: true
+  display:
+    depth: 3
+    backlog: false
+    maturity: false
+    legend: true
+  systems:
+    labels: false
+    coverage: true
+    selected:
+    - APPLICATION-OMS-1
+    - APPLICATION-GOVERNANCE-1
+    highlight: null
+    shape: angled
+    rounded: false
+    overlap: true

notations/schemas/README.md

@@ -0,0 +1,22 @@
+# Capability-map additive schemas
+
+`capability-map-contract.schema.json` is JSON Schema draft-07. Validate a
+canonical CAPABILITY fragment against `#/$defs/capabilityFields`, a canonical
+APPLICATION (or applications catalogue entry) against `#/$defs/applicationFields`,
+and a capability-map `view_config` against `#/$defs/viewConfig`.
+
+These are additive field contracts. Element admission, primitive lifecycle,
+identity and the rest of each notation remain governed by their existing
+specifications. Additional source element fields are accepted; unknown keys in
+the newly defined view settings and technical inventory entries are rejected.
+Schema `default` annotations describe render defaults and do not mutate sources.
+Enable date format assertion in the schema consumer.
+
+The single-file `tools/lint.py` carries an equivalent embedded contract for
+onboarding compatibility. Regression tests require exact parity with this
+schema and the controlled vocabulary. The linter additionally checks local-key
+uniqueness, canonical mapping references, view references and explicit lifetime
+bounds. No external schema library is needed to run the reference linter.
+
+Use the complete synthetic model in `tests/fixtures/capability-management-cycle/`
+for integration checks. See capability-map §16.4 for consumer compatibility.