Skip to content

docs(journal+daily-maintenance): bury legacy /data/journal.md, add 4 journal rules, fix broadcast accuracy#76

Merged
spashii merged 2 commits into
mainfrom
sam/journal-and-broadcast-hygiene
May 25, 2026
Merged

docs(journal+daily-maintenance): bury legacy /data/journal.md, add 4 journal rules, fix broadcast accuracy#76
spashii merged 2 commits into
mainfrom
sam/journal-and-broadcast-hygiene

Conversation

@spashii
Copy link
Copy Markdown
Member

@spashii spashii commented May 25, 2026

Why

Two distinct things went wrong this morning, plus one stale instruction the skill was carrying around:

  1. The 10:12–10:16 triple-post. Sam answered Sameer's multi-channel question at 10:12, then appended a session entry to the legacy /data/journal.md file. That path didn't match the silent-exit gate's /data/journal/ prefix check (sibling, not child), so the write was misclassified as outward-facing → gate fired a retry → retry re-posted a duplicate apology → second retry produced "something's wrong with me — need your eyes." Three messages where one was warranted.

  2. The 07:45 broadcast wrote (typical usage shape: ...) in the Skill-usage section. Sam was following the skill correctly — the skill itself instructed the placeholder. That hedged shorthand is exactly what PR docs(identity): forbid unsourced quantitative or factual claims #67 forbade at the identity level (no unsourced quantitative claims). The skill was steering Sam into the failure.

  3. The skill's docker compose up -d --build rule is stale. Live service auto-deploys via .github/workflows/ci-deploy.yml on push to main. There's no "running daemon is older than source until manual restart" anymore — runtime PRs go live ~10 min after merge.

What this PR does

Bury the legacy journal path

  • Move /data/journal.md in GCS to journal/2026-05-11.md (out-of-band before this PR). Per-day directory is now contiguous from 2026-05-11 through 2026-05-25.
  • Strip every prose mention of /data/journal.md: src/capabilities/journal.md, src/capabilities/self-maintenance.md, src/runtime/orchestration.md, src/skills/daily-maintenance/skill.md:20-21.
  • Delete the unused LEGACY_JOURNAL_PATH constant from src/runtime/config.py.

Add 4 journal writing rules in src/capabilities/journal.md

  • Name subagent dispatches (worker / parallel_workers / consult_opus / ask_operator) in What happened. Today's 07:45 entry fired consult_opus but didn't mention it — so grep consult_opus data/journal/ undercounts.
  • Cite counts; never guess them. No "typical" / "usual" / "approximately." Cross-references PR docs(identity): forbid unsourced quantitative or factual claims #67's identity rule.
  • Empty-list front-matter convention: issues: [] / prs: [], never None or blank — grep predicates depend on one shape.
  • Daily synthesis lives in yesterday's file — pointer to daily-maintenance §4 so the amendment pattern is visible from journal.md alone.

Fluff pass on the touched .md files

Tighten phrasing toward README voice: short sentences, active verbs, no throat-clearing. journal.md drops 13 lines net.

Broadcast-skill accuracy + reader-first examples

  • Replace the docker compose up -d --build rule with the actual CI-deploy story.
  • Drop the (typical usage shape) placeholder. Cite real counts or skip the section.
  • Add a ### What \"consequence-first\" means in a bullet subsection with a 6-row before/after table. Catches the engineering-internal-phrasing failure mode the 7am post drifted into on a few bullets ("structurally enforce a Slack reply on Slack-triggered sessions" etc.).

Defense-in-depth on the silent-exit gate

Refactor src/runtime/session.py:824 from inline \"/data/journal/\" prefix to _is_journal_path() helper that reads JOURNAL_DIR from config. Behavior identical given current SAM_HOME=/data but the rule now has a named, greppable home and honors SAM_HOME overrides correctly.

