Operating discipline · 8 rules · 74+ feedback memories

What kept breaking, what got written down.

Eight numbered rules, crystallized from incidents logged across ~414 sessions. The per-rule headline, the failure mode that produced it, and what it looks like in practice.

The arc

journal → extract → consolidate

Tsvetok keeps a memory journal — decisions, project state, incidents, procedures, personal facts. When something breaks in a way the system should not repeat, the post-incident retrospective writes a feedback memory: what the symptom was, what the cause turned out to be, and what would have caught it earlier. Each feedback memory is a single incident with a session number and a date attached. They accumulate.

By session 119 (2026-04-26), 74 feedback memories had piled up. Reading them individually was no longer the right interface — the same five or six failure modes were showing up under different incident names. TSK-008 consolidated the 74+ feedback memories into eight operational rules and pinned them at the top of the system's primary instruction file (CLAUDE.md). The per-incident detail stays in git history under the memory directory; the rules are the load-bearing summary the orchestrator reads on every session start.

The unusual output is not a framework; it is the habit of turning incidents into rules. The rules are the output of the work, not policy imposed from above. They were renamed once more at session 158 (2026-05-06): twelve numbered rules folded into eight named ones, with the orphaned numbers preserved as sub-bullets so cross-document references survive. The rest of this page is a redacted public summary of those eight.

The 8 rules

headline · origin · practice

Pipeline-by-impact

RuleLookups and one-line fixes ship directly. Multi-session features touching a frozen contract run the full pipeline: PRD, critic loop with diverse providers and severity thresholds, frozen acceptance criteria, planner, specialist execution, ship.

Failure modeSelf-classifying a change as "this feels multi-session" and pre-emptively spinning up the full pipeline. The orchestrator spends 10× more energy on briefs and permission rituals than on shipping product. S139, 2026-04-30.

In practiceDefault for product-feature work is implement, test in sim, commit, surface the diff. The full pipeline runs only when David explicitly invokes it, or when the change touches a named frozen contract (Postgres CHECK or RLS, edge-function dual-mode auth, Keychain refresh path, dependency bumps with consumer-side override risk).

Specialist over serial

RuleWhen two or more independent items each produce more than ~5k tokens of output, dispatch each to a fresh subagent — in parallel where files are disjoint. The hidden cost of in-thread serialization is main-context growth; subagent fanout is 3–5× cheaper above 150k context.

Failure modeSerializing independent work in the orchestrator thread. Context fills, the planner loses precision in the second half of the session, retros come out shallow. S140, 2026-04-30 — three-way parallel fanout closed cleanly with 1821 of 1821 tests passing on the merged tree.

In practiceBriefs pin contracts (acceptance criteria, frozen system prompts, frozen tool schemas, line-citing inputs, precedent files to mirror), not implementations. HEAD-drift adaptations the specialist surfaces are the pattern working as intended.

Code like it ships

RuleResult-tuple service functions ({data, error}), structured error types, input validation, timeouts on network calls, code signing — even on "quick" implementations. Test in the simulator or running app, not just curl. Clean up at session end and verify cleanup ops by re-querying the target.

Failure modeLong-lived feature branches, commits ahead of origin/main at session close, retros that claim "shipped to main" when origin froze two weeks ago. S147→S155 git-topology incident — origin/main froze for two weeks at one SHA while 80 commits piled on a feature branch.

In practiceA read-only git-survey verb walks active projects' .git dirs and reports branches ahead of origin/main. The session-start briefing emits a drift stanza at a one-day threshold; the end-session skill refuses to complete while drift exists.

Memory is a journal

RuleStore David's unique data — decisions, project state, incidents, procedures, personal facts. Do not store external software versions, API capabilities, or CLI flags. Look those up fresh. Negative claims ("X doesn't exist", "blocked", "not available") require re-verification before acting.

Failure modeClick-by-click instructions delivered from training-data memory. The orchestrator invented an App Store Connect enrollment URL and a "Apple Small Business Program" subtab path; both were fabricated. S139, 2026-04-30.

In practicePositive instructions about third-party UI (App Store Connect, Apple Developer, Stripe, GitHub) ALSO get re-verified against current docs before delivery, with the source cited. Project-registry JSON overrides any prose memory; shelved-project memories override stale task carry-forwards.

Confirm before prod writes

RuleShow the plan and wait for explicit approval before deploying, restarting services, running destructive git operations, making external API calls that change state, or deleting files. Auto-merge specialist-authored PRs when CI is green and all acceptance criteria pass and the dispatch was at David's direct instruction.

Failure modeRe-prompting for permission at every intermediate stage of an already-authorized pipeline. The instruction-to-execute already authorized the chain; surfacing every artifact as a "want me to proceed?" prompt is the failure mode, not the safety. S120, 2026-04-26.

