Add finishing-cldk-work mode skill (#29)

* feat: add finishing-cldk-work mode skill

* docs: correct Application import path in release gate command

Author: rahlk

skills/codeanalyzer-backend/references/packaging-and-release.md

@@ -0,0 +1,81 @@
+---
+name: finishing-cldk-work
+description: Use when implementation on a CLDK branch is complete and the work needs verification, merge, release, documentation updates, and issue closeout — before claiming any CLDK work is done.
+---
+
+# Finishing CLDK work
+
+The ladder's exit. Every other rung — `designing-cldk-changes`,
+`maintaining-cldk`, `codeanalyzer-backend`, `cldk-sdk-frontend` — terminates
+here. Nothing is "done" until it has passed through this gate: gates green,
+a real ship decision, release mechanics if warranted, and closeout.
+
+## Entry Preconditions
+
+Implementation is complete on a branch. Most arrivals come from
+`maintaining-cldk`, carrying a **propagation verdict** in hand (the
+required output of its propagation sweep — a list of follow-on repos, or
+`none` with its reasoning). Arrivals from `codeanalyzer-backend` or
+`cldk-sdk-frontend` carry no verdict of their own; treat their Terminal
+State handoff as "implementation complete, gates not yet re-run here."
+Either way, do not start from a bare "it's done" claim with no artifact
+behind it.
+
+## Verification Gates
+
+Which commands to run depend on the repo type — analyzer, SDK, or docs —
+see the full matrix in `references/release-gates.md`.
+
+<HARD-GATE>
+No success claim, no tag, no release, no 'done' without running the gate
+commands NOW and reading their output. 'Passed earlier' is not evidence.
+</HARD-GATE>
+
+A same-day CI run, a teammate's "LGTM," or your own memory of an earlier
+pass are all the same failure shape: assurance detached from a command you
+just watched execute. Re-run the gate on the exact commit you're about to
+act on.
+
+## Ship Decision
+
+Passing gates only tells you the branch is mergeable — it does not tell you
+whether to release. Decide explicitly:
+
+- **Forces a release:** a behavior change reaches users (a bug fix, a new
+  field, a new accessor), or a downstream pin needs to move (an SDK's
+  `codeanalyzer-<lang>==X` needs the fix that just landed).
+- **Merge-only, no release:** docs-only changes, internal refactors with no
+  observable behavior change, test-only changes. Merge and stop — cutting a
+  release train for these is manufacturing release noise, not shipping
+  value. The one exception: if docs are themselves published from a tagged
+  release (a docs-site build keyed to a version), a "docs-only" change can
+  still need one — check before assuming not.
+
+## Release Mechanics
+
+Once a release is warranted, mechanics differ by repo type — full detail in
+`references/packaging-and-release.md`:
+
+- **Analyzer** (`codeanalyzer-<lang>`) — a tag-triggered pipeline: PyPI thin
+  wheel, GitHub Release binaries, and a Homebrew formula push, all cut from
+  one `vX.Y.Z` tag in lockstep.
+- **SDK** (`python-sdk`, `typescript-sdk`, …) — bump the analyzer version
+  pin to the just-released version, then the SDK's own release.
+
+Never tag off a stale local build; the tag is what the pipeline trusts.
+
+## Closeout
+
+Docs updates, issue/epic bookkeeping, and following the propagation verdict
+through — full etiquette in `references/docs-and-closeout.md`. In brief:
+update the surfaces that describe what changed, close the child issue(s)
+this work resolves, tick the epic's checklist if one exists, and for every
+repo the propagation verdict listed, file the follow-on issue before
+stopping — a verdict that lists a repo and gets no issue is a dropped
+thread, not a closed one.
+
+## Terminal State
+
+finishing-cldk-work is the ladder's exit. If the propagation verdict listed
+follow-on repos, each becomes a new maintaining-cldk entry (file the issues
+before stopping).

skills/finishing-cldk-work/SKILL.md

@@ -0,0 +1,74 @@
+# Docs and closeout
+
+The last mile: making the docs match what actually shipped, closing the paperwork, and honoring
+the propagation verdict `maintaining-cldk` handed off. Skipping this is how a merged, released,
+gate-green change still leaves the org in a stale or half-tracked state.
+
+## Docs surfaces
+
+Three surfaces, each with its own staleness question — check all three, not just the one that
+comes to mind first:
+
+- **Repo READMEs** — the analyzer's or SDK's own `README.md`: supported languages/levels, install
+  instructions (`pip install codeanalyzer-<lang>`, `brew install codeanalyzer-<lang>`), CLI flag
+  docs, version badges. A new level, a new accessor, or a new install channel that isn't reflected
+  here is invisible to anyone who doesn't read source.
+- **CLAUDE.md / AGENTS.md / GEMINI.md agent guides** — each repo's own agent-facing conventions
+  (branch naming, test layout, commit style). These drift when a repo's structure changes (a new
+  package, a renamed workflow) but the fix rarely thinks to touch them.
+- **The docs site** (`docs` repo, `codellm-devkit.info`) — two live fronts on the same repo: `main`
+  (mkdocs) and the `astro` branch (Astro/Starlight redesign). A behavior-preserving bug fix rarely
+  needs a docs change; a fix that changes an error message, a CLI flag's behavior, a documented
+  limitation, or a version number usually does. Check whether the change reaches one front or both
+  — don't assume parity between them.
+
+If the release just cut changed a public surface (new field visible through an accessor, new CLI
+flag, new facade method), at least one of these three needs an update. "No behavior changed for
+users" is the only clean exemption, and it should already have been established in the Ship
+Decision step.
+
+## Issue and epic closeout etiquette
+
+- **Close the child issue(s)** this work resolves, with a comment naming the merge commit / release
+  tag that resolved it — not a bare "done."
+- **Tick the epic's checklist**, if this work traces to one (`designing-cldk-changes`'s epic + child
+  issue structure, `skills/designing-cldk-changes/references/epic-and-issue-templates.md`). A child
+  issue closing is what advances the epic's `CHILDREN` checklist; go edit the epic, don't leave it
+  for someone else to notice the child closed.
+- **Don't close the epic itself** until every child on its checklist is closed and its own
+  Definition of Done (gates green across every affected repo, versions pinned in lockstep, docs
+  updated) is genuinely satisfied — not just the child you personally worked.
+- For work with no epic (most `maintaining-cldk` entries — a bug fix or small feature stands alone),
+  closing its single issue with the resolving commit/release reference is the whole of closeout on
+  this axis.
+
+## Propagation-verdict follow-through
+
+`maintaining-cldk`'s propagation sweep hands off a **required** verdict in this exact shape:
+
+> **Propagation verdict:** \<list of follow-on repos + why\> | none, because \<reason\>.
+
+Reading that verdict here is not optional, and neither is acting on it:
+
+- **If the verdict is `none`**, confirm its reasoning is still legible (it should already show its
+  work — what was checked, why each came back negative) and stop; there is nothing further to file.
+- **If the verdict lists follow-on repos**, file a tracking issue for each one **before** declaring
+  this work closed out. Each filed issue is the seed of a new `maintaining-cldk` entry — this is
+  exactly what the Terminal State means by "each becomes a new maintaining-cldk entry." A verdict
+  that names `codeanalyzer-java` and `python-sdk` but produces zero new issues is a verdict that was
+  read and then ignored — the most common way this rung's work silently goes incomplete.
+- Link each follow-on issue back to the work that surfaced it, so the trail from "we found this
+  while fixing X" to "here's the tracked fix for Y" survives past this conversation.
+
+## Definition of done (closeout)
+
+- [ ] Every gate in `references/release-gates.md` that applies to this repo ran on the commit being
+  shipped, and its output was read.
+- [ ] The ship decision was made explicitly (release vs merge-only) and, if a release was cut, its
+  mechanics followed `references/packaging-and-release.md` including version lockstep.
+- [ ] Docs surfaces checked against the actual change — README, agent guides, docs site — updated or
+  explicitly ruled not-needed.
+- [ ] Child issue(s) closed with a reference to the resolving commit/tag; epic checklist ticked if
+  one exists.
+- [ ] Propagation verdict re-read; every listed follow-on repo has a filed issue, or the verdict was
+  `none` with visible reasoning.

