neohaskell
diff --git a/‎.claude/skills/neohaskell-pipeline/SKILL.md‎
Lines changed: 19 additions & 5 deletions b/‎.claude/skills/neohaskell-pipeline/SKILL.md‎
Lines changed: 19 additions & 5 deletions
diff --git a/‎.claude/skills/neohaskell-retrospective-miner/SKILL.md‎
Lines changed: 68 additions & 0 deletions b/‎.claude/skills/neohaskell-retrospective-miner/SKILL.md‎
Lines changed: 68 additions & 0 deletions
diff --git a/‎.gitattributes‎
Lines changed: 6 additions & 0 deletions b/‎.gitattributes‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎.github/workflows/checks.yml‎
Lines changed: 16 additions & 0 deletions b/‎.github/workflows/checks.yml‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎.github/workflows/claude.yml‎
Lines changed: 3 additions & 1 deletion b/‎.github/workflows/claude.yml‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎.github/workflows/dod.yml‎
Lines changed: 56 additions & 0 deletions b/‎.github/workflows/dod.yml‎
Lines changed: 56 additions & 0 deletions
diff --git a/‎.github/workflows/revert.yml‎
Lines changed: 60 additions & 0 deletions b/‎.github/workflows/revert.yml‎
Lines changed: 60 additions & 0 deletions
@@ -8,7 +8,7 @@ description: Orchestrate a NeoHaskell change end-to-end through the spec-gated p
 Exactly **two human gates**: spec approval (draft PR) and final PR review.
 Everything between them is mechanical or agent-run, resumable from
 `.pipeline/state.json`, and telemetered. Stage names below are the telemetry
-schema v2 canon (`telemetry/SCHEMA.md`) — state, telemetry lines, and this
+schema v3 canon (`telemetry/SCHEMA.md`) — state, telemetry lines, and this
 skill share one vocabulary.
 
 ## Stage flow
@@ -19,13 +19,16 @@ intake ─ localize ─ spec ─▶ DRAFT PR ══ GATE 1 (maintainer) ══
 ```
 
 1. **intake** — `./dev pipeline init --run-id YYYY-MM-DD-NNN --request issue#N
-   --branch <branch>`; `scripts/telemetry.py` run start. Restate the request;
+   --branch <branch>`; `./dev telemetry start`. Restate the request;
    ambiguity that changes the contract → one clarifying question NOW (cheap
    here, a wrong PR later).
 2. **localize** — `neohaskell-localizer` skill. Output: capability IDs +
    `touches:`/`files:`/`uses:` lists → `./dev pipeline set plan.touches …`
    etc. The plan is now BINDING: resume never re-plans; a wrong plan parks
    the run (`wrong-localization`) and re-enters from intake, visibly.
+   As you consult each aid (alias, capability, signature), log it:
+   `./dev telemetry consult --asset <kind>:<name>` (e.g. `alias:http-transport`)
+   — this feeds the miner's PRUNE of never-consulted assets.
 3. **spec** — copy `docs/changes/TEMPLATE.md` → `NNN-slug.md` (next 3-digit
    number). Contract delta in signatures vocabulary; criteria C1…Cn each
    naming its proving test AND level (`unit|integration|acceptance` — a
@@ -56,7 +59,9 @@ intake ─ localize ─ spec ─▶ DRAFT PR ══ GATE 1 (maintainer) ══
    hspec-discovered).
 8. **implement** — `neohaskell-implementer` skill; repair loop via
    `./dev check` (never `cabal build` in the loop); max 2 repair rounds per
-   error, then the failure policy below.
+   error, then the failure policy below. Log the aids you actually use
+   (`./dev telemetry consult --asset hot-card:Text.toLower`,
+   `phrasebook:task-validation`, …) so never-consulted assets surface as PRUNE.
 9. **verify** — in order, no skipping:
    a. criteria tests green at their DECLARED levels (`./dev test "<pattern>" <suite>`)
    b. targeted regression: `./dev spec-check --plan <spec>` →
@@ -69,7 +74,7 @@ intake ─ localize ─ spec ─▶ DRAFT PR ══ GATE 1 (maintainer) ══
 11. **ci** — watch checks; bot comments triaged (fix real findings; push
     back with evidence on wrong ones). Merge is the maintainer's.
 
