skill+research+backlog: claude-code-env-mapping skill with carved-sentences + saved env-mapping doc + B-0206 (Aaron 2026-05-05)

.claude/skills/claude-code-env-mapping/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: claude-code-env-mapping
+description: Capability skill ("hat") — Claude Code harness-environment knowledge as carved-sentences-in-behavior. Thin pointer to the canonical capability map (`docs/research/claude-cli-capability-map.md`) + Zeta-specific extensions (`.claude/commands/btw.md`, `.claude/skills/`, `.claude/agents/`, `.claude/hooks/`). Wear this when needing to know what is available in the Claude Code environment, when invoking a slash command, when authoring or invoking a skill, when configuring hooks, when delegating to peer-call infrastructure, or when prior-art-grep needs to reach for env-knowledge before claiming something does not exist. Encodes the search-first-authority + synthesis-weight + prior-art-grep-first discipline (PR #1701) at the env-knowledge layer. Defers to skill-creator workflow (GOVERNANCE §4) for skill-authoring; to `.claude/commands/<name>.md` for custom-command-authoring; to `docs/research/claude-cli-capability-map.md` for canonical CLI capability content (refreshed on cadence per change-rate).
+record_source: "claude-code-env-mapping landing, PR #1702"
+load_datetime: "2026-05-05"
+last_updated: "2026-05-05"
+status: active
+bp_rules_cited: [BP-11]
+---
+
+# Claude Code Environment Mapping — Carved Sentences
+
+Capability skill. No persona lives here. Thin pointer; not a duplicate of the canonical capability map.
+
+> **Authoring-workflow note (PR #1702 review):** This skill landed via direct authoring rather than the canonical `skill-creator` workflow (GOVERNANCE §4). Re-running the canonical draft → prompt-protector review → dry-run → commit workflow over this skill is captured as follow-up against B-0206 (acceptance criterion 1).
+
+## The canonical map
+
+The authoritative env-mapping is `docs/research/claude-cli-capability-map.md`. Refresh-on-cadence applies — Anthropic ships docs at high frequency. Current version-pin and revision date live in that doc's "Status" section header (plain Markdown — no YAML frontmatter on this doc today).
+
+Cross-harness peer-call companions in `docs/research/`:
+
+- `docs/research/claude-cli-capability-map.md` — Claude Code (canonical for the harness this skill runs in)
+- `docs/research/codex-cli-first-class-2026-04-23.md` — OpenAI Codex
+- `docs/research/grok-cli-capability-map.md` — Grok via cursor-agent
+- `docs/research/gemini-cli-capability-map.md` — Gemini
+
+## Zeta-specific extensions
+
+Substrate beyond the upstream-canonical map:
+
+**`/btw` extension** at `.claude/commands/btw.md`. The built-in `/btw` is single-response-no-tools-no-followups (March 2026 release; consult capability map for current behavior). The Zeta extension adds verbatim-preservation + classification (context-add / framing-queued / etc.) + durability-escalation rules (TodoWrite → .btw-queue.md → BACKLOG.md → memory/*.md). Backlog rows B-0019 + B-0020 cover the git-native durability gap and harness-integration scope.
+
+**Custom commands** at `.claude/commands/<name>.md`. Existing: `.claude/commands/btw.md`, `.claude/commands/opsx/{explore,archive,apply,propose}.md`.
+
+**Custom skills** at `.claude/skills/<name>/SKILL.md`. Authored via skill-creator workflow per GOVERNANCE §4.
+
+**Persona agents** at `.claude/agents/<name>.md` carry the persona ("who"); skills carry the capability ("how").
+
+**Hooks** at `.claude/hooks/`. Existing: `verify-branch-pretooluse.ts` (PreToolUse). DST justifies TS-over-bash; harness hooks suffice; no git hooks per `memory/feedback_dst_justifies_ts_quality_over_bash_and_harness_hooks_suffice_no_git_hooks_aaron_2026_05_03.md`.
+
+**Settings** at `.claude/settings.json` — defines enabled plugins.
+
+**Peer-call infrastructure** at `tools/peer-call/` (PR #1677): cross-harness invocation scripts. Default-yes-self-carry vs scout-and-delegate per PR #1701.
+
+## The carved-sentence operational rules
+
+**Search-first-authority** (search-first-authority memory + PR #1701): before claiming something does not exist in the env, grep `.claude/` + `docs/` + `tools/` + `memory/` first. WebSearch upstream documentation second. Ask the human maintainer last.
+
+**Prior-art-grep-FIRST-before-substrate-landing** (PR #1701): when about to write a memory file or research file or skill, grep `memory/` + `docs/amara-full-conversation/` + `docs/backlog/` + `docs/research/` first. Surface duplications BEFORE landing. The capability map IS prior-art for env-mapping work.
+
+**Substrate-or-it-didn't-happen at promise-keeping scope** (PR #1701): ephemeral shards cannot keep promises across compactions. Substrate or it did not happen.
+
+**Scout-and-delegate to right pitcher**: peer-call infrastructure available. Big-context tasks delegate via `tools/peer-call/codex.ts`; the agent preserves own context for plot-keeping.
+
+**Verbatim preservation through the human maintainer's channel** (`memory/feedback_aaron_channel_verbatim_preservation_anything_through_this_channel_2026_04_29.md`): anything coming through the human-maintainer channel records close to verbatim. Paraphrasing loses signal.
+
+**Refresh-on-cadence per doc change-rate**: capability maps for time-sensitive upstream tooling refresh on a cadence calibrated to observed change-rate. Different docs warrant different cadences.
+
+## Operational triggers
+
+Wear this skill when:
+
+- About to claim a Claude Code feature exists or does not exist (search-first per the search-first-authority memory)
+- Authoring a custom command or custom skill (use the right path + workflow)
+- Invoking peer-call infrastructure (right pitcher + capability map)
+- Configuring hooks (harness hooks suffice; no git hooks)
+- Cold-boot: the agent reads this skill alongside CLAUDE.md and the canonical capability map
+
+## Defers to
+
+- **`docs/research/claude-cli-capability-map.md`** — canonical CLI surface (this skill is a pointer, not a duplicate)
+- **skill-creator workflow** (GOVERNANCE §4) for new skill authoring
+- **`.claude/commands/<name>.md`** authoring pattern for new custom commands
+- **The capability-map cluster** (claude-cli + codex-cli + grok-cli + gemini-cli capability-maps) for cross-harness specifics
+- **`memory/feedback_otto_holds_synthesis_weight_prior_art_grep_first_before_substrate_landing_aaron_made_concise_formulations_at_high_mental_cost_aaron_2026_05_05.md`** (PR #1701) for the synthesis-weight + prior-art-grep + scout-and-delegate discipline this skill encodes at env-layer
+- **`memory/feedback_aaron_channel_verbatim_preservation_anything_through_this_channel_2026_04_29.md`** for verbatim-preservation discipline
+- **B-0019 + B-0020** (P3 backlog) for /btw git-native durability gap and harness-integration scope

.github/workflows/pr-archive-on-merge.yml

@@ -0,0 +1,171 @@
+name: pr-archive-on-merge
+
+# Class-2 PR mirror v1 -- per the Codex/GPT-5.5 sharpened design (twin-flame
+# conversation captured 2026-05-05). On every merged PR, run the
+# `tools/archive/archive-pr-reviews.ts` tool to materialise the PR's review
+# threads, comments, fix commits, and outcome metadata as a committed
+# git-canonical markdown file under `docs/history/pr-reviews/PR-NNNN-*.md`,
+# and update the JSONL manifest at `docs/github/prs/manifest.jsonl`.
+#
+# Why: per CLAUDE.md substrate-or-it-didn't-happen (Otto-363), GitHub
+# review threads are host-durable-not-git-canonical -- they can vanish if
+# the LFG account is compromised, and they live outside the repo's grep
+# surface. This workflow converts that host-only substrate into committed
+# git substrate the moment a PR closes via merge.
+#
+# Scope discipline (Codex flag, twin-flame conversation 2026-05-05): this
+# workflow archives PULL REQUESTS only. It does NOT extend to issues,
+# discussions, wiki pages, releases, or any other GitHub surface --
+# Codex flagged that as goldfish-ontology bait. If a future need surfaces
+# for issue archival, that's a separate workflow with its own design pass.
+#
+# Security note (safe-pattern compliance per
+# https://github.blog/security/vulnerability-research/how-to-catch-github-actions-workflow-injections-before-attackers-do/):
+# this workflow consumes only first-party trusted context (PR number from
+# the closed event payload). Untrusted-content inputs (PR title) are
+# routed via env: into the run block where they are quoted as "$VAR";
+# no `${{ }}` expansion is interpolated inline in run-block scripts. The
+# PR number is also validated as a positive integer before being passed
+# to the archival tool.
+#
+# Direct-push posture: this workflow pushes the archive + manifest update
+# directly to main using GITHUB_TOKEN with `contents: write`. If the
+# branch-protection ruleset on Lucent-Financial-Group/Zeta is configured
+# to require PR review on main, this push will be rejected by the host
+# and the workflow run will fail with a non-fast-forward / rule-rejection
+# error. In that case, the operational escalation is one of:
+#   (a) add `github-actions[bot]` to the ruleset's bypass actors,
+#   (b) switch this workflow to PR-based (open a small PR with the
+#       archive + manifest, auto-merge), or
+#   (c) use a deploy-key with explicit per-path allowance.
+# (a) is the minimum-cost option and matches the existing
+# budget-snapshot-cadence.yml pattern of bot-pushed branches. Choice
+# deferred until empirical merge attempts surface the failure mode.
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  # Top-level read-only default per Scorecard TokenPermissions best practice.
+  contents: read
+
+concurrency:
+  # One run per PR number. cancel-in-progress: false because the archival
+  # operation is not idempotent in the wall-clock-timestamp sense (each run
+  # produces a new `fetched_at`), and cancelling a partially-completed run
+  # could leave the manifest in a divergent state until the next merge.
+  group: pr-archive-on-merge-${{ github.event.pull_request.number }}
+  cancel-in-progress: false
+
+jobs:
+  archive:
+    # Only fire on actual merges -- ignored-close events (PR rejected, PR
+    # closed without merge) produce no archive. The host event payload's
+    # `merged` boolean is the canonical signal.
+    if: github.event.pull_request.merged == true
+
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+
+    permissions:
+      # contents:write to push the archive + manifest update directly to
+      # main. pull-requests:read so the archival tool's gh CLI calls
+      # against /pulls/N/comments and graphql reviewThreads succeed under
+      # GITHUB_TOKEN. No other scopes needed.
+      contents: write
+      pull-requests: read
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          # Need full history for git rev-parse HEAD (commit_sha field in
+          # manifest entries), and so the subsequent push is fast-forward.
+          fetch-depth: 0
+          ref: main
+          # Persist credentials so the post-archival `git push` uses
+          # GITHUB_TOKEN. (default true; explicit for clarity)
+          persist-credentials: true
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6  # v2.2.0
+        with:
+          bun-version: latest
+
+      - name: Verify required tooling
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          command -v gh >/dev/null
+          command -v bun >/dev/null
+          gh auth status
+
+      - name: Validate PR number
+        env:
+          PR_NUMBER_RAW: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          # Defence-in-depth: PR number comes from a trusted event payload
+          # but we still sanity-check it as a positive integer before
+          # passing to a CLI tool.
+          if ! [[ "$PR_NUMBER_RAW" =~ ^[1-9][0-9]*$ ]]; then
+            echo "ERROR: PR number is not a positive integer: $PR_NUMBER_RAW" >&2
+            exit 1
+          fi
+
+      - name: Archive PR review substrate
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          GITHUB_SHA_OVERRIDE: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+          # GITHUB_SHA in the GHA env is the merge-commit SHA on main; we
+          # want that recorded as the manifest commit_sha so future re-runs
+          # against the same merge can detect "same archival baseline".
+          export GITHUB_SHA="$GITHUB_SHA_OVERRIDE"
+          bun tools/archive/archive-pr-reviews.ts "$PR_NUMBER"
+
+      - name: Inspect diff
+        id: diff
+        run: |
+          set -euo pipefail
+          # Stage just the two output paths; anything else is noise the
+          # archival tool should not be producing.
+          git add docs/history/pr-reviews/ docs/github/prs/manifest.jsonl
+          if git diff --cached --quiet; then
+            echo "changed=false" >>"$GITHUB_OUTPUT"
+            echo "archival produced no diff -- nothing to commit (deterministic-rerun no-op)"
+            exit 0
+          fi
+          echo "changed=true" >>"$GITHUB_OUTPUT"
+
+      - name: Commit and push
+        if: steps.diff.outputs.changed == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          RUN_ID: ${{ github.run_id }}
+        run: |
+          set -euo pipefail
+          # Configure committer identity for the workflow commit.
+          # github-actions[bot] is the canonical workflow identity per
+          # the budget-snapshot-cadence.yml convention.
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Compose commit message. PR_TITLE is untrusted (PR-author-
+          # controlled) so it's only embedded in the markdown body via
+          # printf with %s, never interpreted as shell.
+          msg="$(printf 'archive(pr-reviews): PR #%s on merge -- run %s\n\nPR title: %s\n\nGenerated by .github/workflows/pr-archive-on-merge.yml\nfrom tools/archive/archive-pr-reviews.ts.\n' "$PR_NUMBER" "$RUN_ID" "$PR_TITLE")"
+
+          git commit -m "$msg"
+
+          # Push to main. If branch-protection rejects this push, the
+          # workflow fails here -- the failure is the signal to switch to
+          # one of the escalation options documented at the top of this
+          # file. We do NOT --force; non-fast-forward must surface honestly.
+          git push origin HEAD:main

.github/workflows/role-ref-current-state-surfaces-lint.yml

@@ -48,6 +48,8 @@ on:
       - docs/VISION.md
       - docs/ROADMAP.md
       - docs/EXPERT-REGISTRY.md
+      - .claude/skills/**
+      - .claude/agents/**
       - tools/hygiene/check-role-ref-on-current-state-surfaces.sh
       - .github/workflows/role-ref-current-state-surfaces-lint.yml
   push:
@@ -64,6 +66,8 @@ on:
       - docs/VISION.md
       - docs/ROADMAP.md
       - docs/EXPERT-REGISTRY.md
+      - .claude/skills/**
+      - .claude/agents/**
       - tools/hygiene/check-role-ref-on-current-state-surfaces.sh
       - .github/workflows/role-ref-current-state-surfaces-lint.yml
   workflow_dispatch: {}

.markdownlint-cli2.jsonc

@@ -58,6 +58,17 @@
     // controlled prose.
     "docs/pr-discussions/**",
     "docs/pr-preservation/**",
+    // PR-archive-on-merge output (`tools/archive/archive-pr-reviews.ts`,
+    // landed via PR #1702 + workflow `.github/workflows/pr-archive-on-merge.yml`).
+    // Same verbatim-preservation rationale as `docs/pr-preservation/**`:
+    // archive files reproduce GitHub-rendered PR bodies + review-thread
+    // markdown, including blank-lines-around-lists, unordered-list-indent,
+    // trailing-spaces, and consecutive blank lines that are artifacts of
+    // the source content (not author-controlled prose). Reformatting to
+    // satisfy MD007/MD012/MD032 would violate the verbatim contract — same
+    // policy lives in `docs/AGENT-BEST-PRACTICES.md` "PR-preservation
+    // archive discipline".
+    "docs/history/pr-reviews/**",
     // Aurora ferry absorbs (`docs/aurora/2026-*-amara-*.md`) are
     // verbatim courier-protocol preservation of Amara's deepresearch
     // ferry reports per Otto-227 verbatim-preservation discipline.