@4pm/cli 1.5.16 → 1.5.17-c

package/dist/project-sample/.claude/templates/README.md

@@ -0,0 +1,14 @@
+# Autonomous book templates
+
+Canonical templates for the 5 "book" files used by the autonomous loop. Each book has two templates:
+
+- `<NAME>.empty.md` — the EMPTY state. The tick's "has work" gate + `/auto-cycle` compare a live book
+  against this (equal ⇒ empty). When clearing/resetting a book, overwrite it with **exactly** this file
+  (`cp .claude/templates/<NAME>.empty.md <NAME>`).
+- `<NAME>.sample.md` — an example WITH DATA, showing the expected format when adding entries.
+
+Books: `USER_TODO`, `AI_TODO`, `AI_PROGRESS`, `AI_DONE`, `USER_QA` (+ `AI_PLACEHOLDER`). Keep the
+header/blockquote when filling a book in; match the sample's format.
+
+All templates are written in English by default; the project's own docs/source language is decided by the
+project `CLAUDE.md`.

package/dist/project-sample/.claude/templates/USER_QA.empty.md

@@ -0,0 +1,6 @@
+# USER_QA — Questions & answers
+
+> When a request is unclear, the AI writes a question here instead of guessing. Answer it, then re-post
+> the clarified request into `USER_TODO.md`.
+
+_(no questions)_

package/dist/project-sample/.claude/templates/USER_QA.sample.md

@@ -0,0 +1,7 @@
+# USER_QA — Questions & answers
+
+## 2026-01-01 — Login: which providers?
+- Original request: "add a login screen".
+- Unclear: email/password only, or also OAuth (Google/GitHub)?
+- Options: (a) email+password only, (b) also Google, (c) also GitHub.
+- Answer:

package/dist/project-sample/.claude/templates/USER_TODO.empty.md

@@ -0,0 +1,6 @@
+# USER_TODO — User requests
+
+> Write what you want the AI to do (in the project's language — default English). The autonomous cycle
+> reads this, generates tasks into `AI_TODO.md`, then clears this file back to the template.
+
+_(no requests)_

package/dist/project-sample/.claude/templates/USER_TODO.sample.md

@@ -0,0 +1,6 @@
+# USER_TODO — User requests
+
+> Write what you want the AI to do. The autonomous cycle reads this, generates tasks, then clears it.
+
+- Add a login screen with email + password, validating inputs and showing errors.
+- Wire it to the existing auth API and handle the error responses.

package/dist/project-sample/.claude/templates/project.secrets.sample.json

@@ -0,0 +1,5 @@
+{
+  "ai_dev_branch": "main",
+  "api_base_url": "https://api.example.com",
+  "api_key": "sk-demo-0000…zzzz"
+}

package/dist/project-sample/.vscode/extensions.json

@@ -0,0 +1,6 @@
+{
+  "recommendations": [
+    "anthropic.claude-code",
+    "editorconfig.editorconfig"
+  ]
+}

package/dist/project-sample/.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+  "files.eol": "\n",
+  "files.insertFinalNewline": true,
+  "files.trimTrailingWhitespace": true,
+  "editor.formatOnSave": true,
+  "editor.tabSize": 2,
+  "editor.rulers": [
+    100
+  ],
+  "[markdown]": {
+    "files.trimTrailingWhitespace": false
+  },
+  "search.exclude": {
+    "**/node_modules": true,
+    "**/dist": true,
+    "**/reports": true
+  }
+}

package/dist/project-sample/AI_DONE.md

@@ -0,0 +1,9 @@
+# AI_DONE — Completed tasks + incidents
+
+> The autonomous cycle appends completed tasks here (ID, description, timestamp) and logs incidents/notes.
+
+## Done
+_(none)_
+
+## Incidents / notes
+_(none)_

package/dist/project-sample/AI_PLACEHOLDER.md

@@ -0,0 +1,19 @@
+# AI_PLACEHOLDER — Placeholder table (key + explanation)
+
+> Lists **placeholders** the AI understands: each has a **key** and an **explanation**. Reference them in
+> docs/config as `${key}$` (e.g. `${ai_dev_branch}$`); the tool substitutes the real **value** at runtime.
+>
+> **Where values live:** the real value of each key is stored in `project.secrets.json` (same folder). This
+> file holds only keys + explanations, so it is **safe to commit** and the AI can read it for context.
+>
+> **Why two files:**
+> - `AI_PLACEHOLDER.md` (this file) — keys + explanations. Safe to commit; not gitignored/denied.
+> - `project.secrets.json` — key → real value. **Gitignored** and **denied** in `.claude/settings.json`,
+>   so secret values never reach git and the AI can't read them directly. Manage values from the web
+>   (Placeholder tab) — they are write-only (never shown back).
+
+| Key | Explanation |
+|-----|-------------|
+| ai_dev_branch | The shared dev branch the AI merges tasks into before the main branch. |
+| api_base_url | Base URL of the internal API the AI calls during integration tests. |
+| api_key | Key for the internal API (real value in project.secrets.json, NOT committed). |

package/dist/project-sample/AI_PROGRESS.md

@@ -0,0 +1,5 @@
+# AI_PROGRESS — Task in progress
+
+> The current in-progress task (set when the cycle starts a task, cleared when it finishes).
+
+_(no task in progress)_

package/dist/project-sample/AI_SECURITY.md

@@ -0,0 +1,30 @@
+# AI_SECURITY — Security rules for the AI
+
+This document describes the **security criteria** the AI (Claude Code) and users must follow when working
+on the project. The AI reads this to know what data to protect, what to mask, and what must NEVER be
+committed. Replace the sample rules below with your project's real policy.
+
+## 1. Security criteria
+- Sensitive information must NOT leak into source code, logs, reports, or docs.
+- Every secret must be loaded from environment variables / a secret manager, NEVER hard-coded.
+- Grant only the least privilege needed for keys, tokens, and accounts.
+
+## 2. What to mask
+When displaying, logging, or capturing evidence, mask the following (keep only a few leading/trailing chars):
+- API keys, secret keys, access/refresh tokens, JWTs.
+- Passwords, database connection strings, private keys.
+- Personal data (PII): email, phone, national id, card numbers.
+- `Authorization` headers, session cookies.
+
+Example: `sk-ABCD…WXYZ` instead of the full key.
+
+## 3. Commit rules
+- NEVER commit: `.env`, `*.key` / `*.pem`, credentials, `secrets.json`, API keys, passwords, or tokens.
+- Check `git diff` before committing; if a secret slipped in, **rotate** that key.
+- Keep `.gitignore` covering sensitive files/dirs (e.g. `.env`, `*.local.json`, `node_modules/`).
+- Never put real customer data into tests/evidence — use fixtures.
+
+## 4. On a leak
+1. Rotate the leaked key/secret immediately.
+2. Remove the secret from git history if needed (e.g. `git filter-repo`).
+3. Record the incident and notify the project manager.

package/dist/project-sample/AI_TODO.md

@@ -0,0 +1,14 @@
+# AI_TODO — Task queue (generated by the AI)
+
+> Tasks are generated from `USER_TODO.md`. ID format `TSK-{groupid:0000}-{taskid:0000}`
+> (group = one request/batch, task = a small sub-task doable in ~1 cycle).
+> **Priority** = High / Medium / Low.
+> **Approved**: the source of truth is `.claude/.autonomous.approvals.json` (the user ticks it in the
+> web VERIFY tab — ADR-0152); the Approved column here is display-only, not where the decision is made.
+> **Depends** = the `TSK-…` ids that must be DONE (present in `AI_DONE.md`) first.
+> `/auto-cycle` only takes tasks that are approved AND have their dependencies met → moves them to
+> `AI_PROGRESS.md`; runs group by group, within a group High → Medium → Low.
+
+| ID | Priority | Approved | Depends | Group | Task description | Notes |
+|----|----------|----------|---------|-------|------------------|-------|
+| | | | | | | |

package/dist/project-sample/USER_QA.md

@@ -0,0 +1,6 @@
+# USER_QA — Questions & answers
+
+> When a request is unclear, the AI writes a question here instead of guessing. Answer it, then re-post
+> the clarified request into `USER_TODO.md`.
+
+_(no questions)_

package/dist/project-sample/USER_TODO.md

