@danmoisan/drm-copilot-mcp 1.0.26 → 1.0.27

package/resources/claude-customizations/.claude/lib/mermaid/MermaidValidation.psm1

@@ -0,0 +1,496 @@
+<#
+.SYNOPSIS
+    Structural Mermaid diagram validator (issue #491).
+
+.DESCRIPTION
+    Public entry point `Test-MermaidDiagram -Content <string>` returns a structured
+    result so a future CI-side deep check can be layered without changing the hook
+    contract:
+
+      Verdict      Valid | Invalid | NotJudged
+      DiagramType  the resolved canonical type, the declared token when the token
+                   did not resolve, or $null
+      Findings     array of { Class; Line; Message } for each detected defect
+      Warnings     array of strings, for example the keyword-drift warning
+
+    The gate's contract is "rejects the named defect classes", NOT "proves
+    validity". `Valid` means no defect of a checked class was found. The checked
+    classes are: missing or clearly non-keyword first line, misspelled diagram
+    keyword, malformed YAML frontmatter, empty or whitespace-only body,
+    unbalanced `[]` / `()` / `{}`, unterminated double-quoted string, arrow token
+    invalid for the declared type, and `subgraph`/`end` imbalance. Semantic and
+    deep-grammar errors are outside its reach; see the feature research for the
+    full "cannot catch" list.
+
+    Fail-open policy, all of which allow rather than reject:
+      1. A first-line token outside the allowlist but shaped like a plausible
+         keyword warns and allows. This is the Mermaid version-drift safety valve.
+         Only a missing or clearly non-keyword first line blocks.
+      2. Diagram types outside the deep-checked set are keyword-checked only.
+      3. A line the classifier cannot categorize is skipped, never rejected.
+      4. A statement-keyword line is exempt from arrow and bracket judgement.
+      5. A block-opening keyword line is exempt from arrow judgement.
+      6. An unverified keyword-accept row warns and declines to judge the body.
+      7. ZenUML bodies use an external plugin grammar and are keyword-checked only.
+
+    Pinned to Mermaid 11.17.0 through MermaidGrammar.psm1. Every function is pure:
+    no filesystem, subprocess, network, or wall-clock access, and no input is
+    mutated. CRLF, CR, and LF inputs produce identical verdicts because line
+    splitting is normalized once in MermaidMarkdownFences.psm1.
+#>
+
+Set-StrictMode -Version Latest
+
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'MermaidGrammar.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'MermaidLineScanner.psm1') -Force
+Import-Module (Join-Path -Path $PSScriptRoot -ChildPath 'MermaidMarkdownFences.psm1') -Force
+
+function Get-MermaidFinding {
+    <#
+    .SYNOPSIS
+        Builds one finding record for the structured validation result.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Class,
+
+        [Parameter(Mandatory)]
+        [int] $Line,
+
+        [Parameter(Mandatory)]
+        [string] $Message
+    )
+
+    return [ordered]@{ Class = $Class; Line = $Line; Message = $Message }
+}
+
+function Get-MermaidFrontmatter {
+    <#
+    .SYNOPSIS
+        Extracts a leading YAML frontmatter block from a diagram's lines.
+    .DESCRIPTION
+        Returns HasFrontmatter, IsMalformed (an opening `---` with no closing
+        `---`), Keys (the top-level `key:` names found), and BodyStartIndex (the
+        zero-based index of the first line after the frontmatter).
+
+        Frontmatter is only recognized when the first non-blank line is exactly
+        `---`, which is the documented Mermaid form.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Line
+    )
+
+    $result = [ordered]@{
+        HasFrontmatter = $false
+        IsMalformed    = $false
+        Keys           = [string[]]@()
+        BodyStartIndex = 0
+    }
+
+    $first = 0
+    while ($first -lt $Line.Count -and [string]::IsNullOrWhiteSpace($Line[$first])) {
+        $first++
+    }
+    if ($first -ge $Line.Count -or $Line[$first].Trim() -ne '---') {
+        return $result
+    }
+
+    $result.HasFrontmatter = $true
+    $keys = [System.Collections.Generic.List[string]]::new()
+    for ($index = $first + 1; $index -lt $Line.Count; $index++) {
+        if ($Line[$index].Trim() -eq '---') {
+            $result.Keys = [string[]]@($keys.ToArray())
+            $result.BodyStartIndex = $index + 1
+            return $result
+        }
+        $match = [regex]::Match($Line[$index], '^(?<key>[A-Za-z_][A-Za-z0-9_-]*)\s*:')
+        if ($match.Success) {
+            $keys.Add($match.Groups['key'].Value)
+        }
+    }
+
+    $result.IsMalformed = $true
+    $result.BodyStartIndex = $Line.Count
+    return $result
+}
+
+function Test-MermaidManagedDiagram {
+    <#
+    .SYNOPSIS
+        Returns $true when a diagram's frontmatter carries the Mermaid Chart `id:` marker.
+    .DESCRIPTION
+        `id:` in the frontmatter is what the Mermaid Chart extension writes when a
+        diagram is connected to the cloud sync workflow. A diagram carrying it must
+        not be hand-edited, so the hook uses this detector as its managed-diagram
+        guard. An `id:` key with an empty value is not treated as a marker, because
+        an unconnected placeholder should not lock the file.
+    #>
+    [CmdletBinding()]
+    [OutputType([bool])]
+    param(
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $Content
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Content)) {
+        return $false
+    }
+
+    $lines = @(Split-MermaidTextLine -Text $Content)
+    $frontmatter = Get-MermaidFrontmatter -Line $lines
+    if (-not $frontmatter.HasFrontmatter) {
+        return $false
+    }
+    if ($frontmatter.Keys -notcontains 'id') {
+        return $false
+    }
+
+    $limit = if ($frontmatter.IsMalformed) { $lines.Count } else { $frontmatter.BodyStartIndex - 1 }
+    for ($index = 0; $index -lt $limit; $index++) {
+        $match = [regex]::Match($lines[$index], '^\s*id\s*:\s*(?<value>.*)$')
+        if ($match.Success -and -not [string]::IsNullOrWhiteSpace($match.Groups['value'].Value)) {
+            return $true
+        }
+    }
+
+    return $false
+}
+
+function Get-MermaidKeywordLineIndex {
+    <#
+    .SYNOPSIS
+        Finds the index of the diagram keyword line within a body line range.
+    .DESCRIPTION
+        Skips blank lines, `%%` comments, and `%%{...}%%` directives, which may all
+        precede the keyword. Returns -1 when no candidate line exists.
+    #>
+    [CmdletBinding()]
+    [OutputType([int])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Line,
+
+        [Parameter(Mandatory)]
+        [int] $StartIndex
+    )
+
+    for ($index = $StartIndex; $index -lt $Line.Count; $index++) {
+        $scan = Get-MermaidLineScan -Line $Line[$index]
+        if ($scan.IsBlank -or $scan.IsComment -or $scan.IsDirective) {
+            continue
+        }
+        return $index
+    }
+
+    return -1
+}
+
+function Get-MermaidArrowFinding {
+    <#
+    .SYNOPSIS
+        Returns arrow findings for one scanned line of a deep-checked diagram.
+    #>
+    [CmdletBinding()]
+    [OutputType([object[]])]
+    param(
+        [Parameter(Mandatory)]
+        [System.Collections.Specialized.OrderedDictionary] $Scan,
+
+        [Parameter(Mandatory)]
+        [string] $DiagramType,
+
+        [Parameter(Mandatory)]
+        [int] $LineNumber
+    )
+
+    $findings = [System.Collections.Generic.List[object]]::new()
+    $pattern = Get-MermaidArrowPattern -DiagramType $DiagramType
+    if ([string]::IsNullOrEmpty($pattern)) {
+        return [object[]]@()
+    }
+
+    # Statement-keyword and block-opening lines carry URLs, CSS, and free text.
+    if ($Scan.Class -eq 'StatementKeyword' -or (Test-MermaidNonEdgeKeyword -Token $Scan.FirstToken)) {
+        return [object[]]@()
+    }
+
+    # For the types whose statements put free text after the first colon, arrow
+    # judgement stops at the colon.
+    $text = $Scan.ArrowText
+    if ((Test-MermaidPostColonLabelType -DiagramType $DiagramType) -and $Scan.ColonIndex -ge 0) {
+        $cut = [Math]::Min($Scan.ColonIndex, $text.Length)
+        $text = $text.Substring(0, $cut)
+    }
+
+    foreach ($token in @(Get-MermaidArrowCandidate -Text $text)) {
+        if ($token -match $pattern) {
+            continue
+        }
+        $findings.Add((Get-MermaidFinding -Class 'InvalidArrowToken' -Line $LineNumber -Message "the token '$token' is not a valid edge form for a '$DiagramType' diagram"))
+    }
+
+    return [object[]]@($findings.ToArray())
+}
+
+function Get-MermaidBodyFinding {
+    <#
+    .SYNOPSIS
+        Runs the deep structural checks over a deep-checked diagram's body.
+    .DESCRIPTION
+        Bracket balance is aggregated across the body rather than judged per line,
+        because legal Mermaid opens a brace block on one line and closes it on
+        another. Closers are clamped at zero and a closer without an opener is never
+        a finding, because a statement-keyword line such as `class Animal {` is
+        exempt from bracket counting while its closing `}` is not, and reporting
+        that as a defect would reject valid class diagrams.
+    #>
+    [CmdletBinding()]
+    [OutputType([object[]])]
+    param(
+        [Parameter(Mandatory)]
+        [AllowEmptyCollection()]
+        [AllowEmptyString()]
+        [string[]] $Line,
+
+        [Parameter(Mandatory)]
+        [int] $BodyStartIndex,
+
+        [Parameter(Mandatory)]
+        [string] $DiagramType,
+
+        [Parameter(Mandatory)]
+        [int] $LineOffset
+    )
+
+    $findings = [System.Collections.Generic.List[object]]::new()
+    $bracketStructural = Test-MermaidBracketStructuralType -DiagramType $DiagramType
+    $postColon = Test-MermaidPostColonLabelType -DiagramType $DiagramType
+    $openers = [ordered]@{
+        Square = [System.Collections.Generic.List[int]]::new()
+        Round  = [System.Collections.Generic.List[int]]::new()
+        Curly  = [System.Collections.Generic.List[int]]::new()
+    }
+    $subgraphOpen = [System.Collections.Generic.List[int]]::new()
+
+    for ($index = $BodyStartIndex; $index -lt $Line.Count; $index++) {
+        $lineNumber = $index + 1 + $LineOffset
+        $scan = Get-MermaidLineScan -Line $Line[$index]
+        if ($scan.IsBlank -or $scan.IsComment -or $scan.IsDirective) {
+            continue
+        }
+
+        foreach ($finding in @(Get-MermaidArrowFinding -Scan $scan -DiagramType $DiagramType -LineNumber $lineNumber)) {
+            $findings.Add($finding)
+        }
+
+        if ($scan.Class -ne 'StatementKeyword') {
+            $quoteText = $scan.Raw
+            if ($postColon -and $scan.ColonIndex -ge 0) {
+                $quoteText = $scan.Raw.Substring(0, [Math]::Min($scan.ColonIndex, $scan.Raw.Length))
+            }
+            if ((Get-MermaidLineScan -Line $quoteText).HasUnterminatedQuote) {
+                $findings.Add((Get-MermaidFinding -Class 'UnterminatedQuote' -Line $lineNumber -Message 'a double-quoted label is not closed on this line'))
+            }
+        }
+
+        if ($DiagramType -eq 'flowchart') {
+            if ($scan.FirstToken -eq 'subgraph') {
+                $subgraphOpen.Add($lineNumber)
+            } elseif ($scan.FirstToken -eq 'end' -and $subgraphOpen.Count -gt 0) {
+                $subgraphOpen.RemoveAt($subgraphOpen.Count - 1)
+            }
+        }
+
+        if (-not $bracketStructural -or $scan.Class -eq 'StatementKeyword') {
+            continue
+        }
+
+        foreach ($kind in @('Square', 'Round', 'Curly')) {
+            $delta = $scan.BracketDelta[$kind]
+            for ($count = 0; $count -lt $delta; $count++) {
+                $openers[$kind].Add($lineNumber)
+            }
+            for ($count = 0; $count -gt $delta; $count--) {
+                if ($openers[$kind].Count -gt 0) {
+                    $openers[$kind].RemoveAt($openers[$kind].Count - 1)
+                }
+            }
+        }
+    }
+
+    $bracketName = [ordered]@{ Square = '[]'; Round = '()'; Curly = '{}' }
+    foreach ($kind in @('Square', 'Round', 'Curly')) {
+        if ($openers[$kind].Count -gt 0) {
+            $findings.Add((Get-MermaidFinding -Class 'UnbalancedBracket' -Line $openers[$kind][0] -Message "a '$($bracketName[$kind])' bracket opened here is never closed"))
+        }
+    }
+
+    foreach ($lineNumber in $subgraphOpen) {
+        $findings.Add((Get-MermaidFinding -Class 'UnclosedSubgraph' -Line $lineNumber -Message "the 'subgraph' opened here has no matching 'end'"))
+    }
+
+    return [object[]]@($findings.ToArray())
+}
+
+function Get-MermaidResult {
+    <#
+    .SYNOPSIS
+        Builds the structured validation result from its parts.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [Parameter(Mandatory)]
+        [string] $Verdict,
+
+        [AllowNull()]
+        [AllowEmptyString()]
+        [string] $DiagramType,
+
+        [AllowEmptyCollection()]
+        [object[]] $Findings = @(),
+
+        [AllowEmptyCollection()]
+        [string[]] $Warnings = @()
+    )
+
+    return [ordered]@{
+        Verdict     = $Verdict
+        DiagramType = $DiagramType
+        Findings    = [object[]]@($Findings)
+        Warnings    = [string[]]@($Warnings)
+    }
+}
+
+function Test-MermaidDiagram {
+    <#
+    .SYNOPSIS
+        Validates one Mermaid diagram and returns the structured result.
+    .PARAMETER Content
+        The full diagram text: optional YAML frontmatter, optional directives and
+        comments, the diagram keyword line, and the body.
+    .PARAMETER LineOffset
+        Added to every reported line number. Callers validating a fenced block
+        inside a larger document pass the block's body start line minus one so the
+        reported numbers are file-relative.
+    #>
+    [CmdletBinding()]
+    [OutputType([System.Collections.Specialized.OrderedDictionary])]
+    param(
+        [AllowEmptyString()]
+        [AllowNull()]
+        [string] $Content,
+
+        [int] $LineOffset = 0
+    )
+
+    if ([string]::IsNullOrWhiteSpace($Content)) {
+        return Get-MermaidResult -Verdict 'Invalid' -DiagramType $null -Findings @(
+            (Get-MermaidFinding -Class 'EmptyDiagram' -Line (1 + $LineOffset) -Message 'the diagram is empty or contains only whitespace')
+        )
+    }
+
+    $lines = @(Split-MermaidTextLine -Text $Content)
+    $frontmatter = Get-MermaidFrontmatter -Line $lines
+    if ($frontmatter.IsMalformed) {
+        return Get-MermaidResult -Verdict 'Invalid' -DiagramType $null -Findings @(
+            (Get-MermaidFinding -Class 'MalformedFrontmatter' -Line (1 + $LineOffset) -Message 'the YAML frontmatter opens with --- but is never closed by a matching ---')
+        )
+    }
+
+    $keywordIndex = Get-MermaidKeywordLineIndex -Line $lines -StartIndex $frontmatter.BodyStartIndex
+    if ($keywordIndex -lt 0) {
+        return Get-MermaidResult -Verdict 'Invalid' -DiagramType $null -Findings @(
+            (Get-MermaidFinding -Class 'MissingDiagramType' -Line (1 + $LineOffset) -Message 'no diagram-type keyword line was found after the frontmatter, directives, and comments')
+        )
+    }
+
+    $keywordLineNumber = $keywordIndex + 1 + $LineOffset
+    $resolved = Resolve-MermaidDiagramType -FirstLine $lines[$keywordIndex]
+
+    if (-not $resolved.IsKnown) {
+        if (-not $resolved.IsPlausibleKeyword) {
+            return Get-MermaidResult -Verdict 'Invalid' -DiagramType $null -Findings @(
+                (Get-MermaidFinding -Class 'MissingDiagramType' -Line $keywordLineNumber -Message "the first line must declare a diagram type, but it begins with '$($resolved.Token)', which is not a diagram-type keyword")
+            )
+        }
+
+        # A near miss is a typo, not version drift, so it is named as a defect. The
+        # single-edit radius is what keeps this from swallowing genuinely new
+        # diagram types; see Resolve-MermaidMisspelledKeyword.
+        if (-not [string]::IsNullOrEmpty($resolved.MisspelledOf)) {
+            return Get-MermaidResult -Verdict 'Invalid' -DiagramType $resolved.Token -Findings @(
+                (Get-MermaidFinding -Class 'MisspelledDiagramType' -Line $keywordLineNumber -Message "the first line declares '$($resolved.Token)', which is one character away from the diagram keyword '$($resolved.MisspelledOf)'. Correct the keyword spelling.")
+            )
+        }
+
+        # Fail-open item 1: the version-drift safety valve. An out-of-date keyword
+        # allowlist costs a warning, never a false rejection.
+        return Get-MermaidResult -Verdict 'NotJudged' -DiagramType $resolved.Token -Warnings @(
+            "'$($resolved.Token)' is not in the Mermaid $(Get-MermaidGrammarVersion) diagram-type allowlist. It is shaped like a diagram keyword, so the body was not judged. Confirm the keyword against the Mermaid documentation and update .claude/lib/mermaid/MermaidGrammar.psm1 if it is a newer diagram type."
+        )
+    }
+
+    $diagramType = $resolved.Type
+    if (-not $resolved.IsVerified) {
+        # Fail-open item 6: the keyword resolves but its exact form was never
+        # verified against the pinned documentation, so the body is not judged.
+        return Get-MermaidResult -Verdict 'NotJudged' -DiagramType $diagramType -Warnings @(
+            "'$($resolved.Token)' is a keyword-accept entry whose exact first-line form was not verified against the pinned Mermaid $(Get-MermaidGrammarVersion) documentation, so the body was not judged."
+        )
+    }
+
+    if (-not (Test-MermaidDeepCheckedType -DiagramType $diagramType)) {
+        # Fail-open items 2 and 7: free-text and plugin-backed grammars are
+        # keyword-checked only.
+        return Get-MermaidResult -Verdict 'Valid' -DiagramType $diagramType
+    }
+
+    $bodyStartIndex = $keywordIndex + 1
+    $hasBody = $false
+    for ($index = $bodyStartIndex; $index -lt $lines.Count; $index++) {
+        $scan = Get-MermaidLineScan -Line $lines[$index]
+        if (-not ($scan.IsBlank -or $scan.IsComment -or $scan.IsDirective)) {
+            $hasBody = $true
+            break
+        }
+    }
+    if (-not $hasBody) {
+        return Get-MermaidResult -Verdict 'Invalid' -DiagramType $diagramType -Findings @(
+            (Get-MermaidFinding -Class 'EmptyDiagramBody' -Line $keywordLineNumber -Message "the '$diagramType' diagram declares a type but has no statements after the keyword line")
+        )
+    }
+
+    $findings = @(Get-MermaidBodyFinding -Line $lines -BodyStartIndex $bodyStartIndex -DiagramType $diagramType -LineOffset $LineOffset)
+    if ($findings.Count -gt 0) {
+        return Get-MermaidResult -Verdict 'Invalid' -DiagramType $diagramType -Findings $findings
+    }
+
+    return Get-MermaidResult -Verdict 'Valid' -DiagramType $diagramType
+}
+
+# Get-MermaidFenceBlock and Split-MermaidTextLine are re-exported from the nested
+# MermaidMarkdownFences module so a consumer that imports this one module gets the whole
+# diagram-extraction surface. A nested module's commands are visible to this module only
+# unless they are named here explicitly.
+Export-ModuleMember -Function `
+    Get-MermaidFenceBlock, `
+    Split-MermaidTextLine, `
+    Get-MermaidFinding, `
+    Get-MermaidFrontmatter, `
+    Test-MermaidManagedDiagram, `
+    Get-MermaidKeywordLineIndex, `
+    Get-MermaidArrowFinding, `
+    Get-MermaidBodyFinding, `
+    Get-MermaidResult, `
+    Test-MermaidDiagram

