@jasonbelmonti/markdown-engine 2.0.0 → 3.0.0

package/docs/contracts/api.md

@@ -1,10 +1,10 @@
 # Public API Contract
 
-Status: package 2.0.0, document contract 1.0.0
-Last updated: 2026-05-13
+Status: package 3.0.0, document contract 1.0.0
+Last updated: 2026-06-05
 
 This document defines the public `@jasonbelmonti/markdown-engine` package
-contract for the `2.0.0` package release. The serialized rich IR document
+contract for the `3.0.0` package release. The serialized rich IR document
 contract remains `documentVersion: "1.0.0"`. The stable public surface is the
 package export from `@jasonbelmonti/markdown-engine`, not internal adapter
 modules or raw parser output. The 1.0 rich IR design is tracked in
@@ -72,7 +72,7 @@ normalize(parsed: ParsedMarkdown, options?: NormalizeOptions): NormalizeResult
 ```
 
 `NormalizeOptions.documentVersion` selects the document contract version.
-Package 2.0 defaults omitted `documentVersion` to the rich IR
+Package 3.0 keeps omitted `documentVersion` defaulting to the rich IR
 `"1.0.0"` contract. The retained `0.1.0`-compatible path is `"0.0.0"` and must
 be requested explicitly.
 
@@ -227,7 +227,9 @@ validateWithProfile(
 
 `parseValidationProfile` accepts YAML text or JSON-safe profile objects. The
 top-level profile keys are `syntaxVersion`, `documentVersion`, and `rules`.
-`syntaxVersion` must be `"markdown-engine.validation@v1"`.
+`syntaxVersion` must be `"markdown-engine.validation@v1"` or
+`"markdown-engine.validation@v2"`; v2 admission is limited to the existing flat
+rule shape.
 `documentVersion` is optional; when provided it must be `"0.0.0"` or
 `"1.0.0"`. The parser preserves omission and does not inject a default into
 the parsed profile.
@@ -309,7 +311,7 @@ code nodes with `kind: "fenced"`. Raw parser node objects are not public.
 
 ## 1.0 Contract
 
-The final 1.0 document contract is selected by default in package 2.0, remains
+The final 1.0 document contract is selected by default in package 3.0, remains
 available explicitly as `documentVersion: "1.0.0"`, and is checked with
 `compatibilityMode: "default"`.
 
@@ -536,8 +538,8 @@ serialization behavior.
 
 ### Compatibility And Migration
 
-The current package version is `2.0.0`. The serialized document contract
-version remains `"1.0.0"`. Package 2.0 selects that rich IR contract by
+The current package version is `3.0.0`. The serialized document contract
+version remains `"1.0.0"`. Package 3.0 selects that rich IR contract by
 default for `normalize(parsed)`; callers may also request it explicitly with
 `normalize(..., { documentVersion: "1.0.0" })`. Serialization gates check it
 with `compatibilityMode: "default"`.
@@ -550,7 +552,7 @@ compatibility from the absence of rich IR fields.
 Migration from the `0.1.0` document shape, or from pre-2.0 API callers that
 depended on implicit legacy normalization, requires consumers to:
 
-- use package 2.0's default `normalize(parsed)` rich IR output or request
+- use package 3.0's default `normalize(parsed)` rich IR output or request
   `documentVersion: "1.0.0"` during normalization;
 - read `target`, `sections`, `textSpans`, `tables`, `lists`, `links`,
   `linkReferences`, and `source` from the normalized document instead of
@@ -609,10 +611,10 @@ exit with code `2`. Validation success exits with code `0`; validation or
 normalization error diagnostics exit with code `1`. Validation JSON includes
 `profile`, `ruleResults`, `diagnostics`, and `evidence`.
 
-Semver classification: package 2.0 makes the rich IR contract the default API
-normalization output while retaining the document contract version
-`"1.0.0"`. This is breaking for API consumers that call `normalize(parsed)` and
-expect the legacy `0.0.0` document shape. Migration is to either consume the
+Semver classification: package 3.0 keeps the rich IR contract as the default
+API normalization output while retaining the document contract version
+`"1.0.0"`. The 2.0 migration remains applicable for API consumers that call
+`normalize(parsed)` and expect the legacy `0.0.0` document shape: consume the
 rich IR fields or pin `documentVersion: "0.0.0"` until the downstream consumer
 is ready. CLI consumers can still pin `--document-version 0.0.0` for explicit
 legacy output.
@@ -651,8 +653,10 @@ The `0.1.0` contract was review-gated by WP-2, MS-2, and MS-3 before first
 publication. From the published `0.1.0` baseline forward, changes to public API
 signatures, result fields, diagnostic schema, source-location semantics,
 validation config semantics, or serialized output shape require
-semantic-version classification. The planned 1.0 rich IR contract will update
-this API contract before 1.0 release approval.
+semantic-version classification. The 1.0 rich IR document contract is now the
+retained default document contract for package 3.0, and the explicit legacy
+`0.0.0` path remains the compatibility boundary for consumers that still need
+the first package-line output shape.
 
 The `@jasonbelmonti/markdown-engine` package boundary remains limited to
 parsing, normalization, deterministic validation, diagnostics, and

package/docs/contracts/declarative-validation.md

@@ -1,19 +1,36 @@
 # Declarative Validation Contract
 
-Status: package 2.0.0, v1 profile syntax, document contract 1.0.0
-Last updated: 2026-05-14
+Status: package 3.0.0, v1 profile syntax with v2 Conditional V2, document contract 1.0.0
+Last updated: 2026-06-05
+Current v2 surface: flat-rule result/evidence shell, ID count-bound schema and
+runtime evaluator contract, plus `tableColumnCoverage` schema, compiled-plan,
+and runtime evaluator contract, grouped rule runtime contract, and rule-level
+`when` schema, matcher, public skipped-rule result, skipped counts, and evidence
+cloning contract.
 
 This document defines the public declarative validation contract for
 `@jasonbelmonti/markdown-engine`. The stable surface is the package-root API,
-the v1 profile syntax, the CLI validation command, diagnostic codes, serialized
-result shapes, and evidence fields. Internal parser output, compiled rule-plan
-records, selector target records, and evaluator implementation modules are not
-public contracts.
-
-Package 2.0 does not introduce `documentVersion: "2.0.0"` or
-`markdown-engine.validation@v2`. Declarative validation continues to use the v1
-profile syntax against the existing `documentVersion: "1.0.0"` rich IR
-document contract.
+the v1 profile syntax, the admitted v2 profile syntax and runtime subset, the
+CLI validation command, diagnostic codes, serialized result shapes, and evidence
+fields. Internal parser output, compiled rule-plan records, selector target
+records, and evaluator implementation modules are not public contracts.
+
+Package 3.0 does not introduce `documentVersion: "3.0.0"` or CLI JSON
+discrimination.
+Declarative validation continues to use the existing `documentVersion: "1.0.0"`
+rich IR document contract, while the profile admission path recognizes
+`markdown-engine.validation@v2` for the same flat rule shape with `id`, optional
+`severity`, `select`, and `assert`; non-recursive `anyOf` and `allOf`; and
+optional rule-level `when`. The admitted v2 path exposes the result and evidence
+shell needed to distinguish assertion, grouped, and skipped evaluation output
+from v1 output, plus the ID count-bound schema, compiled-plan, and runtime
+evaluator contract; the `tableColumnCoverage` schema, compiled-plan, and
+runtime evaluator contract; and the `when` schema plus private compiled-plan and
+matcher contract. Matched applicability continues into normal rule evaluation.
+Non-matching applicability returns a public skipped rule result with
+`status: "skipped"`, `passed: true`, `evaluation.kind: "skipped"`,
+`reason: "whenNotMatched"`, `skippedRuleCount`, no top-level diagnostics, and a
+nested `when` applicability result.
 
 ## 1.0 Contract
 
@@ -53,8 +70,25 @@ syntaxVersion: markdown-engine.validation@v1
 `syntaxVersion` is required. Missing or unsupported values emit
 `profile.config.unsupportedSyntaxVersion`.
 
-The v1 vocabulary is closed. Unknown profile keys, rule keys, selector keys,
-known assertion keys, and nested assertion keys emit
+The v2 syntax is admitted as an additive profile syntax:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+```
+
+This release recognizes v2 as a distinct syntax version at profile admission,
+admits ID count bounds at the schema, compiled-plan, and runtime evaluator
+layers, admits `tableColumnCoverage` at the schema, internal compiled-plan, and
+runtime evaluator layers, admits non-recursive grouped rules at the schema,
+compiled-plan, and runtime evaluator layers, and admits optional rule-level
+`when` at the schema, internal compiled-plan, and matcher layers. Matching
+`when` rules continue through normal flat or grouped evaluation and do not add a
+public `when` field to the evaluated rule result. Non-matching `when` rules are
+not evaluated; they return the public skipped-rule result shape, increment
+`skippedRuleCount`, and leave `evaluatedRuleCount` unchanged.
+
+The admitted v1/v2 flat vocabulary is closed. Unknown profile keys, rule keys,
+selector keys, known assertion keys, and nested assertion keys emit
 `profile.config.unsupportedKey` unless the contract assigns a more specific
 compile diagnostic for an unsupported selector target or unsupported assertion
 member.
