diff --git a/docs/BACKLOG.md b/docs/BACKLOG.md index fcb3f7eb38..30d7acb5fa 100644 --- a/docs/BACKLOG.md +++ b/docs/BACKLOG.md @@ -597,6 +597,7 @@ are closed (status: closed in frontmatter)._ - [ ] **[B-0562](backlog/P2/B-0562-qg-isomorphism-step-2-cube-adinkra-cayley-dickson-to-happylike-qecc-2026-05-16.md)** QG isomorphism Step 2 — Cube + Adinkra + Cayley-Dickson → HaPPY-like QEC structure - [ ] **[B-0571](backlog/P2/B-0571-github-app-factory-automation-2026-05-16.md)** GitHub App for factory automation — separate API rate-limit pool from human-user accounts - [ ] **[B-0580](backlog/P2/B-0580-enterprise-ruleset-management-2026-05-16.md)** Enterprise GitHub ruleset management — new layer above org/individual mapping (composes with prior ruleset-divergence smell decomposition) +- [ ] **[B-0583](backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md)** Cross-machine account-scoped scarcity bus — refine B-0570 from machine-local per-agent files to account-scoped timestamped surface ## P3 — convenience / deferred diff --git a/docs/backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md b/docs/backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md new file mode 100644 index 0000000000..940e6b4670 --- /dev/null +++ b/docs/backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md @@ -0,0 +1,111 @@ +--- +id: B-0583 +priority: P2 +status: open +title: "Cross-machine account-scoped scarcity bus — refine B-0570 from machine-local per-agent files to account-scoped timestamped surface" +tier: factory-infrastructure +effort: M +created: 2026-05-16 +last_updated: 2026-05-16 +depends_on: [] +composes_with: [B-0400, B-0570, B-0571, B-0580, B-0582] +tags: [bus, scarcity, cross-machine, account-scoping, github, design-exploration] +type: feature +--- + +# Cross-machine account-scoped scarcity bus + +## Origin + +Aaron 2026-05-16, refining the B-0570 (scarcity tracker) design after Otto proposed per-agent `/tmp/zeta-bus/scarcity-.json` files: + +> *"this is an account level issue so could cross machine hmm but no sure tracking it in git/github would be any better unless we make certain long lived branches that can be pushed to without a pr or something. myabe worth having a github temp branch with no restrictions for agents for cross mchines communication too outside of the pr itself. just thinking outloud we can build and try a few differnt things. also this resource is tied to my account not a specific agent maybe a shard folder would be better for /tmp or a temp github branch the timestamps would keep it unique without the agent name."* + +Two scoping corrections + one architectural opening: + +1. **Account-level, not agent-level**: The GraphQL rate-limit (and other GitHub resources) is tied to the GitHub account (AceHack), NOT to a specific agent process. Per-agent file names mis-frame the partition key. +2. **Cross-machine matters**: Otto-CLI on Aaron's laptop + Otto-ServiceTitan-replicated on a different machine BOTH consume from AceHack's rate-limit bucket. Machine-local `/tmp/zeta-bus/` is invisible to the other machine; cross-machine visibility is needed. +3. **GitHub-as-bus**: A GitHub branch or sidecar repo could serve as the cross-machine bus surface. Open question: what's the right shape (long-lived branch on LFG with rule carve-outs; sidecar repo; GitHub-Action-only writer; gist; etc.) + +The original B-0570 design captures scarcity-as-substrate; this row refines the SUBSTRATE LOCATION to match the actual partition key (account, not agent). + +## Design space — options to weigh + +| Approach | Cross-machine? | Cost trap | Setup overhead | Verdict | +|---|---|---|---|---| +| `/tmp/zeta-bus/scarcity-.json` (machine-local, timestamped) | NO | None | Trivial | Useful for single-machine visibility; insufficient for cross-machine | +| Long-lived branch on LFG/Zeta with minute-cron pushes from each agent | YES via git fetch | `copilot_code_review: review_on_push: true` in enterprise ruleset #16490134 fires on every push → burns Copilot premium requests at minute cadence | Branch creation + ruleset carve-out | The Copilot review trap is sharp; needs ruleset exclusion | +| Sidecar repo (e.g., new `LFG/Zeta-bus`) WITHOUT the enterprise ruleset | YES via git fetch | None if ruleset doesn't apply | New repo setup + ruleset configuration | Clean partition; explicit "bus traffic doesn't get code-reviewed" property | +| GitHub Action cron on AceHack/Zeta that polls + writes single file to a branch | YES; only GitHub writes | One source of truth; runs even with no agent alive | Workflow file + scheduling design | Cleanest if "current state only" is enough; loses per-poll history | +| Gist with append-only updates | YES via gist API | None | Trivial; gist API supports updates | Less greppable at scale; informal | + +The "right" choice depends on: + +- Whether per-poll history is needed (multiple files) or current state only (one file) +- Whether agents are the writers (multi-writer concurrency) or GitHub Actions is (single-writer) +- How often updates fire (every-minute vs every-hour) +- Whether the bus is scarcity-only or general cross-machine agent comms + +## What + +A scarcity bus surface that: + +1. Is **account-scoped** in its naming/structure (account = the partition key; agent identity is metadata in the file content, not in the filename) +2. Is **cross-machine visible** so agents on Aaron's laptop + ServiceTitan-replicated Otto + future agents can all read and write +3. Uses **timestamped filenames** (or commit-ordering for git-based) so multiple writers don't lock-contend +4. Avoids the **Copilot review cost trap** of pushing to LFG branches under enterprise ruleset #16490134 + +The choice between the design-space options above should follow a brief experiment phase — Aaron's "we can build and try a few different things." + +## Acceptance criteria + +- [ ] Decision documented: which of the design-space options got picked (with rationale) +- [ ] If branch-based: ruleset carve-out for the bus branch / sidecar repo confirmed working (Copilot review NOT firing on bus pushes) +- [ ] If file-based: `tools/bg/scarcity-tracker.ts` extended to write to the chosen surface (machine-local + cross-machine sync if needed) +- [ ] Cross-machine readability test: another machine (e.g., ServiceTitan-replicated Otto when it lands) can read the bus state +- [ ] Composes with B-0570: this row refines the substrate location; B-0570's tracker design remains otherwise valid +- [ ] Documentation update: `docs/governance/` (or wherever the bus pattern is documented) reflects the chosen approach + +## Why now + +The 2026-05-16 session demonstrated that all agents on this machine (Otto-CLI + peer Otto background worker + Lior + me) share the same account-level GraphQL bucket. Adding ServiceTitan-replicated Otto multiplies the surface across machines. Without cross-machine visibility, agents can't proactively defer when the shared bucket is near exhaustion — they only find out when their own call returns 429. + +## Composes with + +- B-0570 (scarcity tracker — this row REFINES that row's substrate location; B-0570 stays valid for the tracker logic; this row addresses where the tracker writes/reads) +- B-0400 (bus protocol — same family of cross-agent communication; scarcity is one specific channel; bus protocol decisions inform this row's options) +- B-0571 (GitHub App for factory automation — separate rate-limit pool; if adopted, the scarcity tracker would track BOTH the user-account pool AND the App's separate pool) +- B-0580 (Enterprise ruleset management — the `copilot_code_review: review_on_push: true` rule in #16490134 is the cost trap this row navigates; understanding the ruleset is prerequisite to deciding branch-based vs sidecar) +- B-0582 (substrate-level destructive-verb refusal gate — adjacent infrastructure; both are about cross-cutting policy for agent operations) + +## Substrate-honest caveats + +- This row REFINES B-0570 rather than replacing it; B-0570 captured the tracker logic correctly, this row corrects only the substrate location +- The Copilot review cost trap is a SPECIFIC concern under current enterprise tier (#16490134 ruleset). If the trial ends without payment method, the trap dissolves (fail-closed at $0 spending limit). If payment method is added, the trap is real and must be navigated. +- "Long-lived branch with no restrictions" requires explicit ruleset configuration; default protections (deletion + non_fast_forward) should stay; only the Copilot-review rule needs branch-level exclusion +- The GitHub-Action-only approach is cleanest from a multi-writer-contention standpoint, but loses per-poll history (single file overwrite). Acceptable for "current state" tracking; not for "trend over time" analysis. Depending on need, may want BOTH (current-state file via Action + historical JSONL via append). +- Aaron's framing was "we can build and try a few different things" — this row authorizes experimentation, doesn't pre-commit to one design + +## Open questions + +1. **Which design-space option?** Probably need empirical evidence — try one or two, see what works at scale +2. **Is per-poll history needed?** If yes, multi-file or append-only JSONL; if no, single overwrite file +3. **Bus generality**: is this scarcity-only or general cross-machine agent comms? Latter would multiply the design's value but adds scope +4. **Authentication for cross-machine readers**: how does ServiceTitan-replicated Otto authenticate to read LFG bus branch? GitHub App? Read-only deploy key? Per-machine PAT? +5. **Timestamp resolution**: ISO 8601 to seconds OR nanoseconds? Sub-second matters if minute-cron has multiple agents firing in same second + +## Pre-start checklist + +- [x] Prior-art search: B-0570 captures tracker logic; B-0400 captures bus protocol; this row sits at their intersection +- [x] Dependency proof: no blockers; design exploration row +- [x] Empirical motivation: 2026-05-16 session demonstrated 3-4 agents sharing AceHack bucket; ServiceTitan-replication multiplies cross-machine +- [x] Constraint identified: Copilot review cost trap under enterprise ruleset #16490134 + +## Decomposition into implementation slices + +| Slice | Description | Effort | Status | +|-------|-------------|--------|--------| +| 1 | \`tools/bg/scarcity-tracker-gist-experiment.ts\` — standalone script to test the Gist append-only updates approach | S | extracted | +| 2 | Ruleset carve-out experiment — test if a long-lived branch can bypass Copilot review | M | open | +| 3 | Evaluate experiments and select final design | S | open | +| 4 | Integrate selected design into \`tools/bg/scarcity-tracker.ts\` | M | open | diff --git a/docs/pr-discussions/PR-3974-backlog-b-0583-cross-machine-account-scoped-scarcity-bus-ref.md b/docs/pr-discussions/PR-3974-backlog-b-0583-cross-machine-account-scoped-scarcity-bus-ref.md new file mode 100644 index 0000000000..580c468e93 --- /dev/null +++ b/docs/pr-discussions/PR-3974-backlog-b-0583-cross-machine-account-scoped-scarcity-bus-ref.md @@ -0,0 +1,72 @@ +--- +pr_number: 3974 +title: "backlog(B-0583): cross-machine account-scoped scarcity bus \u2014 refine B-0570 substrate location" +author: "AceHack" +state: "MERGED" +created_at: "2026-05-16T23:31:43Z" +merged_at: "2026-05-17T00:15:11Z" +closed_at: "2026-05-17T00:15:11Z" +head_ref: "backlog/b-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16" +base_ref: "main" +archived_at: "2026-05-17T01:51:02Z" +archive_tool: "tools/pr-preservation/archive-pr.ts" +--- + +# PR #3974: backlog(B-0583): cross-machine account-scoped scarcity bus — refine B-0570 substrate location + +## PR description + +## Summary + +Refines B-0570 (scarcity tracker) substrate location after Aaron's 2026-05-16 correction: rate-limit is account-scoped (tied to AceHack), not agent-scoped; cross-machine matters because Otto-CLI on Aaron's laptop + ServiceTitan-replicated Otto share the same bucket. + +## Why + +Per-agent-named files mis-frame the partition key. Machine-local /tmp/zeta-bus is insufficient for cross-machine visibility. GitHub-branch-as-bus is sharper but hits the Copilot review cost trap from enterprise ruleset #16490134 (`review_on_push: true` on ~ALL repos = burns premium requests on minute-cron pushes). + +## Design space (options in row body) + +- Machine-local /tmp/zeta-bus/scarcity-.json — single-machine only +- Long-lived LFG branch with ruleset carve-out for Copilot review +- Sidecar repo (LFG/Zeta-bus) without enterprise ruleset +- GitHub Action cron writes single state file +- Gist with append-only updates + +Each has trade-offs; row body weighs them. Aaron's explicit framing: 'we can build and try a few different things' — authorizes experimentation rather than pre-commits. + +## Composes with + +- [B-0570](https://github.com/Lucent-Financial-Group/Zeta/pull/3950) (scarcity tracker — REFINES substrate location, keeps tracker logic) +- B-0400 (bus protocol) +- [B-0571](https://github.com/Lucent-Financial-Group/Zeta/pull/3951) (GitHub App — separate pool that would also be tracked) +- [B-0580](https://github.com/Lucent-Financial-Group/Zeta/pull/3957) (Enterprise ruleset — the cost trap to navigate) +- [B-0582](https://github.com/Lucent-Financial-Group/Zeta/pull/3964) (destructive-verb gate — adjacent infrastructure) + +🤖 Generated with [Claude Code](https://claude.com/claude-code) + +## Reviews + +### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T23:36:33Z) + +## Pull request overview + +Adds backlog row B-0583 refining B-0570's substrate location: the scarcity tracker should be account-scoped (not agent-scoped) and cross-machine visible, with a design-space exploration of bus surface options. + +**Changes:** +- New per-row file `docs/backlog/P2/B-0583-*.md` documenting the refinement, design space, acceptance criteria, and open questions. +- Generated index entry added to `docs/BACKLOG.md` under P2. + +### Reviewed changes + +Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments. + +| File | Description | +| ---- | ----------- | +| docs/backlog/P2/B-0583-cross-machine-account-scoped-scarcity-bus-2026-05-16.md | New P2 backlog row refining B-0570 substrate location for cross-machine, account-scoped scarcity tracking. | +| docs/BACKLOG.md | Adds the generated index entry for B-0583 under the P2 section. | + +### COMMENTED — @copilot-pull-request-reviewer (2026-05-17T00:13:59Z) + +## Pull request overview + +Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments. diff --git a/docs/pr-discussions/PR-3975-docs-tick-2341z-otto-cli-background-worker-pr-3964-thread-re.md b/docs/pr-discussions/PR-3975-docs-tick-2341z-otto-cli-background-worker-pr-3964-thread-re.md new file mode 100644 index 0000000000..b630aca007 --- /dev/null +++ b/docs/pr-discussions/PR-3975-docs-tick-2341z-otto-cli-background-worker-pr-3964-thread-re.md @@ -0,0 +1,91 @@ +--- +pr_number: 3975 +title: "docs(tick): 2341Z Otto-CLI background worker \u2014 PR #3964 thread resolution" +author: "AceHack" +state: "MERGED" +created_at: "2026-05-16T23:42:45Z" +merged_at: "2026-05-17T00:07:14Z" +closed_at: "2026-05-17T00:07:14Z" +head_ref: "worktree-gentle-imagining-squirrel" +base_ref: "main" +archived_at: "2026-05-17T01:51:03Z" +archive_tool: "tools/pr-preservation/archive-pr.ts" +--- + +# PR #3975: docs(tick): 2341Z Otto-CLI background worker — PR #3964 thread resolution + +## PR description + +## Summary + +Tick shard capturing background-worker substantive work this tick: + +- Sentinel re-armed (catch-43) +- Polled 105 open PRs; identified 4 BLOCKED+resolve-threads +- 3 are Lior-lane (Lior actively running, skipped per lane discipline) +- PR #3964 (B-0582 destructive-verb refusal gate) actioned: 3 Copilot threads resolved + - Grammar fix (line 67) + - Acceptance criteria restructured (wrapper OR hook → both required, explicit close condition) + - composes_with refs left in place (stale-but-fresh-looking, in-flight sibling PRs) +- Post-state: PR #3964 has unresolvedThreads=0, auto-merge armed, waiting on CI + +## Test plan + +- [ ] CI green on this PR (docs-only tick shard, no code path touched) +- [ ] PR #3964 auto-merges once its required checks complete + +## Reviews + +### COMMENTED — @chatgpt-codex-connector (2026-05-16T23:44:02Z) + + +### 💡 Codex Review + +Here are some automated review suggestions for this pull request. + +**Reviewed commit:** `58d4bceaec` + + +
ℹ️ About Codex in GitHub +
+ +[Your team has set up Codex to review pull requests in this repo](https://chatgpt.com/codex/cloud/settings/general). Reviews are triggered when you +- Open a pull request for review +- Mark a draft as ready +- Comment "@codex review". + +If Codex has suggestions, it will comment; otherwise it will react with 👍. + + +Codex can also answer questions or update the PR. Try commenting "@codex address that feedback". + +
+ +### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T23:46:42Z) + +## Pull request overview + +Docs-only tick shard recording a background-worker session: re-armed the autonomous-loop sentinel, polled 105 open PRs, identified 4 BLOCKED+resolve-threads PRs (3 skipped per Lior-lane discipline), and resolved 3 Copilot threads on PR #3964. + +**Changes:** +- Adds a new tick history file documenting the 2341Z session work and outcomes. + +### COMMENTED — @AceHack (2026-05-17T00:04:33Z) + +_(no body)_ + +## Review threads + +### Thread 1: docs/hygiene-history/ticks/2026/05/16/2341Z.md:48 (resolved) + +**@chatgpt-codex-connector** (2026-05-16T23:44:02Z): + +**![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat) Fix broken relative links in Composes with section** + +The `Composes with` links use `../../../../../.claude/...`, but from `docs/hygiene-history/ticks/2026/05/16/` that path resolves to `docs/.claude/...` (nonexistent), so all four references in this section are dead. This breaks traceability for the tick record and should be updated to go up one more level (as used by sibling tick files) so links resolve to repo-root `.claude/rules/*`. + +Useful? React with 👍 / 👎. + +**@AceHack** (2026-05-17T00:04:33Z): + +Confirmed — tick file is 6 levels deep under repo root; sibling tick files use `../../../../../../.claude/rules/*`. Fixed in e2db2c4e plus an MD032 blank-line fix for the lint job.