-After merge: `scripts/telemetry.py` finish (outcome `ok`), golden archive
+After merge: `./dev telemetry finish` (outcome `ok`), golden archive
 (`telemetry/golden/<run_id>/`: request.md, spec.md, final.diff, verdict.md,
 transcript.md).
 
@@ -91,10 +96,19 @@ pipeline succeeding at honesty, not failing at work. Labels are the closed
 taxonomy (SCHEMA.md); `other` requires `failure_note` and a weekly-review
 reclassification.
 
+**Closing a non-`ok` run carries the class-fix (Phase 6, enforced).**
+`./dev telemetry finish --outcome {parked,failed} --failure-label <l>
+--asset-delta <type>:<destination>` — the delta is the fix for the *class*
+(a new alias, phrasebook entry, hlint rule, hook, hot-card line…) that ships
+alongside the retry. `none:<reason>` is the honest escape when no asset applies;
+the emitter refuses to close a failed/parked run without one.
+
 ## Resume contract
 
 `./dev pipeline status` → resume at the recorded stage with the recorded
 plan. Never re-derive `touches:`/`files:`/`uses:` on resume. If reality
 contradicts the plan (file moved, API changed under you), park with
 `wrong-localization` — the asset fix (alias, capability, extension point)
-ships with the retry, per the failure→asset-delta protocol (Phase 6).
+ships with the retry, per the failure→asset-delta protocol (ADR-0068). Log the
+aids you consult while working (`./dev telemetry consult --asset
+<kind>:<name>`) so the weekly miner can PRUNE what nothing uses.
@@ -0,0 +1,68 @@
+---
+name: neohaskell-retrospective-miner
+description: Weekly retrospective mining of pipeline telemetry into ≤5 validated asset-delta recommendations. Use at the weekly telemetry review, once real runs have accumulated in telemetry/runs.jsonl. Reads the deterministic digest, proposes recommendations under a closed contract, and records the ones that pass.
+---
+
+# Retrospective miner (weekly learning loop)
+
+The judgement half of Phase 6's learning loop (ADR-0068). The deterministic half —
+gathering runs, computing the digest, and enforcing the recommendation contract —
+is `./dev retrospect`; this skill decides *what to recommend*. **Activation
+gate:** run this only once `telemetry/runs.jsonl` holds real runs (it has one
+dummy line today); with no data there is nothing to mine.
+
+## Procedure
+
+1. **Digest.** `./dev retrospect --since <YYYY-MM-DD of the week>` → the markdown
+   digest (outcomes, failure labels, stage times, invented-API trend vs the
+   first-5-runs baseline, waiting-on-human, assets-consulted frequency, bench
+   pointer). This is your evidence base — do not recall, transcribe.
+2. **Find friction.** From the digest + the week's golden stage summaries
+   (`telemetry/golden/<run_id>/`), name concrete friction: an invented API that
+   recurred, a stage repeatedly over its time-box, a failure label clustering, an
+   asset nothing consulted.
+3. **Propose ≤5 recommendations**, each under the closed contract:
+   `{week, friction, evidence:[run:stage,…], delta_type, destination, estimated_saving_s}`.
+4. **Record the survivors.** `./dev retrospect --record '<json>'` per recommendation
+   — the harness re-checks the contract and appends to
+   `telemetry/recommendations.jsonl`, or rejects with the failed rule. Do not
+   hand-edit that file.
+
+## The contract (the harness enforces all of this — internalize it, don't fight it)
+
+- **Cited friction + measured cost (rule a):** `friction` is a real observation;
+  `estimated_saving_s` is a positive, measured number. No counterfactual "this
+  might help" — those are hypotheses, not findings, and are discarded.
+- **≥2 independent runs (rule b):** `evidence` must cite the same friction across
+  **two or more distinct run_ids**. One-off friction is noise; act on recurrence.
+- **Closed taxonomy (rule c):** `delta_type` ∈ `alias | extension-point |
+  phrasebook | hot-card | hlint-rule | hook | cli-utility | skill-edit |
+  telemetry-label | PRUNE | none`. A proposal that needs a *new* asset kind or a
+  new CLI utility is an ontology change — surface it to the maintainer in the
+  review, never `--record` it.
+- **Validation over time (rule d):** an implemented delta is `validated` against
+  its claimed metric over subsequent weeks; no movement makes it a `PRUNE`
+  candidate in turn. The weekly review flips `status`/`validated` with
+  `./dev retrospect --set '<week>' '<friction-substr>' --status implemented|pruned
+  [--validated true|false]` — the sanctioned rewriter, so the file stays
+  append-plus-gated-edit, never hand-edited.
+- **Removal is first-class (rule e):** the digest's "assets consulted" frequency
+  plus the asset inventory surface never-consulted assets — recommend `PRUNE`.
+
+## Destinations (delta_type → the real file the fix lands in)
+
+`alias` → `codemap/capabilities.yaml` · `extension-point` → `codemap/extension-points.yaml`
+· `phrasebook` → `codemap/phrasebook.md` · `hot-card` → `codemap/api-hot.md`
+· `hlint-rule` → `.hlint.yaml` (skill: `neohaskell-dialect-rules`) · `hook` →
+`.claude/hooks/*` · `cli-utility` → `scripts/*` (+ a `./dev` verb) · `skill-edit`
+→ `.claude/skills/*/SKILL.md` · `telemetry-label` → `telemetry/SCHEMA.md` (a
+schema bump) · `PRUNE` → delete the unused asset · `none` → the `destination`
+field carries the justification.
+
+## Output of the weekly review
+
+The review picks **1–2** recorded recommendations to implement that week (the
+maintainer's call); the rest stay `proposed` for re-evaluation. The instance-fix
+and the class-fix ship together (`./dev telemetry finish --asset-delta` already
+recorded the class-fix for each failed run this week — the miner generalizes
+across runs, it does not replace the per-run delta).
@@ -1,3 +1,9 @@
 
 # Use bd merge for beads JSONL files
 .beads/issues.jsonl merge=beads
+
+# Append-only pipeline ledgers: parallel worktree pipelines append concurrently,
+# so union-merge (a git built-in — no driver install needed) keeps both sides'
+# lines instead of conflicting. run_id uniqueness is guarded in telemetry.py start.
+telemetry/runs.jsonl merge=union
+telemetry/recommendations.jsonl merge=union
@@ -82,6 +82,22 @@ jobs:
         env:
           BASE_REF: ${{ github.base_ref }}
         run: ./dev spec-check --reviews-pr "origin/${BASE_REF}"
+      # Changelog gate: at PR-ready, every changed spec must have a CHANGELOG.md
+      # entry (breaking ones with a migration note) — the changelog is generated,
+      # not hand-written (Phase 6, task 3).
+      - name: Changelog entries present (PR-ready only)
+        if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: ./dev changelog --check "origin/${BASE_REF}"
+      # DoD criterion-test gate: at PR-ready, every criterion in a changed spec
+      # must name a proving test that RESOLVES (a real .hurl or *.hs spec module)
+      # — a criterion can't cite a test that was never written (Phase 6, task 1).
+      - name: Criterion proving-tests resolve (PR-ready only)
+        if: github.event_name == 'pull_request' && github.event.pull_request.draft == false
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: ./dev spec-check --criteria-tests "origin/${BASE_REF}"
 
   expectations:
     name: expectation guard (test-contract diff)
 
@@ -18,9 +18,11 @@ jobs:
     # author-association check makes that signal unforgeable: comments from
     # anyone who is not an org OWNER/MEMBER are ignored entirely (which also
     # closes the standing hole of any passer-by invoking the action).
+    # A `/revert` comment is the kill switch (revert.yml), NOT a @claude trigger —
+    # excluded here so the two workflows stay disjoint even for `/revert @claude`.
     if: |
       (
-        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+        (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') && !startsWith(github.event.comment.body, '/revert')) ||
         (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
         (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
         (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
 
@@ -0,0 +1,56 @@
+# Definition-of-done gate (pipeline Phase 6, task 1) — POST-MERGE, NOTIFY-ONLY.
+#
+# Watches the post-merge suites on `main`: both "Test" (Linux: doctest + all
+# nhcore suites incl. the acceptance test-hurl job) and "Test macOS" (Darwin
+# subset). If EITHER concludes `failure` on a push to `main`, the merge is
+# flagged as a **revert-candidate** and a notification is posted. NB: both
+# workflows carry a `paths:` filter, so a pure-tooling merge (only scripts/,
+# docs/, telemetry/, .claude/) triggers neither and this gate correctly no-ops
+# for it — there is no compiled surface to regress.
+# It NEVER auto-reverts (ADR-0068); the kill switch (`/revert`, revert.yml) is a
+# separate, deliberate maintainer action.
+name: dod
+
+on:
+  workflow_run:
+    workflows: ["Test", "Test macOS"]
+    types: [completed]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  flag:
+    if: >-
+      github.event.workflow_run.event == 'push' &&
+      github.event.workflow_run.head_branch == 'main' &&
+      github.event.workflow_run.conclusion == 'failure'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Flag the merge as a revert-candidate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+          WORKFLOW: ${{ github.event.workflow_run.name }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+        run: |
+          set -euo pipefail
+          # Resolve the PR that produced this commit from the commit→PRs association
+          # (exact), falling back to the last "#NNN" in the squash subject.
+          NUM=$(gh api "repos/${REPO}/commits/${SHA}/pulls" -q '.[0].number' 2>/dev/null || true)
+          if [ -z "${NUM}" ]; then
+            MSG=$(gh api "repos/${REPO}/commits/${SHA}" -q '.commit.message' | head -1)
+            NUM=$(printf '%s' "$MSG" | grep -oE '#[0-9]+' | tail -1 | tr -d '#' || true)
+          fi
+          BODY=$(printf '%s' "⚠️ **DoD gate**: the \`${WORKFLOW}\` suite failed on \`main\` after this merged (\`${SHA}\`) — the change is not green at its declared levels. Marked **revert-candidate**. Verify the criteria, or trigger the kill switch by commenting \`/revert\`. Notify-only — nothing was reverted. Run: ${RUN_URL}")
+          if [ -n "${NUM}" ]; then
+            gh label create revert-candidate --color B60205 --description "Post-merge DoD suite failure; candidate for /revert" 2>/dev/null || true
+            gh pr edit "${NUM}" --add-label revert-candidate || echo "note: could not label PR #${NUM}"
+            gh pr comment "${NUM}" --body "${BODY}"
+          else
+            gh issue create --title "DoD gate failed on main (${SHA})" --body "${BODY}"
+          fi
@@ -0,0 +1,60 @@
+# Kill switch (pipeline Phase 6, task 2; ADR-0068) — MAINTAINER-TRIGGERED.
+#
+# A maintainer comments `/revert` on a MERGED PR → this opens a revert PR (it
+# never merges it). The author-association gate mirrors claude.yml: a comment
+# from anyone who is not an org OWNER/MEMBER is ignored entirely, so the ability
+# to trigger a revert is unforgeable. NeoHaskell is org-owned, so OWNER/MEMBER is
+# the maintainer set (COLLABORATOR = outside collaborators, deliberately excluded).
+# The trigger is an exact `/revert` (or `/revert <args>`) — not a `/revert…`
+# prefix — and claude.yml excludes `/revert` comments from its `@claude` handler,
+# so the two workflows are disjoint and never double-fire on one comment.
+name: revert
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+# One revert run per PR at a time — two quick `/revert` comments must not race
+# on creating the same revert branch.
+concurrency:
+  group: revert-${{ github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  revert:
+    if: >-
+      github.event.issue.pull_request &&
+      (github.event.comment.body == '/revert' || startsWith(github.event.comment.body, '/revert ')) &&
+      contains(fromJSON('["OWNER", "MEMBER"]'), github.event.comment.author_association)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          # full history so `git revert` can resolve the merge commit
+          fetch-depth: 0
+          # don't leave the token in .git/config for every later step; the push
+          # below authenticates via an explicit tokenized remote instead
+          persist-credentials: false
+      - name: Open a revert PR for the merged change
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.issue.number }}
+          BASE: ${{ github.event.repository.default_branch }}
+        run: |
+          set -euo pipefail
+          SHA=$(gh pr view "${PR}" --json mergeCommit -q '.mergeCommit.oid')
+          if [ -z "${SHA}" ] || [ "${SHA}" = "null" ]; then
+            gh pr comment "${PR}" --body "revert: PR #${PR} is not merged — nothing to revert."
+            exit 0
+          fi
+          # explicit push auth (persist-credentials:false above) — scoped to this job
+          git remote set-url origin "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          ./dev revert "${SHA}" --base "${BASE}"