@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/standards/deferred-actions-schema.md

@@ -0,0 +1,204 @@
+---
+tier: lite
+description: Standard for docs/deferred-actions/*.md entries — the capability-routed handoff primitive that carries deferred work across session modalities.
+---
+
+# Deferred Actions Schema
+
+Standard for `docs/deferred-actions/*.md` entries — the capability-routed
+handoff primitive that carries deferred work across session modalities.
+
+Any session whose capabilities don't satisfy a pending action writes an
+entry. Any capable future session picks it up at session-start via
+`.claude/hooks/session-reflection.d/60-deferred-actions.sh`.
+
+## Why this exists
+
+Sessions have different capability surfaces (desktop, mobile-ephemeral,
+cloud-web, CI). Work produced in one environment may not be deliverable
+from that environment — a mobile session can compose a release-notes
+addendum but cannot push it to Google Docs (no service-account key);
+an abruptly-stopped session has pending artifacts but no chance to
+push them.
+
+Without this handoff, that work silently drops. With it, the next
+capable session sees a `BLOCKED:` entry and resolves it inline with
+the existing blocked-items protocol.
+
+## File location
+
+```
+docs/deferred-actions/
+├── README.md
+├── <ISO-ts>-<slug>.md          # pending entries
+└── completed/
+    └── <ISO-ts>-<slug>.md      # git mv'd here on resolution (audit trail)
+```
+
+Entries live flat under `docs/deferred-actions/`. On completion, the
+session that resolves the entry runs `git mv` to `completed/` as the
+audit record. The file name never changes, so history tracks the same
+file across the move.
+
+## Frontmatter schema
+
+Every entry starts with YAML frontmatter. Required fields are enforced
+by the scan hook; missing required fields cause the entry to surface as
+`MALFORMED:` with a pointer to this standard.
+
+```yaml
+---
+id: <ISO-ts>-<slug>
+created_by_session: <chronicle-slug-or-session-id>
+created_in: desktop | ephemeral-mobile | ephemeral-ci | cloud-web
+created_at: <ISO-8601 timestamp, UTC>
+pending_action: <slug describing the action>
+requires_capability: [<cap>, <cap>, ...]
+priority: high | medium | low
+origin_skill: /<skill-name>
+resolves_when: |
+  <multi-line description of what "done" looks like>
+---
+```
+
+### Field reference
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | yes | Human-readable slug matching the filename (without `.md`). Pattern: `YYYY-MM-DDTHH-MM-SSZ-<slug>`. Dashes in the timestamp portion to keep it filesystem-safe. |
+| `created_by_session` | yes | Chronicle filename (without `.md`) when available; otherwise a session identifier that future readers can trace. |
+| `created_in` | yes | Modality vocabulary — one of `desktop`, `ephemeral-mobile`, `ephemeral-ci`, `cloud-web`. Extend vocabulary by adding rows to the modality table below, not by inventing values inline. |
+| `created_at` | yes | ISO-8601 UTC timestamp. Used by the scan hook to sort entries by age for surfacing. |
+| `pending_action` | yes | Slug describing what needs to happen. Not free-form prose — a reviewable verb phrase. Examples: `push-release-notes-to-gdoc`, `write-retroactive-version-tag`, `apply-memory-proposal`. |
+| `requires_capability` | yes | List of capability tokens (vocabulary below). Session-start hook compares to current modality's capabilities; match → `BLOCKED:`, miss → `INFORM:`. |
+| `priority` | yes | `high` / `medium` / `low`. Surfaces sort order + operator attention. Reserve `high` for integrity-critical (missing chronicle, lost memory proposal). |
+| `origin_skill` | yes | Slash-command name of the skill that created the entry (e.g., `/release-notes`). Lets the session resuming the work re-enter the same skill with context. |
+| `resolves_when` | yes | Plain-language description of the end state. Not a checklist — one or two sentences the resolver can match against. |
+
+## Capability vocabulary
+
+Stable set. Extend via this standard, not by inventing tokens inline.
+
+| Capability | Meaning |
+|------------|---------|
+| `gcloud-auth` | Session can authenticate to Google Cloud (SA key at `~/.config/gcloud/sunjay-google-ops.json`). Needed for Google Docs push. |
+| `google-docs-write` | Session has network + credentials to write to Google Docs. Composite — requires `gcloud-auth` + `network`. |
+| `gh-auth` | `gh` CLI installed + authenticated in this session. |
+| `git-push` | Session can push commits to remote (SSH keys or HTTPS PAT present). |
+| `git-tag` | Session can create + push annotated tags. Superset of `git-push`. |
+| `network` | Session has outbound internet access. Ephemeral sandboxes may not. |
+| `memory-write` | Session can write to `~/.claude/projects/.../memory/`. Ephemeral sandboxes cannot. |
+| `npm-install` | Session has npm + network to install packages. |
+| `playwright-mcp` | Playwright MCP server configured in settings — visual review possible. |
+| `docker-socket` | Session can run Docker (some CI runners + most desktops). |
+
+New capabilities require a row here. The scan hook uses this table to
+match entries to sessions — an entry requiring `rhyming-slang-decoder`
+would never resolve because no modality advertises that capability.
+
+## Modality → capability table (reference)
+
+Session-start hook detects modality and synthesizes the capability set.
+Not all modalities are static — a desktop session without `gcloud` auth
+is missing `gcloud-auth` even if its modality generally has it. The
+hook's detection logic (at `60-deferred-actions.sh`) is the source of
+truth; this table is human reference.
+
+| Modality | Typical capabilities |
+|----------|---------------------|
+| `desktop` | `gcloud-auth`, `gh-auth`, `git-push`, `git-tag`, `network`, `memory-write`, `npm-install`, `playwright-mcp` |
+| `ephemeral-mobile` | `gh-auth`, `git-push`, `network` (fine-grained PAT only; no `gcloud`, no `memory-write`) |
+| `ephemeral-ci` | `gh-auth`, `git-push`, `network`, workflow-secret-scoped (may include `google-docs-write` via SA key stored in GH secrets) |
+| `cloud-web` | `network` (limited — no shell, no git, no auth) |
+
+## Priority ladder
+
+| Priority | When to use |
+|----------|-------------|
+| `high` | Integrity-critical: missing chronicle, orphaned memory proposal, data that will be lost if the next session doesn't pick it up. |
+| `medium` | Delivery gaps with a real downstream cost: release notes not pushed to Google Doc (weekly changelog goes stale), LinkedIn draft not published. |
+| `low` | Nice-to-have: metrics refresh, backfill of an ancillary artifact, retroactive tagging. |
+
+Default `medium` if uncertain. Escalate to `high` only when silent drop
+costs more than the cognitive load on the resolver.
+
+## Body sections (in order)
+
+Below the frontmatter, the body uses four sections. Session-reflection
+surfaces frontmatter only; the body is for the resolving session.
+
+```markdown
+## Context
+
+Why the work was deferred (one paragraph). Enough for a resolver who
+wasn't in the original session to understand what's pending and why it
+matters.
+
+## Command to execute
+
+Exact command, env vars, or agent instruction the resolver runs to
+complete the work. Copy-pasteable. If the resolution is multi-step, a
+small checklist. If it requires operator judgment (merge proposal,
+edit memory file), state "operator action" and describe it.
+
+## On completion
+
+What the resolver does after the action succeeds — usually `git mv`
+to `completed/` and any side-effect artifacts (e.g., "commit the push
+log as chronicle footnote").
+
+## Cross-refs
+
+Related PRs, issues, chronicles, memory entries, or other deferred
+actions. Makes the audit trail trivially traceable.
+```
+
+## Lifecycle
+
+1. **Create**: skill or hook detects it can't complete an action, writes
+   the entry using `templates/deferred-action-template.md`,
+   commits it as part of the session's normal artifact flow.
+2. **Surface**: next session-start, `60-deferred-actions.sh` scans
+   `docs/deferred-actions/*.md`, detects current capabilities, and emits
+   `BLOCKED:` (resolvable here) or `INFORM:` (visible, not actionable).
+3. **Resolve**: resolving session follows the entry's "Command to
+   execute" section, verifies "On completion" state.
+4. **Archive**: `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`.
+   Commit the move with message `chore: resolve deferred action <id>`.
+
+## Relationship to other rules + standards
+
+- `.claude/rules/deferred-actions.md` — rule governing session-start
+  surfacing + resolution behavior
+- `.claude/rules/blocked-items.md` — generic BLOCKED protocol; deferred
+  actions route through the same "resolve or explicitly defer" path
+- `.claude/rules/mobile-ephemeral-session.md` — modality detection
+  primitives; the scan hook reuses its `$CLAUDE_EPHEMERAL` + heuristic
+  logic
+- `.claude/rules/session-artifacts.md` — chronicle + LinkedIn tier
+  obligations; WS-3's session-rescue writes a deferred-action entry
+  when the Stop hook can't complete these
+- `standards/mobile-ephemeral-session.md` — full standard, informs
+  modality classifications in the capability table
+
+## Extension
+
+- To add a capability: add a row to the capability vocabulary table +
+  update the detection logic in `60-deferred-actions.sh`.
+- To add a modality: add a row to the modality→capability table +
+  update `created_in` vocabulary in the schema.
+- To add a new pending_action type: no schema change needed; the field
+  is free-form slug. If the same action type recurs, update the
+  originating skill's SKILL.md to standardize the slug.
+
+## What this standard is NOT
+
+- Not a task tracker. GitHub issues remain the bassclef task system.
+  Deferred actions are session-to-session handoffs of *already-produced*
+  work that couldn't land.
+- Not an audit log. The `completed/` subdirectory is retention for
+  traceability, not compliance evidence.
+- Not a substitute for `#221`'s workflow-secret SA key path. Once
+  workflow-delivery lands, Google-Doc-push deferrals become rarer.
+  Deferred actions still cover memory proposals, session-rescue, and
+  any future credential-bound action without a workflow fallback.

package/substrate/standards/docs-sync-allowlist.md

@@ -0,0 +1,76 @@
+---
+tier: lite
+description: Files whose change triggers bassclef-docs-sync.yml.
+---
+
+# Docs Sync Allowlist
+
+Files whose change triggers `bassclef-docs-sync.yml`. The workflow syncs bassclef's adopter-facing docs into a discoverable surface (GitHub Wiki + cross-reference verification) so substrate-vs-docs drift can't accumulate silently between sessions.
+
+Tracked under c-package iteration goal 2026-05-13. Closes the discipline gap surfaced when `.bassclef-source.json` was described as pointing at S3 (it points at GitHub) one turn after the description shipped.
+
+## Files
+
+When any of these paths change in a push to `main`, the docs-sync workflow fires:
+
+- `standards/project-directory-layout.md`
+- `docs/bassclef-mental-model.md`
+- `docs/bassclef-overview.md`
+- `docs/getting-started.md` (added 2026-05-14 — dedicated Getting Started walkthrough)
+- `docs/first-use-sequence.md` (added 2026-06-13 — bassclef#965 first-use sequence diagram)
+- `docs/how-skills-work.md` (added 2026-06-13 — adopter guidance on discovery + composition + autonomy modes)
+- `README.md`
+- `docs/hooks-index.md`
+- `docs/glossary.md` (added 2026-05-14 — exhaustive-docs stack)
+- `docs/philosophy.md` (added 2026-05-14)
+- `docs/skills-catalog.md` (added 2026-05-14)
+- `docs/hooks-catalog.md` (added 2026-05-14)
+- `docs/rules-catalog.md` (added 2026-05-14)
+- `architecture/decisions/ADR-*.md` (any new file matching this glob)
+- `.claude/skills/*/SKILL.md` (any new file OR `deprecated: true` flip in frontmatter)
+- `.claude/rules/*.md` (any new file)
+- `standards/bassclef-source-config.md`
+- `standards/vendor-bindings.md`
+- `standards/bassclef-configs-schema.md` (added 2026-06-20 — bassclef#1284 closeout; covers the schema doc updated when new bassclef-configs blocks ship)
+- `standards/sibling-validation-checklist.md` (added 2026-06-20 — bassclef#1284 closeout; operator-runnable end-to-end validation procedure for adopter inheritance)
+- `standards/bassclef-internal-jargon.md` → `Bassclef-Internal-Jargon.md` (added 2026-06-20 — bassclef#1298 / WU-13 of bet 2026-06-20e; the BLOCK / ADVISE / ALLOW wordlist read by turn-prose-kiss-check.sh + pr-body-scrub-check.sh; amended frequently — every wordlist addition should sync to wiki so adopters see current catalog)
+- `standards/adr-template.md` → `ADR-Template.md` (added 2026-06-20 — bassclef#1208 / WU-14 of bet 2026-06-20e; 14-day wiki-as-we-go sweep — ADR template for adopter architecture-record discipline)
+- `standards/bash-hook-safety.md` → `Bash-Hook-Safety.md` (added 2026-06-20 — same; 7 defensive-bash disciplines)
+- `standards/code-safety-principles.md` → `Code-Safety-Principles.md` (added 2026-06-20 — same; language-agnostic safety principles)
+- `standards/frontmatter-schema.md` → `Frontmatter-Schema.md` (added 2026-06-20 — same; required/optional fields for rules + skills)
+- `standards/model-routing-discipline.md` → `Model-Routing-Discipline.md` (added 2026-06-20 — same; per-agent model_tier discipline)
+- `standards/pseudonym-key-schema.md` → `Pseudonym-Key-Schema.md` (added 2026-06-20 — same; operator-private pseudonym registry schema)
+- `standards/security-scanner-adapter.md` → `Security-Scanner-Adapter.md` (added 2026-06-20 — same; per-stack security scanner integration)
+- `standards/tech-stack-config.md` → `Tech-Stack-Config.md` (added 2026-06-20 — same; tech_stack vocabulary bassclef#1127 drives)
+
+## What the workflow does
+
+For each changed allowlisted path:
+
+1. **Identify the artifact class.** Standard / mental-model / overview / README / ADR / skill / rule / hooks-index.
+2. **If a wiki page exists for this artifact**, update it with the new content (light header transform — strip frontmatter, add wiki-style title).
+3. **If no wiki page exists yet**, create one + add to `_Sidebar.md`.
+4. **Cross-reference check.** Grep bassclef-overview + README + mental-model for stale links to the changed file. Surface mismatches as warnings on the PR.
+5. **Step summary.** GitHub Actions step summary names what was synced.
+
+## What does NOT trigger sync
+
+Changes to files NOT on the allowlist. The allowlist is intentionally narrow — internal-decomposition docs, chronicles, iteration goals, LinkedIn drafts, sibling-validations, and audits all stay non-synced. Wiki is for adopter-facing reference, not operator-internal records.
+
+## Adding a new path
+
+When a new file should be synced, edit this allowlist + the workflow's `paths:` filter in the same PR. Per `standards/project-directory-layout.md` anti-drift rule: substrate change + standard update in same change.
+
+## Override
+
+`SKIP_DOCS_SYNC=1` in a commit body skips the workflow for that commit. Logged via trace-helper. Use rarely; prefer narrowing the allowlist if a path shouldn't be synced.
+
+## Sources read
+
+- `docs/iteration-bets/2026-05-13-s3-retirement-docs-sync-hooks-index.md` — parent bet
+- `docs/roadmaps/2026-05-07-7-phase-staircase.md` — current `last_event` = `phase_v_mvd_substrate_shipped` at `2026-05-12T01:30:00Z`
+- `.claude/rules/bassclef-workflow-parity.md` — sibling-grep discipline when adding workflows
+
+## Closes
+
+WU-4 of c-package bet — the standard half. WU-5 ships the `/docs-sync` skill that runs the same logic locally. The workflow YAML itself ships in this same WU.

package/substrate/standards/graceful-exit.md

@@ -0,0 +1,227 @@
+---
+tier: lite
+description: Defines how autonomous agent sessions save state, handle interruptions, and enable the next session to resume without data loss or ambiguity.
+---
+
+# Graceful Exit + Checkpointing Standard
+
+Defines how autonomous agent sessions save state, handle interruptions, and
+enable the next session to resume without data loss or ambiguity.
+
+This standard applies in all configurations. In orchestrator-gated mode it is
+enforced. In operator-gated mode it is advisory — the human is steering, but
+the checkpoint format is still useful.
+
+---
+
+## Exit Conditions
+
+Every agent must recognize the following conditions and respond with the
+prescribed action. Do not finish the current task before responding — respond
+immediately when the condition is detected.
+
+| Condition | Trigger | Required action |
+|-----------|---------|----------------|
+| Time budget exhausted | Turn count or duration reaches iteration ceiling | Save state, report progress, write checkpoint, end gracefully |
+| Budget limit reached | Cost ceiling hit (from cost-governance.md) | Save state, surface cost delta, write checkpoint, end |
+| Ambiguity unresolvable | Agent cannot proceed without a human decision that has not been delegated | Save state, write checkpoint with blocker stated, escalate to human |
+| Blocked by external dependency | A required artifact, credential, service, or decision from outside the session is missing | Save state, log blocker in checkpoint, end — do NOT work around |
+| Error after 3 diagnosis attempts | Three Is/Is Not + Five Whys cycles have not resolved the failure | Save state, escalate to Architect (Builder) or human, end |
+| User interrupts | Human interrupts the session at any point | Save state immediately, write checkpoint, report what is done |
+| Session idle timeout | Session has been inactive (platform-level) | Save state before context is lost |
+| Context window pressure ≥ 70% | Active context fills to 70% of limit | Write checkpoint NOW, let compaction run, re-read survival kit after |
+
+### What "save state" means
+
+1. Commit any in-progress work (even if incomplete — use `chore: wip` if needed)
+2. Clean up worktrees (see below)
+3. Write or update `.claude/CHECKPOINT.md` (see format below)
+4. Update `docs/whereami.md` to reflect current reality
+5. Push if network is available
+
+In that order. Steps 2-3 (worktree cleanup + checkpoint) must complete
+before end of session. If steps 4-5 fail, the checkpoint file alone is
+sufficient for recovery.
+
+### Worktree cleanup (MUST — if any worktrees exist)
+
+If the agent created or used worktrees during this session, clean them up
+before writing the checkpoint. See `standards/worktree-management.md` for
+the full protocol. Summary:
+
+1. For each worktree: commit work, push branch, remove worktree
+2. If removal fails (dirty state, locked files): note in checkpoint
+3. Never leave the session with active worktrees if avoidable
+4. The next session's pre-session audit will catch anything missed
+
+This is a MUST gate because stale worktrees cause branch locks, disk
+waste, and confusing state for the next session.
+
+---
+
+## Checkpoint Format
+
+**Location**: `.claude/CHECKPOINT.md`
+
+This file is overwritten on every checkpoint. It contains the latest state
+only — it is not a log. The chronicle is the log.
+
+```markdown
+# Checkpoint
+
+written_at: YYYY-MM-DDTHH:MM:SSZ
+session_id: (same as chronicle entry if one exists)
+exit_reason: (one of: appetite_exhausted | budget_limit | ambiguity | blocked |
+              error_escalation | user_interrupt | idle_timeout | context_pressure |
+              role_transition | phase_transition | periodic)
+
+---
+
+## Agent state
+
+active_agent: Builder
+task: Implementing SearchBar component per spec at docs/specs/crm.md#search
+status: in_progress   # done | in_progress | blocked
+
+### Done this session
+- Implemented DealCard component (commit abc1234)
+- Added unit tests for DealCard (commit def5678)
+- Updated design tokens for card treatment (commit ghi9012)
+
+### In progress
+- SearchBar component — skeleton written, filter logic incomplete
+  - File: src/components/SearchBar.tsx (partially complete)
+  - Blocking decision: none
+  - Estimated remaining: ~15 turns
+
+### Blocked
+(none — or state the blocker)
+
+### Artifacts produced this session
+| Artifact | Path | Commit |
+|----------|------|--------|
+| DealCard component | src/components/DealCard.tsx | abc1234 |
+| DealCard tests | src/components/DealCard.test.tsx | def5678 |
+| Design tokens | docs/design/tokens/card.md | ghi9012 |
+
+### Decision authority exercised
+- Accepted ADR-009 (component library choice) — no violations
+- Spec interpretation: SearchBar debounce = 300ms (inferred from interaction-design)
+
+---
+
+## Iteration state
+
+iteration_bet: docs/iteration-bets/2026-04-07-crm-build.md
+iteration_phase: Construction
+gate_checklist:
+  - [x] Spec exists and is referenced
+  - [x] GitHub issue open (#41)
+  - [x] Branch stack manifest written
+  - [ ] All tasks complete
+  - [ ] Reviewer sign-off
+  - [ ] Designer sign-off
+
+risk_register_changes: none this session
+
+budget:
+  turns_consumed: 14
+  turns_remaining: ~6 (estimate)
+  duration: ~22 minutes
+
+---
+
+## Handoff state
+
+next_agent: Builder (resume) | Reviewer (if all tasks done)
+resume_task: Complete SearchBar filter logic, then /verify, then open PR
+
+### Survival kit (what the next agent MUST read before starting)
+1. docs/iteration-bets/2026-04-07-crm-build.md — scope + acceptance criteria
+2. docs/specs/crm.md — current spec
+3. strategy/agent-choreography.md Section 9 — MUST gates
+4. docs/whereami.md — current phase and subsystem status
+5. docs/branch-stacks/2026-04-07-crm-stack.md — branch dependencies
+6. .claude/agents/builder.md — luminaries + checkpointing rules
+
+### Context the next agent needs
+- SearchBar is branch `feature/41-crm-search`, PR not yet open
+- DealCard PR is open (#38), awaiting Reviewer
+- Design token values are in docs/design/tokens/card.md — read before building
+
+### Blockers for the next agent
+(none — or state them clearly)
+```
+
+---
+
+## Checkpoint Triggers
+
+Checkpoints fire in two modes: event-driven and periodic.
+
+### Event-driven triggers (fire immediately when the event occurs)
+
+| Event | Who triggers |
+|-------|-------------|
+| Any exit condition (see table above) | Active agent |
+| Role transition (any agent hands off to another) | Outgoing agent, before signaling completion |
+| Phase transition (Inception → Elaboration, etc.) | Orchestrator, after gate validation |
+| Context pressure ≥ 70% | Active agent (self-monitored) |
+
+### Periodic trigger
+
+Every 20 turns (configurable in substrate.config.md as `checkpoint_interval`).
+If no `checkpoint_interval` is set, default is 20 turns.
+
+The periodic trigger exists because event-driven triggers rely on the agent
+recognizing the event. Long tasks can drift without triggering any event.
+The periodic checkpoint ensures a recovery point always exists within 20 turns.
+
+### What to skip
+
+Do NOT write a checkpoint for trivial tool calls (read, grep, glob). A
+checkpoint is a meaningful state save — it fires at the granularity of
+"completed or partially completed a task," not at every action.
+
+---
+
+## Recovery Protocol
+
+When a session starts after a previous session ended abnormally (or was
+interrupted), the Orchestrator (or the operator in operator-gated mode) checks for a
+checkpoint before scheduling any work:
+
+1. Check if `.claude/CHECKPOINT.md` exists
+2. If it exists: read it, read `docs/whereami.md`, reconcile any gaps
+3. Present to operator:
+   ```
+   Last session stopped: [exit_reason] at [written_at]
+   Active agent was: [agent] working on [task]
+   Done: [list from checkpoint]
+   In progress: [list from checkpoint]
+   Blocked: [list from checkpoint]
+   Resume from here, or restart from last clean gate?
+   ```
+4. On resume: activate the agent named in `next_agent`, point it at the
+   survival kit files listed in the checkpoint
+5. On restart: operator decides what to keep. Delete checkpoint after restart
+   to avoid stale state
+
+The checkpoint is advisory — the operator always decides whether to resume
+or restart. Never resume silently without presenting the checkpoint summary.
+
+---
+
+## Relationship to Other Standards
+
+| Standard | Relationship |
+|----------|-------------|
+| `strategy/agent-choreography.md` | Sections 10 and 12a define when to checkpoint; this standard defines how |
+| `.claude/rules/guardrails.md` | Exit conditions in guardrails reference this standard for protocol |
+| `.claude/skills/session-end/SKILL.md` | Session-end reads the checkpoint if present; incorporates it into the chronicle |
+| `standards/branch-stacking.md` | Branch stack manifest is part of the survival kit for Construction checkpoints |
+| `docs/whereami.md` | Updated at every checkpoint; the checkpoint and whereami are complementary |
+
+The checkpoint captures **agent-level state** (what this agent was doing, what's
+done, what's next). Phase-state captures **project-level state** (phase, iteration,
+subsystem maturity). Both must be current for a clean recovery.

package/substrate/standards/hook-idempotency.md

@@ -0,0 +1,102 @@
+---
+tier: lite
+description: Hooks must be idempotent. If a hook fails partway and reruns, it must not duplicate work, generate false warnings, or corrupt state.
+---
+
+# Hook Idempotency Standard
+
+## Principle
+
+Hooks must be idempotent. If a hook fails partway and reruns, it must
+not duplicate work, generate false warnings, or corrupt state.
+
+## Rules
+
+### 1. No write-then-detect
+
+A hook must not write state and then check for that state in the same
+execution. The classic violation:
+
+```bash
+# BAD: writes SESSION_LOCK, then detects it and warns "another session active"
+echo "$(date)" > .claude/SESSION_LOCK
+if [ -f .claude/SESSION_LOCK ]; then
+  echo "WARNING: another session may be active"
+fi
+```
+
+Fix: check BEFORE writing, or use a lock acquisition pattern:
+
+```bash
+# GOOD: check first, then write
+if [ -f .claude/SESSION_LOCK ]; then
+  echo "WARNING: another session may be active"
+else
+  echo "$(date)" > .claude/SESSION_LOCK
+fi
+```
+
+### 2. Append with dedup
+
+Hooks that append to files (trace logs, artifact lists) must check
+whether the content already exists:
+
+```bash
+# BAD: appends every run, creating duplicates on retry
+echo "gate: temperance" >> docs/sdlc-traces/today.log
+
+# GOOD: check before appending
+grep -q "gate: temperance" docs/sdlc-traces/today.log 2>/dev/null || \
+  echo "gate: temperance" >> docs/sdlc-traces/today.log
+```
+
+### 3. Create-if-missing, not create-always
+
+```bash
+# BAD: overwrites existing file on every run
+echo "# Risk Register" > docs/risk-register.md
+
+# GOOD: only create if missing
+[ -f docs/risk-register.md ] || echo "# Risk Register" > docs/risk-register.md
+```
+
+### 4. Exit codes are meaningful
+
+- Exit 0: hook succeeded, continue
+- Exit non-zero: hook failed, behavior depends on hook type
+  - PreToolUse hooks: non-zero blocks the tool call
+  - PostToolUse/Stop hooks: non-zero is logged but doesn't block
+
+Never swallow errors silently:
+
+```bash
+# BAD: hides failures
+some_command 2>/dev/null || true
+
+# GOOD: log the failure, then decide whether to continue
+some_command 2>&1 || echo "WARNING: some_command failed (non-blocking)"
+```
+
+### 5. Timeout awareness
+
+Stop hooks have limited execution time. If your Stop hook does
+network operations (git push, API calls), put them AFTER local
+operations so that local artifacts are saved even if the hook times out.
+
+```bash
+# Phase 1: Local (always completes)
+write_chronicle
+update_memory
+remove_session_lock
+
+# Phase 2: Remote (may timeout — that's OK)
+git push || echo "WARNING: push failed — run manually"
+push_to_gdoc || echo "WARNING: Google Doc push skipped"
+```
+
+Minimum recommended Stop hook timeout: 30 seconds.
+
+## Verification
+
+The `/substrate-check` skill includes a hook idempotency spot-check (step 8)
+that scans for common violations of these rules.