@@ -113,15 +147,52 @@ results, and does not evaluate rules.
 The top-level profile shape is:
 
 ```ts
+type ValidationProfileSyntaxVersion =
+  | "markdown-engine.validation@v1"
+  | "markdown-engine.validation@v2";
+
 interface ValidationProfile {
-  syntaxVersion: "markdown-engine.validation@v1";
+  syntaxVersion: ValidationProfileSyntaxVersion;
   documentVersion?: EngineDocumentVersion;
   rules: readonly DeclarativeValidationRule[];
 }
 
-interface DeclarativeValidationRule {
+type DeclarativeValidationRule =
+  | DeclarativeValidationFlatRule
+  | DeclarativeValidationGroupRule;
+
+interface DeclarativeValidationRuleFields {
   id: string;
   severity?: "error" | "warning" | "info";
+  when?: DeclarativeValidationApplicability;
+}
+
+interface DeclarativeValidationFlatRule extends DeclarativeValidationRuleFields {
+  select: DeclarativeSelector;
+  assert: DeclarativeAssertion;
+}
+
+interface DeclarativeValidationApplicability {
+  select: DeclarativeSelector;
+  assert: DeclarativeAssertion;
+}
+
+type DeclarativeValidationGroupRule =
+  | DeclarativeValidationAnyOfRule
+  | DeclarativeValidationAllOfRule;
+
+interface DeclarativeValidationAnyOfRule
+  extends DeclarativeValidationRuleFields {
+  anyOf: readonly DeclarativeValidationBranch[];
+}
+
+interface DeclarativeValidationAllOfRule
+  extends DeclarativeValidationRuleFields {
+  allOf: readonly DeclarativeValidationBranch[];
+}
+
+interface DeclarativeValidationBranch {
+  label?: string;
   select: DeclarativeSelector;
   assert: DeclarativeAssertion;
 }
@@ -134,6 +205,11 @@ evidence identify output by `ruleId`.
 Rule `severity` defaults to `error` when omitted. Unsupported severity values
 emit `profile.config.invalidShape`.
 
+Rule-level `when` is allowed only on v2 rules. Branch-level `when` remains
+unsupported. V1 profiles preserve the original flat rule authoring contract;
+grouped `anyOf` / `allOf`, ID count bounds, `tableColumnCoverage`, and
+rule-level `when` are v2 additions.
+
 Profile values must be JSON-safe data properties after YAML materialization.
 Functions, accessors, proxies, cyclic structures, sparse arrays, `undefined`
 payloads in required positions, non-finite numbers, and `__proto__` properties
@@ -203,11 +279,27 @@ interface DeclarativeAssertion {
     prefix?: string;
     unique?: boolean;
     caseSensitive?: boolean;
+    minCount?: number;
+    maxCount?: number;
   };
   references?: {
     idsFrom: { section?: string; column?: string; prefix?: string };
     mustAppearIn: readonly string[];
   };
+  tableColumnCoverage?: {
+    source: {
+      section: string;
+      column: string;
+      prefix?: string;
+      caseSensitive?: boolean;
+    };
+    target: {
+      section: string;
+      tableHeader?: readonly string[];
+      column: string;
+    };
+    require: "everySourceId";
+  };
   text?: {
     contains?: string;
     excludes?: readonly string[];
@@ -242,6 +334,7 @@ Selector/assertion compatibility is part of the public contract:
 | `tableColumnsRequired` | `table` |
 | `ids` | all supported selector targets |
 | `references` | `document` |
+| `tableColumnCoverage` | `document` |
 | `text` | all supported selector targets |
 | `textOccurrenceCount` | all supported selector targets |
 | `textLength` | all supported selector targets |
@@ -258,9 +351,32 @@ resolves zero targets.
 headings appear as an ordered subsequence in the normalized section tree
 flattened in source order.
 
-`ids.unique` must be `true`; `prefix` and `caseSensitive` are modifiers, not
-standalone predicates. `caseSensitive` defaults to `true`. ID tokens use the
+For v1 profiles, `ids.unique` must be `true`. For v2 profiles, `ids.unique`
+must be `true` when provided and may be omitted when `ids.minCount` or
+`ids.maxCount` provides the predicate. `prefix` and `caseSensitive` are modifiers,
+not standalone predicates. `caseSensitive` defaults to `true`. ID tokens use the
 documented token grammar `[A-Za-z][A-Za-z0-9]*-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*`.
+For v2 profiles, `ids.minCount` and `ids.maxCount` are admitted as non-negative
+integer schema and compiled-plan fields. When both are present, `minCount` must
+be less than or equal to `maxCount`. Runtime count evaluation uses unique
+comparison values after prefix filtering and duplicate occurrence de-duplication.
+Failed lower and upper bounds emit `profile.validation.idCountTooLow` and
+`profile.validation.idCountTooHigh`.
+
+For v2 profiles, `tableColumnCoverage` is admitted as a flat-rule schema and
+internal compiled-plan assertion. It is compatible only with a `document`
+selector because the assertion owns its source and target table-column inputs.
+`source.section`, `source.column`, `target.section`, and `target.column` are
+required non-empty strings. `source.prefix` is optional and must be non-empty
+when provided. `source.caseSensitive` is optional and defaults to `true` in the
+compiled plan. `target.tableHeader` is an optional non-empty string array.
+`require` must be exactly `"everySourceId"`. Runtime evaluation extracts unique
+source IDs from `source.section` and `source.column`, applies `source.prefix`
+and `source.caseSensitive`, and requires every source ID comparison value to
+appear in the configured target table column. IDs appearing elsewhere in the
+target section do not satisfy coverage. Missing target sections, missing target
+columns, and missing target-column IDs emit deterministic validation diagnostics
+source-grounded to the source ID when source evidence is available.
 
 `text` must include `contains` or a non-empty `excludes` array.
 `textOccurrenceCount.count` is a finite number and counts non-overlapping
@@ -284,11 +400,17 @@ error severity. Validation diagnostics use the rule severity. Source ranges are
 included when a selected target has source evidence; locations are omitted
 rather than fabricated when unavailable.
 
+Rule-level `when` uses the existing validation diagnostic codes. When
+applicability does not match, those diagnostics are cloned into
+`ruleResults[].when.diagnostics`; they are not promoted into top-level
+`diagnostics`, so a skipped rule with a nested error-severity applicability
+diagnostic can still leave the aggregate `valid` value `true`.
+
 | Code | Severity source | Emitted when |
 | --- | --- | --- |
 | `profile.config.invalidYaml` | `error` | YAML text cannot be parsed or materialized as JSON-safe profile data. |
 | `profile.config.yamlWarning` | `warning` | YAML materialization produces a non-fatal parser warning. |
-| `profile.config.unsupportedSyntaxVersion` | `error` | `syntaxVersion` is missing or is not `markdown-engine.validation@v1`. |
+| `profile.config.unsupportedSyntaxVersion` | `error` | `syntaxVersion` is missing or is not `markdown-engine.validation@v1` or `markdown-engine.validation@v2`. |
 | `profile.config.invalidShape` | `error` | Required fields are missing, fields have wrong types, arrays or strings are empty, rule IDs duplicate, scalar values are invalid, table predicates are ineffective, or assertion payloads contain no effective predicate. |
 | `profile.config.documentVersionMismatch` | `error` | Resolved profile `documentVersion` differs from the supplied `EngineDocument.version`. |
 | `profile.config.unsupportedKey` | `error` | A closed profile, rule, selector, known assertion object, nested object, regex-like key, executable-like key, or direct typed profile object contains unsupported syntax. |
@@ -299,12 +421,17 @@ rather than fabricated when unavailable.
 | `profile.validation.assertionFailed` | Rule severity | A supported assertion evaluates and fails without a more specific diagnostic code, including missing table columns, exact occurrence-count mismatches, and text-length bound failures. |
 | `profile.validation.duplicateId` | Rule severity | An `ids.unique` assertion finds repeated IDs. |
 | `profile.validation.frontmatterFieldMissing` | Rule severity | A required frontmatter field is absent. |
+| `profile.validation.idCountTooHigh` | Rule severity | Unique ID count after filtering is higher than `ids.maxCount`. |
+| `profile.validation.idCountTooLow` | Rule severity | Unique ID count after filtering is lower than `ids.minCount`. |
 | `profile.validation.referenceMissing` | Rule severity | A source ID is absent from a required target section. |
 | `profile.validation.sectionMissing` | Rule severity | A required section heading is absent. |
 | `profile.validation.sectionOrder` | Rule severity | A strict required-section order cannot be satisfied. |
+| `profile.validation.tableColumnCoverageIdMissing` | Rule severity | A source ID is absent from the configured target table column. |
+| `profile.validation.tableColumnCoverageTargetColumnMissing` | Rule severity | The configured target table column cannot be resolved. |
+| `profile.validation.tableColumnCoverageTargetSectionMissing` | Rule severity | The configured target section cannot be resolved. |
 | `profile.validation.textExcluded` | Rule severity | A selected target contains forbidden literal text. |
 | `profile.validation.textMissing` | Rule severity | A selected target lacks required literal text from a `text.contains` assertion. |
-| `profile.validation.assertionUnsupported` | `error` | A compiled assertion has no evaluator implementation; this is an internal safety diagnostic. |
+| `profile.validation.assertionUnsupported` | `error` | A compiled assertion or compiled assertion feature has no evaluator implementation; this is an internal safety diagnostic. |
 
 ## Result Shape
 
@@ -314,9 +441,12 @@ rather than fabricated when unavailable.
 interface DeclarativeValidationResult extends ValidationResult {
   valid: boolean;
   diagnostics: readonly MarkdownDiagnostic[];
-  ruleResults: readonly ValidationRuleResult[];
+  ruleResults: readonly (
+    | ValidationRuleResult
+    | DeclarativeValidationRuleResultV2
+  )[];
   profile: {
-    syntaxVersion: "markdown-engine.validation@v1";
+    syntaxVersion: ValidationProfileSyntaxVersion;
     documentVersion: EngineDocumentVersion;
     ruleCount: number;
   };
@@ -324,9 +454,61 @@ interface DeclarativeValidationResult extends ValidationResult {
 }
 ```
 