skills/finishing-cldk-work/references/docs-and-closeout.md

@@ -0,0 +1,108 @@
+# Packaging & release: tag-triggered automation
+
+Release mechanics for both halves of the ladder that reach this rung: an **analyzer**
+(`codeanalyzer-<lang>`) cutting its own distribution, and an **SDK** (`python-sdk`,
+`typescript-sdk`, …) picking up a new analyzer release via a pin bump and cutting its own. Neither
+is a manual, one-off act — both are `git tag vX.Y.Z && git push origin vX.Y.Z` triggering a CI
+workflow that does the rest. Never publish by hand; if the tag-push doesn't produce the artifact,
+fix the workflow rather than uploading around it.
+
+## Analyzer release: the thin-PyPI-binary model
+
+The analyzer repo builds its self-contained binary for every supported platform, then a **tag-
+triggered** `.github/workflows/release.yml` publishes it three ways in one coordinated run. The
+reference implementation is `codeanalyzer-ts` (`packaging/python/` + `.github/workflows/release.yml`)
+— mirror it for any new analyzer.
+
+1. **Thin PyPI package `codeanalyzer-<lang>`** — one platform-tagged wheel per OS/arch, each
+   carrying the prebuilt binary under `_bin/` and exposing `bin_path()`. This is what the Python SDK
+   `pip`-depends on.
+2. **Raw binaries as GitHub Release assets**, with a SHA256 checksum per artifact — for consumers
+   that can't `pip install`, and what the TypeScript SDK downloads directly.
+3. **A Homebrew formula** (`Formula/codeanalyzer-<lang>.rb`) pushed to the shared tap
+   `codellm-devkit/homebrew-tap`, so end users get `brew install codeanalyzer-<lang>`.
+
+**Two wheel shapes.** Compiled-binary analyzers (TS, Go, Rust, C++, JVM) ship a platform-tagged
+wheel (`py3-none-<platform>`) carrying the binary, no usable sdist. A **Python** analyzer (e.g.
+`codeanalyzer-python`) is the exception: the wheel carries importable Python code, is platform-
+independent, and is imported in-process — no binary, no `bin_path()`.
+
+**Build strategy** is a per-language decision, not a detail: single-host cross-compilation (Bun,
+Go, Rust — one CI job emits every platform binary) when the toolchain cross-compiles cleanly, or a
+native-runner build matrix (GraalVM `native-image`, clang with per-target sysroots — one CI leg per
+`(os, arch)` fanning in to one publish job) when it can't. State which one applies in the analyzer
+README's Architecture & Tooling section.
+
+### The release workflow, in order
+
+Trigger on `v*.*.*` tags (+ `workflow_dispatch`); `permissions: contents: write` (+ `id-token: write`
+for PyPI OIDC):
+
+1. Verify the tag version matches the analyzer manifest; gate on the analyzer's own test suite
+   **first** — on failure, delete the just-pushed tag (`git push --delete origin <tag>`) so a broken
+   build leaves no half-released version behind.
+2. Build the platform wheels (single-host: one job runs the per-target loop; matrix: one leg per
+   `(os, arch)`, then a fan-in job).
+3. `auditwheel repair` Linux wheels to a manylinux policy (cover musllinux or document it
+   unsupported); emit a SHA256 checksum per artifact.
+4. **Smoke-test every wheel before publishing** — install on a clean runner, run
+   `codeanalyzer-<lang> --help` or a tiny fixture analysis.
+5. Extract raw binaries into `release-bins/`.
+6. Publish the GitHub Release with the binaries + checksums as assets.
+7. Publish the wheels to PyPI as `codeanalyzer-<lang>` — Trusted Publishing (OIDC), no long-lived
+   token; `skip-existing: true` so a re-run is idempotent.
+8. **Separate `homebrew` job** (`needs: release`, fed `release-bins/` via artifact — not a rebuild):
+   generate the formula, push it to `codellm-devkit/homebrew-tap` with a `HOMEBREW_TAP_TOKEN` PAT.
+   Isolating this job matters: it's the step most likely to fail (cross-repo PAT), and if it rode
+   inside the publish job a token failure would mark an otherwise-successful PyPI+Release run red
+   and unrecoverable-without-a-new-tag.
+
+For a **Python analyzer**, drop steps 2–5 (compile/extract) and publish one pure wheel + sdist.
+Ship no sdist for compiled analyzers, or one whose build fails with a clear "no prebuilt binary for
+this platform" message — never let pip silently fall back to a from-source compile.
+
+Tag the release `vX.Y.Z` with real notes: a hand-curated *Keep a Changelog* block (`### Added` /
+`### Changed` — mark **BREAKING** inline / `### Fixed`) plus an auto-generated "Detailed Changes"
+block. Don't ship a release with an empty body.
+
+## SDK release: pin bump, then its own release
+
+An SDK never re-publishes an analyzer's artifact — it depends on it. Once an analyzer release
+exists (PyPI + Release binaries, above), the SDK's release is a two-step act:
+
+1. **Bump the pin** to the just-released version — the Python SDK's `pyproject.toml`
+   `dependencies` (`codeanalyzer-<lang>==X.Y.Z`) and its `[tool.backend-versions]` table; the
+   TypeScript SDK's equivalent pin to the same tag. This is its own PR, reviewed and merged before
+   any tag.
+2. **Cut the SDK's own release** the same tag-triggered way: a `chore(release): X.Y.Z` PR bumps the
+   SDK's own version + changelog (this alone ships nothing), then `git tag vX.Y.Z && git push
+   origin vX.Y.Z` triggers the SDK's release workflow — its own test suite, its own PyPI/npm
+   publish, and (if wired) a docs-repo dispatch to regenerate the API reference. A version bump PR
+   with no tag pushed is a no-op release-wise; don't mistake merging it for shipping.
+
+A pin bump with no analyzer release behind it, or an analyzer release with no consumer ever bumping
+the pin, both leave the fix unreachable by users — "the fix is released" and "the fix is
+consumable" are different claims; the pin is the gate between them.
+
+## Version lockstep (the one rule that bites)
+
+Keep the version identical across all of these for a given analyzer release, or pip resolves a
+mismatched binary:
+
+- the analyzer manifest (`package.json` version, or the build version for Go/Rust/JVM);
+- `packaging/python/pyproject.toml`'s `project.version` **and** `__init__.py`'s `__version__`;
+- the Python SDK pin — both `dependencies` and `[tool.backend-versions]`;
+- the TypeScript SDK pin — the Release tag/binary filename it downloads;
+- the Homebrew formula's `version` and asset URLs/checksums — the release workflow regenerates this
+  every tag; don't hand-edit it.
+
+## How each SDK consumes the artifact
+
+- **Python SDK** — resolves the binary in priority order: `analysis_backend_path` →
+  `$CODEANALYZER_<LANG>_BIN` → `codeanalyzer_<lang>.bin_path()` (the pip package) → an in-tree
+  bundled fallback. (Python analyzer: `import codeanalyzer_<lang>`, run in-process.)
+- **TypeScript SDK** — cannot consume a PyPI wheel; resolves `analysisBackendPath` →
+  `$CODEANALYZER_<LANG>_BIN` → the GitHub Release asset binary.
+
+This is the contract `cldk-sdk-frontend` wires against — publish accordingly, and don't change the
+resolution order without updating both sides.

skills/finishing-cldk-work/references/packaging-and-release.md

@@ -0,0 +1,55 @@
+# Release gates — the verification matrix
+
+What "run the gate commands NOW" (the SKILL.md HARD-GATE) means, concretely, per repo type. This
+file is a **summary matrix** for the ship decision — it names which gates exist and the commands
+that invoke them. It does not restate their pass/fail criteria or fixture design; those live in the
+two authoritative references and must stay in sync with them, not be re-derived here:
+
+- **Analyzer repos** (`codeanalyzer-<lang>`) — full gate detail in
+  `skills/codeanalyzer-backend/references/testing-and-validation.md`.
+- **SDK repos** (`python-sdk`, `typescript-sdk`, …) — full gate detail in
+  `skills/cldk-sdk-frontend/references/sdk-testing.md`.
+
+Re-run every gate in this matrix that applies to the repo you're finishing, on the exact commit
+you're about to tag or merge. A green run from an earlier commit, an earlier session, or someone
+else's machine does not satisfy the HARD-GATE.
+
+## Analyzer repos (`codeanalyzer-<lang>`)
+
+| Gate | Command | What it proves |
+| --- | --- | --- |
+| Fixture suite | `go test ./...` (or the ecosystem equivalent — `pytest`, `mvn test`, `cargo test`) | Per-level unit/fixture assertions pass, up to the analyzer's current `max_level`. |
+| Schema conformance | Run the CLI at the target level (`codeanalyzer-<lang> -i testdata/fixture -a <1\|2\|3\|4> -o out/`), then `python -c "import json; from cldk.models.cpg.models import Application; Application(**json.load(open('out/analysis.json')))"` | Output validates against the shared CPG models — not just "the binary ran." |
+| Monotonicity | Run `-a 1`, `-a 2`, `-a 3`, `-a 4` on the same fixture; diff the JSON | `json(-a 1) ⊆ json(-a 2) ⊆ json(-a 3) ⊆ json(-a 4)` — no level rewrites a lower level's facts. |
+| Determinism | `codeanalyzer-<lang> -i testdata/fixture -j 1 -o j1/` vs `... -j <N> -o jN/`; diff | `-j N` output is byte-identical to `-j 1`. |
+| Cross-projection | Compare `--emit neo4j` node/edge counts (at full depth) against the JSON at `max_level` | The two projections agree, modulo documented `HAS_*` containment edges. |
+
+The full per-level assertions (named expected call-graph edges, exact PDG-slice sets, cache
+round-trip tests, the two-tier identity gate) are in `testing-and-validation.md` — this matrix only
+names the commands, not what "green" means field by field.
+
+## SDK repos (`python-sdk`, `typescript-sdk`, …)
+
+| Gate | Command | What it proves |
+| --- | --- | --- |
+| Mocked | `pytest tests/test_<lang>_analysis.py` (or `bun test` for the TS SDK) | Facade/view logic is correct given a fixture `analysis.json`; includes the public-API-stability assertion. |
+| E2E | `pytest tests/test_<lang>_e2e.py` | The real binary produces conformant output end to end; skips cleanly when the binary is absent, must pass when it's on `PATH`. |
+| Backend-contract | `pytest tests/test_<lang>_backend_contract.py` | The concrete backend implements every `<Lang>AnalysisBackend` ABC method (local/Neo4j parity). |
+| Client-analysis (if L3/L4 exposed) | the slice/taint gate tests named in `sdk-testing.md § Client-analysis gates` | Slice and taint queries over the analyzer's graph match hand-computed expected sets. |
+
+All three core tiers must be green before a merge is even considered mergeable, independent of
+whether a release follows.
+
+## Docs repos (`docs`)
+
+| Gate | Command | What it proves |
+| --- | --- | --- |
+| Build | `mkdocs build --strict` (the `main` mkdocs front) and/or `npm run build` (the `astro` branch's Astro/Starlight front) | The site builds cleanly on the content you're about to publish — a broken build is not a docs-only no-op. |
+
+Both fronts are the same repo (`skills/maintaining-cldk/references/repo-map.md`) — check whether the
+change reaches one or both before treating a single green build as sufficient.
+
+## Reading the result
+
+"Green" means every applicable row above ran on the current commit and its output was read, not
+assumed. A gate you didn't run is not a gate you passed.

skills/finishing-cldk-work/references/release-gates.md

@@ -31,7 +31,7 @@ pinned by a version-locked dependency (`python-sdk`'s
 reach a single SDK user until:
 
 1. the analyzer cuts a release with the fix (per
-   `skills/codeanalyzer-backend/references/packaging-and-release.md`), and
+   `skills/finishing-cldk-work/references/packaging-and-release.md`), and
 2. the pinning SDK bumps its dependency to that version.
 
 State explicitly whether a pin bump is needed, and in which SDK(s). "The fix