session-orchestrator 3.17.0 → 3.19.0

package/skills/claude-md-drift-check/checker.mjs

@@ -34,7 +34,10 @@ import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { resolveInstructionFile } from '../../scripts/lib/common.mjs';
 import { _parseVaultIntegration } from '../../scripts/lib/config/vault-integration.mjs';
+import { _parseDriftCheck } from '../../scripts/lib/config/drift-check.mjs';
+import { isSessionConfigHeading } from '../../scripts/lib/config/section-extractor.mjs';
 import { parseGlobsFrontmatter } from '../../scripts/lib/rule-loader.mjs';
+import { resolveRepoSpec } from '../../scripts/lib/vcs-repo-spec.mjs';
 
 const FORWARD_HEADING_RE =
   /(?:^|\b)(what'?s?\s+next|backlog|open\s+issues?|offene\s+(?:issues?|themen)|todo|next\s+steps?|roadmap)(?:$|\b)/i;
@@ -44,6 +47,10 @@ const BACKWARD_HEADING_RE =
 function parseArgs(argv) {
   const out = {
     mode: 'warn',
+    // #864: true only when --mode was actually passed on argv. Distinguishes
+    // "operator explicitly requested warn" from "the flag was never given" —
+    // the latter is where the target's own drift-check.mode default applies.
+    modeExplicit: false,
     includePaths: [],
     skipPathResolver: false,
     skipProjectCount: false,
@@ -62,7 +69,7 @@ function parseArgs(argv) {
   };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--mode') out.mode = argv[++i];
+    if (a === '--mode') { out.mode = argv[++i]; out.modeExplicit = true; }
     else if (a === '--include-path') out.includePaths.push(argv[++i]);
     else if (a === '--repo') out.repo = argv[++i];
     else if (a === '--commands-dir') out.commandsDir = argv[++i];
@@ -79,7 +86,7 @@ function parseArgs(argv) {
     else if (a === '--skip-rule-scoping') out.skipRuleScoping = true;
     else if (a === '--skip-docs-parity') out.skipDocsParity = true;
     else if (a === '--help' || a === '-h') {
-      process.stdout.write('Usage: checker.mjs [--mode hard|warn|off] [--include-path GLOB]... [--repo OWNER/NAME] [--commands-dir PATH] [--config-template PATH] [--skip-surface-count] [--skip-command-count] [--skip-generated-rule-staleness] [--skip-rule-scoping] [--skip-docs-parity] [--skip-*]\n');
+      process.stdout.write('Usage: checker.mjs [--mode strict|warn|off] [--include-path GLOB]... [--repo OWNER/NAME] [--commands-dir PATH] [--config-template PATH] [--skip-surface-count] [--skip-command-count] [--skip-generated-rule-staleness] [--skip-rule-scoping] [--skip-docs-parity] [--skip-*]\n  --mode precedence (issue #864): explicit --mode > target CLAUDE.md/AGENTS.md drift-check.mode > \'warn\'\n');
       process.exit(0);
     } else {
       process.stderr.write(`{"status":"infra-error","reason":"unknown arg: ${a}"}\n`);
@@ -146,7 +153,14 @@ function extractSessionConfigBlock(content, { occurrence = 'first' } = {}) {
   const lines = content.split('\n');
   const headingIdxs = [];
   for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Session Config\b/.test(lines[i])) headingIdxs.push(i);
+    // SSOT predicate (#968). The previous local `/^##\s+Session Config\b/`
+    // was the loosest JS comparator in the repo: no end anchor and `\s+`
+    // instead of a single space, so it accepted `##  Session Config` (two
+    // spaces) and `## Session Config Convention` — both of which the runtime
+    // parser rejects. This checker's whole job is to report on the block the
+    // runtime reads, so matching a heading the runtime cannot see made it
+    // audit a section that does not exist.
+    if (isSessionConfigHeading(lines[i])) headingIdxs.push(i);
   }
   if (headingIdxs.length === 0) return null;
 
@@ -172,10 +186,23 @@ function extractSessionConfigBlock(content, { occurrence = 'first' } = {}) {
 /**
  * Extract top-level YAML keys from a YAML body. Only column-0 keys are
  * collected (indented keys are children and ignored).
+ *
+ * Accepts four equivalent forms consumer CLAUDE.md files write a Session
+ * Config key in: bare `key:`, Markdown bullet `- key:`, bold `**key:**`
+ * (closing bold before the colon), and the bold-bullet consumer shape
+ * `- **key:** value` (bold wraps the key AND colon together, closing bold
+ * AFTER the colon). Baseline issue #60: the original bare-only regex
+ * extracted zero keys from bullet-form local files, so session-config-parity
+ * (Check 6, below) either false-positived on every mandatory key (local side
+ * reads as empty) or, when the TEMPLATE side also used bullet form, passed
+ * vacuously (both sides empty, so the diff was always empty). Sibling
+ * precedent: `scripts/lib/config/block-header.mjs` recognizes only header
+ * lines, not individual key-value pairs — this function is the per-key
+ * counterpart.
  */
 function extractTopLevelKeys(body) {
   const keys = [];
-  const re = /^([A-Za-z][\w-]*):/gm;
+  const re = /^(?:-\s+)?(?:\*\*)?([A-Za-z][\w-]*)(?:\*\*)?:/gm;
   let m;
   while ((m = re.exec(body)) !== null) {
     keys.push(m[1]);
@@ -416,13 +443,20 @@ function buildSurfaceDescriptors(vaultDir, commandsDir) {
   ];
 }
 
-const REPO_SHAPE_RE = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/;
-
-function detectRepo(vaultDir) {
-  const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: vaultDir, encoding: 'utf8' }).trim();
-  const m = /[:/]([^:/\s]+\/[^/\s]+?)(?:\.git)?$/.exec(url);
-  const candidate = m ? m[1] : null;
-  return candidate && REPO_SHAPE_RE.test(candidate) ? candidate : null;
+/**
+ * Guard for a `--repo`/`-R` argv value before it is passed to `glab`
+ * (host-pinning, #872). Replaces the old `REPO_SHAPE_RE` "owner/repo" shape
+ * check — `resolveRepoSpec` for `vcs: 'gitlab'` returns the raw remote URL
+ * (which `glab -R`/`--repo` explicitly accepts), so the guard only needs to
+ * reject the same argv-corrupting characters checked elsewhere in this repo
+ * (see `ARG_BOUNDARY_DANGEROUS` in scripts/lib/test-runner/issue-reconcile.mjs):
+ * non-empty and free of whitespace/newlines.
+ *
+ * @param {unknown} spec
+ * @returns {boolean}
+ */
+function isSafeRepoSpec(spec) {
+  return typeof spec === 'string' && spec.length > 0 && !/\s/.test(spec);
 }
 
 function hasGlab() {
@@ -432,11 +466,18 @@ function hasGlab() {
   } catch { return false; }
 }
 
-function lookupIssueState(iid, repo, cache) {
+function lookupIssueState(iid, repo, cache, vaultDir) {
   if (cache.has(iid)) return cache.get(iid);
   let state = 'unknown';
   try {
+    // #872: cwd: vaultDir — without it, a bare `cwd`-less spawn resolves the
+    // ambient GITLAB_HOST relative to the PROCESS cwd (not vaultDir), which
+    // can silently target the wrong instance on a multi-instance host even
+    // though `--repo <repo>` is already present (host-pinning consistency
+    // with detectRepo's git-remote resolution above, which DOES use
+    // `cwd: vaultDir` via resolveRepoSpec).
     const out = execFileSync('glab', ['issue', 'view', iid, '--repo', repo], {
+      cwd: vaultDir,
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
     });
@@ -450,8 +491,11 @@ function lookupIssueState(iid, repo, cache) {
 // ───────────────────────────────────────────────────────────────────────────
 // Rule-scoping family (Check 9) — validates .claude/rules/*.md frontmatter
 // against the scripts/lib/rule-loader.mjs contract:
-//   1. paths-presence   → errors[]:   a top-level `paths:` key (rule-loader.mjs
-//      only recognises `globs:`; `paths:` silently loads the rule ALWAYS-ON).
+//   1. paths-presence   → errors[]:   a top-level `paths:` key that
+//      rule-loader.mjs's parseGlobsFrontmatter (the `paths:` alias, issue
+//      #795) fails to recognise — a genuine parse mismatch. A well-formed
+//      `paths:`-only rule is NOT flagged: since #795, `paths:` is a full
+//      alias for `globs:` and loads correctly SCOPED (#840).
 //   2. cited-but-missing → errors[]:  (a) `.claude/rules/<name>.md` citations in
 //      CLAUDE.md/AGENTS.md that don't exist on disk; (b) bare `<name>.md`
 //      tokens in a rule's own `## See Also` footer that don't exist on disk
@@ -585,18 +629,70 @@ function main() {
   const args = parseArgs(process.argv.slice(2));
   const vaultDir = resolve(process.env.VAULT_DIR || process.cwd());
 
-  if (!['hard', 'warn', 'off'].includes(args.mode)) {
-    process.stderr.write(`{"status":"infra-error","reason":"invalid --mode: ${args.mode}"}\n`);
-    process.exit(2);
-  }
-
-  // Alias-aware instruction file resolution (issue #33).
+  // Alias-aware instruction file resolution (issue #33) — resolved BEFORE
+  // mode defaulting so an unspecified --mode can read the target's OWN
+  // drift-check.mode (issue #864).
   // CLAUDE.md (Claude Code / Cursor IDE) and AGENTS.md (Codex CLI) are
   // transparent aliases — see skills/_shared/instruction-file-resolution.md.
   const instr = resolveInstructionFile(vaultDir); // {path, kind} | null
   const resolvedPath = instr ? instr.path : null;
   const resolvedKind = instr ? instr.kind : null;
 
+  // #864: precedence is --mode flag > target's drift-check.mode > 'warn'.
+  // An invocation without an explicit --mode previously always ran in the
+  // hardcoded 'warn' default even when the target's own Session Config
+  // declared `drift-check.mode: strict` — silently softening the very
+  // contract the config was meant to enforce. Only substitute when --mode
+  // was never passed on argv; an explicit flag always wins. `_parseDriftCheck`
+  // is the SAME parser scripts/lib/config.mjs uses elsewhere, so this reuses
+  // rather than re-derives the drift-check block's mode-parsing/normalization
+  // (including its own hard→strict alias and its 'warn' fallback on absence
+  // or an invalid value).
+  //
+  // Blast-radius guard (QA follow-up on #864, reproduced empirically):
+  // the auto-read must not apply AT ALL when the feature it belongs to is
+  // disabled — `drift-check.enabled: false` means the operator switched the
+  // whole gate off, and a stale/dormant `mode: strict` sitting in that
+  // disabled block must not hard-block a bare invocation. Read `enabled` off
+  // the SAME `_parseDriftCheck()` call (it already parses the flag) rather
+  // than a second bespoke regex.
+  //
+  // Separately, a config-derived `mode: off` is never auto-applied even when
+  // `enabled: true`: 'off' is a legitimate silencing only when a human
+  // explicitly types `--mode off` on the CLI. Picking it up silently from
+  // config would turn what used to be a full warn-mode report into an
+  // undetectable no-op on every future bare invocation — the exact silent
+  // failure class `.claude/rules/verification-before-completion.md` § VBC-005
+  // exists to prevent. Concretely: config-derived mode is applied only when
+  // `enabled === true` AND `mode !== 'off'`; a config `mode: off` downgrades
+  // to the built-in 'warn' default instead of taking effect. This keeps
+  // `status: 'skipped-mode-off'` reachable ONLY via an explicit `--mode off`
+  // flag — a caller who never passed that flag can rely on a bare invocation
+  // always actually running its checks, even against a config that declares
+  // `mode: off`.
+  if (!args.modeExplicit && instr) {
+    try {
+      const targetDriftCheck = _parseDriftCheck(readFileSync(instr.path, 'utf8'));
+      if (targetDriftCheck.enabled && targetDriftCheck.mode !== 'off') {
+        args.mode = targetDriftCheck.mode;
+      }
+    } catch {
+      // target file unreadable (race, permissions) — keep the 'warn' CLI default
+    }
+  }
+
+  if (!['strict', 'hard', 'warn', 'off'].includes(args.mode)) {
+    process.stderr.write(`{"status":"infra-error","reason":"invalid --mode: ${args.mode}"}\n`);
+    process.exit(2);
+  }
+  // `hard` is a legacy alias for `strict` (#217 enum migration — parity with
+  // the vault-sync validator, which normalizes the reverse direction). Collapse
+  // to a single blocking value so exactly one internal value flows downstream.
+  // (`_parseDriftCheck` already normalizes 'hard'->'strict' on the config-default
+  // path above, so this is a no-op there — it remains load-bearing for an
+  // explicit `--mode hard` on the CLI.)
+  if (args.mode === 'hard') args.mode = 'strict';
+
   if (args.mode === 'off') {
     process.stdout.write(JSON.stringify({
       status: 'skipped-mode-off', mode: 'off', vault_dir: vaultDir,
@@ -657,13 +753,20 @@ function main() {
   const commandSurface = activeSurfaces.find((s) => s.id === 'command-count');
   const actualCommandCount = commandSurface ? commandSurface.actual : null;
 
+  // #872: CLI --repo always wins; otherwise auto-detect a --repo spec from
+  // the local git remotes (host-pinning — a bare glab spawn falls back to
+  // the ambient GITLAB_HOST, which can silently target the wrong instance
+  // on a multi-instance host).
   let repo = args.repo;
   const glabPresent = !args.skipIssueRefs && hasGlab();
   if (!args.skipIssueRefs && !glabPresent) {
     checksSkipped.push('issue-reference-freshness: glab not found in PATH');
   }
   if (!args.skipIssueRefs && glabPresent && !repo) {
-    try { repo = detectRepo(vaultDir); } catch { /* ignore */ }
+    try {
+      const resolved = resolveRepoSpec({ repoRoot: vaultDir, vcs: 'gitlab' });
+      repo = resolved && isSafeRepoSpec(resolved) ? resolved : null;
+    } catch { /* ignore */ }
     if (!repo) checksSkipped.push('issue-reference-freshness: could not detect origin repo (use --repo)');
   }
   const runIssueCheck = !args.skipIssueRefs && glabPresent && !!repo;
@@ -979,18 +1082,32 @@ function main() {
         }
 
         // --- Probe 1: paths-presence → errors[] ---
+        // Since ef7f4fc (2026-07-13, issue #795), rule-loader.mjs's
+        // parseGlobsFrontmatter() accepts `paths:` as a full alias for
+        // `globs:` (globs: wins silently only when BOTH keys are present on
+        // the same rule — see rule-loader.mjs module doc). A well-formed
+        // `paths:`-only rule therefore loads correctly SCOPED, not
+        // always-on — declaring `paths:` alone must NOT be flagged (#840).
+        // This probe reuses parseGlobsFrontmatter — the SAME parser
+        // rule-loader.mjs itself runs — rather than re-deriving the alias
+        // rule with a second hand-rolled regex; duplicating a loader's
+        // parsing logic is exactly the drift class that caused #840. It
+        // fires only when the textual `paths:` key is present yet
+        // parseGlobsFrontmatter failed to recognise it (globs === null) —
+        // a genuine parse mismatch between this probe's textual detection
+        // and the loader's actual behaviour, not routine `paths:` usage.
+        let parsed;
+        try { parsed = parseGlobsFrontmatter(content); } catch { parsed = { globs: null, meta: {} }; }
         const fmBody = extractFrontmatterBlockBody(content);
-        if (fmBody && /^paths:/m.test(fmBody)) {
+        if (fmBody && /^paths:/m.test(fmBody) && parsed.globs === null) {
           errors.push({
             check: 'rule-scoping', file: relPath, line: 1,
-            message: `Rule frontmatter declares 'paths:' which rule-loader.mjs does not recognise — the rule silently loads ALWAYS-ON regardless of file scope. Migrate to 'globs:'.`,
+            message: `Rule frontmatter declares 'paths:' but rule-loader.mjs's parseGlobsFrontmatter did not recognise it — the rule may silently load ALWAYS-ON. Verify the paths:/globs: frontmatter syntax.`,
             extracted: 'paths:',
           });
         }
 
         // --- Probes 3 & 4: zero-match-globs / foreign-glob → warnings[] ---
-        let parsed;
-        try { parsed = parseGlobsFrontmatter(content); } catch { parsed = { globs: null, meta: {} }; }
         const globs = parsed.globs;
         if (Array.isArray(globs) && globs.length > 0) {
           if (trackedFiles === null) trackedFiles = listTrackedFiles(vaultDir);
@@ -1212,7 +1329,7 @@ function main() {
       files_scanned: 0, checks_run: checksRun, checks_skipped: checksSkipped,
       errors, warnings, reason: 'no scope files matched',
     }) + '\n');
-    process.exit(errors.length > 0 && args.mode === 'hard' ? 1 : 0);
+    process.exit(errors.length > 0 && args.mode === 'strict' ? 1 : 0);
   }
 
   for (const abs of scopeFiles) {
@@ -1272,7 +1389,7 @@ function main() {
         let m;
         while ((m = issueRegex.exec(line)) !== null) {
           const iid = m[1];
-          const state = lookupIssueState(iid, repo, issueCache);
+          const state = lookupIssueState(iid, repo, issueCache, vaultDir);
           if (state === 'closed') {
             errors.push({
               check: 'issue-reference-freshness', file: rel, line: lineNum,
@@ -1374,7 +1491,7 @@ function main() {
   }
   process.stdout.write(JSON.stringify(result) + '\n');
 
-  process.exit(errors.length > 0 && args.mode === 'hard' ? 1 : 0);
+  process.exit(errors.length > 0 && args.mode === 'strict' ? 1 : 0);
 }
 
 main();

package/skills/contract-version-bump/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: contract-version-bump
+user-invocable: true
+tags: [contracts, versioning, schema, changelog, governance]
+model: sonnet
+model-preference: sonnet
+model-preference-codex: gpt-5.4-mini
+model-preference-cursor: claude-sonnet-4-6
+args-schema:
+  - flag: --contract <path>
+    description: "Path to the contract file being bumped (JSON Schema, API spec, config schema). Inferred from conversation context if omitted."
+description: >
+  Use this skill when changing a machine-readable contract — a JSON Schema, an API spec, or a
+  config schema — and bumping its version: tightening a constraint, adding/removing/renaming a
+  field, introducing a breaking change, raising an API version, or writing the changelog entry
+  for a schema change. Trigger on "change the schema", "tighten this constraint", "bump the
+  schema version", "breaking change to the API", "new API version", "changelog entry for a
+  schema change". Runs six phases — classify against the contract's OWN versioning rule (not
+  generic semver instinct), find every version literal and vendored copy, check consumer
+  compatibility for new keywords, apply consistently, write the changelog entry, and report
+  downstream drift — codifying three non-obvious traps hit in a real case (GitLab issue #17,
+  `aiat-enablement` repo, 2026-07-25).
+---
+
+# Contract Version Bump
+
+> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent
+> aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md).
+> Every reference to `CLAUDE.md` in this skill resolves via that precedence rule.
+
+A version bump on a machine-readable contract (JSON Schema, OpenAPI/API spec, config schema) is
+not just "increment the number." Three failure modes recur and are each individually
+non-obvious enough that a careful agent still misses them without a checklist: the contract's
+own versioning rule may not even cover the change you're making; version literals live in more
+places than you remember; and a schema keyword that no consumer evaluates is worse than no
+constraint at all, because it *looks* enforced. This skill runs six phases to close all three.
+
+**Reference case:** `aiat-enablement` repo, GitLab issue #17 (2026-07-25). A JSON Schema contract
+(`docs/spec/estate.schema.json`, draft/2020-12) had six fields tightened with new `pattern`
+constraints; `schema_version` moved `0.1.0` → `0.1.1`. All three traps below happened in that
+one change. Where cited, "the reference case" means this.
+
+## Phase 1: Classify against the CONTRACT'S OWN versioning rule
+
+Do not classify Patch/Minor/Major from generic semver instinct. Read the contract's own
+versioning-rules section (in its prose spec, README, or a `## Versioning` block near the schema)
+and ask explicitly: **does this rule even define the change class you're making?**
+
+```bash
+# Does the spec define rules for Patch changes at all? (substitute Minor/Major as needed)
+grep -n "^#.*[Vv]ersion" docs/spec/<contract>.md
+grep -c "Patch" docs/spec/<contract>.md
+```
+
+If the clause you need is missing, **authoring that clause is part of this change**, not a
+side quest — write it with an explicit justification for why the new class exists and why your
+change belongs in it, then proceed. If the clause exists but classifies your change as a stricter
+tier than you assumed (e.g. a "just tightening a pattern" edit is actually forbidden under an
+additive-only Minor rule), the rule wins — either recategorize the change or amend the rule
+first, but never bump the number past what the contract's own rule permits.
+
+Reference case: `docs/spec/estate-yaml-v0.md` defined only Minor (additive-only) and Major
+(needs a migration step). `grep -c "Patch" docs/spec/estate-yaml-v0.md` returned `0`. A
+constraint tightening is not additive, so under the existing rule alone it was forbidden. The
+Patch clause had to be authored — with a written justification (no production consumers yet
+validate against this vorproduktions-schema, so no migration burden exists) — before the bump
+was legitimate.
+
+## Phase 2: Find every version literal and copy — mechanically, not from memory
+
+Never trust "I updated it everywhere I remember." Grep for the literal.
+
+```bash
+# 1. Every occurrence of the current version string in this repo
+grep -rn "<current-version>" --include=*.json --include=*.md --include=*.yaml --include=*.yml .
+
+# 2. The field/key that carries the version, wherever it's mentioned in prose
+#    (field-catalog tables, example fixtures, README snippets)
+grep -rln "schema_version\|apiVersion\|<version-field-name>" docs/ examples/ 2>/dev/null
+
+# 3. Vendored copies in sibling repos — check every path under the instruction
+#    file's `cross-repos:` list. Match by basename, not by path: a vendored copy
+#    is rarely at an identical relative path.
+#    CLAUDE.md and AGENTS.md are transparent aliases — resolve whichever exists.
+INSTR=$([ -f CLAUDE.md ] && echo CLAUDE.md || echo AGENTS.md)
+for repo in $(yq '.["cross-repos"][]' "$INSTR" 2>/dev/null || grep -A20 '^cross-repos:' "$INSTR" | grep '  - ' | sed 's/^ *- *//'); do
+  find "$repo" -iname "$(basename <contract-file>)" 2>/dev/null
+done
+```
+
+For every location found, decide explicitly: **does it get bumped, or is it exempt?** Exemptions
+are legitimate (a dated SSOT snapshot like a PRD is allowed to stay frozen at the version it was
+approved under) but the exemption must be written down next to the literal that was skipped, or
+the next diff will read as silent divergence.
+
+Reference case: `schema_version` lived in five places — the schema file itself
+(`docs/spec/estate.schema.json`), the field-catalog table in the prose spec
+(`docs/spec/estate-yaml-v0.md`), an example fixture (`docs/spec/examples/estate.example.yaml`), a
+**vendored copy in a different repo** (`aiat-poc-infra/scripts/estate/estate.schema.json`), and
+the PRD (`docs/prd/2026-07-25-aiat-enablement.md`, Anhang D.1). The PRD was deliberately *not*
+bumped — but that decision was written into the spec's "Anmerkungen zu diesem Dokument" section
+explicitly, precisely so it would never be mistaken for an oversight.
+
+## Phase 3: Check consumer compatibility for every new/changed keyword
+
+For each keyword you are adding or changing (`pattern`, `maxLength`, `enum`, `format`,
+`additionalProperties`, a new required field, a new `apiVersion` value, …), find every known
+consumer of the contract and ask: **does this consumer actually evaluate this keyword, or does
+it silently ignore what it doesn't recognize?**
+
+- A full-featured library (ajv, `jsonschema`, an OpenAPI-generated client) generally implements
+  the standard vocabulary — trust it, but confirm the vocabulary/draft version matches (e.g. a
+  draft-07 validator will not enforce 2020-12-only keywords).
+- A hand-written parser/interpreter (a bash+heredoc validator, a custom regex-based checker, a
+  bespoke deserializer) is the risk case. Grep its source for the keyword name:
+
+```bash
+grep -n "maxLength\|minLength\|pattern\|format\|enum" <consumer-script-or-module>
+```
+
+If the keyword is absent from the consumer's implementation, you have three options — pick one
+and write it down, never leave it implicit:
+1. **Extend the consumer** to support the keyword (preferred when the consumer is yours to change).
+2. **Fold the constraint into a keyword the consumer already supports** (e.g. encode a length
+   limit inside a `pattern` instead of a separate `maxLength`).
+3. **Accept the gap and document it as a known limitation** in the spec, naming the consumer —
+   only when neither of the above is feasible right now.
+
+A constraint a consumer silently ignores is worse than no constraint: it looks enforced in the
+schema, so nobody double-checks the actual runtime behavior, and invalid data passes through
+undetected.
+
+Reference case: `maxLength: 63` was the natural way to express S3 bucket-name limits. The
+downstream validator (`aiat-poc-infra/scripts/estate/validate-estate-yaml.sh`) is a hand-written
+JSON-Schema mini-interpreter that does not implement `maxLength` — it would have parsed the
+schema, not recognized the keyword, and silently done nothing, so a 200-character bucket name
+would still validate green. Decision: extend the consumer (option 1) rather than relying only on
+the `pattern`'s implicit length ceiling — the `maxLength` branch was added to the interpreter in
+the same session, on branch `feature/estate-yaml-format-tightening-17`, and proven by a mutation
+test (disable the branch → the `[MAXLENGTH]` assertion goes red while `[PATTERN]` still fires).
+
+That mutation test is itself the lesson: because the bucket `pattern`
+(`^[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]$`) already bounds total length via its quantifier, an
+over-length value trips BOTH rules. A fixture alone could not prove the new `maxLength` code was
+load-bearing — only disabling that code and watching the specific assertion fail could. When a
+new keyword overlaps an existing constraint, prove it in isolation or you have not proven it.
+
+## Phase 4: Apply consistently
+
+Bump the version literal and the constraint change together, everywhere Phase 2 found a
+non-exempt occurrence. For each exemption identified in Phase 2, write the reason next to it
+(a spec's "Anmerkungen"/decisions section, a code comment, a linked issue) — an exemption without
+a written reason is indistinguishable from a bug the next time someone diffs the two documents.
+
+## Phase 5: Write the changelog entry
+
+Follow [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) conventions already in use in
+this repo's `CHANGELOG.md` — add the entry under the repo's convention for in-progress work
+(commonly an `## [Unreleased]` section; check the top of the file for the existing pattern before
+inventing a new one). What goes in the entry depends on the classification from Phase 1:
+
+- **Patch (constraint tightening on an existing field):** name every field that changed, the old
+  constraint and the new one. **State explicitly that this can reject previously-valid documents
+  for consumers, even though the version number alone does not signal a breaking change** — the
+  version-number tier and the actual blast radius for a consumer are two different axes; do not
+  let the reader infer breaking-ness from the tier alone.
+- **Minor (additive field(s)):** name the new field(s) and confirm the change is additive-only —
+  no existing field's meaning, requiredness, or name changed.
+- **Major (breaking structural change):** name the field(s)/structure that changed and link the
+  migration step (e.g. `migrations/<contract>/`) a consumer must run.
+
+## Phase 6: Report downstream drift
+
+List every vendored copy or dependent repo found in Phase 2 that this change did **not** update.
+For each: name the repo/path, why it wasn't updated now (e.g. "follow-up MR pending, tracked
+separately"), and the tracking issue if one exists. Never let a known-stale copy pass silently —
+surface it as explicit follow-up work, even if fixing it is out of scope for this change.
+
+---
+
+## Checklist
+
+- [ ] Read the contract's own versioning-rule section. Does it define the change class you're
+      making? If not, write the clause first (with justification), before touching the version.
+- [ ] Classify Patch / Minor / Major against that rule — not generic semver instinct.
+- [ ] `grep -rn` the current version literal across this repo (schema, prose spec, examples/fixtures).
+- [ ] Search every repo in the instruction file's `cross-repos:` list (`CLAUDE.md`, or `AGENTS.md`
+      on Codex CLI) for a vendored copy (basename match).
+- [ ] For every new/changed keyword, grep each known consumer's source for that keyword name.
+      Decide: extend / fold into a supported keyword / document the gap — pick one, write it down.
+- [ ] Apply the bump + constraint change to every non-exempt literal found in Phase 2.
+- [ ] Write the reason next to every exemption (a document deliberately NOT bumped).
+- [ ] Write the changelog entry — name the fields, old vs. new constraint, and call out breaking
+      risk for consumers explicitly, independent of the version tier.
+- [ ] List every dependent repo/copy left un-synced, with a tracking issue.
+
+## Anti-Patterns
+
+1. **Silent contract violation.** Bumping a version for a change class the contract's own rule
+   doesn't cover — or actively forbids — without amending the rule first. *Reference case:* the
+   spec defined only Minor (additive) and Major (needs migration); a constraint tightening isn't
+   additive, so it was forbidden under the existing rule until a Patch clause was authored with
+   an explicit justification.
+2. **Literal drift from memory.** Updating the version "everywhere I remember" instead of
+   grepping mechanically. *Reference case:* the version literal lived in five places, including a
+   vendored copy in a *different* repo (`aiat-poc-infra`) that a memory-based sweep would not
+   have found; one location (the PRD) was correctly left un-bumped, but only because that
+   exemption was written down explicitly instead of left silent.
+3. **Ignored keyword, worse than no keyword.** Adding a schema keyword without checking whether
+   every known consumer evaluates it. *Reference case:* `maxLength: 63` would have been silently
+   skipped by a hand-written validator that doesn't implement it — the schema would have *looked*
+   enforced while the runtime check let arbitrarily long values through.
+
+## When this does not apply
+
+Pure documentation-only edits to a contract (typo fixes, added examples, clarified descriptions)
+that change no validated field, constraint, or version-relevant semantics do not need a version
+bump or this skill — but if you're unsure whether a wording change is validation-relevant, treat
+it as a change and run Phase 1.

package/skills/discovery/SKILL.md

@@ -373,7 +373,7 @@ AskUserQuestion({
     question: "<finding title>\n\n<file_path>:<line_number>\n```\n<matched_text with +/-3 lines context>\n```\n\n<description>\n\nRecommended fix: <recommended_fix>",
     header: "<severity>",
     options: [
-      { label: "Create issue (<severity>)", description: "Create a priority:<severity> issue for this finding" },
+      { label: "Create issue (<severity>)", description: "Create a priority::<severity> issue for this finding" },
       { label: "Adjust priority", description: "Create issue with different priority" },
       { label: "Dismiss -- intentional", description: "This is by design, skip" },
       { label: "Dismiss -- false positive", description: "Detection was wrong, skip" }
@@ -432,10 +432,10 @@ AskUserQuestion({
 For each approved finding:
 
 1. Format using the Discovery Finding Issue Template from `issue-templates.md`
-2. Determine labels: `type:discovery` + `priority:<level>` + `area:<inferred from category/filepath>` + `status:ready`
+2. Determine labels: `type:discovery` + `priority::<level>` + `area:<inferred from category/filepath>` + `status:ready`
 3. Create issue via VCS CLI:
-   - **GitLab**: `glab issue create --title "[Discovery] <title>" --label "type:discovery,priority:<level>,area:<area>,status:ready" --description "<body>"`
-   - **GitHub**: `gh issue create --title "[Discovery] <title>" --label "type:discovery,priority:<level>,area:<area>,status:ready" --body "<body>"`
+   - **GitLab**: `glab issue create --title "[Discovery] <title>" --label "type:discovery,priority::<level>,area:<area>,status:ready" --description "<body>"`
+   - **GitHub**: `gh issue create --title "[Discovery] <title>" --label "type:discovery,priority::<level>,area:<area>,status:ready" --body "<body>"`
 4. Brief pause (1s) between creations for rate limiting
 
 ### 6.2 Final Report

package/skills/discovery/issue-templates.md

@@ -10,7 +10,7 @@ References the label taxonomy from the gitlab-ops skill.
 Discovery findings use the following labels from the gitlab-ops label taxonomy:
 
 - **Type:** `type:discovery`
-- **Priority:** `priority:critical` | `priority:high` | `priority:medium` | `priority:low` (mapped from probe severity)
+- **Priority:** `priority::critical` | `priority::high` | `priority::medium` | `priority::low` (mapped from probe severity)
 - **Area:** `area:frontend` | `area:backend` | `area:security` | `area:testing` | `area:ci` | `area:infrastructure` (mapped from probe category)
 - **Status:** `status:ready`
 
@@ -28,10 +28,10 @@ Discovery findings use the following labels from the gitlab-ops label taxonomy:
 
 | Probe Severity | Priority Label |
 |---|---|
-| Critical | `priority:critical` |
-| High | `priority:high` |
-| Medium | `priority:medium` |
-| Low | `priority:low` |
+| Critical | `priority::critical` |
+| High | `priority::high` |
+| Medium | `priority::medium` |
+| Low | `priority::low` |
 
 ---
 
@@ -74,14 +74,14 @@ Used for a single finding from a single probe.
 - [ ] Quality gates pass after fix
 ```
 
-**Labels:** `type:discovery`, `priority:<level>`, `area:<area>`, `status:ready`
+**Labels:** `type:discovery`, `priority::<level>`, `area:<area>`, `status:ready`
 
 **CLI Example:**
 ```bash
 # GitHub
 gh issue create \
   --title "[Discovery] <finding_title>" \
-  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
 <template body filled in>
 EOF
@@ -90,7 +90,7 @@ EOF
 # GitLab
 glab issue create \
   --title "[Discovery] <finding_title>" \
-  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'
 <template body filled in>
 EOF
@@ -154,14 +154,14 @@ Used when multiple related findings from the same probe or category are grouped
 - [ ] Quality gates pass after fixes
 ```
 
-**Labels:** `type:discovery`, `priority:<highest_severity_found>`, `area:<area>`, `status:ready`
+**Labels:** `type:discovery`, `priority::<highest_severity_found>`, `area:<area>`, `status:ready`
 
 **CLI Example:**
 ```bash
 # GitHub
 gh issue create \
   --title "[Discovery] <category> audit: <summary>" \
-  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --body "$(cat <<'EOF'
 <template body filled in>
 EOF
@@ -170,7 +170,7 @@ EOF
 # GitLab
 glab issue create \
   --title "[Discovery] <category> audit: <summary>" \
-  --label "type:discovery,priority:<level>,area:<area>,status:ready" \
+  --label "type:discovery,priority::<level>,area:<area>,status:ready" \
   --description "$(cat <<'EOF'
 <template body filled in>
 EOF

package/skills/discovery/probes-audit.md

@@ -78,7 +78,7 @@ Category: <name>
 
 **Default Severity:** High if `score_0_10 < 5`; Medium if `5 <= score_0_10 < 7`.
 
-**Labels for auto-created issues:** `type:discovery`, `area:harness` (new label — add to VCS label set if absent), `priority:high` or `priority:medium` per severity, `status:ready`.
+**Labels for auto-created issues:** `type:discovery`, `area:harness` (new label — add to VCS label set if absent), `priority::high` or `priority::medium` per severity, `status:ready`.
 
 **Skip Conditions:**
 

package/skills/discovery/probes-feature.md

@@ -147,4 +147,4 @@ verification_method: vcs-issue
 
 ---
 
-**Labels for auto-created issues:** `type:discovery`, `area:skills`, `priority:high` (High/Critical severity) or `priority:medium` (Medium severity), `status:ready`.
+**Labels for auto-created issues:** `type:discovery`, `area:skills`, `priority::high` (High/Critical severity) or `priority::medium` (Medium severity), `status:ready`.