-`valid` is `false` when any error-severity diagnostic exists. Warning and info
-validation diagnostics can make a rule result fail without making the aggregate
-result invalid.
+For admitted v2 profiles, result metadata records
+`syntaxVersion: "markdown-engine.validation@v2"`, `evaluatedRuleCount`, and
+`skippedRuleCount`. V2 rule results include the v1-compatible `ruleId`,
+`passed`, and `diagnostics` fields plus `status`, optional skipped
+applicability metadata, and flat, grouped, or skipped evaluation metadata:
+
+```ts
+interface DeclarativeValidationRuleResultV2 extends ValidationRuleResult {
+  status: "passed" | "failed" | "skipped";
+  when?: DeclarativeValidationApplicabilityResult;
+  evaluation:
+    | { kind: "assertions"; diagnostics: readonly MarkdownDiagnostic[] }
+    | {
+        kind: "anyOf";
+        selectedBranch?: DeclarativeValidationBranchReference;
+        branches: readonly DeclarativeValidationBranchResult[];
+      }
+    | {
+        kind: "allOf";
+        branches: readonly DeclarativeValidationBranchResult[];
+      }
+    | { kind: "skipped"; reason: "whenNotMatched" };
+}
+
+interface DeclarativeValidationApplicabilityResult {
+  status: "matched" | "notMatched";
+  diagnostics: readonly MarkdownDiagnostic[];
+}
+
+interface DeclarativeValidationBranchReference {
+  branchIndex: number;
+  label?: string;
+}
+
+interface DeclarativeValidationBranchResult
+  extends DeclarativeValidationBranchReference {
+  status: "passed" | "failed";
+  diagnostics: readonly MarkdownDiagnostic[];
+}
+```
+
+For configured `when`, matched applicability continues into normal flat or
+grouped evaluation and contributes one evaluated rule. The evaluated rule result
+does not serialize a `when` field. Non-matching applicability returns one
+skipped rule result with `status: "skipped"`, `passed: true`, empty top-level
+rule `diagnostics`, `when.status: "notMatched"`, nested applicability
+diagnostics, `evaluation.kind: "skipped"`, and `reason: "whenNotMatched"`.
+Skipped rules increment `skippedRuleCount`, do not increment
+`evaluatedRuleCount`, and do not evaluate flat assertions or grouped branches.
+
+`valid` is `false` when any top-level error-severity diagnostic exists in
+`diagnostics`. Nested skipped applicability diagnostics under
+`ruleResults[].when.diagnostics` do not by themselves make the aggregate result
+invalid. Warning and info validation diagnostics can make a rule result fail
+without making the aggregate result invalid.
 
 Rule results are sorted deterministically. Each rule result includes the public
 `ruleId`, `passed`, and cloned diagnostics. Results do not expose compiled rule