In practiceOnce David says "go" on a multi-task batch, the entire pipeline (brief, critic, fix, dispatch, ship) runs without per-stage gates. Re-prompt only on a critic returning a needs-major-rework verdict, a non-zero exit code, or one of the named destructive operation classes.

Verify the bytes

RuleA fix is not "cured" until the production data layer confirms the user-facing flow completes end-to-end. Sim verification, grep-HEAD checks, green CI, and merged commits-to-main are all necessary proofs. None of them are sufficient.

Failure modeThe S148→S166 in-app-purchase incident. The retro headline read "subscribe-500 cured at the secrets layer AND hardened on iOS." The caveat — "end-to-end IAP-flow validity still untested" — was buried as a footnote. Seven TestFlight builds shipped on that assumption. A direct database query at S166 (2026-05-07) showed zero rows ever in subscription, auth_events, or telemetry_event. The cure wrote zero bytes for the entire seven-build run.

In practiceEvery fix-claim pairs with a data-layer fact: row count, specific PostgREST query result, webhook event count, subscription state transition. Caveats go at the top of the retro, not the bottom. A separate pitfall catalog ships alongside the rule, with 26 specific traps (BSD grep -Z, xcconfig // URL truncation, SwiftUI NavigationStack inside if/else, PyMuPDF EXIF strip on FlateDecode bitmaps, and similar).

Ship before polish

RuleFeatures ship in this order: build, test in simulator, commit, push to TestFlight, then polish App Store Connect (screenshots, metadata, review notes, marketing copy). Never propose ASC chores while features are incomplete or untested.

Failure modeMid-feature, agents stall product work to suggest "let's set up App Store metadata." The framing "we can't ship without screenshots" inverts the value gradient — screenshots are cheap and last-mile; missing functionality is not. S139, 2026-04-30 — David flagged a sustained pattern; this rule was added to break it.

In practiceIf David asks "what's next?" mid-feature, the answer is the next code slice, not a metadata chore. The same shape applies to creative output: spend effort on editorial selection (what mattered, what was load-bearing for the next session), not on hitting word counts or character caps.

Instrument before iterating

RuleEscape patch-and-check loops fast. Five sub-rules bound the loop: stop on repeated stack signatures, escalate at iteration two, refute a dismissed hypothesis with a concrete experiment, ship diagnostics before a third behavior patch, and answer "symptom-vs-cause at the same architecture layer?" in every fix retro.

Failure modeS143 onboarding crash (2026-05-02): build 10, 11, and 12 shipped three timing-targeted fixes and crashed at byte-identical stack offsets each time. The architecture council that eventually returned a 4-of-4 consensus in 152 seconds for ~$2 of tokens would have prevented iterations 3 and 4 if invoked at iteration 2. Identical offsets in system frames meant the fix was targeting the wrong architecture layer; the actual cause was a NavigationStack in an if/else branch torn down by a parent re-render mid-mutation.

In practiceOnce a fix has failed once, it is by definition not a one-line fix; it's an open architectural question. The cure is mechanical: instrument with os_signpost on suspect-view lifecycle, render counters, and path-mutation logs in one TestFlight build, then read the ground truth.

One pattern under the microscope

specialist over serial · brief-pinning

Rule 2 has the strongest measurement trail. The discipline is brief-pinning: when an orchestrator dispatches work to a specialist subagent, the brief pins contracts tight — frozen system prompts, frozen tool schemas, frozen protocols, line-citing inputs from the working tree, explicit precedent files for the specialist to mirror. The pin is on contracts, not implementations. Line numbers and exact data-structure shapes drift; acceptance criteria do not.

Across sessions 137 through 140 (2026-04-28 to 2026-04-30), fifteen cumulative specialist dispatches were measured against their stated appetite (the orchestrator's wall-clock estimate at dispatch time). The median specialist wall-clock came in at 0.22× of stated appetite, with a range of 0.10× to 1.0× — never over. When briefs pin contracts tight, specialist wall-clock collapses by a factor of five to ten relative to a loose brief on the same scope. The lesson is to spend more orchestrator time on brief authoring and less on appetite inflation; appetite estimates should reflect contract uncertainty, not lines-of-code count.

The session 140 fanout (three specialists dispatched in parallel against disjoint files) closed cleanly with all 1821 tests passing on the merged tree and zero integration regressions. The validated move is three-way dispatch only when file ownership is disjoint; serial dispatch on the same scope is the case to avoid.

Runbook pointers

internal · not public

The rules are pointers. The bodies — the install rituals, the verdict ledgers, the test surfaces — live in internal runbooks under ~/tsvetok/docs/runbooks/ on the host. They are not published; the descriptions below are elevator pitches, not deep links.

TCC & code signing

All Tsvetok Swift binaries sign with one stable identity (Apple Development, team YPTTM63WP9). Ad-hoc signing is forbidden — the csreq blob in ~/Library/Application Support/com.apple.TCC/TCC.db is identity-bound, not hash-bound, so a recompile that re-signs with the same identity preserves every TCC grant. Six signed binaries carry this identity (calendar-query, reminders-query, photos-query, notes-cli, axorc, plus the AppleServicesServer). Binaries needing Photos or iCloud TCC only work when spawned from a registered LaunchAgent, not from interactive bash.
Per-project hooks

Strict-tier projects (currently zhiva, future external client work) get a SessionStart hook and a PreToolUse hook installed via a project-aware Python installer. Tsvetok itself is loose-tier (SessionStart only — it's the orchestrator, not a client). The SessionStart hook hard-fails with a critical block when it resolves into a git worktree that lacks a settings.json, refusing further work until the installer reruns. The cure is to rerun the installer immediately after any git worktree add.
Personal-data broker

Foreign-project Claude Code sessions cannot call the memory or apple-services MCP tools directly — those are denied at project scope. Personal-data access is mediated through a per-session MCP stdio server with a three-tool surface (request, status, fetch). It is denied-by-default and fails CLOSED: if the broker cannot read its state, every tool call returns denied with a best-effort audit row. Grants are per-agent-identity, not per-project-instance — David approves the agent's capability, not the project. The audit log and grants ledger are append-only on disk, with the invariant enforced by a pre-commit lint that refuses seek, truncate, and write-mode flags near these paths.
Registry write-protection

Nine mutating verbs on the project-registry CLI refuse with exit code 5 unless either (a) the current working directory resolves to the Tsvetok canonical path, or (b) a three-factor allowlist match passes — an auth-context flag, an environment name variable, and an environment path variable, all agreeing with a source-baked entry. Every successful mutation appends to ~/.tsvetok/state/mutations.log; every refusal appends to mutations-refused.log. Both logs are append-only under fcntl.flock, with a daily LaunchAgent that validates every line round-trips JSON.
Orchestration tests

The orchestration architecture rests on platform invariants. Tier A (~4 seconds, every commit, hard-fail) covers the CWD-resolver matrix, the cross-project foreign-reference guard, the SessionStart hook latency and content contract, and the worktree-without-settings hard-fail. Tier B (~80 seconds, nightly, skip-by-default) is eight platform-behavior probes that spawn claude -p against synthetic project CWDs to assert the invariants the architecture depends on. When a Tier B probe flips, the architecture's assumption no longer holds — the cure begins by naming the verdict that flipped, not by drafting code.
Remote workflow

David drives Claude Code on the Mac mini from an mbp16 laptop over the built-in Desktop SSH workspace, routed through Tailscale rather than the local LAN — the CGNAT range sidesteps a sandbox block on RFC1918 addresses. The hard-isolation rule: never tmux attach -t tsvetana from any non-local surface. That tmux session holds the local Tsvetana identity (iMessage plugin allowlist, paired chat IDs, running app state); multi-client attach shares keystrokes and corrupts iMessage routing. Read-only inspection of the session is fine.

What this discipline isn't

caveat

These rules are not a methodology that ports cold to another team. They crystallized from specific incidents on one host, with one developer, against one assistant configuration. The S148 cure-claims rule is calibrated to the in-app-purchase + Apple Server Notifications path that surfaced it; the rule 8 byte-identical-stack heuristic is calibrated to a SwiftUI NavigationStack failure mode that does not generalize to web stacks; the brief-pinning measurements are 15 dispatches on this codebase, not a benchmark.

The portable part is the habit: keep a memory journal, write a feedback memory after every incident, periodically consolidate the journal into a small numbered set of operating rules, and pin those rules where the orchestrator reads them on session start. The specific rules below shape themselves to whatever the system keeps breaking on. A different system breaks on different things and will end up with different rules.

Where the discipline lives in code

on-host paths

~/tsvetok/CLAUDE.md Canonical text of the 8 operational rules. Read by the orchestrator on every session start.
~/tsvetok/docs/runbooks/*.md Per-rule and per-architecture-surface body documents — install rituals, verdict ledgers, test surfaces.
~/tsvetok/docs/pitfalls.md 26-trap catalog for rule 6 (Verify the bytes) — BSD grep flags, xcconfig comment-character collision, SwiftUI lifecycle traps, and similar.
~/tsvetok/.claude/skills/ Skill surface — /audit (multi-provider council review), /audit-four-cs (self-audit), /level-up (discovery prompt), /pending (decision ledger), /end-session (close ritual).
~/.tsvetok/state/projects.json Canonical project-state registry. Overrides any prose memory. Mutating verbs refuse outside the Tsvetok canonical CWD or a three-factor allowlist match.
~/.claude/projects/.../memory/MEMORY.md Memory journal — feedback memories, project memories, reference memories. The substrate the 8 rules were consolidated from.