feat: introduce Batch and Merge Skills

.claude/skills/EXAMPLE-REPORT.md

@@ -0,0 +1,160 @@
+# Reporting Example
+
+An illustrative report showing the two-layer format used by both skills. The numbers,
+issue references, and SHAs below are **fictional** — this file demonstrates *format and
+evidence discipline*, nothing more. It is not a record of real work.
+
+For the rules themselves see `batch-skill/SKILL.md` and `merge-skill/SKILL.md`.
+
+---
+
+# Human Report
+
+## v1.0 Phase 1 — Batch Execution
+
+**Result**: 4 of 4 issues completed and merged
+**Execution**: serial (parallel safety not CONFIRMED for any pair)
+
+| Issue | Title | PR | Result |
+|---|---|---|---|
+| #7 | Diagnostic SSOT | #121 | Merged |
+| #8 | Regression Tests | #122 | Merged |
+| #9 | RT Semantics | #123 | Merged |
+| #10 | Interprocedural Analysis | #124 | Merged |
+
+**Changes**: 12 files, +1,247 / −89 lines, 3 new test files
+**Verification**: build passed, 234/234 tests passed, CI passed for each PR HEAD
+**Approvals**: 1 effective human approval per PR, each bound to that PR's final HEAD
+
+**Notes for the reader**
+
+- Issues #7–#10 form a dependency chain, so they ran serially. Parallelism was never
+  eligible here.
+- Each merge was executed only after an explicit human approval of that specific HEAD.
+
+**Next**: Phase 2 (#11–#13). Their independence is not yet CONFIRMED, so plan for serial
+execution until it is.
+
+---
+
+# AI Report
+
+## Verification SHA binding
+
+Every item below is bound to the SHA named beside it. Evidence gathered for a different
+SHA is not reused.
+
+| PR | Verification SHA |
+|---|---|
+| #121 | `abc1234` |
+| #122 | `bcd2345` |
+| #123 | `cde3456` |
+| #124 | `def4567` |
+
+## CONFIRMED
+
+Observed from a trusted source during this run.
+
+**Git state** (per issue, at its verification SHA)
+- Branch, base commit, and result commit identified for each of #7–#10
+- Working tree clean at each verification point — no uncommitted or untracked files
+- Each feature branch ancestry to the base branch established
+
+**Build and test**
+- Build succeeded for each verification SHA
+- 234/234 tests passed; 0 failed, 0 skipped
+- Analyzer suites: RT 24 passed, LVP 18 passed, FIF 12 passed
+
+**CI**
+- CI concluded successfully for each PR
+- CI HEAD == PR HEAD confirmed for each PR (see the SHA table above)
+- No required check left pending, queued, or in progress
+- Stale runs at superseded commits were identified and excluded
+
+**Reviews**
+- Required approvals: 1 (source: `.kiro/merge.config.json` → `requiredApprovals`)
+- Effective human approvals: 1 per PR, each submitted against that PR's final HEAD
+- Stale approvals ignored: 0
+- Bot reviews excluded: 4 — automated review tooling, not counted as human approval
+- Outstanding `CHANGES_REQUESTED`: none
+
+**Mergeability**
+- No conflicts with the base branch for any PR
+- Host-reported merge state clean for each PR
+
+**File conflict analysis** — read from the actual branch diffs, not inferred from issue
+descriptions, because the batch conflict gate requires CONFIRMED evidence:
+- #7 touches `Analyzer.cs`, `DiagnosticCatalog.cs`, localization files
+- #8 touches `Tests/`, `TestData/`, `TestBase.cs` — no overlap with #7
+- #9 touches `ReferentialTransparencyAnalyzer.cs`, `SemanticAnalyzer.cs` — no overlap with #7, #8
+- #10 touches `InterproceduralAnalyzer.cs`, `CallGraphBuilder.cs` — no overlap with #7–#9
+- Shared mutable configuration touched by more than one issue: none
+- Shared public contract touched by more than one issue: none
+
+**Human approval**
+- Explicit human approval recorded per PR, naming the PR and its SHA, before execution
+
+**Post-merge**
+- Each PR state `MERGED`; merge commit identified for each
+- Base branch contains the expected result; base branch HEAD verified after each merge
+- Post-merge CI on the base branch concluded successfully
+
+## INFERRED
+
+Reasonable conclusions from the confirmed facts. **None of these opened a gate.** They
+are recorded for context, and where they bore on execution they pushed toward the safe
+side.
+
+- **Dependency chain satisfied** — inferred from execution order: #7 completed first,
+  then #8, #9, #10, each after its blocker merged.
+- **Phase 2 (#11–#13) may be independent** — inferred from the analyzers they are
+  scoped to. This did **not** authorise parallelism. Independence must be CONFIRMED on
+  every dimension before #11–#13 run in parallel; until then they run serially.
+
+## UNVERIFIED
+
+Not established. Each would block any gate that depended on it.
+
+- Long-term performance impact of the #10 interprocedural changes — not measured
+- Downstream consumer compatibility beyond the repository's own test suite — not exercised
+
+Neither is a gate item for this batch, so neither blocked it. They are reported rather
+than omitted so the reader can see the edge of what was checked.
+
+## Gate results
+
+Batch gate, per issue: all items CONFIRMED → each PR a merge candidate.
+
+Merge gate, per PR:
+
+```text
+Layer 1 — technical gates:  all CONFIRMED  → MERGE CANDIDATE
+Layer 2 — human approval:   EXPLICIT HUMAN APPROVAL recorded
+Verdict:                    MERGED, post-merge verification passed
+```
+
+Passing layer 1 produced a candidate only. Every merge required the layer 2 approval.
+
+---
+
+## What a blocked report looks like
+
+The same structure, with the verdict and the blocking reason stated plainly. Blocked is
+a normal, correct outcome — not a failure of the report.
+
+```text
+PR:                 #125
+Verification SHA:   ef56789
+CI:                 success, CI HEAD == PR HEAD (ef56789)
+Mergeability:       clean, no conflicts
+Required approvals: 1
+Effective human approvals: 0
+Bot reviews excluded: 1
+
+Verdict: MERGE BLOCKED
+  - Requires 1 effective human approval on ef56789, has 0
+```
+
+Note what this report does **not** do: it does not describe the PR as ready, safe, or
+merely awaiting a formality. Zero human approvals means blocked, and the passing CI does
+not soften that.

.claude/skills/README.md

@@ -0,0 +1,119 @@
+# PureSharp Batch & Merge Skills
+
+Two skills coordinate multi-issue development and safe integration for the PureSharp
+v1.0.0 roadmap.
+
+| Skill | Specification | Responsibility |
+|---|---|---|
+| **Batch Skill** | `batch-skill/SKILL.md` | Orchestrate multiple issues: dependencies, parallel safety, execution graph, aggregation |
+| **Merge Skill** | `merge-skill/SKILL.md` | Verify a PR against merge gates, enforce the human approval boundary, verify after merge |
+
+## Scriptless by design
+
+Each `SKILL.md` is an **executable specification and the single source of truth** for its
+skill. There are no helper scripts, and none may be added as a requirement.
+
+This is deliberate. The skills define **which facts must be established**, not **which
+commands to run** — so they carry no dependency on PowerShell version, shell dialect,
+path separator, file encoding, exit-code convention, or any one CLI being installed.
+
+They run unchanged on Windows, Linux, macOS, and WSL. No PowerShell, Bash, Python, or
+Node runtime is required.
+
+Establish each fact with whichever trusted source the environment offers — a GitHub
+connector, `gh`, the GitHub API, `git` for local facts, or the repository's own build and
+test tooling. If **no** available source can establish a required fact, the result is
+**UNVERIFIED**, and UNVERIFIED blocks. Skipping a check because a tool is missing is
+never acceptable.
+
+Porting the removed helper scripts into another language would reintroduce exactly the
+coupling this design removes, and is not a valid change.
+
+## Using the skills
+
+Invoke a skill and follow its specification. The Merge Skill's default mode is
+verification only: it reads state, changes nothing, and is safe to run at any time.
+
+```text
+Batch Skill   → analyse issues, decide execution order, run, aggregate, report
+Merge Skill   → verify a PR against the gates, report MERGE CANDIDATE or MERGE BLOCKED
+```
+
+Neither skill merges anything on its own. See `WORKFLOW.md` for the end-to-end flow.
+
+## Safety principles
+
+These are fixed policy. No configuration, flag, or argument relaxes them.
+
+1. **Fail closed.** Any error, ambiguity, or missing evidence blocks.
+2. **Explicit human approval before every merge.** Technical verification success is not
+   permission to merge. The approval comes from one of exactly two sources — a
+   third-party GitHub `APPROVED` review, or, for a self-authored PR in a repository that
+   requires no third-party review, an explicit out-of-band approval bound to the exact
+   HEAD SHA. **Repository policy always wins**: where the repository requires approving
+   reviews, nothing here bypasses it. A self-authored PR is never recorded as carrying
+   its author's GitHub approval.
+3. **Evidence is bound to an exact commit.** Stale evidence never satisfies a gate; a new
+   push invalidates all prior evidence, approvals included.
+4. **UNVERIFIED blocks. INFERRED never opens a gate.**
+5. **Parallel execution requires proof of safety**, not merely the absence of known
+   danger. Serial is the safe default.
+6. **Auto-merge is never enabled**; the base branch is never force-pushed or pushed to
+   directly.
+
+## Evidence classification
+
+Both skills use these three labels and no others.
+
+| Label | Meaning | May open a gate? |
+|---|---|---|
+| **CONFIRMED** | Actually observed from a trusted source this run | Yes |
+| **INFERRED** | Reasonable conclusion from confirmed facts, not itself observed | No — may only support a decision that fails safe |
+| **UNVERIFIED** | Not established, including "the tool was unavailable" | No — blocks |
+
+**Golden rule**: never claim success for something you have not verified.
+
+## Configuration
+
+Both configuration files carry **data only**. Behaviour lives in the `SKILL.md` files.
+
+| File | Keys |
+|---|---|
+| `.kiro/merge.config.json` | `requiredApprovals`, `mergeMethod`, `deleteBranchAfterMerge` |
+| `.kiro/batch.config.json` | `maxParallelTasks` |
+
+A missing file, malformed JSON, an unknown key, or a value out of range is a **CONFIG
+ERROR** and blocks. Safety policy is deliberately absent from both schemas so it cannot
+be switched off, and configuration can only make a gate stricter, never weaker.
+
+## Files
+
+```text
+.claude/skills/
+├── README.md              (this file — overview, invocation, safety principles)
+├── WORKFLOW.md            (end-to-end workflow: batch → PR → review → merge)
+├── EXAMPLE-REPORT.md      (reporting example)
+├── batch-skill/
+│   └── SKILL.md           (batch specification — SSOT)
+└── merge-skill/
+    └── SKILL.md           (merge specification — SSOT)
+
+.kiro/
+├── batch.config.json
+└── merge.config.json
+```
+
+## Project context
+
+The skills support the PureSharp v1.0.0 roadmap tracked in **Issue #6**. The roadmap's
+phases, issue membership, and target dates live in the GitHub issues — deliberately not
+duplicated here, where a second copy would silently go stale.
+
+## See also
+
+- `WORKFLOW.md` — end-to-end workflow
+- `EXAMPLE-REPORT.md` — reporting example
+- `batch-skill/SKILL.md`, `merge-skill/SKILL.md` — the specifications themselves
+- Issue #18 — Batch and Merge Skills
+- Issue #6 — PureSharp v1.0.0 roadmap
+- `.kiro/steering/` — project guidance documents