@@ -338,16 +520,27 @@ Evidence is emitted only when `DeclarativeValidationOptions.includeEvidence` is
 `true`:
 
 ```ts
-interface DeclarativeValidationEvidence {
+interface DeclarativeValidationEvidence<
+  RuleResult extends ValidationRuleResult = ValidationRuleResult,
+> {
   inputHash: string;
   profileHash: string;
   engineVersion: string;
   runtimeVersion: string;
-  ruleResults: readonly ValidationRuleResult[];
+  ruleResults: readonly RuleResult[];
   diagnostics: readonly MarkdownDiagnostic[];
 }
 ```
 
+For v1 profiles, `ruleResults` contains the unchanged v1 rule-result shape. For
+admitted v2 profiles, `ruleResults` clones the public v2 rule-result shape,
+including `status`, flat assertion evaluation, and grouped `anyOf` / `allOf`
+branch evaluation. Skipped v2 rule results are cloned through evidence in the
+same `ruleResults` array, and `evidence.diagnostics` clones the top-level
+diagnostics array. Evidence does not serialize compiled rule plans, selector
+target records, assertion-specific ID count evidence, or assertion-specific
+table-column coverage evidence.
+
 `inputHash` is a lowercase hexadecimal SHA-256 digest of the stable JSON
 serialization of the supplied normalized `EngineDocument` after omitting only
 the top-level `document.path` field. Structural target paths remain part of the
