@4pm/cli 1.5.16 → 1.5.17-b

package/dist/index.js

@@ -32916,6 +32916,7 @@ var AI_PROMPT_MAX_LEN = 5e5;
 var COMMAND_IMAGE_MAX_BYTES = 5 * 1024 * 1024;
 var COMMAND_IMAGE_MAX_COUNT = 10;
 var COMMAND_IMAGE_MIME_TYPES = ["image/png", "image/jpeg", "image/webp", "image/gif"];
+var COMMAND_IMAGE_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(png|jpg|webp|gif)$/;
 function commandImageExt(mime) {
   switch (mime) {
     case "image/png":
@@ -32931,7 +32932,9 @@ function commandImageExt(mime) {
   }
 }
 var commandImageRefSchema = external_exports.object({
-  id: external_exports.string().min(1).max(200),
+  // Constrained to `<uuidv4>.<ext>` (the only id the upload mints) so a client-supplied id can never
+  // inject `/` or `..` into the `command-images/{orgId}/{id}` storage key (path-traversal guard).
+  id: external_exports.string().regex(COMMAND_IMAGE_ID_RE),
   placeholder: external_exports.string().min(1).max(40),
   name: external_exports.string().max(255),
   mime: external_exports.enum(COMMAND_IMAGE_MIME_TYPES)
@@ -33904,7 +33907,7 @@ function decryptPayload(key, payloadBase64, nonceBase64) {
 }
 
 // src/core/ws-client.ts
-import { existsSync as existsSync14, mkdirSync as mkdirSync6, rmSync as rmSync5 } from "fs";
+import { existsSync as existsSync15, mkdirSync as mkdirSync6, rmSync as rmSync5 } from "fs";
 import { randomUUID as randomCommandId } from "crypto";
 
 // src/core/update-scheduler.ts
@@ -37095,6 +37098,7 @@ async function setCommitAuthor(cwd2, machineUsername) {
 
 // src/core/scaffold.ts
 import { cp, mkdir as mkdir8, writeFile as writeFile8 } from "fs/promises";
+import { existsSync as existsSync12 } from "fs";
 import { execFile as execFile10 } from "child_process";
 import { dirname as dirname8, join as join23, resolve as resolve7 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
@@ -37139,7 +37143,11 @@ async function provisionRepos(target, repos, emit, opts = {}) {
 function sampleDir() {
   if (process.env.SCAFFOLD_SAMPLE_DIR) return process.env.SCAFFOLD_SAMPLE_DIR;
   const here = dirname8(fileURLToPath3(import.meta.url));
-  return resolve7(here, "../../project-sample");
+  const bundled = resolve7(here, "project-sample");
+  for (const candidate of [bundled, resolve7(here, "../project-sample"), resolve7(here, "../../project-sample")]) {
+    if (existsSync12(candidate)) return candidate;
+  }
+  return bundled;
 }
 async function scaffoldProject(payload, profileDir2, onProgress) {
   const emit = (step, message) => onProgress?.({ projectId: payload.projectId, step, message });
@@ -37218,7 +37226,7 @@ async function addProject(payload, profileDir2, onProgress) {
 }
 
 // src/ui/slash-commands.ts
-import { existsSync as existsSync12 } from "fs";
+import { existsSync as existsSync13 } from "fs";
 import { join as join24 } from "path";
 var CONFIG_KEYS = [
   "aiCli",
@@ -37281,7 +37289,7 @@ function runConfig(ctx) {
       ctx.print(`\u2714 ${verb} default config: ${path}`);
       ctx.print("add claude profiles: /config set claudeHome .claude .claude-1 (tried in order)");
     };
-    if (existsSync12(path)) {
+    if (existsSync13(path)) {
       ctx.confirm(
         `config exists: ${path} \u2014 replace it with defaults? (y/N)`,
         () => writeDefaults("replaced with")
@@ -37679,7 +37687,7 @@ async function runMemoryCompaction(ai, cwd2, input) {
 }
 
 // src/core/config-sync.ts
-import { existsSync as existsSync13, readFileSync as readFileSync15 } from "fs";
+import { existsSync as existsSync14, readFileSync as readFileSync15 } from "fs";
 import { join as join25 } from "path";
 var SERVER_MANAGED_KEYS = [
   "physicPath",
@@ -37698,7 +37706,7 @@ var SERVER_MANAGED_KEYS = [
 ];
 function readConfigText(profileDir2) {
   const path = join25(profileDir2, "config.json");
-  if (existsSync13(path)) {
+  if (existsSync14(path)) {
     try {
       return readFileSync15(path, "utf8");
     } catch {
@@ -39464,7 +39472,7 @@ ${guardedPrompt}`;
   /** Create the physic folder at an absolute path if missing (best-effort). */
   ensurePhysicFolderPath(folder) {
     try {
-      if (!existsSync14(folder)) {
+      if (!existsSync15(folder)) {
         mkdirSync6(folder, { recursive: true });
         this.bus.log(`Created physic project folder: ${folder}`);
       }
@@ -39494,7 +39502,7 @@ ${guardedPrompt}`;
       projects: [],
       version: CLI_VERSION,
       physicPath,
-      physicPathExists: physicPath ? existsSync14(physicPath) : void 0,
+      physicPathExists: physicPath ? existsSync15(physicPath) : void 0,
       // Real coarse state (ADR-0152): !paused and a recent tick (was hard-coded false).
       autonomousRunning: physicPath ? isAutonomousRunning(physicPath) : false,
       // The machine-user AI-run limit (0 = unlimited) + profile count so a dispatch can resolve the
@@ -45679,7 +45687,7 @@ var import_react21 = __toESM(require_react(), 1);
 var import_react26 = __toESM(require_react(), 1);
 
 // src/core/input-history.ts
-import { existsSync as existsSync16, readFileSync as readFileSync18, writeFileSync as writeFileSync9 } from "fs";
+import { existsSync as existsSync17, readFileSync as readFileSync18, writeFileSync as writeFileSync9 } from "fs";
 import { join as join29 } from "path";
 var MAX_HISTORY = 200;
 function historyPath(profileDir2) {
@@ -45687,7 +45695,7 @@ function historyPath(profileDir2) {
 }
 function loadInputHistory(profileDir2) {
   const path = historyPath(profileDir2);
-  if (!existsSync16(path)) return [];
+  if (!existsSync17(path)) return [];
   try {
     const data = JSON.parse(readFileSync18(path, "utf8"));
     return Array.isArray(data) ? data.filter((x) => typeof x === "string") : [];

package/dist/project-sample/.claude/.autonomous.approvals.json

@@ -0,0 +1 @@
+{}

package/dist/project-sample/.claude/.autonomous.settings.json

@@ -0,0 +1,24 @@
+{
+  "_about": "Autonomous workflow config. autonomous-tick.sh READS this file EVERY cron tick, so edits take effect from the next tick. Keys starting with '_' are comments and are ignored by the script.",
+  "paused": true,
+  "_paused": "true = PAUSED: the tick still runs but skips immediately, without invoking Claude. A quick brake without removing the crontab entry.",
+  "max_session_pct": 80,
+  "max_weekly_pct": 90,
+  "_quota": "Only run when session_pct < max_session_pct AND weekly_pct < max_weekly_pct (read from the usage skill).",
+  "cron_schedule": "*/5 * * * *",
+  "_cron_schedule": "Standard 5-field cron. When you change this, the tick rewrites the crontab line pointing at autonomous-tick.sh on the next run (only if the crontab already has the autonomous line — install it once manually first).",
+  "command": "/auto-cycle",
+  "_command": "The headless slash-command each tick invokes.",
+  "model": "",
+  "_model": "Empty = Claude Code's default model. Or set an id (e.g. 'claude-sonnet-4-6') to force a cheaper/faster model for the autonomous loop.",
+  "quiet_hours": "",
+  "_quiet_hours": "Empty = run ALL DAY. Or 'HH:MM-HH:MM' (e.g. '00:00-06:00') to SKIP within that window; a window crossing midnight is valid (e.g. '22:00-06:00').",
+  "max_ticks_per_day": -1,
+  "_max_ticks_per_day": "-1 = NO limit. >0 = cap on the number of ticks that actually invoke Claude in one (local) day. The count is stored under ticks{day,count} in .claude/.autonomous.histories.json.",
+  "stop_on_consecutive_failures": 3,
+  "_stop_on_consecutive_failures": "After N consecutive FAILED command runs -> set paused=true to stop safely. 0 = off. The count is stored under consecutive_fails in .claude/.autonomous.histories.json (reset on success).",
+  "log_retention_days": 14,
+  "_log_retention_days": "Logs are written per DAY: .claude/logs/autonomous-tick-YYYY-MM-DD.log. Delete log files older than N days. 0 = keep forever.",
+  "notify_webhook": "",
+  "_notify_webhook": "TBD — a webhook URL (Slack/Discord) to notify on finish/error. NOT wired yet (read but unused)."
+}

package/dist/project-sample/.claude/AUTONOMOUS-CRON.md

@@ -0,0 +1,38 @@
+# Set up a 10-minute cron for `autonomous-tick.sh`
+
+How to install the **autonomous cycle** on **WSL (Ubuntu)**: cron calls
+[`autonomous-tick.sh`](autonomous-tick.sh) every **10 minutes**; each run does one `claude -p /auto-cycle`
+cycle then exits. A file lock (`.claude/.autonomous.lock`) ensures **no two runs overlap** (a later tick
+that sees the lock skips).
+
+> All commands below run in a **WSL shell** (Ubuntu) unless noted as PowerShell/Windows. Call the project
+> root `$PROJECT` (e.g. `~/projects/<your-project>`).
+
+## 0. Set a variable for convenience
+```bash
+PROJECT="$HOME/projects/<your-project>"   # fix to your path
+cd "$PROJECT"
+```
+
+## 1. Check the required tools
+Every line must print a path/version (not "not found"):
+```bash
+command -v cron   || echo "missing cron"
+command -v claude || echo "missing claude (install natively in WSL)"
+command -v git    || echo "missing git"
+command -v python3 || echo "missing python3"
+```
+
+## 2. Make the tick executable + install the cron line
+```bash
+chmod +x "$PROJECT/.claude/hooks/autonomous-tick.sh"
+crontab -e
+# add (fix the path):
+*/10 * * * * /home/<user>/projects/<your-project>/.claude/hooks/autonomous-tick.sh
+```
+The schedule is also driven by `cron_schedule` in `.claude/.autonomous.settings.json`; once the crontab
+line exists, the tick keeps it in sync on later runs.
+
+## 3. Enable / watch
+- Set `"paused": false` in `.claude/.autonomous.settings.json` to enable (or use the web Autonomous tab).
+- Watch: `tail -f .claude/logs/autonomous-tick-$(date +%F).log`

package/dist/project-sample/.claude/AUTONOMOUS.md

@@ -0,0 +1,52 @@
+# Autonomous mode — how it's assembled
+
+> **Sample project — defines the workflow only, does NOT run on its own.** The files below describe an
+> unattended work loop, intended to run on **WSL** (an isolated environment where the AI can be given
+> full permissions).
+
+## The pieces
+| File | Role |
+|------|------|
+| `.claude/hooks/autonomous-tick.sh` | Cron tick (every ~10 min); a lock so **busy ⇒ skip, idle ⇒ run**; calls `claude -p /auto-cycle`. |
+| `.claude/commands/auto-cycle.md` | Defines **one cycle**: token gate → sync `${ai_dev_branch}$` → generate tasks → do one task → test → merge into `${ai_dev_branch}$`. |
+| `.claude/skills/check-usage/check_usage.py` | The `check-usage` skill: prints token % and writes `output/last-usage-check.json` (deleted + recreated each run) for the token gate to read. |
+| `.claude/.autonomous.approvals.json` | Approval source of truth (ADR-0152): `{ "<TSK-id>": {approved, by, at} }` — the web VERIFY tab writes it; `/auto-cycle` reads it. |
+| `USER_TODO.md` | The user writes requests here; the cycle reads then clears it. |
+| `AI_TODO.md` / `AI_PROGRESS.md` / `AI_DONE.md` | The task books: queue → in progress → done (ID `TSK-{group:0000}-{task:0000}`). |
+| `.claude/templates/<NAME>.{empty,sample}.md` | Canonical templates for the 5 books. The "has work" gate + `/auto-cycle` **compare against `*.empty.md`** to tell empty/has-work and reset correctly (see `README.md` in that folder). |
+| `.claude/settings.json` | The "bypass all" permission profile for autonomous mode (see the note below). |
+
+## Lifecycle (1 tick)
+```
+cron ~10min → autonomous-tick.sh
+  ├─ locked?  → log "skip", exit (wait for the next tick)
+  └─ idle → claude -p /auto-cycle
+       0. usage: session<80% & weekly<90%?  (no → stop)
+       1. checkout/fetch/pull the `${ai_dev_branch}$` branch
+       2. USER_TODO.md → generate tasks into AI_TODO.md (with IDs) → clear USER_TODO.md
+       3. pick one APPROVED task (approvals + dependencies) → AI_PROGRESS.md, remove from AI_TODO.md, commit
+       4. task/TSK-… branch → implement → commit → run the project's tests
+       5. back to `${ai_dev_branch}$` → merge task (resolve conflicts if any) → AI_DONE.md, remove from AI_PROGRESS.md, commit
+       6. report on the `conversation` branch (CONVERSATION.md, ≤50 entries) for later agents
+       7. recheck usage → stop
+```
+
+## Install on WSL
+```bash
+chmod +x .claude/hooks/autonomous-tick.sh
+crontab -e
+# add the line (fix /path):
+*/10 * * * * /path/to/project/.claude/hooks/autonomous-tick.sh
+# watch:
+tail -f .claude/logs/autonomous-tick-$(date +%F).log
+```
+Requirements: `claude` logged in (has `~/.claude/.credentials.json`), plus `git` and `python3`, and the
+project's test tooling (per `CLAUDE.md`).
+
+## Note on permissions (important)
+- Claude Code only auto-loads `.claude/settings.json` and `.claude/settings.local.json`. To make a
+  full-permission profile take effect, one of:
+  1. The tick already passes `--permission-mode bypassPermissions --dangerously-skip-permissions` (in use).
+  2. Or copy the profile into `.claude/settings.local.json`.
+  3. Or point `CLAUDE_CONFIG_DIR` at the profile dir when running headless.
+- Only enable full permissions in an isolated environment (WSL/CI). Never on a machine with sensitive data.

package/dist/project-sample/.claude/commands/auto-cycle.md

@@ -0,0 +1,176 @@
+---
+description: Autonomous cycle — pull a request from USER_TODO, do ONE small approved task, test it, merge into ${ai_dev_branch}$. (The token gate is checked by autonomous-tick.sh BEFORE Claude is invoked.)
+allowed-tools: Bash(*), Read(*), Edit(*), Write(*), Glob(*), Grep(*)
+---
+
+# /auto-cycle — one autonomous work cycle
+
+You are running **unattended** (headless, triggered by cron every ~10 min via
+`.claude/hooks/autonomous-tick.sh`). Do **exactly one full cycle** with the steps below, then **stop**.
+The integration branch is named **`${ai_dev_branch}$`** (the placeholder is resolved at runtime — see
+`AI_PLACEHOLDER.md`); a task branch is **merged straight into `${ai_dev_branch}$`** (no PR).
+
+> Survival rule: **each cycle does exactly ONE small task** to avoid running out of tokens mid-way. If a
+> step fails, log it in `AI_DONE.md` under "Incidents", **clean the lock (Step 8)**, then stop — don't
+> push on.
+>
+> **Lock (`.claude/.autonomous.lock`):** whether the cycle ends normally or on error, you MUST delete
+> the lock file before stopping so the next cron tick isn't blocked by a stale lock (Step 8) —
+> mandatory, even on an early error exit.
+>
+> **Token gate:** the quota check (session/weekly) moved to the `autonomous-tick.sh` wrapper — it runs
+> first and only invokes Claude when quota is sufficient. So by the time `/auto-cycle` starts, the gate
+> has already passed; don't re-check at the top.
+>
+> **Books & templates (MUST compare):** the 5 book files at the repo root — `USER_TODO.md`,
+> `AI_TODO.md`, `AI_PROGRESS.md`, `AI_DONE.md`, `USER_QA.md` — have canonical templates in
+> `.claude/templates/` (`<NAME>.empty.md` = EMPTY state, `<NAME>.sample.md` = example WITH DATA; see
+> `.claude/templates/README.md`). Rules:
+> - **Is a file empty / has work?** → compare against `<NAME>.empty.md` (empty ⇔ equal to the empty
+>   template after trimming trailing whitespace + leading/trailing blank lines). Don't guess by skimming.
+> - **When clearing / resetting** a file → overwrite with the **exact** `<NAME>.empty.md`
+>   (`cp .claude/templates/<NAME>.empty.md <NAME>`). The tick's "has work" gate relies on this match.
+> - **When adding data** → keep the header/blockquote, fill in per `<NAME>.sample.md`.
+>
+> **Language:** write books/docs/code in the language the project's `CLAUDE.md` specifies (default
+> English). Don't switch languages on your own.
+
+---
+
+## Step 1 — Sync the `${ai_dev_branch}$` branch
+1. If not on `${ai_dev_branch}$`:
+   - `git fetch origin`
+   - If it doesn't exist yet: `git checkout -b ${ai_dev_branch}$ origin/${ai_dev_branch}$` (if the remote
+     has it) or `git checkout -b ${ai_dev_branch}$ main` (create from main).
+   - Otherwise: `git checkout ${ai_dev_branch}$`.
+2. `git pull --ff-only origin ${ai_dev_branch}$` (skip if the remote has no such branch yet).
+
+## Step 2 — Intake user requests → generate tasks
+1. Read `USER_TODO.md` and **compare with `.claude/templates/USER_TODO.empty.md`**. If **equal** (only
+   the empty template remains) → **no** new request → skip task generation.
+2. **If anything is unclear / needs a user decision** (ambiguous, missing info, contradictory, or the
+   user said "ask if unclear, don't decide on your own"):
+   - **Do NOT guess** and generate tasks. Write the question into `USER_QA.md` ("Q&A" section) per
+     `.claude/templates/USER_QA.sample.md`: state the original request, what's unclear, and (if possible)
+     options to choose from. Each question has a date + an empty answer slot.
+   - **Clear `USER_TODO.md`** back to the empty template (Step 2.4) — do NOT generate tasks this cycle.
+     The user will read `USER_QA.md`, clarify, and re-post the request into `USER_TODO.md` for a later cycle.
+   - Note in `AI_DONE.md` ("Incidents/notes") that this cycle stopped waiting for an answer, then go to
+     Step 8 (clean the lock) and **stop**.
+3. If the request is clear enough: split it into small tasks doable in ~1 cycle. Write them into
+   `AI_TODO.md` per `.claude/templates/AI_TODO.sample.md` (**7-column table:
+   `| ID | Priority | Approved | Depends | Group | Task description | Notes |`**), each with an
+   **ID `TSK-{groupid:0000}-{taskid:0000}`** (group = one request/batch, task = a sub-task).
+   - **`Priority` column**: judge it — `High` / `Medium` / `Low` (default `Medium`).
+   - **`Approved` column**: leave BLANK. This is a display-only mirror — the source of truth for approval
+     is `.claude/.autonomous.approvals.json` (the user ticks it in the web VERIFY tab — ADR-0152). Do NOT
+     fill it in yourself and do NOT read it to decide (see Step 3).
+   - **`Depends` column**: if a task must wait for another, list the `TSK-…` ids here (comma-separated);
+     leave empty otherwise. Step 3 skips a task whose dependencies aren't in `AI_DONE.md` yet.
+
+   **ID rules (MANDATORY):**
+   - **Each analysis of `USER_TODO.md` → one NEW `groupid`.** All sub-tasks split from that batch share
+     this `groupid`, differing only by `taskid`.
+   - **`groupid` must be UNIQUE and INCREASING** across all history (including groups already DONE and
+     cleared from `AI_TODO.md`). Since the books are cleared each cycle, **check git history** for the
+     largest `groupid` ever used, then take `max + 1`:
+     ```bash
+     MAXG=$( { git log -p -- AI_TODO.md AI_DONE.md AI_PROGRESS.md 2>/dev/null; \
+               cat AI_TODO.md AI_DONE.md AI_PROGRESS.md 2>/dev/null; } \
+             | grep -oE 'TSK-[0-9]{4}-[0-9]{4}' | sed -E 's/TSK-([0-9]{4}).*/\1/' \
+             | sort -rn | head -1 ); MAXG=${MAXG:-0}
+     NEWG=$(printf '%04d' $((10#$MAXG + 1)))
+     ```
+   - **`taskid` starts at `0001` and increases WITHIN the group**: `TSK-{NEWG}-0001`, `TSK-{NEWG}-0002`, …
+4. **Clear `USER_TODO.md`** by overwriting with the exact empty template
+   (`cp .claude/templates/USER_TODO.empty.md USER_TODO.md`) — so old tasks aren't recreated next cycle AND
+   the tick's "has work" gate correctly sees it as empty.
+
+## Step 3 — Pick ONE APPROVED task (with satisfied dependencies) and start it
+> **VERIFY gate (MANDATORY):** the source of truth for approval is `.claude/.autonomous.approvals.json`
+> (ADR-0152), NOT the `Approved` column in `AI_TODO.md`. A task is **approved** when approvals has
+> `"<TSK-id>": { "approved": true, … }`. A task not in approvals (or `approved:false`) = NOT permitted →
+> **skip it, leave it queued**.
+
+1. Read `.claude/.autonomous.approvals.json` (JSON `{ "<TSK-id>": {approved, by, at}, … }`; missing file
+   ⇒ nothing approved) and `AI_TODO.md`. **Filter tasks meeting BOTH**:
+   - **Approved**: `approved === true` in approvals.
+   - **Dependencies met**: every `TSK-…` in the `Depends` column is already in `AI_DONE.md` (done). If a
+     dependency isn't done yet → **skip** (wait for a later cycle), even if approved.
+   Pick the next task: **run group by group** (smallest group with an eligible task first), **within a
+   group prefer `Priority` High → Medium → Low**, then line order.
+   - **If NO eligible task** (empty, or all waiting for approval / dependencies — including tasks just
+     generated in Step 2): **take no task**. Write one line into `AI_DONE.md` ("Incidents/notes")
+     (e.g. "this cycle only generated tasks / waiting for VERIFY approval / waiting for dependencies"),
+     then go to Step 8 (clean the lock) and **stop**.
+2. Move that task into `AI_PROGRESS.md` (with a start timestamp, per
+   `.claude/templates/AI_PROGRESS.sample.md`), **remove it from `AI_TODO.md`**. If `AI_TODO.md` is now
+   empty → `cp .claude/templates/AI_TODO.empty.md AI_TODO.md`.
+3. Commit on `${ai_dev_branch}$`: `git add -A && git commit -m "chore(auto): start TSK-xxxx-xxxx"`.
+
+## Step 4 — Implement the task on its own branch
+1. Create the branch: `git checkout -b task/TSK-xxxx-xxxx`.
+2. Implement the task **following the project's architecture + the conventions in `CLAUDE.md`**. Add or
+   update tests as appropriate for the change.
+3. **Test** by running the project's test command (see `CLAUDE.md` / the project's scripts — e.g.
+   `scripts/test.*`, `npm test`, `pnpm test`, `pytest`, …). If the project defines an integration-test /
+   evidence harness, use it and keep the produced report/evidence so it can be reviewed later.
+4. **Wait for the tests to finish** and check the result before continuing.
+5. Commit (include any produced report/evidence so the integration branch carries it):
+   `git add -A && git commit -m "feat(TSK-xxxx-xxxx): <short description>"`.
+
+## Step 5 — Merge into `${ai_dev_branch}$`, update the books
+1. `git checkout ${ai_dev_branch}$`
+2. `git merge --no-ff task/TSK-xxxx-xxxx`
+   - **On CONFLICT** (parallel agents may have moved the integration branch — MEMO #40): `git status`
+     shows `UU` files. **Resolve them yourself**: edit each conflicted file into a correct merged result
+     (remove every `<<<<<<< ======= >>>>>>>` marker), `git add <file>`, then `git commit --no-edit` to
+     finish the merge. If a conflict is too complex to be sure → `git merge --abort`, write a question
+     into `USER_QA.md`, go to Step 8 and stop (don't guess).
+3. Record the task in `AI_DONE.md` (ID, description, timestamp — per `.claude/templates/AI_DONE.sample.md`).
+   **Remove it from `AI_PROGRESS.md`**: if nothing is in progress after removal, reset with
+   `cp .claude/templates/AI_PROGRESS.empty.md AI_PROGRESS.md`. Likewise, if `AI_TODO.md` is now empty →
+   `cp .claude/templates/AI_TODO.empty.md AI_TODO.md`.
+4. Commit: `git add -A && git commit -m "chore(auto): finish TSK-xxxx-xxxx, merge into ${ai_dev_branch}$"`.
+5. (Optional) `git push origin ${ai_dev_branch}$`.
+
+## Step 6 — Recheck the token budget
+1. Re-run the **check-usage** skill: `python .claude/skills/check-usage/check_usage.py`, then **wait 3s**
+   (`sleep 3`) for the result file to be written.
+2. Print a summary: task done, tokens remaining.
+
+## Step 7 — Commit & push `${ai_dev_branch}$`
+1. `git checkout ${ai_dev_branch}$`
+2. `git add -A && git commit -m "chore(auto): update books after the autonomous cycle"` (skip if no change).
+3. `git push origin ${ai_dev_branch}$`.
+
+## Step 7.5 — Report on the `conversation` branch (share context with later agents — MEMO #40)
+> Multiple Claude instances take different tasks in parallel; a later agent needs to know what an earlier
+> one did. Use a dedicated branch named **`conversation`** holding **only** the file `CONVERSATION.md`
+> (no source or docs), keeping **at most the 50 most recent reports** (trim older ones when over).
+
+1. Save the context (task ID + summary + list of files changed this cycle).
+2. `git stash -u` if there are uncommitted changes (usually none — the books were committed in Step 7).
+3. Switch to the conversation branch (create it orphan if missing):
+   - `git fetch origin` → `git checkout conversation` (exists) or
+     `git checkout --orphan conversation && git rm -rf . 2>/dev/null` (create fresh, clean).
+   - `git pull --ff-only origin conversation` (skip if the remote has none).
+4. Append an entry to the **end** of `CONVERSATION.md`:
+   ```
+   ## <yyyy-MM-dd HH:mm> · TSK-xxxx-xxxx
+   - Did: <short summary>
+   - Files: <paths, comma-separated>
+   - Merged into: ${ai_dev_branch}$ (<conflict / no conflict>)
+   ```
+   If the number of `##` entries exceeds **50** → drop the oldest ones down to 50.
+5. `git add CONVERSATION.md && git commit -m "chore(conversation): TSK-xxxx-xxxx" && git push origin conversation`.
+6. Return to the integration branch: `git checkout ${ai_dev_branch}$` (and `git stash pop` if you stashed in 2).
+
+## Step 8 — Clean the lock (ALWAYS run, even on error/early exit)
+> This is the **final action of every cycle** — run it whether the cycle succeeded, hit an error, or was
+> blocked at the token gate. Goal: never let a stale lock block the next cron tick.
+1. Delete the lock file: `rm -f .claude/.autonomous.lock` (run in the project root).
+   - The lock IS the file `.autonomous.lock`: `autonomous-tick.sh` creates it at start and treats "the
+     file exists" = a run is in progress. Deleting it here releases the lock for the next tick.
+   - This is `/auto-cycle`'s responsibility; the wrapper only has a safety-net trap in case the cycle dies.
+2. **STOP** (the next cron tick will trigger the next cycle).

package/dist/project-sample/.claude/hooks/autonomous-history.py

@@ -0,0 +1,193 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+Manage .claude/.autonomous.histories.json — the SINGLE file combining the autonomous workflow's state + history.
+
+Structure:
+{
+  "cron_applied": "*/10 * * * *",     # the cron schedule applied last time (to detect a schedule change)
+  "consecutive_fails": 0,              # number of CONSECUTIVE failed command runs (reset on success)
+  "ticks": {"day": "YYYY-MM-DD", "count": N},  # count of ticks that actually invoked Claude today
+  "records": [ {...}, ... ]            # cron run history, NEWEST LAST, at most 50 records
+}
+
+Each record:
+{
+  "ts": "YYYY-MM-DD HH:MM:SS",
+  "status": "success" | "failure" | "skip",
+  "rc": <int|null>,                    # the command's exit code (null if it didn't run)
+  "gate": "<token-gate string>",
+  "note": "<short note>",
+  "command": "/auto-cycle",
+  "tick": "YYYY-MM-DD #N",             # day + tick number within the day
+  "config": { cron_schedule, model, max_session_pct, max_weekly_pct, quiet_hours,
+              max_ticks_per_day, stop_on_consecutive_failures, paused }
+}
+
+Usage (the file path is the first arg):
+  history.py <file> migrate <cron-applied> <fails> <ticks>   # one-time load from 3 old files (paths)
+  history.py <file> get-cron
+  history.py <file> set-cron <schedule>
+  history.py <file> get-fails
+  history.py <file> set-fails <n>
+  history.py <file> get-ticks <today>         # print the count for 'today' (0 if a different day/missing)
+  history.py <file> set-ticks <day> <count>
+  history.py <file> record <ts> <status> <rc> <gate> <note>   # config is read from the CFG_* env vars
+
+Philosophy: NEVER break on a missing/corrupt file — always initialize the default skeleton.
+"""
+import json
+import os
+import sys
+
+MAX_RECORDS = 50
+
+SKELETON = {
+    "cron_applied": "",
+    "consecutive_fails": 0,
+    "ticks": {"day": "", "count": 0},
+    "records": [],
+}
+
+
+def load(path):
+    try:
+        with open(path, encoding="utf-8") as f:
+            d = json.load(f)
+        if not isinstance(d, dict):
+            raise ValueError("not an object")
+    except Exception:
+        d = {}
+    out = dict(SKELETON)
+    out.update({k: d[k] for k in SKELETON if k in d})
+    if not isinstance(out.get("ticks"), dict):
+        out["ticks"] = dict(SKELETON["ticks"])
+    if not isinstance(out.get("records"), list):
+        out["records"] = []
+    return out
+
+
+def save(path, d):
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(d, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def cfg_from_env():
+    def g(k, default=""):
+        return os.environ.get(k, default)
+    return {
+        "cron_schedule": g("CFG_CRON_SCHEDULE"),
+        "model": g("CFG_MODEL"),
+        "max_session_pct": g("CFG_MAX_SESSION_PCT"),
+        "max_weekly_pct": g("CFG_MAX_WEEKLY_PCT"),
+        "quiet_hours": g("CFG_QUIET_HOURS"),
+        "max_ticks_per_day": g("CFG_MAX_TICKS_PER_DAY"),
+        "stop_on_consecutive_failures": g("CFG_STOP_ON_CONSEC_FAILURES"),
+        "paused": g("CFG_PAUSED"),
+    }
+
+
+def main():
+    if len(sys.argv) < 3:
+        sys.stderr.write("missing args: <file> <op> [...]\n")
+        return 2
+    path = sys.argv[1]
+    op = sys.argv[2]
+    args = sys.argv[3:]
+    d = load(path)
+
+    if op == "get-cron":
+        sys.stdout.write(str(d.get("cron_applied", "")))
+        return 0
+
+    if op == "set-cron":
+        d["cron_applied"] = args[0] if args else ""
+        save(path, d)
+        return 0
+
+    if op == "get-fails":
+        sys.stdout.write(str(int(d.get("consecutive_fails", 0) or 0)))
+        return 0
+
+    if op == "set-fails":
+        d["consecutive_fails"] = int(args[0]) if args else 0
+        save(path, d)
+        return 0
+
+    if op == "get-ticks":
+        today = args[0] if args else ""
+        t = d.get("ticks", {})
+        sys.stdout.write(str(int(t.get("count", 0) or 0) if t.get("day") == today else 0))
+        return 0
+
+    if op == "set-ticks":
+        day = args[0] if len(args) > 0 else ""
+        count = int(args[1]) if len(args) > 1 else 0
+        d["ticks"] = {"day": day, "count": count}
+        save(path, d)
+        return 0
+
+    if op == "record":
+        ts = args[0] if len(args) > 0 else ""
+        status = args[1] if len(args) > 1 else ""
+        rc_raw = args[2] if len(args) > 2 else ""
+        gate = args[3] if len(args) > 3 else ""
+        note = args[4] if len(args) > 4 else ""
+        try:
+            rc = int(rc_raw)
+        except (ValueError, TypeError):
+            rc = None
+        t = d.get("ticks", {})
+        rec = {
+            "ts": ts,
+            "status": status,
+            "rc": rc,
+            "gate": gate,
+            "note": note,
+            "command": os.environ.get("CFG_COMMAND", ""),
+            "tick": "%s #%s" % (t.get("day", ""), t.get("count", 0)),
+            "config": cfg_from_env(),
+        }
+        d["records"].append(rec)
+        if len(d["records"]) > MAX_RECORDS:
+            d["records"] = d["records"][-MAX_RECORDS:]
+        save(path, d)
+        return 0
+
+    if op == "migrate":
+        # Only load when histories.json has no real data yet (don't overwrite live data).
+        cron_p = args[0] if len(args) > 0 else ""
+        fails_p = args[1] if len(args) > 1 else ""
+        ticks_p = args[2] if len(args) > 2 else ""
+
+        def read_txt(p):
+            try:
+                with open(p, encoding="utf-8") as f:
+                    return f.read().strip()
+            except Exception:
+                return ""
+
+        if cron_p and not d.get("cron_applied"):
+            v = read_txt(cron_p)
+            if v:
+                d["cron_applied"] = v
+        if fails_p and not d.get("consecutive_fails"):
+            v = read_txt(fails_p)
+            if v.isdigit():
+                d["consecutive_fails"] = int(v)
+        if ticks_p and not d.get("ticks", {}).get("day"):
+            parts = read_txt(ticks_p).split()
+            if len(parts) == 2 and parts[1].isdigit():
+                d["ticks"] = {"day": parts[0], "count": int(parts[1])}
+        save(path, d)
+        return 0
+
+    sys.stderr.write("invalid op: %s\n" % op)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())