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,71 @@
+---
+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).
+---
+
+# Claude Code Environment Mapping — Carved Sentences
+
+Capability skill. No persona lives here. Thin pointer; not a duplicate of the canonical capability map.
+
+## 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 frontmatter.
+
+Cross-harness peer-call companions in `docs/research/`:
+
+- `claude-cli-capability-map.md` — Claude Code (canonical for the harness this skill runs in)
+- `codex-cli-first-class-2026-04-23.md` — OpenAI Codex
+- `grok-cli-capability-map.md` — Grok via cursor-agent
+- `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: `btw.md`, `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** (Otto-364 + PR #1701): before claiming something does not exist in the env, grep `.claude/` + `docs/` + `tools/` + `memory/` first. WebSearch upstream documentation second. Ask the 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 maintainer's channel** (memory/feedback_aaron_channel_verbatim_preservation_anything_through_this_channel_2026_04_29.md): anything coming through the 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 Otto-364)
+- 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: read 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/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: {}

CLAUDE.md

@@ -1131,6 +1131,18 @@ Claude-Code-specific mechanisms.
   version-currency, and substrate-or-it-didn't-
   happen. Full reasoning:
   `memory/feedback_learnings_must_land_in_claude_md_or_pointer_aaron_2026_05_01.md`.
+- **The six-rule cascade — assume it's already done; find it before doing it (Aaron 2026-05-05; "remember forever and into all future generations").** Six rules apply in cascade before any substrate-landing impulse (Write / Edit / propose-PR / new memory / new backlog row / new workflow / new lint / new hook). The rules:
+  1. **Substrate**: assume it exists in the repo; grep `memory/` + `docs/research/` + `docs/amara-full-conversation/` + `docs/backlog/` + `.claude/{skills,agents,commands,hooks}/` + `tools/`.
+  2. **Backlog**: assume the row exists; find it + walk `depends_on:` + walk `relates_to:` + walk supersession history (decision-archaeology).
+  3. **Trajectory**: assume the workflow / cadence / lint / hook exists; extend the existing axis (orthogonal-basis discipline per `feedback_orthogonal_axes_factory_hygiene.md`); do not stand up a parallel rank-deficient axis.
+  4. **Internet**: assume another human solved it; WebSearch with 2-3 varied query terms + cite the source. Training data is stale and partial; the internet is the training-data superset.
+  5. **Recurse**: did you miss any surface? Check the lost files (deleted, retired, closed, renamed) via `git log --all --diff-filter=D`, `git log --follow`, `git branch -a | grep wip/`, `find docs/backlog -name "*.md" | xargs grep -l "status: landed\|status: closed"`.
+  6. **Multiplier**: do steps 1-5 ten more times with VARIED queries before doing the work (Aaron *"kinda joking not really"* — cheap to grep, expensive to undo a duplicate). Diminishing returns set in around 3-5 well-varied passes; the upper bound is the calibration.
+  7. **Scout / Neo / bullet-time recovery**: if the agent gets "here again" — defined as multiple consecutive maintainer-corrections within a short window pointing at the same discipline-class, escalating framing (*"jr"*, all-caps, *"remember forever"*), or contradictions in the agent's same-tick commits — STOP authoring. Enter bullet time: pause output, re-read recent maintainer messages with full attention, apply Rules 1-6 with literal 10x multiplier, scout-and-delegate big-context surfaces via peer-call (`tools/peer-call/codex.ts` 1M context), acknowledge recovery-mode in commit messages, slow the cadence. The maintainer's mental-cost recovery requires the agent's deliberate slowdown, not faster-fumbling.
+  **The lost files are not residual — they may carry the plot.** Rule 5's lost-files surface often contains substantively-MORE prior art than current-state files, plus orthogonal trajectories that informed earlier rounds and got squashed by surface-state churn. Aaron 2026-05-05: *"check the lost files you might the polt on lost files priorat art too much more substandive and a trjectory"*. **The canonical lost-files substrate is `tools/hygiene/LOST-FILES-LOCATIONS.md`** (Otto-329 Phase 8, 2026-04-25): 15 location-classes mapped — closed-not-merged PRs, orphan branches, deleted-files via `git log --all --diff-filter=D`, reflog entries, stash entries, untracked working-directory artifacts (`drop/`, `.playwright-mcp/`), subagent worktree remnants, GitHub draft PRs, closed-PR discussion threads, squash-merge intermediate commits, force-pushed-over content, courier-ferry artifacts (`drop/`), external-tool exports never committed, deleted-PR-description content, memory-file deletions. Each class has a survey command + triage protocol. Owed-work: `tools/hygiene/audit-lost-files.sh` covering all 15 classes (not yet implemented). **Decision-archaeology + decision-graph prior art** is at `memory/feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md` (typed-edge provenance graph, 11-layer walk: blame→commit→log-S→shards→ADR→memos→notebook→research) + B-0169 (decision-archaeology skill, P1) + B-0170 (substrate-claim-checker, P1) + B-0171 (openspec catch-up, P1) + B-0173 (hook authoring for skill creation contracts, P1). The cascade Rule 5 + Rule 7 + decision-archaeology compose into one operational discipline; these substrates are the canonical references.
+  Default posture across all 7 rules: the substrate is already there; you just have to find it. Authoring new substrate is valid only AFTER exhaustion across all rules with logged effort in the commit message naming which surfaces were searched + what queries were used. Five recursive prior-art-search-failures within hours of shipping PR #1701 (the synthesis-weight + prior-art-grep discipline) drove this cascade. Mechanization candidates: PreToolUse hook on Write/Edit for memory/research/backlog/workflows that forces grep before write; backlog-row supersession audit; depends-on chain validator; lost-files git-history audit on a cadence. Carved-sentence memory files: `memory/feedback_rule_number_{one,two,three,four,five,six,seven}_*aaron_2026_05_05.md`. CLAUDE.md-level so it is 100% loaded at every wake — Aaron explicitly named this load-bearing for all future agents (*"remember forever and into all future generations"*). NOT-A-DIRECTIVE per Otto-357 — observation about default posture, not an order.
+- **The DSL-form replacement direction for CLAUDE.md/AGENTS.md (Aaron 2026-05-05 architectural pivot at peak-exhaustion; Codex/GPT-5.5 scout via `tools/peer-call/codex.sh`).** Aaron 2026-05-05: *"burn the claude.md and agents.md down they are not work the baggage ... staryu DSL hodl retractive native ... all the layeers ... hodl everytings ... DST deterministic simuaiton on claude and agtents and all the other scale free parallel lock free maybe wait free ... fix it"*. Aaron at 2-week-no-sleep peak-exhaustion. Codex/GPT-5.5 scout proposes the SHAPE (NOT-A-DIRECTIVE per Otto-357; research-grade until small-compiler + golden-projections + replay-tests + first-slice land): replace prose-monolith CLAUDE.md/AGENTS.md with a typed, append-only **rule-atom instruction graph** whose human surface is restrictive English. Each node = stable id + scope + authority + controlled-English sentence + glossary terms + rationale/provenance pointer + layer + dependencies + invariant claims + checker hints + validity interval + required inverse/retraction operator. Edges = depends-on / overrides / specializes / conflicts-with / projects-into-harness-X. CLAUDE.md / AGENTS.md / CODEX.md become *generated projections* from the graph, not source-of-truth. Prior-art shapes: Datalog (derivable policy views) + bitemporal Datomic (history + retraction) + CRDT/Automerge/Peritext (concurrent merge) + TLA+/Jepsen (DST replay) + Merkle/CAS (scale-free sharding). 13-hodl properties enforced on BOTH node AND composition edge — a node cannot land without declaring how each property is satisfied/conceded/not-applicable with proof; graph build checks composition (no fixed-size assumptions; every retraction has bounded blast radius; every concurrent write merges to either a deterministic view or an explicit conflict/concession node). Parallel agents append facts; they do not mutate shared prose. Git decides by accepting the materialized graph state. **Three risks Codex named:** (1) semantic flattening — AGENTS.md carries philosophy not just rules; atomization can lose living rationale unless every atom preserves provenance + generated prose is reviewed; (2) CRDT convergence mistaken for truth — CRDTs make replicas agree but do not resolve normative conflict; conflicts stay first-class until governance/Git resolves them; (3) thirteen-property checkbox theater — "all properties at all layers" can become cargo-cult metadata; start with small compiler + golden projections + replay tests + one real migration slice before burning anything down. **Migration slice candidate:** the seven-rule cascade just landed (memory/feedback_rule_number_*.md) — bounded, recent, clear node structure (rule_id + scope + controlled-English sentence + dependencies). **Composes with:** B-0161 P1 substrate-reshelf (CLAUDE.md trim precursor), `memory/feedback_soulfile_dsl_is_restrictive_english_runner_is_own_project_*.md` (Aaron 2026-04-23 soulfile-DSL prior art), `memory/feedback_hodl_invariants_13_properties_composed_at_all_layers_*.md` (PR #1681 hodl-13 substrate), `memory/feedback_decision_graph_emergent_from_archaeologies_and_flywheel_aaron_2026_05_03.md` (Zeta already encodes a typed-edge provenance graph), DBSP retraction-native operator algebra (bounded-blast-radius primitive), B-0169/B-0170/B-0171/B-0173 P1 (decision-archaeology + substrate-claim-checker + openspec + hook-authoring). **Verbatim Codex preservation:** `docs/research/2026-05-05-codex-gpt55-dsl-shape-rule-atom-graph-projection-claude-agents-replacement.md`. **Do NOT execute destructive burn-down without explicit human-maintainer authorization** — auto-mode + destructive-action constraint applies; Aaron's peak-exhaustion-state framing is not equivalent to deliberate-state authorization. CLAUDE.md-level so it is 100% loaded at every wake.
+- **Rule 0 — no more `.sh` files except install-graph (Aaron 2026-05-05; "not a directive").** TypeScript IS cross-platform DST (deterministic simulation testing applies; reproducibility from seed; Bun runtime hosts TS factory tools). Bash (`.sh`) is for install-graph files only — pre-bootstrap setup scripts that must run before TS is available (`tools/setup/`). Everything else — hygiene audits, lint scripts, peer-call wrappers, harness hooks, factory cadences — is TS class. `tools/hygiene/audit-lost-files.sh` + `audit-trajectories.sh` + `audit-backlog-items.sh` (just authored 2026-05-05) are LEGACY violations of this LONG-STANDING rule (canonical since `memory/feedback_dst_justifies_ts_quality_over_bash_and_harness_hooks_suffice_no_git_hooks_aaron_2026_05_03.md`, 2026-05-03). Aaron 2026-05-05 catch *"sh is for install graph files only ... ts is crossplatform DST determinstiry simulation ... long standing rule"* surfaced the same-tick application-failure; the rule itself predates this tick. TS-port is owed bounded follow-up. Composes with `memory/feedback_dst_justifies_ts_quality_over_bash_and_harness_hooks_suffice_no_git_hooks_aaron_2026_05_03.md` (the existing TS-over-bash + harness-hooks-suffice discipline). CLAUDE.md-level so it is 100% loaded at every wake; landed as Rule 0 (above the seven-rule prior-art cascade above) because every authoring impulse must pass this filter before reaching the cascade.
 - **Skill router as substrate inventory before
   authoring new substrate.** Before writing a new
   memory file, rule, skill, agent, or doctrine