@@ -360,7 +553,7 @@ serialization of the resolved `ValidationProfile` after applying the resolved
 the same profile hash for the same document version and rules.
 
 `engineVersion` records the package version that produced the evidence. In the
-2.0 release line this is `"2.0.0"` even though `documentVersion` remains
+3.0 release line this is `"3.0.0"` even though `documentVersion` remains
 `"1.0.0"`.
 
 Raw Markdown bytes, raw YAML bytes, YAML comments, caller file paths, and
@@ -384,7 +577,9 @@ validate the Markdown file.
 
 After profile compilation succeeds, the CLI emits a validation-result JSON
 shape whether the document passes or fails. Validation CLI results include
-evidence.
+evidence. V2 CLI results use the same validation-result arm of the CLI JSON
+union; there is no extra CLI discriminator beyond
+`profile.syntaxVersion: "markdown-engine.validation@v2"`.
 
 ## CLI JSON Union
 
@@ -411,23 +606,72 @@ unsupported assertion members, and incompatible selector/assertion pairs. It
 contains no `profile` and no `evidence`.
 
 Validation-result JSON is used after profile compilation succeeds. It contains
-`profile`, `ruleResults`, `diagnostics`, `valid`, and `evidence`.
+`profile`, `ruleResults`, `diagnostics`, `valid`, and `evidence`. For v2
+profiles, that same validation-result JSON can include `evaluatedRuleCount`,
+`skippedRuleCount`, `status: "skipped"`, nested `when` diagnostics, and
+`evaluation.kind: "skipped"`.
 
 ## Exit Codes
 
 | Exit code | Meaning |
 | --- | --- |
