(chore): upgrade claude

[drmoisan]

chore(claude): sync .claude runtime — Python-free enforcement hooks, TaskMaster blast-radius map, Mermaid gate

Summary

• Enforcement hooks no longer require a Python interpreter.validate-orchestrator-output.ps1, enforce-discovery-artifact-gate.ps1, and validate-discovery-artifact-gate.ps1 previously shelled out to python -m scripts.dev_tools.…. TaskMaster has no scripts/dev_tools tree, so those calls could never succeed here. Validation now runs in-process through 15 new PowerShell modules under .claude/lib/.
• config/blast-radius.json is retargeted to this repository. The module map is replaced with TaskMaster's 20 actual projects (QuickFiler, ToDoModel, UtilitiesCS, TaskVisualization, … plus each .Test sibling) in place of the reference repo's four location buckets, and a new mandate_reads exclusion list stops policy-file citations from being counted as write contention.
• New structural Mermaid validation gate, registered on the Write|Edit matcher: one hook (enforce-mermaid-validation.ps1, 390 lines), four .claude/lib/mermaid/ modules, an authoring skill with nine per-type references, and .claude/rules/mermaid.md.
• Parallel-orchestration surface hardened: the cohort barrier becomes per-edge rather than whole-cohort, max_concurrency widens from 1..8 to 1..32, manifest invariant M8 (expected_conflict_components) is added, and enforce-epic-merge-gate.ps1 gains a third allow-branch for per-item parallel merges.
• Coverage policy corrected for unevaluable thresholds: the >= 75% branch-coverage gate no longer applies to PowerShell (Pester) or bash (kcov), which measure no branch coverage. Line coverage and the no-regression rule are unchanged, and no file leaves the coverage denominator.
• New plan-acceptance-gate rules G1–G6 (.claude/rules/plan-acceptance-gates.md) that reject atomic-plan acceptance conditions which cannot fail.
• VSTO publish version bumped 1.0.0.25 → 1.0.0.27 (TaskMaster/TaskMaster.csproj).

Why

The context bundle carries no PR Intent fields and no feature-doc excerpts, so the motivation below is read from the diff itself rather than from an authored intent record.

This is a push-down sync of the .claude runtime from the reference repository into TaskMaster. Two of the incoming changes fix conditions that were structurally broken in this repository specifically:

1. Portability. The .claude/** payload ships to destinations with no guaranteed Python, Poetry, or scripts/dev_tools. TaskMaster is exactly such a destination — scripts/dev_tools does not exist here — so every hook path that invoked python -m scripts.dev_tools.… either failed obscurely or blocked the operation it gated. The replacement modules are destination-runtime PowerShell ports measured row by row against the Python reference's parity inventory.
2. Blast-radius fitness. The inbound config/blast-radius.json previously carried the reference repo's module map (claude-runtime, config, docs, tests). Buckets keyed on where a file lives rather than on which subsystem owns it match nearly every work item, so a level that always fires suppresses concurrency while carrying no information. The map is now keyed on TaskMaster's real project boundaries.

The coverage-policy change removes a threshold that could not be evaluated: Pester reports command (instruction) and line coverage only, so a >= 75% branch gate on PowerShell had no measurable input. The vendored prose is explicit that this is a capability limit on an unevaluable threshold, not a licence to exclude files from measurement.

What Changed

Portable validation modules (new, 15 files)

Area	Modules
Orchestrator-state parity	OrchestratorStateCheckpointValue, OrchestratorStateCompletionChecks, OrchestratorStateReceipts, OrchestratorStateModelReceipts, OrchestratorStateRoutingContract, OrchestratorStateRoutingMatrix, OrchestratorStateUnconditional, OrchestratorStateCodexModelReceipts, OrchestratorStateCodexTopologyReceipts
Discovery artifacts	DiscoveryValidation (schema validation via Test-Json -SchemaFile)
Codex routing	CodexDeployment, CodexTopology
Blast radius	BlastRadiusNormalization
Mermaid	MermaidGrammar, MermaidLineScanner, MermaidMarkdownFences, MermaidValidation

OrchestratorState.psm1 and OrchestratorStateCompletion.psm1 were modified to compose the new siblings; the split exists so no module exceeds the repository's 500-line file cap.

Hooks

• enforce-mermaid-validation.ps1 — newPreToolUse gate on Write|Edit, wired in .claude/settings.json.
• validate-orchestrator-output.ps1 — default invoker names no interpreter and starts no subprocess. Adds Test-OrchestratorCheckpointStructure, a type-scoped check (exists / parses / object root) for epic-orchestrator-state and parallel-orchestrator-state, where the Python reference exits 2 under this hook's flag pair and runs no checks at all. The standard-checkpoint required-key block and the model-routing gate are deliberately not applied to those types.
• enforce-epic-merge-gate.ps1 — third allow-branch: a gh pr merge --merge is authorized from the parallel checkpoint when route_id == "parallel", the command's explicit PR number matches an items[] entry, and that item's merge_status == "ci_green". The PR-number parser is broadened additively to accept gh pr merge --merge 410 (flag before number) while preserving the original gh pr merge 410 capture verbatim. Every other case still fails closed with EPIC_MERGE_GATE_BLOCKED.
• enforce-discovery-artifact-gate.ps1, validate-discovery-artifact-gate.ps1 — Invoke-DiscoveryValidatorExe keeps its name, -ValidatorArgs <string[]> signature, and @{ ExitCode; Output } return shape so existing mocks bind; only the body changes. Both now require PowerShell 7.4+.

Rules and policy

• Added: .claude/rules/mermaid.md, .claude/rules/plan-acceptance-gates.md.
• Modified: quality-tiers.md, general-unit-test.md, powershell.md — branch-coverage exemption for PowerShell and bash. parallel-orchestration.md — M8, the 1..32 bound with its constraint analysis, the blast-radius contention doctrine, and the parallel merge-gate branch. typescript.md — ESLint stack, architecture-boundary pointer, property/mutation/golden-test obligations, determinism rules, and coverage aligned to the uniform 85/75 tier rule. csharp.md — toolchain prose rewritten (see Backward Compatibility).

Skills and agents

• Added: mermaid-diagram skill plus nine per-type reference files (flowchart, sequence, class, state, er, c4, gantt, pie, other-types).
• Modified: atomic-plan-contract gains a mandatory wrap-tolerant assertion-authoring section; evidence-and-timestamp-conventions gains the optional ExpectedExitCode field with exact-spelling, first-wins, and per-file semantics; feature-promotion-lifecycle gains check 4b (the promoted record must survive new_active_feature_folder); feature-review-workflow, powershell-qa-gate, and agents/feature-review.md carry the branch-coverage exemption; parallel-plan, parallel-orchestrate, parallel-add, parallel-remove, and agents/parallel-*.md carry the per-edge barrier and bounded preparation waves; agents/typescript-engineer.md pins model: sonnet.
• .claude/lib/bash/parallel-manifest-validate.sh implements M8 and raises PM_MAX_CONCURRENCY to 32.

Not changed

No production C# source, no test project, no CI workflow, and no .github/** file is touched. The only non-.claude changes are config/blast-radius.json and the ApplicationVersion bump.

Architecture / How It Fits Together

.claude/settings.json (PreToolUse: Write|Edit, Bash)
|
+- enforce-mermaid-validation.ps1 --> .claude/lib/mermaid/
| MermaidMarkdownFences -> MermaidLineScanner -> MermaidGrammar -> MermaidValidation
| Test-MermaidDiagram => { Verdict = Valid | Invalid | NotJudged; DiagramType; Findings }
|
+- enforce-epic-merge-gate.ps1 --> checkpoint-only decision, three branches
| child (epic_mode) | epic (epic_merge_pr.ci_gate) | parallel (items[].merge_status)
|
+- validate-orchestrator-output.ps1 --> .claude/lib/orchestrator-state/
| orchestrator-state => full completion parity
| epic-/parallel-orchestrator-state => structural check only
| unknown type => fail closed
|
+- enforce/validate-discovery-artifact-gate.ps1 --> .claude/lib/discovery-validation/
Invoke-DiscoveryArtifactValidation => @{ ExitCode; Output }

Two contracts are load-bearing across the whole set:

• Success is silent. A passing validation returns ExitCode = 0 with an emptyOutput. The callers deny on a non-zero exit code or on non-empty output, so any success chatter inside a validator would deny a passing validation.
• Fail closed. A missing file, unreadable content, invalid JSON, a non-object root, or an unrecognized artifact type all deny. An unrecognized type must never read as a clean pass.

config/blast-radius.json feeds .claude/lib/blast-radius/: mandate_reads entries are stripped from the harvest by derive_blast_radiusand from the plan-side extraction by validate_blast_radius, so both stay self-consistent against a radius derived from the same plan. The key is optional and fail-closed — omitting it excludes nothing and reproduces prior behaviour exactly.

Verification

Completed

Check	Command	Result
CI (branch head 1dab2523)	gh pr checks 575	5 / 5 pass — actionlint, format-check, build-analyzers, build-nullable, mstest-coverage
C# formatting	dotnet tool run csharpier check .	exit 0 — 10,487 files checked, no diffs
PowerShell parse	[Parser]::ParseFile over all .claude/lib/**/*.psm1 and .claude/hooks/*.ps1	59 files parsed, 0 failures
Module load	Import-Module on OrchestratorStateCompletion, DiscoveryValidation, CodexTopology, CodexDeployment, BlastRadius	all import clean
Mermaid validator behaviour	Test-MermaidDiagram on a balanced and an unbalanced flowchart TD	Valid / flowchart and Invalid / 1 finding
Blast-radius config	ConvertFrom-Json on config/blast-radius.json	parses; 20 modules, 6 mandate_reads, 3 shared_surfaces
Environment prerequisite	$PSVersionTable.PSVersion	7.6.5 — satisfies the new PowerShell 7.4+ floor

Not verified in this PR

• No Pester suite exercises the 23 changed or added .psm1 modules. TaskMaster carries Pester tests only under tests/scripts/vscode/, and no CI job runs Pester at all. The parity test suites live in the upstream reference repository; the modules land here untested. The checks above establish that they parse, import, and behave correctly on a smoke sample — not that they are at parity.
• The parallel merge-gate branch, the discovery gates, and the mermaid hook were not exercised end-to-end through an actual PreToolUse invocation.
• No behavioural verification of the ExpectedExitCode evidence field or the G1–G6 plan gates (the latter's enforcement lives in scripts/dev_tools/, which this repository does not have).

Recommended before merge

dotnet tool run csharpier check .
msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU"/p:EnableNETAnalyzers=true /p:EnforceCodeStyleInBuild=true
msbuild TaskMaster.sln /t:Rebuild /m /p:Configuration=Debug "/p:Platform=Any CPU"/p:TreatWarningsAsErrors=true
# Exercise the newly registered Write|Edit gate before relying on it:
pwsh -NoProfile -File .claude/hooks/enforce-mermaid-validation.ps1 # with a representative CLAUDE_TOOL_INPUT

Backward Compatibility / Migration Notes

• PowerShell 7.4+ is now required by both discovery gates (Test-Json -SchemaFile Draft 2020-12). The local environment is 7.6.5; any consumer on 7.0–7.3 loses those gates.
• No public C# API, project reference, or build target changes. Compile-level compatibility is unaffected.
• Function seams preserved deliberately.Invoke-DiscoveryValidatorExe keeps its name, parameter, and return shape; Get-EpicMergeGateCommandPrNumber preserves its original regex as the first branch. Existing mocks and Should -Invoke assertions continue to bind.
• max_concurrency widening is one-directional. A manifest valid under 1..8 stays valid under 1..32. The epic surface is untouched: max_parallel_features remains 1..8.
• M8 is key-gated. A manifest without expected_conflict_components produces a byte-identical error list to before. When present, the value must be a YAML block sequence — the bash subset parser rejects flow collections such as members: [101, 102].
• Two local hardenings in .claude/rules/csharp.md and .claude/skills/csharp-qa-gate/SKILL.md were overwritten by the generic upstream text, namely (a) the direct references to .github/workflows/_build-analyzers.yml and _build-nullable.yml, and (b) the requirement to capture an MSBuild file log and record zero occurrences of Skipping target "CoreCompile". The substantive /t:Rebuild and "do not pass /p:Nullable=enable" guidance survives in both files and in CLAUDE.md, but the CoreCompile skip-count evidence obligation is gone. Restoring it is a follow-up.
• ApplicationVersion 1.0.0.25 → 1.0.0.27 affects the VSTO publish manifest, not the assembly contract.

Risks and Mitigations

Risk	Assessment	Mitigation
A defect in the new Write/Edit mermaid gate blocks all file writes	Highest-impact risk in the change: the hook is unconditionally registered and runs on every Write and Edit.	The validator smoke-tests correctly and allows where it declines to judge (unknown keyword-shaped tokens pass with a drift warning). Rollback is a two-line revert of the .claude/settings.json hook entry.
Ported modules diverge from the Python reference	Real and unmeasured here — no Pester suite runs against them in this repository.	The prose records the parity inventory row by row. The pragmatic mitigation is that these code paths were already non-functional in TaskMaster (no scripts/dev_tools), so a divergent port is still strictly better than a hook that cannot run.
Vendored prose cites reference-repo issue numbers that collide with unrelated TaskMaster issues	Confirmed. The changed rule files cite #472, #475, #487, #489, and #491 as provenance. In TaskMaster those numbers are five open, unrelated QuickFiler/ItemViewer bugs. A reader following them lands on the wrong ticket.	No auto-close bullet is emitted from those numbers (see GitHub Auto-close). Follow-up: strip or re-label them in the vendored prose.
Doc/config divergence in the module map	parallel-orchestration.md still describes the reference repo's seven subsystem modules (mcp-server, benchmarks, poshqc, powershell-dev-tools, codex-runtime, config, schemas); the shipped config/blast-radius.json declares 20 TaskMaster projects. The prose does not describe the config.	Config is authoritative and is what the modules read; the prose is narrative. Follow-up to reconcile.
mandate_reads over-excludes	artifacts/** is excluded as a mandate read while the same rule file states artifacts/ is not a known top-level segment for a subtree claim.	The exclusion is fail-closed and read-only in effect: a genuine write must still be enumerated explicitly, and detect_escaped_paths catches an actual write against observed diff evidence rather than plan prose.
Dangling references in typescript.md	The rewritten rules reference .dependency-cruiser.cjs, run-jest.cjs, package.json, and quality-tiers.yml — none of which exist in TaskMaster (architecture-boundaries.md does exist).	Forward-looking, consistent with the No-COM / Office.js target architecture. Inert until a TypeScript surface lands; no gate reads them today.
parallel-plan still names a Python diagnostic	The skill instructs poetry run python -m scripts.dev_tools.parallel_lane_assertion, which cannot run here.	The diagnostic is advisory-only and never blocks; a failure to run costs a diagnostic, not a gate. Follow-up to port or remove.

Rollback: the change is one commit (1dab2523) touching only .claude/**, config/blast-radius.json, and one .csproj line. git revert 1dab2523 restores prior behaviour with no build or data implications.

Review Guide

64 files, +9,191 / −441. Roughly 8,700 of the added lines are new PowerShell modules and skill reference documents; the behavioural surface is much smaller than the line count suggests.

Suggested order:

1. .claude/settings.json (5 lines) — the only file that changes what actually executes. Confirm the mermaid hook registration and the skill permission.
2. config/blast-radius.json (72 lines) — the sole non-.claude behavioural change. Confirm the 20 project buckets match this repository's layout.
3. .claude/hooks/enforce-epic-merge-gate.ps1 (+109/−5) — security-relevant: it authorizes gh pr merge. Focus on Test-ParallelCheckpointAllowsMerge and the broadened PR-number regex; verify every path still fails closed.
4. .claude/hooks/validate-orchestrator-output.ps1 (+117/−46) — the interpreter removal and the type-scoped structural check.
5. .claude/hooks/enforce-mermaid-validation.ps1 (390 lines, new) — read with .claude/lib/mermaid/MermaidValidation.psm1. Highest blast radius if wrong.
6. Rules diffs — quality-tiers.md, general-unit-test.md, powershell.md (the coverage-policy change, roughly 10 lines total), then csharp.md (the overwrite noted above), then parallel-orchestration.md.
7. Everything else — the 15 new .psm1 modules, the 10 mermaid skill and reference documents, and the remaining skill prose. Largest diffs, lowest per-line risk; each module carries a header comment stating its parity scope.

Low-signal by volume: .claude/skills/mermaid-diagram/references/*.md (9 files, roughly 530 lines) are pure syntax reference. .claude/lib/orchestrator-state/*.psm1 (9 new files, roughly 3,000 lines) are mechanical row-by-row ports.

Follow-ups

• Restore the CoreCompile skip-count evidence obligation in .claude/skills/csharp-qa-gate/SKILL.md, and the CI workflow filename references in .claude/rules/csharp.md, that this sync overwrote.
• Strip or re-label the reference-repo issue citations (#472, #475, #487, #489, #491) in the vendored rule and module prose so they cannot be mistaken for TaskMaster issues.
• Reconcile the parallel-orchestration.md module-map narrative with the shipped config/blast-radius.json.
• Establish a Pester job for .claude/lib/** so ported modules are verified in this repository rather than only upstream, or record an explicit exemption.
• Port or remove the scripts/dev_tools/parallel_lane_assertion invocation in parallel-plan, and the plan_gate_discrimination enforcement path referenced by .claude/rules/plan-acceptance-gates.md.

GitHub Auto-close

• None