Test plan

  • pytest tests/ — 170 passed
  • Cold-read every diff before push
  • After merge: tomorrow's 7am post should (a) skip (typical usage shape) or cite real counts, (b) phrase any merged runtime PR with the CI-deploy framing, (c) not contain any reference to /data/journal.md, (d) name any consult_opus dispatch by tool name in What happened.
  • If Sam ever appends to /data/journal.md again after this lands, the silent-exit-gate defense will still misfire — by design, since the prose now forbids the write. The right signal in that case is the gate firing once, not silently swallowing the rule break.

Out of scope

  • Sam's narration of the 10:15 / 10:16 messages ("tripped the daemon's silent-exit gate" — internal-jargon leak into a user-facing channel). That's a separate identity-level rule about how to self-explain glitches; flagged as a follow-up, not bundled here.

spashii added 2 commits May 25, 2026 11:13
Bury the legacy /data/journal.md path entirely — file is gone from GCS
(moved to journal/2026-05-11.md) and every source mention is removed.
Prose passes tighten phrasing toward README voice: short sentences,
active verbs, no throat-clearing.

Four new writing rules in capabilities/journal.md:

- Name subagent dispatches in `What happened`. Today's 07:45 entry
  fired consult_opus but didn't say so, so grep across journals
  undercounts dispatches.
- Cite counts; never guess. Skill-usage sections come from the audit
  log, not memory. No "typical" / "usual" / "approximately" — cross-
  references PR #67's identity-level honesty rule.
- Front-matter empty lists: `issues: []` / `prs: []`. Never `None` or
  blank — grep predicates depend on one shape. `participants: None`
  reserved for cron firings.
- End-of-day synthesis lives in yesterday's file. Pointer to
  daily-maintenance §4 so the amendment pattern is visible from
  journal.md alone.

Files touched:
- src/capabilities/journal.md   rewrite, 4 rules added, fluff trimmed
- src/capabilities/self-maintenance.md  one-line cleanup of journal §
- src/runtime/orchestration.md  drops legacy-grep instruction
- src/runtime/config.py         delete unused LEGACY_JOURNAL_PATH
- src/skills/daily-maintenance/skill.md  drops dead read-fallback
Three corrections, one belt-and-suspenders:

1. `_is_journal_path` helper in src/runtime/session.py. Refactors the
   silent-exit-gate classifier's inline `"/data/journal/"` prefix to
   read JOURNAL_DIR from config (so SAM_HOME overrides work in tests)
   and gives the rule a named, greppable home. Behavior identical
   given the current SAM_HOME=/data — but if Sam ever drifts toward
   writing journal-shaped files outside JOURNAL_DIR, this is where the
   defense goes.

2. Drop the `(typical usage shape)` placeholder from the §4 Skill-usage
   sub-section. Today's broadcast wrote "(typical usage shape: ...)"
   exactly as the skill instructed — but that hedged-shorthand pattern
   is what `src/capabilities/journal.md` and `src/identity.md` (#67)
   forbid. Either cite real counts from /data/tool_calls/<date>.jsonl
   or skip the section.

3. Replace the stale "docker compose up -d --build" rule in §5 Bucket A.
   Live service auto-deploys via .github/workflows/ci-deploy.yml on
   push to main — runtime merges go live ~10 min after merge, not on
   manual restart. New phrasing names the CI deploy and the
   capability/skill no-deploy distinction.

4. Add a "What 'consequence-first' means in a bullet" subsection with
   a 6-row before/after table. Catches the engineering-internal-phrasing
   failure mode (the one this morning's 7am post drifted into on a few
   bullets like "structurally enforce a Slack reply"). Existing tight-
   post / tone-deaf examples retained.
@spashii spashii added this pull request to the merge queue May 25, 2026
Merged via the queue into main with commit b080c83 May 25, 2026
2 checks passed
@spashii spashii deleted the sam/journal-and-broadcast-hygiene branch May 25, 2026 09:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants