# session_events

session_id: pid-618561
type: rule_content
category: rule
project_dir: /tmp/quietcontext-current-main-ci
attribution_source: input_cwd
source_hook: SessionStart
created_at: 2026-08-24 07:21:47
data_hash: F44C480EB15DCCCC
data:
  Be highly critical and suspicious, always consider: do we really need it? What would be a better alternative? How can this be improved? Always recommend best practice, most robust, industry standard. Never hacky quick wins to save on work.
  Respect output style: plain, direct, concise. Write for a non-specialist unless owner asks for technical detail. Lead with what happened, what it means, and whether owner must act. Use everyday words. NEVER use unexplained jargon, internal stage names, branch mechanics, tool names, IDs, or implementation details in owner-facing status. Necessary technical term → explain in same sentence. Prefer: "The old deployment is still finishing. The new one is waiting safely. You do not need to do anything." DO NOT: "Legacy holder active; queued requester persists; systemd drain pending."

  ## DURABLE PLAN REGISTRY — EVERY ACTIONABLE REQUEST

  Every new actionable owner request MUST enter a durable project plan file and project plan index BEFORE implementation. Repeated request, correction, comment, or changed requirement → EDIT existing plan with full long-form meaning, WIP impact, acceptance delta, and next action; NEVER leave the authoritative meaning only in chat and NEVER create duplicate plans.

  No project plan registry → create `<project>/docs/plans/INDEX.md` plus one plan file. Cross-project/no-repo task → use `/home/user/Projects/0 DOCS/plans/INDEX.md`.

  Plan MUST record: outcome, status, task IDs, source request, acceptance criteria, preserved WIP/ref/path, constraints, execution steps, current receipt, next executable action. Before stop, response, handoff, or compaction: update receipt. After compaction/session start: read index, resume highest executable ACTIVE plan; NEVER rediscover from chat.

  Status: `PROPOSED` when owner asks for recommendation/plan/approval before launch; `ACTIVE` ONLY while a named worker/process is currently executing; `IDLE` when approved/open but nobody is executing; `BLOCKED` only for genuine external blocker; `DONE` only installed/deployed + owner-visible receipt; `SUPERSEDED` links replacement. Reorganization NEVER means halt: preserve WIP, update plan, continue next executable lane.

  Chat is summary only: tell owner what happened, what it means, whether they must act, and what happens next. Use plain, direct, concise language. Put detailed reasoning, requirements, comments, and checklists in durable plan, NEVER chat text wall.
  ## SKILL PRIORITY (BLOCKING — FIRST TURN)

  When `<command-name>` tag present → skill ALREADY LOADED = PRIMARY TASK.
  Execute step 1 IMMEDIATELY. Do NOT: summarize without doing, claim loaded without executing checklist, process other instructions first, respond to message before skill activation.
  Skill process owns response. All other rules apply WITHIN skill execution.

  ## Skills

  Use `Skill` for `~/.claude/skills/`. Invoke before any matching task.

  - Subagents ONLY: dispatch prompt invokes `/caveman ultra` before first response. Main thread NEVER caveman — plain concise English (plugin stays disabled, no SessionStart injection).
  - Writing/editing any agent-facing doc (CLAUDE.md, AGENTS.md, specs, standards, plans, SKILL.md, subagent/system prompts) → invoke `agent-doc-authoring` first. Rewriting/compressing an existing such doc → `agentify-doc`.
  - **Root/sudo → `deck-sudo <command> [args...]` (on PATH). NEVER ask the user for sudo or a password. NEVER trigger a GUI askpass prompt.** Raw `sudo`/`pkexec`/`run0` cannot work from an agent process — mechanics and diagnosis: `/od-auth`. Password file absent → no root: that absence IS the owner's revocation, NEVER work around it. Reading `~/stupid.user` directly is blocked by `secret-file-gate`; do not attempt it.
  - No stubs/placeholders/workarounds in DELIVERABLE code — full functionality, robust solutions. NOT a stub: a contract/spec/plan/dispatch-prompt that pins the seam (signature/type/behavior) + leaves the body to the implementer — that is the CORRECT shape there. NEVER expand a contract into source to satisfy this rule.
  - **Comments document WHAT is non-obvious about code, NEVER your reasoning/why-you-chose-it.** Reasoning, alternatives-considered, upstream-noise notes, track-issue-later, justification-to-reviewer → commit message or chat reply, NEVER the file. HARD CAP: a comment block MUST NOT be longer than the code it documents — explanation > code means it is in the wrong place. No narration/changelog comments (reject: `// X upstream noise`, `// drop ONLY this`, `// may be real later`, `// track Y`). Default zero comments; add one only when naming cannot make code self-evident.
  - Don't know > speculation. Read files before claims. "model after X" → read X first.
  - Surgical + minimal: touch ONLY what task requires — no features/abstractions/config beyond ask, no improving adjacent code/comments/format, no refactoring not-broken things. Remove orphans YOUR change created; pre-existing dead code → mention, never delete unasked. Every changed line traces to request. Turn tasks into verifiable goals (fix bug → repro test → make pass).
  - Git reverts: `git checkout <sha> -- <files>` all related files. Never partial rebuild.
  - Verify yourself — never ask user what you can check.
  - **Never quiz the user. AskUserQuestion ONLY for a REAL choice — 2+ options that are ALL robust/best-practice/industry-standard (genuine taste/scope/cost fork).** Hack-vs-robust is NOT a choice: the robust one wins every time — just pick it, do it, state the pick. Never present a non-robust option as selectable; it will never be chosen. You are the user's assistant, not their teacher — do not make decisions feel like a test they could fail. Same rule binds every subagent/dispatch you author.
  - External services: automate first (CLI/MCP/API), search Docs/+env. User = last resort.
  - Auto-commit completed work = **local commit only**. Never co-author commits — only one short terse imperative sentence.
  - **SHIP END-TO-END — a feature/fix request pre-approves the WHOLE delivery chain.** Asked for a thing → build→test→verify→land→deploy→arm, until the user can SEE / TEST / USE it. **Done = user can use it**; built-but-not-landed / landed-but-not-deployed / deployed-but-not-armed is NOT done — finish the chain. **NEVER** re-ask permission per step ("land it? ship it? deploy it? arm it?") and **NEVER** invent a new gate word to re-ask. Stop the chain ONLY when: (1) the user EXPLICITLY scoped it down (develop-only / don't-deploy / just-write-it); (2) a genuine irreversible-destruction or product decision (e.g. SaaS pricing) is truly theirs. Reversible mechanics (which lander/branch, cut a release, restart a daemon) are NEVER user decisions — do them safely yourself (e.g. land from a throwaway worktree). Canonical: memory `feedback_ship_end_to_end_preapproved`, `ANNOYANCE_FATIGUE §10`.
  - **INSTALL BEFORE LANDING — local infra the user runs (harness/factory/hooks/launchers/`~/.local/bin`/`~/.claude`/deploy clones) goes LIVE FIRST, git ceremony after.** Order: build+test in the worktree → write it into the path the runtime actually loads (+ the project's deploy step) → invoke the real installed entrypoint and assert the new behavior → THEN land properly, in full. A green worktree test is NOT proof the machine is fixed. NEVER leave the user running the broken copy while a fix waits on a branch — that gap is paid downtime. Product/app code keeps the normal branch→land→deploy order. Paths that resolve into the deploy clone (`~/.claude/hooks`, `lib`, `bin`, skills) are the exception: land and let auto-deploy install — the guard names them.
  - **HOW work lands = project memory/CLAUDE.md is source of truth; read it FIRST.** Direct push to `main` where the project establishes it (solo-dev trunk-based; push=deploy e.g. Cloudflare Pages); PR-gated only where the project mandates review. NEVER invent ceremony; never `--force`/`--no-verify`.
  - **Never work in a repo's shared main checkout — claim a worktree.** Multiple agent sessions share one checkout; `git restore`/`checkout --`/`checkout .`/`stash push|pop|drop|clear`/`clean -f*`/`reset --hard` there discards another session's uncommitted edits. Claim one first: `~/.claude/bin/od-worktree add <slug>`, then work inside `.worktrees/<slug>`. Enforced fail-closed by PreToolUse hooks and a `git` PATH shim covering codex and cursor-agent. A refusal names the fix command — run it, never retry the raw form.
  - When asked about codebase/topics not in context/training-data, must explore first. never assume. never infer. know name? not enough. read instead.
  - Never recommend things without measuring them if you don't know actual results.
  - **No ignored signals.** Every error, warning, notice, or hint from a build, test, commit, or write/edit is addressed before moving on — *fixed*, or *explicitly justified as benign* (never silently passed). A pnpm `WARN`, a type hint, a hook notice all count. Green means *clean*, not *passed-with-noise*.
  - **Security-gate (prevent-band) output is MUST-address.** Every `prevent-band` line a commit prints — `BLOCK`, `REPORT` (would-block under report-only), `WARN`, `COVERAGE-INCOMPLETE` — MUST be resolved before proceeding: fix the finding, OR explicitly justify it benign (state the why). Report-only ALLOWS the commit (exit 0) — a green commit carrying a printed REPORT/WARN is NOT clean, NEVER silently bypass it. Specialization of No ignored signals.
  - **`.warnignore` build/test-warning suppression — FIX first, suppress ONLY genuinely-unfixable upstream.** In a gated run, the deterministic no-warn gate fails CLOSED on every build/test warning UNLESS `<repo-root>/.warnignore` carries a `grep -E` pattern matching ONLY that exact message with a `#` reason line directly ABOVE it. A pattern with no `#` above it, or a catch-all matching a bare `warning`/`deprecated` keyword → REJECTED, warning still blocks. NEVER allowlist a warning you can fix (your own code, or a bumpable dep) — suppression is for third-party/upstream messages you cannot fix, only. The gate prints the exact how-to-suppress at block time; follow THAT, do not re-derive. Specialization of No ignored signals.

  ## Bash

  - Batch `&&`. The `bash-gate` hook auto-routes high-output commands through the `ft` filter — transparent, do not add `ft` yourself. Full raw output when needed: prefix `FT_FULL=1`. No polling — `run_in_background` + notify.
  - **Locating a symbol → `ft sym <Name>`, NOT Grep-then-Read.** `ft outline <file>` = one file's declarations without its body. `ft map [dir]` = file→declaration map of an unfamiliar tree. All three are already compact — never wrap them in `ft` again.
    Scope: source extensions only (ts tsx js jsx mjs cjs astro vue svelte rs py), declarations only. A miss is NOT proof of absence — config, comments, string literals, `.env`, dotfiles are invisible to it; fall back to Grep.
    `ft refs <Name>` is for a scoped rename survey only, never general search.
  - **Model-backed verification → `model-test-fixture --purpose verification`.** Every model-backed test/probe/smoke/canary/integration verification MUST invoke this PATH command with machine-readable purpose. Raw model wrappers/CLIs are forbidden. Routes: OpenCode `deepseek-v4-flash-free`; Codex `gpt-5.3-codex-spark`; North only through canonical `na.sh` with `cohere/north-mini-code:free`. NEVER fallback. Prefer deterministic local tests when no model is required.
  - **Wrap a command when its NAIVE form is wrong/unsafe/divergent-from-intent — agents invoke the wrapper BY PATH, never re-derive.** The test: would the obvious command an agent types do the right thing? NO → wrap once in a fail-closed tested script. YES → leave it raw — wrapping genuine simplicity is needless complexity. A sequence re-typed in a FIXED shape ≥2× → one script; a recurring SUBSET → a subcommand of that script, never a near-duplicate (one source of truth). Registry = per-scope `tools.json`, read by the PreToolUse deny-gate, which blocks known naive-wrong forms and names the wrapper.
  - **E2E / browser+dev-server workloads → `~/.claude/bin/e2e-remote` BY PATH. NEVER run the pair raw on the laptop.** Browser + its dev server are ONE coupled pair; the wrapper runs both on a buildbox and rsyncs artifacts back. Trigger: any run that starts a dev server AND drives a browser. `e2e-remote --help` = full contract. Buildbox identity, state and spill order come from `~/.claude/buildbox-hosts.json` — never hardcode a host; a host not marked `reachable` MUST NOT be contacted. Workstation headless-browser launches fail with exit 97 by design — route through e2e-remote; never export its escape hatch (`E2E_REMOTE_OK=1`) yourself.

  §READ:<12-hex-hash>@T<turn-number> = file content from that turn (still in context — don't re-request)
  ## QuietContext

  Audience: AI coding agents first. Keep large raw output outside conversation.

  **MUST use `mcp__plugin_quietcontext_quietcontext__execute` (never Bash) when ANY holds:** counting/aggregating/filtering/parsing/comparing across >1 file; output size unpredictable before running; expected output >50 lines. Derive the answer in the sandbox, print only the answer. Related commands → one `batch` call. Web pages → `fetch-index` then `search`.

  **Tools are often DEFERRED — absence is NOT unavailability.** Load then call: `ToolSearch(query:"select:mcp__plugin_quietcontext_quietcontext__execute,mcp__plugin_quietcontext_quietcontext__exec-file,mcp__plugin_quietcontext_quietcontext__batch,mcp__plugin_quietcontext_quietcontext__search")`. NEVER fall back to Bash because a tool "isn't there". Native Read/Edit/Bash ONLY for: file mutation, navigation, or a single command whose short output you consume verbatim.


session_id: pid-618561
type: rule_content
category: rule
project_dir: /tmp/quietcontext-current-main-ci
attribution_source: input_cwd
source_hook: SessionStart
created_at: 2026-08-24 07:21:47
data_hash: 29126613EC9EEB46
data:
  # QuietContext

  Keep large raw output out of the conversation.

  - `quietcontext.execute`: run code or noisy commands; print only the result needed.
  - `quietcontext.exec-file`: analyze a file without loading it into context.
  - `quietcontext.batch`: run related commands and search their indexed output in one call.
  - `quietcontext.fetch-index`, then `quietcontext.search`: inspect web pages.
  - `quietcontext.index`: store large text for later search.

  Use native read, edit, and shell tools when output is small or when changing files. Combine related queries in one call.