-| `0` | Validation completed with no error-severity diagnostics. |
-| `1` | Profile/config/compile, Markdown normalization, document-version mismatch, or validation diagnostics include at least one error. |
+| `0` | Validation completed with no top-level error-severity diagnostics. |
+| `1` | Profile/config/compile, Markdown normalization, document-version mismatch, or top-level validation diagnostics include at least one error. |
 | `2` | CLI usage, unsupported format, unknown argument, missing argument value, repeated singleton flag, unsupported `--document-version`, or local file read error. |
 
 ## Compatibility And Migration
 
 The v1 declarative validation syntax is a durable authoring contract for the
-2.0 package release line. Changes to profile syntax names, selector names,
+3.0 package release line. Changes to profile syntax names, selector names,
 assertion names, result fields, diagnostic codes, CLI flags, CLI JSON shape, or
 evidence hash inputs require explicit compatibility review.
 
+V1 preservation is explicit: v1 authoring syntax, v1 rule result shape, v1
+diagnostic inventory, v1 CLI JSON behavior, and v1 evidence hash inputs remain
+unchanged by the admitted v2 syntax.
+
+Compatibility examples:
+
+```yaml
+# v1 compatibility profile: remains on the v1 authoring and result contract.
+syntaxVersion: markdown-engine.validation@v1
+rules:
+  - id: sections.present
+    select:
+      target: document
+    assert:
+      sectionsRequired:
+        headings:
+          - Mission Brief
+```
+
+```yaml
+# v2 opt-in profile: selects Conditional V2 behavior explicitly.
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: release.docs
+    anyOf:
+      - label: release-section
+        select:
+          target: section
+          title: Release
+        assert:
+          exists: true
+      - label: changelog-link
+        select:
+          target: link
+          text: changelog
+        assert:
+          exists: true
+```
+
+The v1 profile above continues to emit the v1 validation-result shape. The v2
+profile above emits syntax-versioned v2 result metadata with
+`evaluatedRuleCount` and `skippedRuleCount`; v2 rule results include `status`
+and `evaluation`. The CLI does not add a second discriminator for v2; consumers
+branch on
+`profile.syntaxVersion: "markdown-engine.validation@v2"`.
+
 Migration notes:
 
 - Consumers using fixed `validate(document, config)` rule families can continue
