feat(B-0581): decompose Slice 2 (detailed spec) from PR 3961

docs/backlog/P2/B-0581-gh-auth-refresh-skill-wrapper-2026-05-16.md

@@ -0,0 +1,139 @@
+---
+id: B-0581
+priority: P2
+status: open
+title: "Skill — wrap `gh auth refresh` interactive flow + record scope-grant registry (per-machine, per-human-touch)"
+tier: factory-infrastructure
+effort: S
+created: 2026-05-16
+last_updated: 2026-05-16
+depends_on: []
+composes_with: [B-0570, B-0571, B-0580]
+tags: [skill, github, auth, oauth, scope-management, registry, human-in-the-loop]
+type: feature
+---
+
+# Skill — `gh auth refresh` interactive-flow wrapper + scope-grant registry
+
+## Origin
+
+Aaron 2026-05-16, after Otto tried to fire `gh auth refresh` blindly via Bash tool and got blocked on the interactive Y/n prompt:
+
+> *"we need a skill around this"*
+
+Then, when describing the maintainer-side experience:
+
+> *"you have to hit enter once i think to make it pop open"*
+
+And after I confirmed the operational pattern:
+
+> *"when we work on that backlog item i can be he human that clicks the screen to test it"*
+
+The empirical artifact that triggered the row: a successful gh auth refresh run that surfaced the operational flow:
+
+```text
+$ gh auth refresh -h github.com -s "<comma-separated-scopes>"
+? Authenticate Git with your GitHub credentials? Yes
+! First copy your one-time code: 472D-B3EF
+Press Enter to open https://github.com/login/device in your browser...
+✓ Authentication complete.
+```
+
+Otto running this command via Bash tool either hangs at the Y/n prompt or — if it answers — burns the one-time code (`472D-B3EF`) without surfacing it to the human. The code is the load-bearing credential that the human must transfer terminal→browser.
+
+## What
+
+A skill (`.claude/skills/gh-auth-refresh-wrapper/SKILL.md`) that wraps the `gh auth refresh` flow so:
+
+1. Otto knows what scopes are being requested (it constructed the command)
+2. The one-time code is surfaced PROMINENTLY to the human (chat output minimum; clipboard copy + OS notification as enhancements)
+3. The Enter-to-open-browser step is pumped automatically (or the human is told exactly what to type)
+4. Post-approval, `gh auth status` is polled until the new scopes appear
+5. The scope grant is RECORDED in a registry: which machine, which scopes, which human approved, when
+
+## Acceptance criteria
+
+- [ ] `.claude/skills/gh-auth-refresh-wrapper/SKILL.md` exists with carved-sentence + operational content
+- [ ] Skill body documents the 6-step flow (preceding section)
+- [ ] Skill includes a `tools/auth/gh-auth-refresh-wrapper.ts` helper that:
+  - Spawns `gh auth refresh -h github.com -s <scope-list>` with stdin pumped to handle Y/n
+  - Streams stdout; on detection of `! First copy your one-time code: <CODE>`, captures the code
+  - Displays code to the human PROMINENTLY (e.g., to stdout with a large banner + macOS `osascript -e 'display notification ...'` for OS-level surfacing + `pbcopy` for clipboard)
+  - Pumps Enter to trigger browser open (only after surfacing the code to give the human time to copy)
+  - Polls `gh auth status` until target scopes appear (or timeout)
+- [ ] Registry written to `~/.local/share/zeta/scope-grants.jsonl` (or similar) — append-only JSON-lines log of: `{machineId, scopes[], grantedBy, grantedAt, command}`
+- [ ] Tests: helper-script unit tests with injected stdin/stdout streams covering: success path, Y/n refusal, OAuth timeout, code-capture regex
+- [ ] Documented in the skill's body + composes-with B-0570 (scarcity tracker — scope grant affects available API budget)
+
+## Why now
+
+The 2026-05-16 session demonstrated the exact failure mode: Otto fired the command via Bash tool, the interactive flow hung, the user rejected the tool call, then ran it himself in his terminal and walked through the OAuth flow manually. The substrate-honest discipline says: encode this workflow in a skill so future-Otto (and future humans) follow the right shape automatically.
+
+Composes with several recent landings:
+
+- B-0570 (scarcity tracker) — scope grants affect what API calls Otto can make + the budget categories it can monitor
+- B-0571 (GitHub App for factory automation) — the PRODUCTION-grade alternative to this human-laptop-OAuth flow; both can coexist
+- B-0580 (Enterprise ruleset mgmt) — uses enterprise-scope APIs that need scope grants this skill wraps
+
+Plus the canonical memory file: `feedback_aaron_fine_grained_pat_workflow_for_otto_human_maintainer_pattern_not_production_2026_05_16.md` (user-scope memory) — captures the full workflow + the empirical pattern this skill operationalizes.
+
+## Decomposition into implementation slices
+
+| Slice | Description | Effort | Status |
+|-------|-------------|--------|--------|
+| 1 | `tools/auth/gh-auth-refresh-wrapper.ts` — spawn gh + stdin pump + stdout regex for code capture | S | open |
+| 2 | Code-surfacing UI: stdout banner + `pbcopy` + `osascript` notification | XS | open |
+| 3 | Post-approval scope-status polling loop with timeout | XS | open |
+| 4 | Registry write: `~/.local/share/zeta/scope-grants.jsonl` append on success | XS | open |
+| 5 | `.claude/skills/gh-auth-refresh-wrapper/SKILL.md` — invoke procedure, carved sentence | XS | open |
+| 6 | Tests with injected stdin/stdout streams (success / refusal / timeout / regex) | S | open |
+
+Total: S (small overall — one short evening's work)
+
+## Test plan
+
+**Aaron volunteered to be the human-in-the-loop for testing**:
+
+> *"when we work on that backlog item i can be he human that clicks the screen to test it"*
+
+So when this row gets picked up:
+
+1. Otto implements the slices
+2. Otto invokes the wrapper from a test script targeting a minimal scope (e.g., `gist`)
+3. Aaron approves in his browser
+4. Verify the code was surfaced before the browser-open prompt
+5. Verify `gh auth status` shows the new scope post-approval
+6. Verify the registry entry got written with correct fields
+
+## Composes with
+
+- B-0570 (scarcity tracker — scope changes the API surface available)
+- B-0571 (GitHub App for factory automation — production alternative)
+- B-0580 (Enterprise ruleset management — uses scopes this skill grants)
+- `feedback_aaron_fine_grained_pat_workflow_for_otto_human_maintainer_pattern_not_production_2026_05_16.md` (user-scope memory — origin substrate)
+- `.claude/rules/methodology-hard-limits.md` (scope grants are budget-touching; the rule's least-privilege principle composes)
+- `.claude/rules/dont-ask-permission.md` (within authority — Otto requests scopes via this skill; human-in-loop approval is built into the flow itself)
+- `.claude/skills/make-persistent/SKILL.md` (sibling skill: installs persistent agent service; similarly multi-step, with operational details that need encoding)
+
+## Substrate-honest caveats
+
+- This skill targets the MAINTAINER-LAPTOP workflow, not production. Production should use GitHub App (B-0571).
+- The registry (`~/.local/share/zeta/scope-grants.jsonl`) is per-machine local storage. Multi-machine visibility would need a separate aggregation step (probably out of scope for the first version).
+- The `pbcopy` + `osascript` notifications are macOS-only. Cross-platform support (Linux/Windows) is a future slice.
+- The polling for post-approval scope appearance has a timeout; if the human takes >timeout to approve, the skill should surface "approval still pending, run `gh auth status` later to verify" rather than hang or error.
+- Some scope names get collapsed by GitHub's OAuth flow (e.g., `manage_billing:enterprise` may not appear in the resulting list but billing endpoints work via `admin:enterprise`). The skill should record what was REQUESTED + what's currently GRANTED — both, not just one.
+
+## Open questions
+
+1. **Registry location**: `~/.local/share/zeta/scope-grants.jsonl` or in-repo `docs/auth/scope-grants.jsonl`? Per-machine is JSONL-local; in-repo would need conflict-resolution. JSONL-local is simpler for v1.
+2. **Human identifier**: GitHub username from `gh api user --jq .login`? Or local OS username from `whoami`? Both for cross-reference?
+3. **Machine identifier**: `hostname` is human-readable; `system_profiler SPHardwareDataType` gets the hardware UUID on macOS. Probably hostname for simplicity.
+4. **Code-surface UX**: should the skill PAUSE waiting for the human to confirm they've copied the code, before pumping Enter? Safer but adds an extra interaction. Alternative: surface the code prominently and wait a few seconds before pumping Enter (giving copy time without explicit confirmation).
+5. **Stdin pumping for Y/n**: should the skill auto-answer Y, or surface the prompt to the human? Y is the safe default (it's the literal default), but human visibility might be preferred.
+
+## Pre-start checklist
+
+- [x] Prior-art search: no existing gh-auth-refresh wrapper in `tools/`
+- [x] Dependency proof: depends only on `gh` CLI being installed (standard prerequisite)
+- [x] Empirical: the failure mode + the successful manual flow both observed 2026-05-16 (Aaron's terminal run with one-time code `472D-B3EF`)
+- [x] Human test-volunteer identified: Aaron

docs/pr-discussions/PR-3816-shard-tick-2026-05-16t07-45z-pure-git-tick-pr-3814-merged-vi.md

@@ -0,0 +1,34 @@
+---
+pr_number: 3816
+title: "shard(tick): 2026-05-16T07:45Z \u2014 pure-git tick; PR #3814 merged via peer-assisted cross-lane open"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-16T07:56:28Z"
+merged_at: "2026-05-16T07:57:47Z"
+closed_at: "2026-05-16T07:57:47Z"
+head_ref: "shard/tick-0745z-otto-cli-2026-05-16"
+base_ref: "main"
+archived_at: "2026-05-16T08:25:36Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #3816: shard(tick): 2026-05-16T07:45Z — pure-git tick; PR #3814 merged via peer-assisted cross-lane open
+
+## PR description
+
+Pure-git tick. PR #3814 (last tick's B-0346 audit shard) merged — peer Otto opened the PR for the branch I pushed but couldn't PR due to rate-limit exhaustion. NEW convergence pattern: peer cross-lane PR-opening closes rate-limit gaps.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T07:58:16Z)
+
+## Pull request overview
+
+Adds a new hygiene-history tick shard documenting the 2026-05-16T07:45Z “pure-git” tick, including refresh state, the peer-assisted PR-opening pattern observed for PR #3814, and the operational rationale/visibility signals for the session.
+
+**Changes:**
+- Added a new tick entry capturing the 07:45Z state (rate-limit at 0/5000, sentinel alive, `origin/main` advanced).
+- Documented the new “peer cross-lane PR-opening” convergence pattern used to bridge rate-limit exhaustion.
+- Recorded the pure-git operational rationale and close-out visibility bullets.

docs/pr-discussions/PR-3818-rule-holding-discipline-cascade-saturation-empirical-anchor.md

@@ -0,0 +1,54 @@
+---
+pr_number: 3818
+title: "rule(holding-discipline): cascade-saturation empirical anchor + pure-git compatibility + sub-case 5"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-16T07:56:57Z"
+merged_at: "2026-05-16T07:58:16Z"
+closed_at: "2026-05-16T07:58:16Z"
+head_ref: "rule/holding-discipline-cascade-saturation-otto-cli-2026-05-16"
+base_ref: "main"
+archived_at: "2026-05-16T08:25:36Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #3818: rule(holding-discipline): cascade-saturation empirical anchor + pure-git compatibility + sub-case 5
+
+## PR description
+
+## Summary
+
+Three edits to `.claude/rules/holding-without-named-dependency-is-standing-by-failure.md` based on this session's empirical evidence:
+
+1. **Concrete-artifact definition** expanded to cover pure-git tier (branch-pushed-no-PR counts for counter reset)
+2. **Cascade-saturation empirical anchor** sub-section — rule operated correctly through 4 cycles this session; validates 5 properties including multi-cycle non-accumulation
+3. **NEW sub-case 5 discovered during authoring**: peer-side destructive git operations (`git reset --hard`, etc.) discard unstaged tracked-modifications. First authoring attempt of THIS commit was destroyed; re-application IS the empirical proof. Mitigation: commit immediately after Edit during peer saturation.
+
+Recursively self-validating: the meta-fallback's claim ("ALWAYS works because session behavior is observable") is proven BY the act of authoring it. The commit IS the session's behavior being documented.
+
+Composes with `refresh-world-model-poll-pr-gate.md` (rate tiers) + `claim-acquire-before-worktree-work.md` (saturation-ceiling sub-cases — sub-case 5 to land there in follow-up).
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T07:58:17Z)
+
+## Pull request overview
+
+Documentation-only edits to a Claude rules file that codifies session-empirical observations about cascade-saturation behavior and a newly-discovered worktree-borrow failure sub-case. Also appends a resolution table to backlog row B-0557.
+
+**Changes:**
+- Expands "concrete artifact" definition in the holding-discipline rule to include pure-git tier branch-pushed-no-PR substrate.
+- Adds a cascade-saturation empirical-anchor sub-section documenting four observed cycles and five validated properties.
+- Adds sub-case 5 (peer-side destructive git operations discard unstaged tracked-modifications) plus mitigation.
+- Appends Resolution table for B-0557 listing the four shipped slices.
+
+### Reviewed changes
+
+Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
+
+| File | Description |
+| ---- | ----------- |
+| `.claude/rules/holding-without-named-dependency-is-standing-by-failure.md` | Adds pure-git artifact clause, cascade-saturation anchor section, and sub-case 5 with mitigation. |
+| `docs/backlog/P3/B-0557-...-2026-05-16.md` | Appends Resolution section with per-slice PR/merge-commit table and test-count delta. |

docs/pr-discussions/PR-3819-chore-b-0557-close-row-all-4-quality-slices-shipped-infrastr.md

@@ -0,0 +1,70 @@
+---
+pr_number: 3819
+title: "chore(b-0557): close row \u2014 all 4 quality slices shipped (infrastructure-eats-itself)"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-16T08:00:46Z"
+merged_at: "2026-05-16T08:07:51Z"
+closed_at: "2026-05-16T08:07:51Z"
+head_ref: "chore/b0557-close-row-otto-cli-2026-05-16"
+base_ref: "main"
+archived_at: "2026-05-16T08:25:56Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #3819: chore(b-0557): close row — all 4 quality slices shipped (infrastructure-eats-itself)
+
+## PR description
+
+## Summary
+
+- Closes [B-0557](docs/backlog/P3/B-0557-audit-backlog-status-drift-quality-improvements-2026-05-16.md). All 4 quality-improvement slices shipped within the same 2026-05-16 session that filed the row.
+- **Infrastructure-eats-itself moment**: the audit tool that B-0557 specified would have flagged B-0557 itself as a genuine drift candidate (every primary artifact on main, all acceptance bullets shipped, status still `open`).
+
+## Slice trail
+
+| Slice | PR | Merge commit |
+|---|---|---|
+| 1 — `--check` flag | [#3783](https://github.com/Lucent-Financial-Group/Zeta/pull/3783) | `0a57a814` |
+| 2 — try/catch on FS reads | [#3788](https://github.com/Lucent-Financial-Group/Zeta/pull/3788) | `6809f6e3` |
+| 3 — chdir to repo root + 2 tests | [#3790](https://github.com/Lucent-Financial-Group/Zeta/pull/3790) | `472024dc` |
+| 4 — mixed-bullet + tsc-strict fix | [#3809](https://github.com/Lucent-Financial-Group/Zeta/pull/3809) | `eb04e3d` |
+
+## Test plan
+
+- [x] Row status flipped to closed + closed: 2026-05-16
+- [x] Resolution section maps all 4 slices to merge commits
+- [x] `BACKLOG.md` regen single-line `[ ]` → `[x]` for B-0557
+- [x] All 20 audit-tool tests passing on main
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T08:02:33Z)
+
+## Pull request overview
+
+This PR closes backlog row B-0557 and updates the generated backlog index to mark the quality-improvement work as complete.
+
+**Changes:**
+- Marks B-0557 as `closed` with a `closed` date.
+- Adds a resolution section mapping the four shipped slices to PRs and merge commits.
+- Regenerates `docs/BACKLOG.md` to show B-0557 as closed.
+
+### Reviewed changes
+
+Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
+
+| File | Description |
+| ---- | ----------- |
+| `docs/backlog/P3/B-0557-audit-backlog-status-drift-quality-improvements-2026-05-16.md` | Closes the per-row backlog item and documents resolution evidence. |
+| `docs/BACKLOG.md` | Updates the generated backlog index checkbox for B-0557. |
+
+## Review threads
+
+### Thread 1: docs/backlog/P3/B-0557-audit-backlog-status-drift-quality-improvements-2026-05-16.md:92 (resolved)
+
+**@copilot-pull-request-reviewer** (2026-05-16T08:02:32Z):
+
+This closure still asserts that the cwd-independent acceptance bullet is complete, but the shipped implementation only resolves the repo root via `git rev-parse` from the current working directory and falls back to `process.cwd()` outside a Git repo. That does not satisfy the row’s existing `cd /tmp && bun /path/to/...` acceptance criterion, so either narrow the acceptance text/resolution to “from repo subdirectories” or land the import.meta-based root detection before closing the row.

docs/pr-discussions/PR-3820-chore-b-0272-close-row-tosec-canonicalizer-shipped-2026-05-0.md

@@ -0,0 +1,43 @@
+---
+pr_number: 3820
+title: "chore(b-0272): close row \u2014 TOSEC canonicalizer shipped 2026-05-09 (10th pure-drift)"
+author: "AceHack"
+state: "MERGED"
+created_at: "2026-05-16T08:01:17Z"
+merged_at: "2026-05-16T08:02:37Z"
+closed_at: "2026-05-16T08:02:37Z"
+head_ref: "chore/b0272-close-row-otto-cli-2026-05-16"
+base_ref: "main"
+archived_at: "2026-05-16T08:27:25Z"
+archive_tool: "tools/pr-preservation/archive-pr.ts"
+---
+
+# PR #3820: chore(b-0272): close row — TOSEC canonicalizer shipped 2026-05-09 (10th pure-drift)
+
+## PR description
+
+Pure-drift close. All 3 acceptance items shipped via PRs #2166 + #2168 + #2172. Surfaced by audit tool; per-acceptance verification confirmed.
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+## Reviews
+
+### COMMENTED — @copilot-pull-request-reviewer (2026-05-16T08:03:00Z)
+
+## Pull request overview
+
+Closes backlog row **B-0272** as shipped (pure-drift close) and updates the main backlog index to reflect the closed status.
+
+**Changes:**
+- Mark **B-0272** row frontmatter as `status: closed`, updating `last_updated` and adding `closed` date.
+- Add a **Resolution** section documenting why/how the row is being closed (pure drift) and linking to the shipping PRs.
+- Flip **B-0272** to checked/closed in `docs/BACKLOG.md`.
+
+### Reviewed changes
+
+Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
+
+| File | Description |
+| ---- | ----------- |
+| docs/backlog/P1/B-0272-atari-rom-canonical-naming-tosec-lookup-2026-05-08.md | Closes the row and records resolution/provenance for the shipped acceptance criteria. |
+| docs/BACKLOG.md | Updates the P1 index entry for B-0272 to show it as closed. |