@thebassclef/lite 0.1.3 → 1.0.0

package/substrate/standards/hook-injection-discipline.md

@@ -1,202 +0,0 @@
----
-tier: lite
-status: live
-date: 2026-06-27
-authority: ADR-035
-references:
-  - {type: adr, id: ADR-035, anchor: hooks as steering surfaces}
-  - {type: rule, id: .claude/rules/cold-adopter-harness-discipline.md, anchor: per-PR harness gate}
-  - {type: rule, id: .claude/rules/testing-tier-config.md, anchor: Tier 0 strict-TDD on .claude/hooks/*.sh}
-  - {type: rule, id: .claude/rules/bootstrap-pair-discipline.md, anchor: hook ships with paired test + settings entry}
-  - {type: standard, id: standards/hook-install-class.md, anchor: install-class header pairs with this discipline}
-  - {type: standard, id: standards/mechanism-fidelity.md, anchor: audit verifies injection hooks fire correctly}
-  - {type: external, id: code.claude.com/docs/en/hooks, anchor: hook event taxonomy as of 2026-06-27}
-luminaries:
-  primary: [hyrum-wright, tony-hoare]
-  supporting: [john-ousterhout, kent-beck, michael-nygard]
-description: - ADR-035 (just shipped, 8632d15) — 9-surface hook taxonomy + block-vs-inject menu; this standard names the contract for the inject side - code.claude.com/docs/en/hooks (WebFetch 2026-06-27) — additionalContext injection JSON shape; 10K char limit…
----
-
-# Hook injection discipline
-
-> **Anthropic docs reference:** Cites code.claude.com/docs/en/hooks as of 2026-06-27. Hook events and capabilities evolve. Before authoring a new injection hook, verify the event taxonomy and `additionalContext` capability against the current docs. The 10,000-character limit + JSON envelope shape + per-event injection support documented here may shift in future Claude Code releases.
-
-## Sources read
-
-- ADR-035 (just shipped, `8632d15`) — 9-surface hook taxonomy + block-vs-inject menu; this standard names the contract for the inject side
-- `code.claude.com/docs/en/hooks` (WebFetch 2026-06-27) — `additionalContext` injection JSON shape; 10K char limit; six events that support injection
-- `.claude/hooks/turn-prose-kiss-check.sh` (existing pattern) — example of a Stop hook that emits stderr (block) but does not yet inject `additionalContext`
-- `.claude/hooks/pr-body-scrub-check.sh` (sibling pattern) — example of structured stderr + exit code 2
-- `standards/bash-hook-safety.md` (sibling standard) — seven defensive disciplines for bash hooks
-
-## What this standard covers
-
-The contract for hooks that **inject context** into Claude's working memory rather than **block** a tool call. Six of nine Anthropic hook events accept an `additionalContext` field that becomes a system reminder attached to the agent's next turn. Bassclef has used hooks mostly as blockers; this standard names the contract for the other shape.
-
-Companion standards:
-- `standards/hook-install-class.md` — every hook declares whether it installs operator-class (`$HOME`) or project-class (`$CLAUDE_PROJECT_DIR`); injection hooks honor the declaration
-- `standards/mechanism-fidelity.md` — the audit method that verifies an injection hook actually fires + produces observable effect
-- `standards/bash-hook-safety.md` — seven defensive bash disciplines that injection hooks follow
-
-## When to inject vs block
-
-Per ADR-035 decision menu:
-
-| Discipline shape | Output mechanism | Hook event |
-|---|---|---|
-| **Refuse** the tool call (the gate must have authority) | `exit 2` | PreToolUse (also Stop for post-write rewrite) |
-| **Steer** the agent (rule sits at recency edge of context) | `additionalContext` injection | UserPromptSubmit, UserPromptExpansion, PostToolUse, PostToolBatch, Stop, SubagentStop, SessionStart |
-| **Verify** the hook works | Tier 0 strict-TDD per `testing-tier-config.md` | n/a — applies to all hook types |
-| **End-to-end test** the hook's stated effect | cold-adopter harness check class | n/a — applies to all hook types |
-
-Pick block when the gate's job is to refuse. Pick inject when the gate's job is to remind, prime, or shape the next generation step. Use both when both apply (block + inject in the same hook).
-
-## JSON envelope contract
-
-Every injection hook returns valid JSON on stdout with this shape:
-
-```json
-{
-  "hookSpecificOutput": {
-    "hookEventName": "<EventName>",
-    "additionalContext": "<text that becomes a system reminder>"
-  }
-}
-```
-
-Event-specific fields (per Anthropic docs):
-
-| Event | Additional fields allowed |
-|---|---|
-| `SessionStart` | `sessionTitle`, `initialUserMessage`, `watchPaths`, `reloadSkills` |
-| `UserPromptSubmit` | `decision: "block"`, `reason` |
-| `UserPromptExpansion` | `decision: "block"`, `reason` |
-| `PreToolUse` | `permissionDecision`, `permissionDecisionReason`, `updatedInput` |
-| `PostToolUse` | `updatedToolOutput`, `decision: "block"` |
-| `PostToolBatch` | `decision: "block"` |
-| `Stop` | `decision: "block"` (the special pattern that lets the rewrite turn continue) |
-| `SubagentStop` | `decision: "block"` |
-
-When in doubt, verify against the latest Anthropic docs. The verify-latest header at the top of this standard names the reference.
-
-## 10,000-character rule
-
-`additionalContext` is capped at 10,000 characters by Anthropic. Excess is saved to file with a preview shown to the agent. For a hook that injects a wordlist + reminder text, this is ample (a 30-term wordlist + per-term gloss + 2-3 sentences of framing typically lands under 2,000 chars).
-
-If a hook's intended injection exceeds the cap, restructure rather than truncate — either inject the index + write the full content to a file the agent can Read, OR split across multiple injection surfaces (SessionStart for full wordlist; UserPromptSubmit for compressed reminder).
-
-## Marker-driven injection
-
-When a hook should fire injection only on specific surfaces (e.g., turn-prose check only on /longrun-dispatched surfaces), it reads a marker file from `state/markers/<surface-type>/<surface-name>.marker`. Marker presence = the surface applies; marker absence = pass-through silently.
-
-Two marker conventions:
-
-- **Persistent markers** (per session or across sessions) — committed to git. Examples: `state/markers/temperance/`, `state/markers/luminary/`, `state/markers/arc-walk/`, `state/markers/adr/`, `state/markers/reviewer/`. These form audit trail.
-- **Transient markers** (per turn or per surface, expire after the hook reads) — gitignored. Examples: `state/markers/turn-prose-surface/`. These signal the NEXT hook firing only and must not persist in committed state. Persisting them breaks tests that assume clean repo state (see bet 2026-06-27c WU-1 chronicle for the live failure example).
-
-Per `standards/hook-install-class.md`, the marker location is consistent across install classes: hooks read from `$CLAUDE_PROJECT_DIR/state/markers/` if the dir exists, falling back to `$HOME/state/markers/` for operator-class hooks.
-
-## Fail-soft contract
-
-Every injection hook fails soft on missing prerequisites. Order of fallback (per ADR-035 Class A cure pattern):
-
-1. Read project-relative path (`$CLAUDE_PROJECT_DIR/<resource>`) — preferred
-2. Read env-var override (`$<HOOK_PREFIX>_<RESOURCE>` — e.g., `KISS_STANDARDS_FILE`)
-3. Read user-level path (`$HOME/.claude/<resource>`) — operator-class fallback
-4. Use inline defaults — last resort
-
-If all four fail, the hook still exits 0 (silent pass) but emits a structured stderr message describing the fallback chain that failed. Adopters running the cold-adopter harness see the stderr in the harness output; the harness check class catches silent fallbacks per `standards/mechanism-fidelity.md`.
-
-The shared helper library `lib/hook-inject.sh` (lands in WU-3 of bet 2026-06-27c) implements this fallback chain so individual hooks call `resolve_<resource>_path` rather than repeating the logic.
-
-## Tier 0 testing requirement
-
-Per `.claude/rules/testing-tier-config.md`, every hook in `.claude/hooks/*.sh` lands Tier 0 strict TDD. For injection hooks specifically, the test asserts:
-
-1. **JSON output validity** — stdout parses as JSON
-2. **Event name correctness** — `hookSpecificOutput.hookEventName` matches the wired event
-3. **Injection content presence** — `additionalContext` non-empty when expected
-4. **Fail-soft behavior** — missing inputs produce exit 0 + structured stderr (not exit 2)
-5. **Both install classes** — test runs under project-class install layout AND operator-class install layout (per `standards/hook-install-class.md`)
-6. **10,000-char ceiling** — injection content does not exceed the cap
-
-The cold-adopter harness `hook-end-to-end-smoke` check class (lands in WU-5 of bet 2026-06-27c) re-runs steps 1-5 in adopter-shaped fixtures so the contract holds end-to-end.
-
-## Worked example
-
-A hypothetical UserPromptSubmit hook that injects the BLOCK wordlist on every operator turn (the cure pattern for bassclef-upstream#1027 / #1051):
-
-```bash
-#!/bin/bash
-# tier: standard
-# install-class: dual
-# user-prompt-submit-kiss-prime.sh — inject BLOCK wordlist as additionalContext
-set -euo pipefail
-
-# Source the shared helper
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-source "${SCRIPT_DIR}/_lib/hook-inject.sh" 2>/dev/null \
-  || source "${CLAUDE_PROJECT_DIR:-}/lib/hook-inject.sh" 2>/dev/null \
-  || { echo "lib/hook-inject.sh missing" >&2; exit 0; }
-
-# Resolve wordlist path (project → env → user → inline defaults)
-WORDLIST=$(resolve_standards_path "bassclef-internal-jargon.md") || exit 0
-
-# Build the injection
-TERMS=$(extract_block_terms "$WORDLIST")
-INJECTION="REMINDER: scan your draft against these BLOCK terms before posting:
-${TERMS}
-Substitute per the grade-10 plain-English table. Reserved-name allowlist: substrate, bassclef, cameo, Studio, Band, bandleader."
-
-# Emit the JSON envelope (10K char-safe; structured stderr on failure)
-emit_additional_context "UserPromptSubmit" "$INJECTION"
-exit 0
-```
-
-Tier 0 test asserts the hook produces valid JSON envelope + non-empty `additionalContext` + exit 0 under both install layouts.
-
-## Anti-patterns
-
-### Inject when you should block
-
-If a discipline genuinely requires refusing the action (e.g., destructive-command-guard), inject is wrong. The agent reads the injection and can still proceed. INSTEAD use PreToolUse exit 2.
-
-### Block when you should inject
-
-If a discipline benefits from steering the agent's generation rather than refusing the action (e.g., remind about the wordlist before the agent drafts a PR body), block is wrong — the agent sees the block AFTER drafting; the draft is already in transcript. INSTEAD use UserPromptSubmit injection so the rule sits at the recency edge BEFORE generation.
-
-### Read project resources via SCRIPT_DIR/../.. under operator-class install
-
-Per the Class A cure pattern (`turn-prose-kiss-check.sh` live failure example), a hook authored with project-relative reads but wired at `$HOME` resolves paths to `~/standards/` (nonexistent). INSTEAD use `lib/hook-inject.sh`'s resolve-helpers which honor declared install-class.
-
-### Inject without test
-
-A hook that injects but has no Tier 0 test isn't verified to produce its claimed effect. Per ADR-035 substrate-as-system tenet, this is legacy code. INSTEAD: ship the Tier 0 test in the same PR as the hook.
-
-### Persist a transient marker
-
-Committing a `state/markers/turn-prose-surface/*.marker` to git makes the hook see a marker that should expire per-turn. Tests that check "no marker → no advisory" break. INSTEAD: per the gitignore convention in `.gitignore`, transient marker directories are excluded.
-
-## Composes with
-
-- `standards/hook-install-class.md` — every injection hook declares install-class header; `lib/hook-inject.sh` honors it
-- `standards/mechanism-fidelity.md` — audit verifies injection hooks fire + produce observable effect
-- `standards/bash-hook-safety.md` — seven defensive bash disciplines that injection hooks follow
-- `standards/cold-adopter-harness.md` — `hook-end-to-end-smoke` check class re-verifies injection contract
-- `.claude/rules/testing-tier-config.md` — Tier 0 strict-TDD on `.claude/hooks/*.sh`
-- `.claude/rules/bootstrap-pair-discipline.md` — every hook ships with paired test + settings.json entry
-- `.claude/rules/blocked-items.md` — protocol when an injection hook surfaces a `BLOCKED:` condition
-
-## Refs
-
-- ADR-035 — hooks-as-steering-surfaces decision
-- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
-- bassclef-upstream#1027 / #1051 / #1304 — prior lineage of turn-prose-kiss-check (Class B steering layer)
-- `code.claude.com/docs/en/hooks` — Anthropic hook reference
-- Michael Nygard — *Release It!* (stability patterns; fail-soft framing)
-- Tony Hoare — pre/postcondition contract programming
-- Hyrum Wright — Hyrum's Law (observable behavior becomes contract)
-
-## Retirement condition
-
-This standard retires only if Claude Code's hook event surface changes shape enough that `additionalContext` is no longer the injection mechanism. The verify-latest header is the cue: every reader checks the Anthropic reference before authoring; if the surface has shifted, the standard amends or supersedes.

package/substrate/standards/hook-install-class.md

@@ -1,215 +0,0 @@
----
-tier: lite
-status: live
-date: 2026-06-27
-authority: ADR-035
-references:
-  - {type: adr, id: ADR-035, anchor: substrate-as-system tenet + hooks as steering surfaces}
-  - {type: adr, id: ADR-032, anchor: adopter sync dispatcher architecture}
-  - {type: adr, id: ADR-034, anchor: operator-class two-stage bootstrap}
-  - {type: standard, id: standards/hook-injection-discipline.md, anchor: injection hooks honor install-class}
-  - {type: standard, id: standards/cold-adopter-harness.md, anchor: harness verifies install-class matches actual wiring}
-  - {type: rule, id: .claude/rules/bootstrap-pair-discipline.md, anchor: new hook ships with install-class declaration}
-  - {type: rule, id: .claude/rules/cold-adopter-harness-discipline.md, anchor: per-PR harness gate}
-luminaries:
-  primary: [john-ousterhout, linus-torvalds]
-  supporting: [hyrum-wright, frederick-brooks]
-description: "- ADR-035 — names the install-class declaration as a foundational invariant (# install-class: operator | project | dual header) - ADR-032 — adopter sync dispatcher architecture (operator-class hooks wired at $HOME; project-class hooks wired at…"
----
-
-# Hook install class
-
-> **Anthropic docs reference:** This standard does not depend on a specific Anthropic surface — it is a bassclef convention layered over the Claude Code hook system. The convention applies regardless of future Claude Code hook event additions.
-
-## Sources read
-
-- ADR-035 — names the install-class declaration as a foundational invariant (`# install-class: operator | project | dual` header)
-- ADR-032 — adopter sync dispatcher architecture (operator-class hooks wired at `$HOME`; project-class hooks wired at `$CLAUDE_PROJECT_DIR`)
-- ADR-034 — extends ADR-032 to operator's own machine; both hook types now exist
-- `.claude/hooks/turn-prose-kiss-check.sh` — the live Class A failure: code reads `$SCRIPT_DIR/../..` (project-relative); wiring at `$HOME` (operator-class); paths resolve to nonexistent locations
-- `presence/install/bassclef-sync.template.sh` — the install template that copies hooks; will read install-class headers to decide where each goes
-- `scripts/cold-adopter-harness-sync.sh` — runs structural checks today; will gain `hook-path-resolution-under-install-class` check class in WU-5
-
-## What this standard covers
-
-Every hook in `.claude/hooks/*.sh` declares its install class via a header line:
-
-```bash
-# install-class: operator | project | dual
-```
-
-The install class tells the install template (`presence/install/bassclef-sync.template.sh`) where to install the hook + tells the hook's code which path resolution layout to use + tells the cold-adopter harness which install layout to verify against.
-
-This standard exists because the 2026-06-27 /diagnose of `turn-prose-kiss-check.sh` surfaced the Class A failure: hook authored project-relative reads but wired operator-class. Declared install-class makes the mismatch a declarative property the harness can verify rather than a latent bug.
-
-## Install classes
-
-### `operator`
-
-The hook lives at `$HOME/.claude/hooks/<name>.sh` and is invoked by the operator's user-level Claude Code settings. Examples (current):
-
-- `bassclef-sync.sh` — adopter sync engine; operator runs it; updates ride to adopters via the install template
-- `session-end.sh` — session lifecycle; operator-scope
-- `bug-diagnosis.sh` — diagnosis trigger; operator-scope
-- `tool-failure-diagnosis.sh` — failure trigger; operator-scope
-- `deploy-guard.sh` — deploy gate; operator-scope
-- `memory-write-audit.sh` — memory write trigger; operator-scope
-
-Operator-class hooks resolve project resources via the fallback chain (per `standards/hook-injection-discipline.md` fail-soft contract):
-1. `$CLAUDE_PROJECT_DIR/<resource>` — when the active session has a project
-2. Env-var override
-3. `$HOME/.claude/<resource>` — operator-scope fallback
-4. Inline defaults
-
-Operator-class hooks MUST NOT read via `$SCRIPT_DIR/../../<project-resource>` because under `$HOME` install layout, that resolves to `~/<project-resource>` (nonexistent).
-
-### `project`
-
-The hook lives at `$CLAUDE_PROJECT_DIR/.claude/hooks/<name>.sh` and is invoked by the project's `.claude/settings.json`. Examples (current):
-
-- `artifact-ingestion-gate.sh` — fires on Edit/Write of generative artifacts in the project
-- `atomic-pr-check.sh` — fires on `git push` for this project
-- `bet-doc-gate.sh` — fires on Edit/Write of `docs/iteration-bets/*.md`
-- `destructive-command-guard.sh` — fires on Bash for destructive commands
-- `pre-build-gate.sh` — fires on Edit/Write before first edit per branch
-- `pre-commit-gate.sh` — fires on Bash matching git commit
-- `pre-gh-pr-body-scrub.sh` — fires on Bash matching gh pr create
-- `pre-gh-pr-title-scrub.sh` — fires on same
-- `pre-git-commit-msg-scrub.sh` — fires on git commit messages
-- `reviewer-dispatch-check.sh` — fires at Stop event
-- `session-reflection.sh` — fires at SessionStart for the project
-- `state-validate.sh` — fires on Edit/Write of state-spine entities
-- `temperance-gate.sh` — fires per-branch
-- `testing-tier-enforce.sh` — fires on Edit/Write of substrate-internal paths
-
-Project-class hooks can use `$SCRIPT_DIR/../..` to reach project resources because under `$CLAUDE_PROJECT_DIR` install layout, that resolves correctly to the project root.
-
-### `dual`
-
-The hook works correctly under both install classes. Either:
-- Code uses `lib/hook-inject.sh` resolve-helpers (preferred — always works regardless of install layout)
-- Code reads only its own directory + env-var overrides + inline defaults (no project-resource reads)
-
-Examples that should be `dual`:
-- `turn-prose-kiss-check.sh` — needs to fire at Stop for operator-class scenarios (Stop is session-level) AND for project-class scenarios (cure work in follow-on goal)
-- Future injection hooks that ship to adopters
-
-## Header convention
-
-Position: top of file, after the shebang + tier declaration, before the description.
-
-```bash
-#!/bin/bash
-# tier: standard
-# install-class: dual
-# <one-line description>
-#
-# <rest of header comment>
-```
-
-The header is parseable by simple grep:
-
-```bash
-INSTALL_CLASS=$(grep -m1 '^# install-class:' .claude/hooks/<name>.sh | sed 's/^# install-class: *//')
-```
-
-If the header is missing, the hook is treated as `project` (current default).
-
-## Install template enforcement
-
-The install template (`presence/install/bassclef-sync.template.sh`) reads the install-class header at sync time. For each hook in the source tree:
-
-| Declared install-class | Action |
-|---|---|
-| `operator` | Copy to `$HOME/.claude/hooks/<name>.sh`. Refuse to copy into `$CLAUDE_PROJECT_DIR/.claude/hooks/`. |
-| `project` | Refuse to copy into `$HOME/.claude/hooks/`. Project-class hooks land via bassclef-sync's project file resolution, not via copy. |
-| `dual` | Copy to `$HOME` AND make available under `$CLAUDE_PROJECT_DIR`. |
-| `missing` | Treat as `project` (backwards-compatible default). |
-
-This enforcement closes the failure mode where an operator-class hook copy + project-relative reads produce silent fallbacks.
-
-(The actual template amendment lands in a follow-on goal; the standard documents the contract now so future authors honor it from the start.)
-
-## Cold-adopter harness verification
-
-The cold-adopter harness check class `hook-path-resolution-under-install-class` (lands in WU-5 of bet 2026-06-27c) verifies that declared install-class matches actual behavior. Per hook:
-
-1. Read declared install-class from header
-2. Install the hook fresh under the declared layout (operator-class → `$HOME`; project-class → `$CLAUDE_PROJECT_DIR`; dual → both)
-3. Run the hook against a fixture trigger
-4. Assert all path resolutions succeed (no `falls back to defaults` warnings in stderr)
-5. Fail the check if any path lookup misses
-
-This is the mechanical layer that catches future instances of the Class A failure at PR time.
-
-## Worked example
-
-### Operator-class hook (existing)
-
-```bash
-#!/bin/bash
-# tier: standard
-# install-class: operator
-# bassclef-sync.sh — adopter sync engine; invoked by user-level Claude Code settings.
-# ...
-```
-
-### Project-class hook (existing)
-
-```bash
-#!/bin/bash
-# tier: standard
-# install-class: project
-# bet-doc-gate.sh — PreToolUse Edit/Write on docs/iteration-bets/*.md.
-# Fires arc-walk + produces/consumes checks per goal doc discipline.
-# ...
-```
-
-### Dual hook (the cure for turn-prose-kiss-check.sh in follow-on goal)
-
-```bash
-#!/bin/bash
-# tier: standard
-# install-class: dual
-# turn-prose-kiss-check.sh — Stop hook that scans assistant prose against
-# BLOCK wordlist. Uses lib/hook-inject.sh resolve-helpers so path resolution
-# works under both operator-class wiring at $HOME and project-class wiring
-# at $CLAUDE_PROJECT_DIR.
-# ...
-```
-
-## Anti-patterns
-
-### Author project-relative reads + wire operator-class
-
-The Class A failure pattern from bet 2026-06-27c /diagnose. INSTEAD: declare `# install-class: dual` + use `lib/hook-inject.sh` resolve-helpers.
-
-### Decline to declare install-class
-
-A hook without the header defaults to `project` and the install template refuses to copy it to `$HOME`. INSTEAD: pick `operator` / `project` / `dual` deliberately at author time.
-
-### Mix install-class with hard-coded `$HOME` or `$CLAUDE_PROJECT_DIR` references
-
-Defeats the abstraction. INSTEAD: source `lib/hook-inject.sh` + call its resolve-helpers; the helpers do the install-class-aware lookup.
-
-## Composes with
-
-- `standards/hook-injection-discipline.md` — injection hooks honor install-class via the fallback chain
-- `standards/cold-adopter-harness.md` (standard tier) — `hook-path-resolution-under-install-class` check class verifies declared header matches actual behavior
-- `presence/install/bassclef-sync.template.sh` — install template reads the header to decide install path
-- `.claude/rules/bootstrap-pair-discipline.md` — new hook ships with install-class header in its bootstrap pair
-- `.claude/rules/cold-adopter-harness-discipline.md` — per-PR harness gate runs the verification
-
-## Refs
-
-- ADR-035 — names install-class as a foundational invariant
-- ADR-032 — adopter sync dispatcher architecture (operator-class vs project-class distinction)
-- ADR-034 — operator-class two-stage bootstrap (where the operator-class hooks fold in)
-- bassclef-upstream#417 — umbrella tracking for bet 2026-06-27c
-- `architecture/audits/2026-06-27-mechanism-fidelity.md` (lands in WU-6) — first audit run will classify each hook by install-class + flag Class A mismatches
-- @luminary john-ousterhout — deep modules: declared install-class is the small interface that hides path-resolution complexity
-- @luminary linus-torvalds — we-don't-break-adopters: install-class declaration prevents a hook from silently breaking under adopter install layout
-
-## Retirement condition
-
-This standard retires only if bassclef stops distinguishing operator-class vs project-class hooks. The `dual` class may become the default if all future hooks are authored to use `lib/hook-inject.sh` resolve-helpers from the start, but the discipline of declaring install-class persists as audit trail.

package/substrate/standards/input-handler-interface.md

@@ -1,152 +0,0 @@
----
-tier: lite
-description: "The interface contract between operator inputs (text / URL / image / repo / transcript / napkin / mixed) and the cameo pipeline's extraction layer."
----
-
-# Input Handler Interface
-
-The interface contract between operator inputs (text / URL / image /
-repo / transcript / napkin / mixed) and the cameo pipeline's
-extraction layer. `/interpret-input` produces a normalized `InputArtifact`
-from any input shape; downstream skills (`/objectory-decompose`,
-`/value-prop`, `/personas`) consume the normalized artifact, never raw
-operator input.
-
-This standard is the contract. The implementation is
-`.claude/skills/interpret-input/SKILL.md` + `scripts/interpret-input.sh`.
-Schema lives at `standards/state-spine/schemas/input-artifact.schema.json`.
-
-## Why this exists
-
-Without an input-handler interface, every input shape requires its own
-extraction code path. Adding a new input mode (e.g., PowerPoint slides,
-PRD documents) means re-shaping the entire chain. The interface lets us:
-
-- Implement extractors as ADAPTERS to the same downstream contract
-- Test each extractor independently against the same schema
-- Add new extractors without changing core extraction semantics
-- Validate inputs structurally at the boundary
-
-Per parent bet's amendment 2026-04-26c: original Phase B baked text-only
-into `/objectory-decompose --text`, deferring abstraction to Phase C.
-This forced a Phase B → Phase C refactor. The current shape establishes
-the interface from day one with text as the first extractor implementation.
-
-## Sources read
-
-- `docs/iteration-bets/2026-04-25-example-pipeline.md` Phase B amendment 2026-04-26c — interface-establishing rationale
-- `docs/iteration-bets/2026-04-27d-example-pipeline-phase-b-mvp.md` WU-A — implementation scope
-- `standards/state-spine/schemas/input-artifact.schema.json` — schema this contract references
-- `standards/state-spine.md` §"Storage format" — InputArtifact is Shape C (pure JSON at `docs/input-artifacts/<slug>.json`)
-- `.claude/luminaries/martin-fowler.md` — Adapter pattern (each extractor adapts a source shape to the InputArtifact contract)
-
-## Auto-detection heuristic
-
-When `--type` is `auto` (default), `/interpret-input` infers type from
-the source string:
-
-| Pattern | Detected type |
-|---|---|
-| `^https?://` (URL prefix) | `url` |
-| `\.(png\|jpg\|jpeg\|gif\|webp\|svg)$` (image extension) | `image` |
-| `\.git$` or `github\.com` (repo URL/path) | `repo` |
-| (default) | `text` |
-
-Operator overrides by passing `--type=transcript` / `--type=napkin` /
-`--type=mixed` explicitly. Auto-detection cannot distinguish a typed
-transcript from prose, nor a hand-drawn napkin from a regular image —
-both default to `text` and `image` respectively without explicit override.
-
-## Extractor responsibilities
-
-Each extractor implements one input type. Common responsibilities:
-
-| Step | What | Required |
-|---|---|---|
-| 1. Receive raw input | Accept `source` argument verbatim | yes |
-| 2. Validate / normalize | Trim, decode, check existence (for paths) | yes |
-| 3. Populate `extracted_text` | Produce normalized prose for downstream | yes |
-| 4. Populate `structural_hints` | Extract type-specific signals when available | optional |
-| 5. Populate `external_urls` | URL regex matches in source / extracted text | optional |
-| 6. Schema validate | Output must conform to InputArtifact schema | yes |
-
-`extracted_text` is the load-bearing output — `/objectory-decompose`
-operates on it. `structural_hints` are best-effort enrichment.
-
-## Phase B vs Phase C scope
-
-**Phase B (this MVP, WU-A)**: text mode is fully implemented. Other
-modes return stub `InputArtifact` with:
-
-- `type: <name>` (correct)
-- `source: <input>` (correct)
-- `extracted_text: "deferred to Phase C"` (sentinel value)
-- All structural_hints empty
-- `external_urls: []`
-
-This lets downstream skills (`/objectory-decompose`, `/preview`)
-exercise the interface against any input type without breaking on
-"extractor not implemented." Stub artifacts are still schema-valid.
-
-**Phase C (follow-up goal)**: implements remaining extractors as ADAPTERS
-against this contract. No core extraction changes; only new extractor
-implementations.
-
-| Type | Extractor approach | Phase |
-|---|---|---|
-| text | Identity (extracted_text = source); URL regex for external_urls | B (this MVP) |
-| url | Fetch + readable-text scrape; cite references | C |
-| image | Vision-based UI-element extraction → boundary_objects | C |
-| repo | Read README + top-level structure + open issues | C |
-| transcript | Speaker-tagged actor → verb mapping | C |
-| napkin | Hand-drawn diagram → entities + boundary_objects | C |
-| mixed | Compose multiple extractors over multi-source input | C |
-
-## Storage shape
-
-InputArtifact is Shape C (pure JSON) per `standards/state-spine.md`
-§"Storage format":
-
-```
-docs/input-artifacts/<slug>.json
-```
-
-Validated at write by `state-validate.sh` PreToolUse hook against
-`input-artifact.schema.json`. Operator-readable narrative belongs in
-chronicles + decompositions, not in InputArtifact bodies.
-
-## Slug convention
-
-```
-<YYYY-MM-DD>-<type>-<6-char-hash-of-source>
-```
-
-Examples:
-- `2026-04-27-text-3a1b2c` (text input from operator paragraph)
-- `2026-04-27-url-9f8e7d` (URL extraction)
-- `2026-04-27-repo-1a2b3c` (repo extraction)
-
-Operator may override via `--slug=<custom>` for memorable fixtures
-(e.g., `2026-04-27-poa-five-pandas-rework`).
-
-## Naming convention
-
-Skills using InputArtifacts read via `state_reference_get input-artifact <slug>`
-per `standards/state-spine-contract.md`. Direct `cat docs/input-artifacts/<slug>.json`
-is forbidden by `accessor-library-discipline.md`.
-
-## Relationship to other standards
-
-- `standards/state-spine.md` §"Storage format" — InputArtifact is Shape C
-- `standards/state-spine/schemas/input-artifact.schema.json` — formal schema
-- `standards/state-spine-contract.md` — accessor surface for reading
-- `.claude/rules/accessor-library-discipline.md` — read-discipline applies
-- `.claude/skills/interpret-input/SKILL.md` — the skill that produces InputArtifacts
-- `.claude/skills/objectory-decompose/SKILL.md` — primary downstream consumer
-- `.claude/skills/preview/SKILL.md` — composer that orchestrates the chain
-
-## Versioning
-
-This contract is v0. New extractor additions are non-breaking (additive).
-Schema changes (new required fields, removed properties) are v1; ship as
-parallel `input-artifact-v1.schema.json` per Fowler expand-and-contract.