@@ -0,0 +1,6 @@
+# USER_TODO — User requests
+
+> Write what you want the AI to do (in the project's language — default English). The autonomous cycle
+> reads this, generates tasks into `AI_TODO.md`, then clears this file back to the template.
+
+_(no requests)_

package/dist/project-sample/project.secrets.json.sample

@@ -0,0 +1,5 @@
+{
+  "ai_dev_branch": "main",
+  "api_base_url": "https://api.example.com",
+  "api_key": "sk-demo-0000…zzzz"
+}

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

@@ -0,0 +1,8 @@
+{
+  "folders": {
+    "docs": ".",
+    "tests": "tests",
+    "reports": "reports",
+    "src": "src"
+  }
+}

package/dist/project-sample/tests/IT/README.md

@@ -0,0 +1,25 @@
+# Integration Test (IT)
+
+Integration tests exercise **real end-to-end flows** and (optionally) capture **evidence** (before/after)
+per test case, so a reviewer can see what changed.
+
+## Layout
+| Folder | Role |
+|--------|------|
+| `senarios/<senario>/` | One folder per scenario: a spec per test case (`TC-00x-*.md`) + `testcases.json` (manifest of case ids/titles/params) + `senario.json` (name, description) |
+| `tools/`     | Your test runner / orchestrator + any helpers (choose the tooling that fits the project) |
+| `evidence/`  | Generated results per case: `<TC>/{before,after}` captures + logs + a summary |
+
+## Idea
+For each relevant test case, capture the state **before** a change, make the change, capture **after**,
+then gather the pair into a reviewable report. Capture only the cases relevant to the task.
+
+## Add a test case
+1. Pick/create a scenario `senarios/<senario>/`. Write `senarios/<senario>/TC-00x-*.md` (keep the
+   sections: Preconditions · Steps · Expected result · Evidence).
+2. Add an entry to `senarios/<senario>/testcases.json` (id, title, params your runner needs).
+3. Run your IT runner for that case to generate evidence.
+
+> This sample ships the structure only — plug in the IT tooling appropriate for your stack (a browser
+> harness like Playwright/Puppeteer for web UIs, an API test runner for services, etc.). Reference the
+> run command from the project `CLAUDE.md`.

package/dist/project-sample/tests/README.md

@@ -0,0 +1,22 @@
+# Tests
+
+Tests are organized in **two levels**:
+
+- **Unit Test (UT)** — test each **unit** (function/module) in isolation; fast, no browser. Lives in
+  `tests/UT/`.
+- **Integration Test (IT)** — test **real integration flows**, optionally capturing **evidence**
+  (before/after) per test case. Lives in `tests/IT/`.
+
+```
+tests/
+├── UT/                         # Unit Test — isolated unit tests
+│   └── README.md               #   naming & conventions
+└── IT/                         # Integration Test — real-flow tests (+ evidence)
+    ├── senarios/<senario>/     #   one folder per scenario: testcase specs (.md) + testcases.json + senario.json
+    ├── tools/                  #   your test runner / helpers
+    └── evidence/               #   before/after + logs (generated)
+```
+
+This sample ships the folder **structure** only — no test cases yet. Pick the test tooling that fits your
+project (e.g. Node's `node:test`, Jest, Vitest, Pytest, Playwright…) and wire your own run command
+(reference it from the project `CLAUDE.md`). See `tests/UT/README.md` and `tests/IT/README.md`.

package/dist/project-sample/tests/UT/README.md

@@ -0,0 +1,18 @@
+# Unit Test (UT)
+
+**Unit** tests: check each function/module in isolation — fast, deterministic, **no browser/render**.
+Complements the Integration Tests in `tests/IT/`.
+
+> This sample ships no UT cases — the folder is a skeleton. Add UT here following the conventions below.
+
+## Conventions
+- One test file per module in `tests/UT/`, named to mirror the module under `src/` (e.g. `<module>.test.*`).
+- Tests should run via your chosen runner (Node `node:test`, Jest, Vitest, Pytest, …) and **exit
+  non-zero on failure** so CI/the runner detects it.
+- Keep UT **fast & isolated**: no network, no writes outside the test dir, no dependence on real time or
+  global state.
+
+## Add a test case
+1. Create `tests/UT/<module>.test.*`.
+2. Import the module under test from `src/`, assert each branch + edge case.
+3. Run your test command to confirm everything is green.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@4pm/cli",
-  "version": "1.5.16",
+  "version": "1.5.17c",
   "private": false,
   "description": "4PM CLI — drives Claude/Codex CLIs on AI worker machines (Node + TypeScript)",
   "license": "LicenseRef-4PM-Source-Available",