@@ -438,6 +682,11 @@ Migration notes:
 - Consumers parsing CLI validation output must handle the
   `DeclarativeValidationCliJsonResult` union. Profile-stage failures do not
   include `profile` or `evidence`.
+- Consumers opting into `markdown-engine.validation@v2` must handle rule
+  `status` values of `"passed"`, `"failed"`, and `"skipped"`, plus
+  `evaluatedRuleCount`, `skippedRuleCount`, grouped branch results, and nested
+  skipped-rule `when` diagnostics. Aggregate validity is still determined from
+  top-level diagnostics.
 - Consumers that compare evidence hashes must normalize expectations around
   resolved `documentVersion`, default rule severity, stable key order, and
   exclusion of only top-level `document.path` from `inputHash`.
@@ -501,6 +750,34 @@ rules:
         count: 1
 ```
 
+Conditional v2 grouped rule with applicability:
+
+```yaml
+syntaxVersion: markdown-engine.validation@v2
+rules:
+  - id: release.when.docs-ready
+    when:
+      select:
+        target: section
+        title: Release
+      assert:
+        exists: true
+    anyOf:
+      - label: contract-link
+        select:
+          target: link
+          section: Release
+          text: contract
+        assert:
+          exists: true
+      - label: contract-heading
+        select:
+          target: heading
+          text: Contract
+        assert:
+          exists: true
+```
+
 CLI invocation:
 
 ```sh