package/resources/claude-customizations/.claude/rules/mermaid.md

@@ -0,0 +1,142 @@
+---
+paths:
+  - "**/*.mmd"
+  - "**/*.mermaid"
+description: Mermaid diagram authoring standards, validation mandate, and managed-diagram constraint.
+---
+
+# Mermaid Diagram Standards
+
+This rule governs Mermaid diagrams in this repository. The authoring workflow, the per-type syntax
+references, and the generation recipes live in `.claude/skills/mermaid-diagram/SKILL.md`; this file
+carries the constraints.
+
+The pinned Mermaid documentation version for the whole surface is **11.17.0**
+(https://mermaid.js.org/intro/syntax-reference.html). The keyword allowlist and the per-type arrow
+token sets are a snapshot of that version, recorded in `.claude/lib/mermaid/MermaidGrammar.psm1`.
+
+## Diagram File Conventions
+
+- A standalone diagram belongs in a `.mmd` file (`.mermaid` is also recognized). The whole file is
+  one diagram: optional YAML frontmatter, optional `%%{init: ...}%%` directives, the diagram-type
+  keyword line, then the body.
+- A diagram embedded in prose belongs in a fenced ` ```mermaid ` block in the Markdown file that
+  discusses it. GitHub renders such fences natively in Markdown, pull requests, and issues.
+- The first line after any frontmatter, directive, comment, and blank line must be the
+  diagram-type keyword. Mermaid keywords are case-sensitive: `C4Context`, `stateDiagram-v2`, and
+  `sequenceDiagram` are exact spellings.
+- Mermaid has no backslash escape. To place a double quote inside a label, use the `#quot;` entity;
+  a backslash before a closing quote closes the span rather than escaping it.
+- Do not commit a diagram file as a test fixture. Diagram fixtures belong in PowerShell
+  here-strings inside the Pester suites, because a `PreToolUse` hook fires on the write of its own
+  fixtures.
+
+## Validation Mandate
+
+Every diagram written to this repository passes through the structural gate
+`.claude/hooks/enforce-mermaid-validation.ps1` on `Write` and `Edit`. The gate is registered in the
+`Write|Edit` matcher of `.claude/settings.json` and runs the dependency-free validator in
+`.claude/lib/mermaid/`.
+
+What the gate rejects, naming the defect class and the line number:
+
+- a missing, non-keyword, or misspelled first-line diagram keyword;
+- YAML frontmatter that opens with `---` and is never closed;
+- an empty or whitespace-only diagram body;
+- unbalanced `[]`, `()`, or `{}` on structural lines of a bracket-structural diagram type,
+  computed by a quote-aware scanner;
+- an unterminated double-quoted label;
+- an arrow or edge token that is not valid for the declared diagram type;
+- a `subgraph` with no matching `end`.
+
+What the gate does NOT do, stated plainly so "validated" is not overclaimed: it does not prove a
+diagram renders, and it performs no parse. Semantic and deep-grammar errors — an undefined node
+reference in a `click` statement, a malformed gantt date, an invalid `classDef` property, a wrong
+`section` structure, an invalid participant reference — are outside its reach. A `Valid` verdict
+means no defect of a checked class was found, nothing more.
+
+Where the gate declines to judge, it allows. An unknown but keyword-shaped first-line token is
+allowed with a drift warning, because the allowlist is a pinned snapshot and an out-of-date
+allowlist must cost a warning rather than a false rejection. Diagram types outside the deep-checked
+set (flowchart, sequence, class, state, ER) are keyword-checked only. An `Edit` payload carries a
+fragment rather than the resulting file, so the syntax check is not attempted and the next `Write`
+catches a regression.
+
+## Managed Diagrams: Do Not Hand-Edit
+
+A `.mmd` or `.mermaid` file whose frontmatter carries an `id:` key is connected to the Mermaid Chart
+cloud sync workflow:
+
+```yaml
+---
+id: cbd9e9ba-a2cb-47c5-a98e-8c28a753428d
+---
+```
+
+Such a diagram must not be hand-edited. The next sync overwrites the edit, so the change is lost
+and the diff is misleading in the meantime. The gate denies both `Write` and `Edit` on a file whose
+on-disk frontmatter carries a non-empty `id:`, with the reason token
+`MERMAID_MANAGED_DIAGRAM_BLOCKED:`.
+
+To change a managed diagram, use the Mermaid Chart sync workflow in VS Code (Mermaid Chart
+extension: **Sync Diagram with Mermaid**, then **Review Mermaid Sync**) and pull the synced result.
+Connecting a diagram, reviewing a sync, and accepting or rejecting synced commits are interactive
+VS Code actions; they are human steps, not automatable from a Claude Code session.
+
+The opt-out marker below never suppresses this constraint: the marker applies to fenced blocks in
+Markdown, and the managed-diagram gate is keyed on diagram file paths.
+
+## Opt-Out Marker for Deliberate Counter-Examples
+
+Documentation legitimately quotes invalid Mermaid to demonstrate a defect. Placing the exact HTML
+comment on the line immediately preceding a fence suppresses validation for that one block:
+
+```text
+<!-- mermaid-validator: ignore -->
+```
+
+Rules for the marker:
+
+- The comment text is exactly `mermaid-validator: ignore`, case-sensitive. Whitespace around the
+  line and inside the comment delimiters is permitted.
+- It must sit on the line immediately before the opening ` ```mermaid ` fence, with no intervening
+  line, blank or otherwise.
+- Its scope is exactly one block. A second counter-example needs its own marker; an unmarked
+  invalid block in the same file is still denied.
+- It applies only to fenced blocks in Markdown. Diagram files have no opt-out: a diagram file is by
+  definition a diagram.
+- A ` ```mermaid ` fence nested inside an outer, longer fence is already treated as example text
+  rather than a diagram and needs no marker.
+
+## Out of Scope: The Non-Portable Extension Mechanisms
+
+The Copilot instruction pack at `.github/instructions/mermaid.instructions.md` relies on VS Code
+extension mechanisms that no Claude Code session can invoke. They are recorded here so a later
+reader does not read the omission as an oversight. The same record appears in
+`.claude/skills/mermaid-diagram/SKILL.md`.
+
+| Mechanism | Why it is not ported | What replaces it |
+| --- | --- | --- |
+| `mermaid-diagram-validator` LM tool | A VS Code Language Model API tool contributed by the extension; not an MCP tool and not callable from a Claude session | The structural gate in this repository, weaker than a real parse and documented as such |
+| `mermaid-diagram-preview` LM tool, `mermaidChart.preview` | A VS Code webview | The conditional rendering paths in the skill; GitHub renders fences natively |
+| `get-syntax-docs-mermaid` LM tool | A VS Code LM API tool | The bundled per-type references under the skill, pinned to 11.17.0, with a documented `WebFetch` fallback to mermaid.js.org |
+| The sixteen `mermaidChart.*` command IDs | Each needs the VS Code command API, an active editor, and the extension host | Portable capabilities are ported by substitution: validation to the hook, generation to the skill recipes, preview to conditional rendering, sync cooperation to the `id:` guard. The command IDs themselves are not ported |
+| `@mermaid-chart` Copilot Chat slash commands | Copilot Chat participants do not exist on the Claude surface | The eight generation intents are skill recipe sections |
+| `mermaidChart.repairDiagram`, `mermaidChart.improveDiagram` | Mermaid AI credits and extension UI | The gate's specific defect messages plus ordinary editing. No credit-consuming path exists on this surface, so there is nothing to warn about |
+| `mermaidChart.login`, `logout`, `connectDiagramToMermaidChart`, `syncDiagramWithMermaid`, `reviewAppCommits`, `regenerateDiagramWithMermaidAI` | Interactive OAuth and extension UI against the Mermaid Chart cloud | Human steps in VS Code. The automatable half is in scope and delivered: the `id:` managed-diagram guard above |
+| `mermaidChart.createMermaidFile`, `mermaidChart.installAiSkills` | Extension UI; the second is the Copilot-surface distribution mechanism | Creating a diagram file is an ordinary `Write`. The Claude distribution mechanism is the bundled resources mirror plus the `pack-manifests/core.json` entry |
+| Deep `mmdc`/Chromium validation | Chromium-backed, seconds-level latency, no validate-only mode; unfit for a per-write gate | Recorded as an optional CI-side follow-up consuming the validator's structured result |
+
+## Example
+
+A minimal valid diagram file, frontmatter included:
+
+```mermaid
+---
+title: Request handling
+---
+flowchart LR
+    A[Client] --> B{Authenticated}
+    B -->|yes| C[Handler]
+    B -->|no| D[Reject]
+```