From c4ba5783b097a0255c6c67d238849e2e3b87dd1c Mon Sep 17 00:00:00 2001 From: hyochan Date: Sat, 21 Nov 2026 00:22:55 +0900 Subject: [PATCH] chore(agents): add autonomous maintenance cycle --- .agents/README.md | 7 +- .agents/scripts/sync-skills.sh | 10 +- .agents/skills/loop-review/SKILL.md | 82 ++++++------ .agents/skills/maintain/SKILL.md | 121 ++++++++++++++++++ .agents/skills/maintain/agents/openai.yaml | 4 + .../skills/maintain/scripts/coordinator.py | 56 ++++++++ .../maintain/scripts/test_coordinator.py | 80 ++++++++++++ .agents/skills/release-update/SKILL.md | 26 +++- .agents/skills/review-self/SKILL.md | 11 +- .agents/skills/update-version/SKILL.md | 47 ++++--- .../update-version/references/workflow.md | 86 ++++++------- .claude/skills/maintain/SKILL.md | 22 ++++ .codex/skills/analyze/SKILL.md | 6 +- .codex/skills/commit/SKILL.md | 6 +- .codex/skills/e2e-test/SKILL.md | 6 +- .codex/skills/grow/SKILL.md | 6 +- .codex/skills/loop-review/SKILL.md | 6 +- .codex/skills/loop-ui/SKILL.md | 6 +- .codex/skills/maintain/SKILL.md | 22 ++++ .codex/skills/maintain/agents/openai.yaml | 4 + .codex/skills/perf-audit/SKILL.md | 6 +- .codex/skills/release-update/SKILL.md | 6 +- .codex/skills/review-pr/SKILL.md | 6 +- .codex/skills/review-self/SKILL.md | 6 +- .codex/skills/update-version/SKILL.md | 6 +- .cursor/rules/maintain.mdc | 26 ++++ .github/workflows/ci.yml | 3 + .grok/skills/maintain/SKILL.md | 21 +++ .notes/DECISIONS.md | 26 ++++ .notes/STATUS.md | 85 ++++++++++++ AGENTS.md | 30 ++++- CLAUDE.md | 30 ++++- shared/AGENTS.md | 5 +- 33 files changed, 720 insertions(+), 150 deletions(-) create mode 100644 .agents/skills/maintain/SKILL.md create mode 100644 .agents/skills/maintain/agents/openai.yaml create mode 100644 .agents/skills/maintain/scripts/coordinator.py create mode 100644 .agents/skills/maintain/scripts/test_coordinator.py create mode 100644 .claude/skills/maintain/SKILL.md create mode 100644 .codex/skills/maintain/SKILL.md create mode 100644 .codex/skills/maintain/agents/openai.yaml create mode 100644 .cursor/rules/maintain.mdc create mode 100644 .grok/skills/maintain/SKILL.md create mode 100644 .notes/STATUS.md diff --git a/.agents/README.md b/.agents/README.md index 466df16..c910f4b 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -49,14 +49,15 @@ a `NN-` prefix (for example `00-project.mdc`) and are never generated or pruned. ``Use when the user runs `/` or `$`, ...`` so every agent's invocation syntax matches. 2. Put anything long in `.agents/skills//references/`. -3. Run `bash .agents/scripts/sync-skills.sh`. -4. Add `.codex/skills//agents/openai.yaml` if the skill should show up in - the Codex skill picker. +3. Optionally author `agents/openai.yaml` in the canonical skill directory. + The sync copies it to the Codex pointer for skill-picker discovery. +4. Run `bash .agents/scripts/sync-skills.sh`. ## Current skills | Skill | Purpose | | --- | --- | +| `maintain` | One serialized maintenance/product cycle, recovery and delivery | | `commit` | Branch checks, conventional commits, push, PR | | `review-self` | Self-review loop over the current work until stable | | `review-pr` | PR review findings and review-comment handling | diff --git a/.agents/scripts/sync-skills.sh b/.agents/scripts/sync-skills.sh index 319888b..1b3bc15 100755 --- a/.agents/scripts/sync-skills.sh +++ b/.agents/scripts/sync-skills.sh @@ -27,8 +27,10 @@ codex_notes() { - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. EOF } @@ -114,6 +116,10 @@ for dir in "$canonical_dir"/*/; do write_pointer .codex "Codex" codex_notes "$name" "$title" "$description" write_pointer .grok "Grok" grok_notes "$name" "$title" "$description" write_cursor_pointer "$name" "$title" "$description" + if [ -f "$dir/agents/openai.yaml" ]; then + mkdir -p ".codex/skills/$name/agents" + cp "$dir/agents/openai.yaml" ".codex/skills/$name/agents/openai.yaml" + fi echo "generated: $name" done diff --git a/.agents/skills/loop-review/SKILL.md b/.agents/skills/loop-review/SKILL.md index 92cfa46..4d5ac7c 100644 --- a/.agents/skills/loop-review/SKILL.md +++ b/.agents/skills/loop-review/SKILL.md @@ -7,7 +7,7 @@ description: Run BooKoo's complete change-to-merge loop from the latest origin/m Own one BooKoo change from a fresh `main` baseline through a verified merge. Delegate to the sibling skill that owns a procedure instead of restating it. -Only the steps no sibling skill owns — external reviewer requests, polling, the +Only the steps no sibling skill owns — polling, the regression gates, and the merge — are specified here. ## Load The Workflows @@ -20,17 +20,22 @@ Read before acting: An explicit invocation authorizes the in-scope commit, push, PR creation, review replies, thread resolution, and merge for this task. It does not authorize `$release-update`, store submission, Expo updates, running data migrations -against production Convex, or unrelated cleanup. +against production Convex, or unrelated cleanup. Existing standing authority in +AGENTS.md still applies when this is a `$maintain` continuation. ## 1. Start From Current Main 1. Snapshot `git status --short --branch`. Preserve every existing change. -2. For a new task, require a clean worktree, then `git fetch origin`, switch to - `main`, and `git pull --ff-only origin main`. -3. Confirm local `main` equals `origin/main`, then create a semantic branch - using the naming rules in `$commit` — `feat/`, `bugfix/`, `docs/`, - `refactor/`, `test/`, or `chore/`. Never a tool or vendor prefix. -4. Record the starting main SHA. The implementation diff must descend from it. +2. Resolve the canonical repository and remote first. For `$maintain`, it is + `hyodotdev/BooKoo`; an ops clone's `origin` can point elsewhere. Fetch that + remote's main explicitly and record its full SHA as the integration base. +3. Require a clean task worktree before claiming new work. Branch from that + fetched main using `$commit` naming rules. Fast-forward an existing local + main only when its lineage matches and no other task uses it; otherwise + preserve it and use an isolated checkout/worktree based on canonical main. +4. Record the remote name and main SHA. Use that remote/main throughout this + loop, including PRs, ancestry checks, push and final readback; `origin/main` + in examples is not authority to integrate into a different repository. If invoked for work already in progress, treat it as a resumed loop. Do not stash, reset, switch branches, or discard anything. Verify the merge base and @@ -71,15 +76,11 @@ Follow `$commit` with push and PR: - Push the semantic branch and open an English PR against `main`. - Apply 1–3 existing repository labels; never invent new ones. -`$commit` does not request external reviewers, so this loop does it. Request -whichever review bot the repository actually has configured, and never block on -the response: post the request, then run the exact-head `$review-self` fallback -in the same round so the head has review coverage immediately. If the bot -reports later on that same head, handle its findings as a new round. - -Do not substitute a different review bot for one that is unavailable, and never -count a silently-ignored reviewer request as coverage — the -`requested_reviewers` API accepts unknown reviewers and adds nobody. +Use `$review-self` for change reviews. Do not request Muse or substitute another +external reviewer. Inspect existing human/automation feedback through `$review-pr`; +report self-review honestly without claiming independent coverage. The single-round +fallback below handles feedback during polling; it does not replace step 3's two +clean snapshots separated by five minutes. When the pushed head is identical to the diff step 3 already stabilized, record that coverage against the head SHA instead of repeating the round. Any later @@ -90,8 +91,8 @@ clean review coverage. ## 5. Poll Until The Exact Head Is Clean -Run `$review-pr` immediately, then re-enter it every five minutes through the -product's recurring wake-up mechanism. `loop-review` is the only polling owner; +Run `$review-pr` immediately, then re-enter it every five minutes through +supported bounded tool waits in the active task. `loop-review` is the only polling owner; `review-pr` performs one pass per round. Each round: @@ -102,20 +103,17 @@ Each round: comment with the plain commit hash, and resolve only the threads you replied to with a fix. 3. Rerun the checks the batch affects plus everything previously failing. -4. After a head change, redo step 4 for the new SHA — re-request the reviewer +4. After a head change, redo step 4 for the new SHA — rerun the affected self-review and re-establish head coverage, since the push invalidated the previous round. -5. Keep polling while CI is pending or a reviewer has reported findings you have - not handled. A missing reviewer response never holds the loop open. Do not - rerun expensive unchanged local checks on a no-op poll, and never retrigger a - review bot on a no-op. +5. Keep polling while CI or actionable feedback is pending. Do not rerun + expensive unchanged local checks on a no-op poll or request review bots. Clean means all of these hold for the same head SHA: - zero unresolved actionable review threads; -- the head has review coverage — either the external reviewer reported on it - with nothing actionable left, or the exact-head `$review-self` fallback ran - clean; +- the head has clean `$review-self` coverage and step 3's two separated clean + snapshots still cover this exact tree; a single fallback is insufficient; - every required CI check is terminal and successful; - the PR is mergeable and carries every required update from `main`; - the worktree is clean and the final diff has been reread. @@ -139,13 +137,11 @@ sign-in providers, invite deep links, app lock, receipt photo capture, notifications, `app.config.ts`, `plugins/`, `android/`, `ios/`, or dependency changes that reach the runtime. -When it is required, **stop without merging even if the PR is otherwise -clean**. Report the scenarios the diff implicates and hand back to the user. Two -things clear the gate, and both are recorded on the PR first: - -1. An `$e2e-test` run covering the implicated scenarios, with its result posted. -2. An explicit written waiver from the user in this conversation, naming what is - waived and why. Record it verbatim on the PR. +When required, run `$e2e-test` for the implicated scenarios and record its +result on the PR before merging. Missing or failed native gates block merging. +Only an explicit written owner waiver naming the omitted checks and reason can +waive a missing gate; record it verbatim. Do not request a waiver for checks that +can be completed under standing authority. Absence of an objection is not a waiver, and the loop never grants itself one. Green CI is not a substitute — CI does not launch a simulator, add a ledger @@ -158,18 +154,20 @@ that justify it; silence reads as an untested merge. ## 7. Merge And Close The Loop Immediately before merging, refetch the PR and confirm its head still equals the -clean reviewed SHA. Squash merge with branch deletion unless a stricter policy -applies. Never bypass branch protection or merge a stale, pending, or failing -head. +clean reviewed SHA. Follow root AGENTS.md: strict nonforce fast-forward only. +Confirm remote main is an ancestor of the reviewed head. Inspect current protection and +rulesets first. If permitted, push the reviewed head to main without force and +verify GitHub marks the PR merged. If protection requires a different method, +report the conflict without bypassing it. Do not silently substitute squash or +merge a stale, pending, or failing head. After merge: 1. Confirm the PR state is `MERGED` and record the merge commit. -2. Delete the reviewer-trigger comments this loop posted and any terminal - "review skipped/unavailable" notices. Never delete human comments, inline - replies, or substantive review feedback. -3. Switch to `main` and fast-forward from `origin/main` when that cannot disturb - other work. +2. Preserve substantive review discussion and evidence; no reviewer-trigger + comments are needed for self-review. +3. Fast-forward the matching local integration checkout only when that cannot + disturb other work. Preserve any legacy ops main with a different history. 4. Report the PR, merge commit, final checks, review coverage, gate results, and anything skipped. Do not release or deploy unless separately requested. diff --git a/.agents/skills/maintain/SKILL.md b/.agents/skills/maintain/SKILL.md new file mode 100644 index 0000000..1e494aa --- /dev/null +++ b/.agents/skills/maintain/SKILL.md @@ -0,0 +1,121 @@ +--- +name: maintain +description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes. +--- + +# Maintain + +Coordinate existing skills; keep their implementation and gates authoritative. +Standing owner authority and its exceptions live in +[AGENTS.md](../../../AGENTS.md#autonomous-operation). Current scope, evidence and +resume point live only in [STATUS](../../../.notes/STATUS.md); decisions and +visual direction stay in their existing `.notes/` owners. + +## Acquire Before Acting + +1. Verify the checkout and canonical remote `https://github.com/hyodotdev/BooKoo`. + An older ops checkout may have unrelated history: preserve it and use the + existing public worktree/checkout. Discover actual remote names; do not assume + `origin` points to the public repo. Inspect Git status without exposing `.local/`. +2. Acquire the host-wide OS lock with + `python3 .agents/skills/maintain/scripts/coordinator.py hold --owner ` + in a managed interactive terminal. Keep that terminal/process alive throughout + the cycle. Require its `ACQUIRED` result; exit code 75 means another run owns + the coordinator: report contention and exit without starting any mutations. + A new checkout without the skill must acquire the same lock from an existing + checkout before creating branches or installing anything. +3. `status` probes the actual kernel lock, not PID guesses. The lock is shared + across worktrees and clones on this host. If the holder dies, the OS releases + it; retain the lock file/inode and acquire it normally. Never unlink it or kill + an unfamiliar holder. A live orphan needs inspection of its terminal/run before + stopping it. Across hosts require shared scheduler concurrency; this local + lock alone is insufficient. Never enable a second host coordinator. +4. Immediately before each mutation after a wait, ensure the holder terminal is + alive and `status` still reports the same owner/PID. If ownership is lost, + stop mutations and reacquire before reconstructing remote state. +5. Release by sending a newline to the holder terminal only after saving the + resume point and stopping owned transient processes. Do not leave a holder + running across a saved external/PENDING checkpoint. + +## Recover And Select + +- Read STATUS, current owner goal, root/directory rules, package/lockfile, current + workflows and relevant sibling skills. Fetch the canonical main; inspect open + PRs, exact CI and release tags/runs. Recover existing task branches first. + Preserve unrelated edits; isolate new work rather than stashing or resetting. +- Recover a pending/failed release before starting a dependent bundle. Query each + platform separately: source/tag, artifact/build ID, internal upload, review, + approval and public availability are different facts. A successful GitHub + Release run only proves dispatch. After timeout query remote state before retry. +- If authentication/external review is the only blocker, record exact prerequisites + and continue independent maintenance; never duplicate an upload or submission. +- With no new goal, choose one evidenced bug/security/performance/compatibility/CI/ + documentation fix. With a product goal, define flows, acceptance and order; + record new direction proposals instead of implementing them without an owner goal. +- Before edits, claim one branch in STATUS with purpose, dependency order, + acceptance, base SHA and expected delivery path. Bound the bundle: newly found + unrelated updates go to the next cycle unless urgent or a real prerequisite. + Use official release notes and compatibility sources for upgrades, preserve + `.ncurc.json` exclusions and patch purposes, and review cumulative native changes. + +## Execute Through Existing Owners + +| Need | Reuse | +| --- | --- | +| Aggregate growth evidence / one growth experiment | `$analyze` / `$grow`, only when relevant to the owner's goal | +| Implementation to integration | `$loop-review` with `$commit`, `$review-self`, `$review-pr` | +| Lists, Convex, rollups | `$perf-audit` | +| UI refinement and implicated device scenarios | `$loop-ui` / `$e2e-test` | +| Marketing version / explicit build-floor decision | `$update-version` | +| Backend, OTA, candidate, store and follow-up | `$release-update` and purchase acceptance matrix | + +Keep one coordinator and one review polling owner. Perform edits, installs, +hook installation, prebuild, integration and delivery sequentially. Self-review +must retain two complete clean snapshots at least five minutes apart covering +the final tree, terminal CI and resolved feedback. A single polling fallback +cannot replace this. Do not invoke external reviewers or call self-review +independent. Use bounded tool waits in the current task, not another automation +watching this PR. Save PENDING when the runtime cannot continue. + +Run current CI's mandatory commands: frozen copyfile install, `bun lint:all`, +`bun typecheck`, coverage tests, full-history secret scan and the separate +anonymous local Convex 100k budget job. The budget child success marker is +required; exit 0 from its parent is insufficient. General Jest may skip that +suite. Prefer exact-head CI for isolated budget/history evidence; never borrow +an old SHA's result for changed inputs. Local QA must remove inherited deployment +credentials and use the existing anonymous runner. Store bounded logs/artifacts +on the verified DevLogs volume on the owner's host; no internal bulk fallback. +Record PASS / FAIL / PENDING / N/A per check and invalidate affected evidence +when files change. Required premerge native gates remain mandatory. + +Read branch protection/rulesets and root merge policy immediately before +integration; use nonforce fast-forward when permitted, never implicit squash or +an admin bypass. Recheck remote main ancestry and exact reviewed head. Verify +GitHub recognizes the PR merge and check the exact main CI/deploy job afterwards. + +## Decide Delivery And Resume + +- Docs, skills and development-tooling-only bundles finish with integration and + exact-main verification. Do not dispatch OTA or store tags for them. +- Runtime bundles deliver only when their acceptance and applicable source, + native, purchase and old-client/backend compatibility gates pass. Compare + cumulative changes since each platform's actual last public artifact. +- Reuse the existing backend CI, Patch OTA or Codemagic/local EAS native path; + no EAS cloud builds. Require backend/index readiness before a dependent client. + Verify target binary/version/fingerprint before asserting OTA compatibility. + Internal candidate uploads precede final candidate acceptance; public review/ + rollout waits for it. Do not raise force-update floors with routine releases. +- Before release record last healthy source/artifact and a supported recovery + path. Verify deployed functions and relevant smoke/error signals afterwards + without gathering private ledgers. On regression stop dependent releases and + use a verified compatible fix, supported OTA recovery or rollout halt. +- Limit the same failure to three cause-based attempts (or a stricter sibling + limit). New evidence must justify a retry. Save exact PR/base/head/merge, + checks, deployment states, external conditions and next runnable action in + STATUS/PR; no duplicate backlog/history file or date-only commits. GitHub PR + metadata owns final merge SHA, avoiding a SHA-only follow-up commit. +- Daily scheduling belongs to the supported app scheduler, once at 09:00 + Asia/Seoul after the first verified cycle. Inspect existing schedules before + creating/updating one; no recursive runner or schedule proliferation. A local + run needs the host awake, app running, project access, credentials and DevLogs + for bulk work. If unavailable, report `$maintain` as the supported manual entry. diff --git a/.agents/skills/maintain/agents/openai.yaml b/.agents/skills/maintain/agents/openai.yaml new file mode 100644 index 0000000..0dea7b9 --- /dev/null +++ b/.agents/skills/maintain/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Maintain BooKoo" + short_description: "Run one serialized maintenance and delivery cycle" + default_prompt: "Use $maintain to recover BooKoo's current work and complete one verified maintenance cycle." diff --git a/.agents/skills/maintain/scripts/coordinator.py b/.agents/skills/maintain/scripts/coordinator.py new file mode 100644 index 0000000..775ad05 --- /dev/null +++ b/.agents/skills/maintain/scripts/coordinator.py @@ -0,0 +1,56 @@ +#!/usr/bin/env python3 +"""Hold one host-wide BooKoo coordinator lock; stdin controls its lifetime. + +The file must never be unlinked: locks attach to inodes. Kernel ownership, +not persisted metadata, decides whether the coordinator is busy. +""" +import argparse +import fcntl +import json +import os +from pathlib import Path +import sys +from datetime import datetime, timezone + + +LOCK_PATH = Path.home() / '.local/state/bookoo-maintain/coordinator.lock' + + +def main() -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('action', choices=('hold', 'status')) + parser.add_argument('--owner', default='manual') + # Tests use their own inode; production callers always use the default. + parser.add_argument('--lock-file', type=Path, default=LOCK_PATH, + help=argparse.SUPPRESS) + args = parser.parse_args() + args.lock_file.parent.mkdir(parents=True, exist_ok=True) + with args.lock_file.open('a+', encoding='utf-8') as lock: + os.chmod(args.lock_file, 0o600) + try: + fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB) + except BlockingIOError: + # The writer can be between truncate and flush: metadata is advisory. + lock.seek(0) + print('BUSY ' + (lock.read(4096).strip() or 'owner metadata pending'), + flush=True) + return 75 + if args.action == 'status': + print('IDLE (no live kernel lock)', flush=True) + return 0 + owner = {'repository': 'hyodotdev/BooKoo', 'owner': args.owner, + 'pid': os.getpid(), + 'startedAt': datetime.now(timezone.utc).isoformat()} + lock.seek(0) + lock.truncate() + json.dump(owner, lock) + lock.flush() + print('ACQUIRED ' + json.dumps(owner), flush=True) + # No daemon or recursive Codex process. EOF/newline closes the lock. + sys.stdin.readline() + print('RELEASED', flush=True) + return 0 + + +if __name__ == '__main__': + sys.exit(main()) diff --git a/.agents/skills/maintain/scripts/test_coordinator.py b/.agents/skills/maintain/scripts/test_coordinator.py new file mode 100644 index 0000000..8b7eea9 --- /dev/null +++ b/.agents/skills/maintain/scripts/test_coordinator.py @@ -0,0 +1,80 @@ +"""Behavioral tests: competing processes, separate cwd, crash and inode reuse.""" +from pathlib import Path +import subprocess +import sys +import tempfile +import unittest + + +SCRIPT = Path(__file__).with_name('coordinator.py').resolve() + + +class CoordinatorTests(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.lock = Path(self.temp.name) / 'coordinator.lock' + + def command(self, action, owner='test'): + return [sys.executable, str(SCRIPT), action, '--owner', owner, + '--lock-file', str(self.lock)] + + def holder(self, owner='first'): + proc = subprocess.Popen(self.command('hold', owner), stdin=subprocess.PIPE, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + text=True) + self.addCleanup(self.close_process, proc) + self.assertTrue(proc.stdout.readline().startswith('ACQUIRED ')) + return proc + + @staticmethod + def close_process(proc): + if proc.poll() is None: + proc.kill() + proc.communicate(timeout=5) + + def test_competing_checkout_cannot_acquire(self): + self.holder() + result = subprocess.run(self.command('hold', 'second'), input='\n', + cwd=self.temp.name, capture_output=True, + text=True, timeout=5) + self.assertEqual(result.returncode, 75) + self.assertIn('BUSY ', result.stdout) + self.assertIn('first', result.stdout) + self.assertEqual(self.lock.stat().st_mode & 0o777, 0o600) + + def test_graceful_release_and_reacquire_same_inode(self): + proc = self.holder() + inode = self.lock.stat().st_ino + proc.communicate(input='\n', timeout=5) + self.assertEqual(proc.returncode, 0) + next_proc = self.holder('next') + self.assertIsNone(next_proc.poll()) + self.assertEqual(self.lock.stat().st_ino, inode) + + def test_crash_releases_despite_stale_metadata(self): + proc = self.holder() + proc.kill() + proc.communicate(timeout=5) + # Even a persisted PID is not evidence of a live coordinator. + self.assertIn('first', self.lock.read_text()) + result = subprocess.run(self.command('status'), capture_output=True, + text=True, timeout=5) + self.assertEqual(result.returncode, 0) + self.assertIn('IDLE', result.stdout) + self.holder('recovered') + + def test_status_reports_live_lock_and_eof_releases(self): + proc = self.holder() + result = subprocess.run(self.command('status'), capture_output=True, + text=True, timeout=5) + self.assertEqual(result.returncode, 75) + proc.communicate(timeout=5) + self.assertEqual(proc.returncode, 0) + result = subprocess.run(self.command('status'), capture_output=True, + text=True, timeout=5) + self.assertEqual(result.returncode, 0) + + +if __name__ == '__main__': + unittest.main() diff --git a/.agents/skills/release-update/SKILL.md b/.agents/skills/release-update/SKILL.md index 9ecb4c6..8b6bfa1 100644 --- a/.agents/skills/release-update/SKILL.md +++ b/.agents/skills/release-update/SKILL.md @@ -28,9 +28,12 @@ states. The app is useless against a stale backend. Before any client artifact reaches users: -1. Push and verify Convex functions for the target deployment: - - `bun dev:convex:once` for dev - - `bun deploy:convex` for production +1. Inspect current `.github/workflows/ci.yml` and repository configuration. + Main CI deploys production only for `hyodotdev/BooKoo` with + `CONVEX_PRODUCTION_DEPLOY=enabled` and its deploy key. Wait for that exact + SHA's deploy job and verify it; do not manually redeploy a successful CI + deployment. Local validation uses isolated anonymous state. An explicitly + required manual deployment must target the named environment. 2. Confirm every new query the client calls exists in the deployed function spec, and that any new index has finished backfilling. 3. A schema change that removes or narrows a field must ship **after** the @@ -85,7 +88,8 @@ existing production binary and no store binary or compliance update is needed. sign from the secure `bookoo_production` group, fail unless the bundle targets the production Convex host (and, on Android, unless the upload key signed it), then upload to TestFlight and a Play internal draft. Review - submission and rollout stay manual. + submission and rollout are separate store actions; standing authority in + AGENTS.md covers routine delivery once candidate acceptance passes. 6. Inspect EAS build metadata and download the artifacts when URLs are available. Verify Android is a readable AAB with the expected package and version, and iOS is an IPA archive with the expected bundle and version. A @@ -155,6 +159,20 @@ existing production binary and no store binary or compliance update is needed. choice blocks submission, stop at that exact boundary and preserve the completed uploads. +## Candidate And Public Acceptance + +Before integration retain the required source, device and old-client/backend +compatibility gates. After integration, confirm exact-SHA backend delivery, build +and inspect the final candidate, then upload it to the internal tester track. +Complete `docs/release/PURCHASE_E2E.md` on that installed candidate when relevant +before public review/rollout. PENDING/FAIL blocks public release. Use all currently +configured locales for notes; never infer public availability from upload or a +successful tag workflow. Check cumulative changes since each platform's last +actual delivery, and choose one build path per platform. Record last healthy +source/artifact, supported recovery and post-delivery smoke checks. On API timeout, +read remote state before retrying. Publish automatically after approval for an +authorized routine release; follow each platform independently. + ## After The Rollout - Set a force-update floor only through `$update-version --force`, and only once diff --git a/.agents/skills/review-self/SKILL.md b/.agents/skills/review-self/SKILL.md index 0b0e05a..370b31f 100644 --- a/.agents/skills/review-self/SKILL.md +++ b/.agents/skills/review-self/SKILL.md @@ -89,13 +89,14 @@ This override exists so a fallback review never starts a second polling loop. ## Recheck Every Five Minutes - Run the first round immediately. -- Use the product's recurring wake-up mechanism to re-enter `$review-self` 300 - seconds later. Never emulate recurrence with shell sleep loops or background - jobs. -- Keep at most one wake-up for the same target. +- In an active task, use supported bounded tool waits to recheck after at least + 300 seconds; do not create an automation to watch this task to completion. + If the environment cannot continue, save a resumable PENDING checkpoint. + Never emulate recurrence with shell sleep loops or detached background jobs. +- Keep one polling owner for the same target. - Carry the original goal, target/base, head and worktree fingerprints, seen feedback/check IDs, poll count, clean count, findings, fix attempts, and - commit/push authority in the scheduled prompt. + commit/push authority in the active loop checkpoint. - Keep loop state out of tracked files and revalidate it against disk and GitHub. - Increment the clean count only after a full round has no actionable findings, diff --git a/.agents/skills/update-version/SKILL.md b/.agents/skills/update-version/SKILL.md index dbe8bb9..ea11fe9 100644 --- a/.agents/skills/update-version/SKILL.md +++ b/.agents/skills/update-version/SKILL.md @@ -12,16 +12,16 @@ Use `references/workflow.md` as the detailed version and force-update checklist. 1. Parse the requested semantic version and whether `--force` was requested. 2. Update the marketing/store `version` in `package.json`; `app.config.ts` reads it. Never duplicate that marketing version in a screen. -3. Inspect native compatibility before building or publishing. Codemagic Patch - targets OTA releases by this marketing version and checks the native - fingerprint. Whenever native dependencies, plugins, permissions or the - native contract change, ship new iOS and Android binaries before any OTA - that depends on them. - A metadata-only version change may retain the existing runtime only after - confirming the native contract is unchanged and recording that decision. - Historical iOS1.1.1 deliberately retained runtime1.1.0 for live Android32/iOS41. - `config.ts` exports the installed native version using expo-application; - manifest version is only a web/Expo Go fallback. +3. Inspect native compatibility before building or publishing. Current delivery + uses Codemagic Patch: package.json version targets a binary marketing version, + and the generated native fingerprint must match. app.config.ts no longer owns + an expo-updates runtimeVersion. Native dependencies/plugins/permissions or + native contract changes require new compatible binaries before their OTA. + Do not bump the marketing version for each compatible JS/assets change. + Store binaries <=1.4.0 use the former expo-updates path; the first Patch binary + is 1.5.0. Inspect actual public binaries and follow `$release-update`. + `config.ts` exports installed native version using expo-application, with + a manifest fallback only for web/Expo Go. 4. For `--force`, warn that the store version must already be available to users. Setting a force-update floor above the newest published build locks every user out of the app with no way forward. @@ -32,20 +32,19 @@ Use `references/workflow.md` as the detailed version and force-update checklist. ## Force-Update Record -The force-update table does **not exist yet** in this repository. Do not invent -a function name and do not create the table as a side effect of a version bump. - -- Read `convex/schema.ts` and `convex/schema/` first and use whatever the - schema actually defines. -- If nothing is defined yet, stop and report that the force-update path is not - implemented. The intended shape — a small `appVersions`-style table holding - `version`, `shouldUpdate`, and `createdAt`, indexed by `shouldUpdate`, read by - a query that the client compares against `appVersion` from `config.ts` — is - documented in `.notes/research/06-martie-convex.md` §2.2 and - `.notes/research/13-convex-scale.md`. Implementing it is a separate task with - its own review, not part of a version bump. -- Once it exists, discover the real function names with `bunx convex function-spec` - rather than guessing, and only then run them. +The existing singleton `appConfig` is the only owner. Read +`convex/schema/appContent.ts`, `convex/app/mutations.ts` (`upsertConfig`), +`convex/app/queries.ts` (`config`) and `src/features/runtime/boot.tsx`. +The gate compares installed native build numbers against +`minSupportedIosBuild` / `minSupportedAndroidBuild`; `latestIosVersion` / +`latestAndroidVersion` are marketing versions, not the enforced floors. +Do not create a second `appVersions` table. + +`upsertConfig` requires an authenticated app ADMIN and **replaces the complete +singleton**. Follow the read/merge/readback procedure in +`references/workflow.md`; preserve maintenance, URLs, optional message key and +all feature flags. A routine version bump never raises a floor. Changing a +floor remains a separate owner decision under AGENTS.md. ## Reference diff --git a/.agents/skills/update-version/references/workflow.md b/.agents/skills/update-version/references/workflow.md index 594b20f..ea2e821 100644 --- a/.agents/skills/update-version/references/workflow.md +++ b/.agents/skills/update-version/references/workflow.md @@ -48,56 +48,52 @@ installed native version; the update manifest is only a web/Expo Go fallback. ### Step 1b — Review native runtime compatibility -Codemagic Patch targets each OTA release at the marketing version in -`package.json` and also compares the native fingerprint. If the release changes -native dependencies, plugins, permissions, entitlements or the native contract, -ship both new iOS and Android binaries before OTA delivery. An OTA requiring -those native APIs must never target older binaries. - -For a metadata-only patch with an unchanged native contract, explicitly retain -the compatible runtime and record the decision in release evidence. Historical -iOS1.1.1 retained runtime1.1.0 to support live Android32/iOS41 through the guarded -OTA workflow. That title change did not include an OTA. -Inspect the resolved configuration and embedded runtime in each new archive. +Current OTA delivery uses Codemagic Patch. package.json version is its target +binary marketing version; Patch verifies a fingerprint of the generated native +projects. `app.config.ts` no longer has an expo-updates runtimeVersion. Do not +restore the obsolete runtime-bump procedure. Historical 1.1.1/runtime 1.1.0 +explains old expo-updates binaries only; it does not authorize Patch delivery. + +Check cumulative native dependency, plugin, permission, entitlement and asset +changes since each platform's actual public binary. Native changes require a +new compatible binary and fresh device/purchase gates before dependent OTA. +Compatible JS/assets changes retain the verified target binary's marketing +version. The first Patch binary is 1.5.0; <=1.4.0 still uses expo-updates. +Inspect the resolved config and archive, not only the version string. Native build numbers (iOS `buildNumber`, Android `versionCode`) are not managed -here. EAS auto-increments them; see `$release-update`. +here. EAS auto-increments them; Codemagic chooses above store maxima. Reconcile +EAS counters before switching build paths; see `$release-update`. ### Step 2 — (only with `--force`) Convex force-update record **Precondition:** the target version must already be live in both stores. A force-update floor above the newest published build bricks every install. -1. Confirm the table and functions exist: - - ```bash - grep -rn "appVersion" convex/schema.ts convex/schema/ 2>/dev/null - bunx convex function-spec | grep -i version - ``` - -2. If they do not exist, stop. Report that force update is not implemented and - point at the intended shape in `.notes/research/06-martie-convex.md` §2.2 - (an `appVersions`-style table: `version: v.string()`, - `shouldUpdate: v.boolean()`, `createdAt: v.number()`, indexed by - `shouldUpdate`). Do not create the table as a side effect of a version bump. - -3. If they do exist, push the functions and run the real mutation name from the - function spec against the dev deployment first: - - ```bash - bun dev:convex:once - bunx convex run : '{"version": "", "shouldUpdate": true}' - ``` - -4. Production is a separate, explicitly confirmed step. Never fold it into the - dev command: - - ```bash - bunx convex deploy - bunx convex run --prod : '{"version": "", "shouldUpdate": true}' - ``` - -5. Verify by reading the record back before reporting success. +1. Read the existing contract: `convex/schema/appContent.ts` defines + `appConfig` indexed by `by_singleton`; `convex/app/queries.ts:config` is its + public projection; `convex/app/mutations.ts:upsertConfig` is the ADMIN-only + full replacement. The client gate is `src/features/runtime/boot.tsx`. + Never create `appVersions` or use an invented `shouldUpdate` mutation. +2. Obtain the owner's exact platform/build floor and named deployment. Confirm + the selected build is publicly obtainable on each affected platform, not + merely uploaded or in internal testing. Ordinary releases keep floors. +3. Read current `app/queries:config` on that deployment. If absent, do not invent + initial feature/maintenance values; obtain the missing configuration. +4. Build the complete mutation arguments from the current config and change + only the approved fields. Preserve both store URLs, marketing versions, + maintenance mode/message, legacy claim switch and every feature flag. + Remove read-only `updatedAt`; normalize a null public maintenanceMessageKey + to an omitted optional argument. `upsertConfig` uses `db.replace`, not patch. +5. Rehearse with the exact schema on isolated local/dev state. Use an authorized + app ADMIN session for the real mutation; deployment credentials do not grant + app ADMIN. Re-read immediately before writing and rebuild if anything changed. + Avoid concurrent configuration writers: this API has no compare-and-swap. +6. Production floors require the separate owner decision. Discover the deployed + function spec, invoke the actual `app/mutations:upsertConfig` once with that + full payload, then read `app/queries:config` back. Record sanitized before/ + after values, deployment and affected platform; never expose admin tokens. + On timeout read back before retrying. Stop if config changed concurrently. ### Step 3 — Report @@ -110,10 +106,10 @@ was not written, say so explicitly and why. | File | Role | | ------------------------------------- | ------------------------------------------------------------------------------------------- | | `package.json` | Sole marketing/store version source (`version` field) | -| `app.config.ts` | Consumes marketing version; owns native compatibility runtime and store ids | +| `app.config.ts` | Consumes marketing version; owns native config and store ids | | `config.ts` | Exports installed native appVersion (manifest fallback only on web/Expo Go) and Convex URLs | -| `convex/schema.ts`, `convex/schema/` | Where the force-update table will be declared | -| `.notes/research/06-martie-convex.md` | Reference shape for the `appVersions` table | +| `convex/schema.ts`, `convex/schema/` | Existing appConfig singleton and its indexes | +| `convex/app/mutations.ts`, `convex/app/queries.ts` | ADMIN replacement and public config projection | | `.notes/research/13-convex-scale.md` | Index and query rules any new table must satisfy | ## Cautions diff --git a/.claude/skills/maintain/SKILL.md b/.claude/skills/maintain/SKILL.md new file mode 100644 index 0000000..2be43ad --- /dev/null +++ b/.claude/skills/maintain/SKILL.md @@ -0,0 +1,22 @@ +--- +name: maintain +description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes. +--- + +# Maintain (Claude Code) + +Canonical definition: `.agents/skills/maintain/SKILL.md`. + +Read that file — and every reference it points to — and follow it as +written. It is agent-neutral, so no section of it is written for another +agent. Relative paths inside it resolve under +`.agents/skills/maintain/`. + +## Claude Code Notes + +- Sibling skills written as `$name` in the canonical file are Claude Code + skills; invoke them as `/name` or through the Skill tool. +- Use the Agent tool (`Explore`) for read-only fan-out when the canonical file + asks for independent review lenses. +- For any interval or recurring step, use `ScheduleWakeup` or `/loop`. Never + emulate it with `sleep`, `while true`, or a detached background process. diff --git a/.codex/skills/analyze/SKILL.md b/.codex/skills/analyze/SKILL.md index a3a8997..99e5507 100644 --- a/.codex/skills/analyze/SKILL.md +++ b/.codex/skills/analyze/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/commit/SKILL.md b/.codex/skills/commit/SKILL.md index 0461bca..6f6cfde 100644 --- a/.codex/skills/commit/SKILL.md +++ b/.codex/skills/commit/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/e2e-test/SKILL.md b/.codex/skills/e2e-test/SKILL.md index 7649ca1..6ef0d4b 100644 --- a/.codex/skills/e2e-test/SKILL.md +++ b/.codex/skills/e2e-test/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/grow/SKILL.md b/.codex/skills/grow/SKILL.md index 1b43e8a..65848fb 100644 --- a/.codex/skills/grow/SKILL.md +++ b/.codex/skills/grow/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/loop-review/SKILL.md b/.codex/skills/loop-review/SKILL.md index f886bdd..aa4df7e 100644 --- a/.codex/skills/loop-review/SKILL.md +++ b/.codex/skills/loop-review/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/loop-ui/SKILL.md b/.codex/skills/loop-ui/SKILL.md index 61a8bdc..8ac8833 100644 --- a/.codex/skills/loop-ui/SKILL.md +++ b/.codex/skills/loop-ui/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/maintain/SKILL.md b/.codex/skills/maintain/SKILL.md new file mode 100644 index 0000000..8148506 --- /dev/null +++ b/.codex/skills/maintain/SKILL.md @@ -0,0 +1,22 @@ +--- +name: maintain +description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes. +--- + +# Maintain (Codex) + +Canonical definition: `.agents/skills/maintain/SKILL.md`. + +Read that file — and every reference it points to — and follow it as +written. It is agent-neutral, so no section of it is written for another +agent. Relative paths inside it resolve under +`.agents/skills/maintain/`. + +## Codex Notes + +- Sibling skills written as `$name` are Codex skills; invoke them directly. +- This skill's Codex interface metadata lives in `agents/openai.yaml`. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/maintain/agents/openai.yaml b/.codex/skills/maintain/agents/openai.yaml new file mode 100644 index 0000000..0dea7b9 --- /dev/null +++ b/.codex/skills/maintain/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Maintain BooKoo" + short_description: "Run one serialized maintenance and delivery cycle" + default_prompt: "Use $maintain to recover BooKoo's current work and complete one verified maintenance cycle." diff --git a/.codex/skills/perf-audit/SKILL.md b/.codex/skills/perf-audit/SKILL.md index 8a932be..b3ddb8f 100644 --- a/.codex/skills/perf-audit/SKILL.md +++ b/.codex/skills/perf-audit/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/release-update/SKILL.md b/.codex/skills/release-update/SKILL.md index 6aa8ae0..cc3318c 100644 --- a/.codex/skills/release-update/SKILL.md +++ b/.codex/skills/release-update/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/review-pr/SKILL.md b/.codex/skills/review-pr/SKILL.md index af2433f..7d02e60 100644 --- a/.codex/skills/review-pr/SKILL.md +++ b/.codex/skills/review-pr/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/review-self/SKILL.md b/.codex/skills/review-self/SKILL.md index d767006..a87960c 100644 --- a/.codex/skills/review-self/SKILL.md +++ b/.codex/skills/review-self/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.codex/skills/update-version/SKILL.md b/.codex/skills/update-version/SKILL.md index 6b1b2ce..9601d85 100644 --- a/.codex/skills/update-version/SKILL.md +++ b/.codex/skills/update-version/SKILL.md @@ -16,5 +16,7 @@ agent. Relative paths inside it resolve under - Sibling skills written as `$name` are Codex skills; invoke them directly. - This skill's Codex interface metadata lives in `agents/openai.yaml`. -- For any interval or recurring step, use a Codex automation. Never emulate it - with `sleep`, `while true`, or a detached background process. +- Use supported bounded tool waits for an active task's review/check interval. + Do not create an automation to monitor one task to completion. Standing daily + project work may use one Codex automation when the user requested it. + Never emulate recurrence with shell sleep loops or detached background jobs. diff --git a/.cursor/rules/maintain.mdc b/.cursor/rules/maintain.mdc new file mode 100644 index 0000000..32ff869 --- /dev/null +++ b/.cursor/rules/maintain.mdc @@ -0,0 +1,26 @@ +--- +description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes. +globs: +alwaysApply: false +--- + +# Maintain (Cursor) + +Canonical definition: `.agents/skills/maintain/SKILL.md`. + +Read that file — and every reference it points to — and follow it as +written. It is agent-neutral, so no section of it is written for another +agent. Relative paths inside it resolve under +`.agents/skills/maintain/`. + +@.agents/skills/maintain/SKILL.md + +## Cursor Notes + +- Sibling skills written as `$name` are sibling rules in `.cursor/rules/`; + pull one in with `@` or ask for it by name. +- This rule is agent-requested (`alwaysApply: false`), so restate the goal + when you invoke it — it is not automatically in context. +- Cursor has no built-in scheduler. For any interval or recurring step, finish + the current round and report that automatic re-entry could not be scheduled. + Never emulate it with `sleep`, `while true`, or a detached background process. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1e73409..8c6c58e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -46,6 +46,9 @@ jobs: # install keeps node_modules isolated and makes reruns deterministic. run: bun install --frozen-lockfile --backend copyfile + - name: Test maintenance coordinator exclusion + run: python3 -B -m unittest discover -s .agents/skills/maintain/scripts -p 'test_*.py' + - name: Check linting run: bun lint:all diff --git a/.grok/skills/maintain/SKILL.md b/.grok/skills/maintain/SKILL.md new file mode 100644 index 0000000..a5cd593 --- /dev/null +++ b/.grok/skills/maintain/SKILL.md @@ -0,0 +1,21 @@ +--- +name: maintain +description: Complete one serialized BooKoo maintenance or owner-directed product cycle, recovering existing work and releases before selecting, verifying, integrating and delivering one bounded bundle. Use when the user runs `/maintain` or `$maintain`, requests autonomous upkeep, or a configured daily maintenance run resumes. +--- + +# Maintain (Grok) + +Canonical definition: `.agents/skills/maintain/SKILL.md`. + +Read that file — and every reference it points to — and follow it as +written. It is agent-neutral, so no section of it is written for another +agent. Relative paths inside it resolve under +`.agents/skills/maintain/`. + +## Grok Notes + +- Sibling skills written as `$name` are Grok skills; invoke them as `/name` or + `/skills `. +- Grok has no built-in scheduler. For any interval or recurring step, finish the + current round and report that automatic re-entry could not be scheduled. + Never emulate it with `sleep`, `while true`, or a detached background process. diff --git a/.notes/DECISIONS.md b/.notes/DECISIONS.md index 052d0d7..4987a03 100644 --- a/.notes/DECISIONS.md +++ b/.notes/DECISIONS.md @@ -260,3 +260,29 @@ behind a capability check. That is the fallback path the feature needs anyway RecallAI's `on-device-organizer.ts` is the precedent, trying the model first and falling back to `classifyDeterministically()`. Slot the model behind the same interface in October. + + +## 2026-11-21 — Autonomous maintenance and delivery + +The owner delegates routine investigation, implementation, necessary compatible +migrations, verification, commit/push/PR/review fixes, integration and existing-path +backend/OTA/native/store submission/publication. AGENTS.md's Autonomous operation +section is the canonical authority boundary; maintain orchestrates existing skills. +Reserved decisions include pricing/payment policy, forced-update floors, new paid +contracts, unsupported privacy/legal answers and irreversible production-data work. + +One host-wide kernel lock serializes daily and manual coordinators across clones +and worktrees. Kernel ownership supersedes stale metadata; never unlink the inode. +No multi-host automation without shared scheduler exclusion. STATUS is tracked and +sanitized; PR metadata owns exact final head/merge/check evidence. Daily default: +09:00 Asia/Seoul, after a verified first cycle; no timestamp-only commits. + +Root strict nonforce fast-forward integration wins over the old loop-review +squash wording. Protection/rulesets must still be inspected on each integration; +no bypass if they conflict. Self-review means self-review, with two clean full +snapshots at least five minutes apart; no external reviewer substitution. + +Existing appConfig owns native build floors. Its ADMIN mutation replaces the +whole singleton, so preserve all unrelated settings and read back; no appVersions +table. Stored date buckets are integers in ledger timezone; ISO date strings are +UI/API codecs. No runtime dependency/version change belongs to this tooling batch. diff --git a/.notes/STATUS.md b/.notes/STATUS.md new file mode 100644 index 0000000..f775a0a --- /dev/null +++ b/.notes/STATUS.md @@ -0,0 +1,85 @@ +# BooKoo operations status + +## Active batch + +- Mode: maintenance. Owner goal: autonomous, sequential maintenance and delivery; + product work follows the owner's latest direction. +- Standing authority: [AGENTS.md](../AGENTS.md#autonomous-operation), granted + 2026-11-21 Asia/Seoul. No price/payment policy, forced-update floor, new paid + contract, invented privacy declaration or irreversible production-data change. +- IMPLEMENTED: `chore/autonomous-maintenance`, base + `0341b45cdafeb368abb03d88aa5e21d720f73076` in + [hyodotdev/BooKoo](https://github.com/hyodotdev/BooKoo). + The pre-existing local ops checkout has a different history and is preserved. +- Scope/order: acquire coordinator lock; restore remote/release state; add + `$maintain` orchestration and test mutual exclusion; correct appConfig/date/ + merge documentation; sync skills; run source checks and two clean self-reviews; + PR/CI/integration; connect one daily run at 09:00 Asia/Seoul. +- Acceptance: discoverable canonical skill, tested crash-safe exclusion across + worktrees, public resumable status, preserved validation/native gates, accurate + source contracts, exact-head CI and self-review, no unnecessary client release. +- Delivery: agent/tooling/docs only. No runtime dependency migration or native + change; device/performance audits N/A for this diff. No OTA/store tag. +- Integration/review record: [tracking PR](https://github.com/hyodotdev/BooKoo/pulls?q=is%3Apr+head%3Achore%2Fautonomous-maintenance). + Its current head, merge SHA, check runs and final delivery comment are the + authoritative completion record. Resume this batch if unmerged; after MERGED + plus successful exact-main CI, select the next cycle below. Do not create a + recursive SHA-only completion commit. + +## Verification and resume + +- PASS baseline: no open public PR; main protection/rulesets absent on inspection. + Root strict nonforce fast-forward policy still applies. +- PASS local: frozen copyfile install; lint:all (all i18n, dependency owner, + tracked-secret, schema, public/store/readiness checks); typecheck; coverage + 227 suites / 1,751 tests passed, 15 existing skips; lock behavioral tests 4/4; + canonical validator and idempotent sync; actual Codex app-server skills/list + discovered enabled maintain with no discovery errors. Initial validator's + missing PyYAML was resolved using an isolated uv dependency, not repo changes. +- Final exact-head evidence: use the tracking PR checks and delivery comment for + full-history secret scan, separate Convex 100k budget marker, two clean full + self-reviews separated by >=300s and exact-main production CI deployment. + These are mandatory integration gates, never inferred from general Jest. +- N/A device/purchase/performance audit: no app/src/native/runtime/Convex change. + The required anonymous budget test still runs in PR CI. +- SSOT/KISS: reuse AGENTS authority, existing status/decisions/design records, + canonical sibling skills, appConfig and shared/date owners. New executable + logic is only a small stdlib OS-lock holder with behavioral tests. Generated + skill pointers derive from the canonical file and metadata. +- Resume: finish this branch before selecting another bundle. No automatic + dependency upgrades during this tooling batch. Local QA must use an isolated + anonymous deployment, never inherited production credentials. +- Product decisions needed: none for this batch. + +## Last observed delivery (verify before client release) + +| Surface | Observed state | Evidence / next read | +| --- | --- | --- | +| Backend | PASS: production deployed source `0341b45c` | [main CI](https://github.com/hyodotdev/BooKoo/actions/runs/44466753587), deploy job succeeded | +| Source | package 1.5.0; Expo 57 / RN 0.86.3 / React 19.2.3 / Convex 1.45.0 / expo-iap 6.4.2 | package.json + bun.lock; no version changes in this batch | +| Release dispatch | PASS: last run was `ota-dry`, not a store or public OTA dispatch; current remote has no tags | [run](https://github.com/hyodotdev/BooKoo/actions/runs/44467232727), step log inspected; do not replay removed tags | +| iOS | PASS ASC readback: 1.5.0 READY_FOR_SALE / AFTER_APPROVAL, selected build 60 VALID, not expired | App 6805969489 / dev.hyo.bookoo, read 2026-11-21 KST; [public Apple lookup](https://itunes.apple.com/lookup?id=6805969489&country=kr) independently confirms 1.5.0 (release 2026-11-18T18:25:16Z) | +| Android | PASS public listing advertises 1.5.0; exact build/versionCode and internal-track state PENDING authenticated Play readback | [public Play](https://play.google.com/store/apps/details?id=dev.hyo.bookoo&hl=en&gl=US); no new upload or rollout performed | +| OTA | PENDING Patch release/deployment readback | Patch first binary 1.5.0; <=1.4.0 uses former expo-updates; do not target an unverified public binary | + +## Next cycle + +Recover any active release first. The most recent observed dispatch was an +OTA dry run, and iOS 1.5.0 is already READY_FOR_SALE: do not duplicate that +submission. Verify actual remaining platform state and candidate gates before +submitting anything. +If only external prerequisites remain, preserve them and select one independent, +small maintenance bundle. Keep proposed new features here with evidence; none yet. +Daily scheduler: local thread heartbeat `bookoo`, named BooKoo 일일 유지보수, +09:00 Asia/Seoul. Created paused; activate only after this batch's final gates +and exact-main CI pass. The live app automation (and final PR delivery comment) +owns current ACTIVE/PAUSED state; do not duplicate it. All three historical +BooKoo release monitors were PAUSED and retain their original purpose. +The host must be awake with Codex running, project/auth access and registered +DevLogs available for bulk runs. Manual entry is `$maintain` in this public +checkout. The lock is host-local; no second host without shared exclusion. + +No owner decision is needed for this tooling batch. Next actions: authenticate +remaining Play/Patch release readbacks using existing available access, then +choose one evidenced maintenance defect. Do not republish iOS 1.5.0 or replay the +removed dry-run tag merely to recreate history. diff --git a/AGENTS.md b/AGENTS.md index f048da9..47b2225 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -29,6 +29,34 @@ rule in `.notes/design/RECONCILIATION.md`. Future work must check those rules be `BooKooLegacy/` is a read-only reference copy of the 2017 app. Never edit or build it. `.local/` holds exported production user data. Never commit it, never quote it, never upload it. +## Autonomous operation + +On 2026-11-21 (Asia/Seoul), the owner delegated routine BooKoo investigation, +code/configuration changes, necessary compatible dependency migrations, tests, +commits, push, PRs, review fixes, integration, existing-path backend/OTA/native +builds, store review submission and publication. This standing authority applies +to `$maintain` and its scheduled continuations; do not request it again for each +technical step. Existing skill wording requiring authorization is satisfied +within this scope. It does not bypass access controls, environment approvals, +branch protection, credentials or required source/native/purchase gates. + +Without a new product goal, preserve product intent and complete one maintenance +bundle. With a goal, record flows, acceptance criteria and implementation order, +then deliver a reviewable result. Record new feature proposals in the existing +status rather than implementing an unsolicited direction. + +Separate owner decisions remain necessary for new prices/payment policy, +forced-update floors, new paid contracts, unsupported privacy/legal declarations +and irreversible production-data deletion/conversion. Human authentication and +unsupported store actions are real handoffs; continue independent work. + +Use [the canonical maintain skill](.agents/skills/maintain/SKILL.md) for one +sequential cycle. Acquire its host-wide coordinator lock before changes or +release actions, including manual continuations; an overlapping run exits. +Read `.notes/STATUS.md` and remote PR/release state before choosing work. Retain +one shared status, publish only sanitized evidence, and do not make timestamp-only +commits or dispatch client releases for docs/skills/tooling-only changes. + ## SSOT and KISS - Before implementation and every review, identify the canonical owner of each @@ -201,7 +229,7 @@ Skills are defined once in `.agents/skills//SKILL.md` and mirrored to `.claude/skills/`, `.codex/skills/`, `.grok/skills/`, and `.cursor/rules/` as thin pointers (those mirrors are generated — they appear on the first sync run). Edit the canonical file only, then run -`bash .agents/scripts/sync-skills.sh`. See `.agents/README.md` (to be created) +`bash .agents/scripts/sync-skills.sh`. See `.agents/README.md` for the layout and the authoring conventions. The sync script owns and overwrites every mirrored pointer, and prunes any diff --git a/CLAUDE.md b/CLAUDE.md index f958842..95d99f9 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,6 +87,34 @@ Directories not created yet at the time of writing — `convex/schema/`, The frozen table and index inventory is `.notes/design/SCHEMA.md`; do not invent table or function names outside that authority. +## Autonomous operation + +On 2026-11-21 (Asia/Seoul), the owner delegated routine BooKoo investigation, +code/configuration changes, necessary compatible dependency migrations, tests, +commits, push, PRs, review fixes, integration, existing-path backend/OTA/native +builds, store review submission and publication. This standing authority applies +to `$maintain` and its scheduled continuations; do not request it again for each +technical step. Existing skill wording requiring authorization is satisfied +within this scope. It does not bypass access controls, environment approvals, +branch protection, credentials or required source/native/purchase gates. + +Without a new product goal, preserve product intent and complete one maintenance +bundle. With a goal, record flows, acceptance criteria and implementation order, +then deliver a reviewable result. Record new feature proposals in the existing +status rather than implementing an unsolicited direction. + +Separate owner decisions remain necessary for new prices/payment policy, +forced-update floors, new paid contracts, unsupported privacy/legal declarations +and irreversible production-data deletion/conversion. Human authentication and +unsupported store actions are real handoffs; continue independent work. + +Use [the canonical maintain skill](.agents/skills/maintain/SKILL.md) for one +sequential cycle. Acquire its host-wide coordinator lock before changes or +release actions, including manual continuations; an overlapping run exits. +Read `.notes/STATUS.md` and remote PR/release state before choosing work. Retain +one shared status, publish only sanitized evidence, and do not make timestamp-only +commits or dispatch client releases for docs/skills/tooling-only changes. + ## Conventions - One table per file in `convex/schema/`, assembled in `convex/schema.ts`. @@ -137,7 +165,7 @@ Skills are defined once in `.agents/skills//SKILL.md` and mirrored to `.claude/skills/`, `.codex/skills/`, `.grok/skills/`, and `.cursor/rules/` as thin pointers (generated — they appear on the first sync run). Edit the canonical file only, then run `bash .agents/scripts/sync-skills.sh`. -See `.agents/README.md` (to be created). +See `.agents/README.md`. ## UI Component Ownership — cpk-ui first diff --git a/shared/AGENTS.md b/shared/AGENTS.md index 9230390..f202189 100644 --- a/shared/AGENTS.md +++ b/shared/AGENTS.md @@ -25,7 +25,10 @@ server** — the client for instant feedback, the server as the real gate: - validation and normalization (usernames, emails, invite codes) - money arithmetic in minor units and currency formatting rules -- period keys (`'YYYY-MM'`, `'YYYY-MM-DD'`) and day-boundary resolution +- stored integer period keys (`monthKey=YYYYMM`, `dayKey=YYYYMMDD`), derived + in the ledger timezone by `shared/date.ts`, and day-boundary resolution; + ISO strings (`YYYY-MM`, `YYYY-MM-DD`) belong only at UI/API boundaries and + use that module's calendar/ISO codecs - category identifiers and their i18n key mapping - the shared error-code union and its payload type