@@ -540,6 +817,11 @@ The v1 contract explicitly excludes:
 - operational-design-spec, AGENTS.md, TASK.md, or other domain-specific rule
   meaning in core engine code
 
+The admitted v2 Conditional V2 surface also excludes `documentVersion: "3.0.0"`,
+recursive grouped rules, branch-level `when`, profile-defined predicates,
+assertion-specific evidence payloads, a separate skipped-rule evidence channel,
+and a new CLI JSON discriminator.
+
 The CLI reads only the caller-specified local Markdown and profile files. The
 API owns no file traversal, daemon, database, browser runtime, network service,
 agent adapter, MCP transport, runtime lens, or persistent cache.
@@ -553,7 +835,8 @@ npm run docs:declarative-validation-contract
 npm run audit:declarative-validation-boundary
 ```
 
-The documentation gate checks this contract, README links, evidence files, and
-package script wiring. The boundary audit checks dependency drift, source-level
-runtime boundary patterns, unsupported regex-like and executable profile-key
-coverage, and declarative validation boundary evidence.
+The documentation gate checks this contract, README links, legacy contract and
+boundary evidence files, Conditional V2 EVD-6 reviewer notes, and package script
+wiring. The boundary audit checks dependency drift, source-level runtime
+boundary patterns, unsupported regex-like and executable profile-key coverage,
+and declarative validation boundary evidence.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonbelmonti/markdown-engine",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "Deterministic Markdown parsing and validation engine package.",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "dist-bundled",
+    "skills",
     "docs/contracts",
     "fixtures/declarative-validation/examples",
     "CHANGELOG.md",
@@ -42,9 +44,11 @@
   "scripts": {
     "clean": "node scripts/clean-dist.mjs",
     "build": "npm run clean && tsc -p tsconfig.json",
+    "build:cli:bundled": "node scripts/build-bundled-cli.mjs",
+    "build:cli-bundle": "node scripts/build-cli-bundle.mjs",
     "prepack": "npm run release:verify",
     "prepublishOnly": "npm run release:verify",
-    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
+    "release:verify": "npm run typecheck && npm test && node scripts/check-boundaries.mjs && npm run docs:rich-ir-contract && npm run docs:declarative-validation-contract && npm run audit:declarative-validation-boundary && npm run build && npm run build:cli:bundled && node scripts/prove-repeatability.mjs --runs 10 && npm run release:check-clean",
     "release:check-clean": "git diff --check HEAD -- && git diff --exit-code HEAD --",
     "snapshots:update:parser": "npm run build && vitest run tests/parser-fixtures.test.ts -u \"--exclude=.worktrees/**\"",
     "snapshots:update:rules": "npm run build && vitest run tests/rules.test.ts -u \"--exclude=.worktrees/**\"",
@@ -65,7 +69,7 @@
     "test:validation:profile": "npm run build && vitest run tests/declarative-validation-profile.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:compiler": "npm run build && vitest run tests/declarative-validation-compiler.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:selectors": "npm run build && vitest run tests/declarative-validation-selectors.test.ts \"--exclude=.worktrees/**\"",
-    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts \"--exclude=.worktrees/**\"",
+    "test:validation:assertions": "npm run build && vitest run tests/declarative-validation-assertions.test.ts tests/declarative-validation-table-column-coverage-fixtures.test.ts tests/declarative-validation-grouped-rules-fixtures.test.ts tests/declarative-validation-when-skipped-rules-fixtures.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:diagnostics": "npm run build && vitest run tests/declarative-validation-diagnostics.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:cli": "npm run build && vitest run tests/declarative-validation-cli.test.ts \"--exclude=.worktrees/**\"",
     "test:validation:examples": "npm run build && vitest run tests/declarative-validation-examples.test.ts \"--exclude=.worktrees/**\"",
@@ -83,6 +87,7 @@
   "devDependencies": {
     "@types/node": "^22.19.17",
     "cmark-gfm": "^0.9.0",
+    "esbuild": "^0.27.7",
     "typescript": "^5.8.3",
     "vitest": "^3.1.3"
   },