@holdpoint/cli 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/templates/MASTER_PROMPT.md

@@ -1,309 +1,39 @@
 # Holdpoint — Eval Checkpoints
 
-This project uses [Holdpoint](https://github.com/holdpoint-dev/holdpoint) to enforce
-eval checkpoints. Before marking any task done, all checks must pass.
-
----
+This repo uses [Holdpoint](https://holdpoint.dev) to enforce eval
+checkpoints. Before marking any task done, all checks must pass.
 
 ## The Rule
 
 Before marking **any** task complete:
 
-1. Run `npx @holdpoint/cli@alpha check` — all tasks must exit 0.
-2. `holdpoint check` also prints every **prompt** check whose `when` matches the
-   files you changed. Read and act on each listed instruction before finishing.
-
----
-
-## The Evolve Loop
-
-`checks.yaml` is not static — it grows alongside the project automatically.
-
-**`holdpoint-evolve` is a deterministic check** in `checks.yaml` that fires whenever you change a structural file (`package.json`, `pyproject.toml`, `go.mod`, `Dockerfile`, `tsconfig.json`, `vitest.config.*`, etc.). When it fires, `npx @holdpoint/cli@alpha evolve` runs and **exits 1 if `checks.yaml` is out of sync** — blocking task completion until you apply the proposals.
-
-When blocked by `holdpoint-evolve`, run:
-
-```
-npx @holdpoint/cli@alpha evolve --apply  # scan, apply proposals, regenerate engine files
-```
-
-Then commit:
-
-```
-git add checks.yaml .github/holdpoint/generated/
-git commit -m "chore: evolve holdpoint checks"
-```
-
-`holdpoint evolve --apply` is idempotent — safe to re-run at any time. It only adds checks for tools/patterns detected in the project and wraps stale checks (whose `when:` pattern no longer matches any file) with `conditionId: file_exists` so they auto-skip instead of failing.
-
-**What triggers evolution:**
-
-- New dependency in `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml`
-- New `Dockerfile`, `docker-compose.yml`, `*.tf`, `openapi.yaml`
-- New test runner config (`vitest.config.*`, `jest.config.*`, `playwright.config.*`)
-- New CI workflow in `.github/workflows/`
-- New TypeScript setup (`tsconfig.json`)
-
-**What does NOT trigger it:** `.ts` / `.py` / `.go` source files, docs, styles, tests — minor work proceeds without interruption.
-
----
-
-## checks.yaml — Full Reference
-
-`checks.yaml` at the project root is the single source of truth. Edit it to add,
-remove, or change checkpoints.
-
-After every edit, regenerate the engine files and commit everything together:
-
-```
-npx @holdpoint/cli@alpha update
-git add checks.yaml .github/holdpoint/generated/ .github/hooks/
-git commit -m "chore: update holdpoint checks"
-```
-
-### Top-level structure
-
-```yaml
-version: 1
-
-context:
-  guides: # project notes shown when `holdpoint check` runs
-    setup: >
-      Use pnpm, not npm. Node 20+ required.
-
-conditions: # gate checks on file/env state
-  - id: dist-built
-    operator: file_exists
-    path: dist/index.js
-
-checks: # list of all checks — each has on/when + cmd (task) or prompt
-  - ...
-```
-
----
-
-### Deterministic check
-
-```yaml
-- id: lint # unique slug, kebab-case
-  label: "ESLint — all packages" # human-readable label shown in output
-  # on: before_done       # lifecycle hook (default; only value today)
-  # when: frontend        # file filter — omit to run on every task
-  cmd: "pnpm turbo lint" # shell command; must exit 0 to pass
-  conditionId: dist-built # optional: skip if condition is not met
-```
-
-### Prompt check
-
-```yaml
-- id: migration-review
-  label: "Review DB migration"
-  when: "^prisma/migrations/" # only fires when migration files change
-  prompt: >
-    Open the new migration file. Confirm it is backward-compatible
-    and does not drop or truncate data without a fallback.
-```
-
----
-
-### `on` — lifecycle hooks
-
-`on` specifies _when in the agent lifecycle_ a check fires. Omit it to use the default.
-
-| Value         | Fires                              |
-| ------------- | ---------------------------------- |
-| `before_done` | Before the agent marks a task done |
-
----
-
-### `when` — file filters
-
-`when` is an optional file filter. If omitted the check runs on every task.
-
-| Value       | Fires when changed files match                                                                     |
-| ----------- | -------------------------------------------------------------------------------------------------- |
-| _(absent)_  | Every task — no file filter applied                                                                |
-| `frontend`  | `**/*.tsx`, `**/*.jsx`, `**/*.css`, `**/*.scss`, `**/tailwind.config.*`, `apps/**`                 |
-| `backend`   | `**/api/**`, `**/server/**`, `**/routes/**`, `**/controllers/**`, `packages/*/src/**`              |
-| `socket`    | `**/socket/**`, `**/ws/**`, `**/websocket/**`                                                      |
-| `visual`    | `**/*.stories.{ts,tsx}`, `**/__screenshots__/**`, `**/*.snap`                                      |
-| `python`    | `**/*.py`, `**/*.pyi`, `**/requirements*.txt`, `**/pyproject.toml`, `**/setup.py`, `**/pytest.ini` |
-| `go`        | `**/*.go`, `**/go.mod`, `**/go.sum`                                                                |
-| `rust`      | `**/*.rs`, `**/Cargo.toml`, `**/Cargo.lock`                                                        |
-| `java`      | `**/*.java`, `**/*.kt`, `**/*.gradle`, `**/*.gradle.kts`, `**/pom.xml`                             |
-| `ruby`      | `**/*.rb`, `**/Gemfile`, `**/Gemfile.lock`, `**/Rakefile`                                          |
-| `database`  | `**/*.sql`, `**/migrations/**`, `**/db/**`, `**/database/**`, `**/prisma/**`, `**/*.prisma`        |
-| `prisma`    | `**/prisma/**`, `**/*.prisma` — focused subset of `database` for Prisma-specific checks            |
-| `testing`   | `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`, `**/test/**`, `**/tests/**`, `**/spec/**`         |
-| `infra`     | `**/Dockerfile*`, `**/docker-compose.*`, `**/*.tf`, `**/*.tfvars`, `**/k8s/**`, `**/kubernetes/**` |
-| `ci`        | `**/.github/workflows/**`, `**/.circleci/**`, `**/Jenkinsfile`, `**/.gitlab-ci.yml`                |
-| `docs`      | `**/*.mdx`, `**/*.rst`, `**/docs/**`, `**/documentation/**`                                        |
-| `"^src/.*"` | Any JavaScript regex tested against each changed file path                                         |
-
-Regex example — fires only when files under `src/api/` change:
-
-```yaml
-when: "^src/api/" # new RegExp(when).test(filePath)
-```
-
-> **Note:** Named scopes use glob matching; plain strings are treated as JavaScript regexes.
-
----
-
-### Conditions
-
-Conditions let you skip a check when a prerequisite is not yet met (e.g. a build
-artefact doesn't exist yet).
-
-| Operator          | What it checks                                    |
-| ----------------- | ------------------------------------------------- |
-| `file_exists`     | A file or directory exists at `path`              |
-| `file_contains`   | The file at `path` contains the substring `value` |
-| `env_var_set`     | The environment variable named `value` is set     |
-| `shell_returns_0` | The shell command in `cmd` exits with code 0      |
-
-```yaml
-conditions:
-  - id: packages-built
-    operator: file_exists
-    path: packages/yaml-core/dist/index.js
-
-checks:
-  - id: validate-templates
-    label: "Templates parse against schema"
-    conditionId: packages-built # skipped (◌) when dist is absent
-    cmd: "node dist/validate.js templates/"
-```
-
----
-
-### Context guides
-
-`context.guides` is a freeform key → multiline-string map. Guides are printed
-at the start of `holdpoint check` output as project-level reminders to whoever
-(or whatever) is running the checks.
-
-```yaml
-context:
-  guides:
-    setup: >
-      This project requires Node 20 and pnpm 9+.
-      Run `pnpm install` from the repo root before any other command.
-    architecture: >
-      API routes live in src/api/. Models live in src/models/.
-      Client code must never import from server modules.
-```
-
----
-
-## Adding a New Check
-
-1. Open `checks.yaml`.
-2. Add your entry under `checks:`.
-3. Run `npx @holdpoint/cli@alpha update`.
-4. Commit `checks.yaml` and the generated files.
-
-**Add a task check (runs a shell command automatically):**
-
-```yaml
-checks:
-  - id: vitest
-    label: "Vitest — unit tests"
-    cmd: "pnpm vitest run"
-```
-
-**Add a scoped task (fires only on matching file changes):**
-
-```yaml
-checks:
-  - id: openapi-sync
-    label: "OpenAPI types are up to date"
-    when: "^src/api/"
-    cmd: "pnpm generate:types && git diff --exit-code src/generated/"
-```
-
-**Add an agent prompt checkpoint:**
-
-```yaml
-checks:
-  - id: jsdoc
-    label: "JSDoc on changed public functions"
-    prompt: >
-      For every public function or export you modified, ensure there is an
-      accurate JSDoc comment: description, @param, and @returns.
-```
-
-**Enforce changelog and git commit on every task (recommended):**
-
-```yaml
-checks:
-  - id: changelog-update
-    label: "Add a CHANGELOG.md entry for this session"
-    prompt: >
-      Before committing, add an entry to CHANGELOG.md describing what was done.
-      Use Keep a Changelog format — add under ## [Unreleased] (create the file
-      and that section if absent). Group entries as Added, Changed, Fixed, or Removed.
-      Be concise but specific. The entry text will serve as the commit message.
-
-  - id: readme-sync
-    label: "Update README.md if user-facing changes were made"
-    prompt: >
-      If you added, changed, or removed user-facing functionality — CLI commands,
-      configuration options, public APIs, or significant new features — update
-      README.md to reflect those changes.
-
-  - id: git-commit
-    label: "Commit all changes before finishing"
-    cmd: 'git rev-parse --is-inside-work-tree 2>/dev/null || exit 0; [ -z "$(git status --porcelain)" ] && exit 0; git status --short; exit 1'
-```
-
-When the `git-commit` check fails (uncommitted changes remain), the agent will also see
-the `changelog-update` and `readme-sync` prompt reminders inline — ensuring it updates
-the changelog, syncs docs, _then_ commits before it can mark the task done.
-
----
-
-## `session_context_files`
-
-`session_context_files` is an optional list of project files that Holdpoint injects
-as context at the start of every Copilot session. Use it for files the agent should
-always read before starting work.
-
-```yaml
-session_context_files:
-  - MASTER_PROMPT.md
-  - AGENT_CONTEXT.md
-```
-
-Files are resolved relative to the repo root and must stay inside it (traversal
-paths like `../../etc/passwd` are rejected). If a file doesn't exist it is silently
-skipped.
+1. Run `holdpoint check` — all checks must exit 0.
+2. `holdpoint check` also prints every **prompt** check whose `when`
+   matches the files you changed. Read and act on each listed
+   instruction before finishing.
+3. Never bypass via `git commit --no-verify` or by skipping a stop
+   hook. If a check is wrong, fix the check in `checks.yaml`, don't
+   route around it.
 
----
+## The Suggest Loop
 
-## Commands
+`checks.yaml` grows with the project. `holdpoint-suggest` is a check
+that fires whenever structural files change (`package.json`,
+`pyproject.toml`, `go.mod`, `Dockerfile`, `tsconfig.json`,
+`vitest.config.*`, etc.). When it fires, `holdpoint suggest` runs and
+**exits 1 if `checks.yaml` is out of sync** — blocking task completion
+until you apply the proposals.
 
-| Command                            | What it does                                            |
-| ---------------------------------- | ------------------------------------------------------- |
-| `npx @holdpoint/cli@alpha check`              | Run checks against all files changed vs HEAD            |
-| `npx @holdpoint/cli@alpha check --staged`     | Run checks against staged files only                    |
-| `npx @holdpoint/cli@alpha evolve`             | Scan project and show proposed additions to checks.yaml |
-| `npx @holdpoint/cli@alpha evolve --apply`     | Apply proposals and regenerate engine files             |
-| `npx @holdpoint/cli@alpha update`             | Regenerate engine files from the current `checks.yaml`  |
-| `npx @holdpoint/cli@alpha validate`           | Validate `checks.yaml` schema (no commands run)         |
-| `npx @holdpoint/cli@alpha builder` | Open the visual builder UI at localhost:4321            |
+When blocked, run:
 
----
+    holdpoint suggest --apply
 
-## Generated files (do not edit directly)
+then commit the changes and continue.
 
-| File                                                | Agent   |
-| --------------------------------------------------- | ------- |
-| `.github/holdpoint/generated/checks.immutable.json` | all     |
-| `.github/hooks/holdpoint.json`                      | Copilot |
-| `.github/hooks/holdpoint-check.mjs`                 | Copilot |
-| `.claude/settings.json`                             | Claude  |
-| `.cursorrules` (Holdpoint section)                  | Cursor  |
+## Going deeper
 
-All generated files are overwritten by `npx @holdpoint/cli@alpha update`. Edit `checks.yaml`,
-then run `update` — never edit the generated files directly.
+For the full reference — every built-in check, every `when:` scope,
+per-engine details, troubleshooting — read
+[`HOLDPOINT_REFERENCE.md`](./HOLDPOINT_REFERENCE.md). The file is on
+disk; you can `cat` it when you need detail. It is intentionally not
+auto-injected because it's reference, not directive.

package/dist/templates/default.yaml

@@ -0,0 +1,249 @@
+version: 1
+
+# Holdpoint default checks — single source of truth across all stacks.
+# Every check below is either universally relevant (e.g. git-commit) or
+# gated by `when:` (path-based scope) AND/OR `conditionId:` (file
+# existence in the repo). Add a new stack by adding a condition that
+# detects its manifest file, then gating stack-specific checks on it —
+# don't fork this file.
+
+context:
+  guides: {}
+
+session_context_files:
+  - MASTER_PROMPT.md
+
+conditions:
+  - id: is-node
+    operator: file_exists
+    path: package.json
+  - id: is-python
+    operator: file_exists
+    path: pyproject.toml
+  - id: is-go
+    operator: file_exists
+    path: go.mod
+  - id: is-rust
+    operator: file_exists
+    path: Cargo.toml
+  - id: has-dockerfile
+    operator: file_exists
+    path: Dockerfile
+  - id: has-openapi
+    operator: file_exists
+    path: openapi.yaml
+  - id: has-playwright
+    operator: file_exists
+    path: playwright.config.ts
+  - id: has-changesets
+    operator: file_exists
+    path: .changeset/config.json
+  - id: has-lint-script
+    operator: file_contains
+    path: package.json
+    contains: '"lint"'
+  - id: has-build-script
+    operator: file_contains
+    path: package.json
+    contains: '"build"'
+  - id: has-test-script
+    operator: file_contains
+    path: package.json
+    contains: '"test"'
+  - id: has-typecheck-script
+    operator: file_contains
+    path: package.json
+    contains: '"typecheck"'
+
+patterns:
+  changelog-files: "(^|/)CHANGELOG\\.md$"
+
+checks:
+  # ── Node / TypeScript / JavaScript ─────────────────────────────────
+  - id: node-lint
+    label: "Lint (Node) — no warnings"
+    conditionId: has-lint-script
+    cmd: "pnpm lint --max-warnings 0"
+  - id: node-typecheck
+    label: "TypeScript type check"
+    conditionId: has-typecheck-script
+    cmd: "pnpm typecheck"
+  - id: node-test
+    label: "Unit tests (Node)"
+    conditionId: has-test-script
+    cmd: "pnpm test --run"
+  - id: node-build
+    label: "Production build (Node)"
+    conditionId: has-build-script
+    when: backend
+    cmd: "pnpm build"
+  - id: jsdoc
+    label: "JSDoc on changed public functions"
+    conditionId: is-node
+    when: backend
+    prompt: >
+      Ensure all changed public functions, classes, and module exports
+      have accurate JSDoc (description + @param + @returns).
+
+  # ── Python ─────────────────────────────────────────────────────────
+  - id: py-lint
+    label: "Ruff (Python lint)"
+    conditionId: is-python
+    when: python
+    cmd: "ruff check ."
+  - id: py-typecheck
+    label: "Mypy (Python type check)"
+    conditionId: is-python
+    when: python
+    cmd: "mypy . --ignore-missing-imports"
+  - id: py-test
+    label: "pytest"
+    conditionId: is-python
+    when: python
+    cmd: "pytest --tb=short -q"
+  - id: py-docstrings
+    label: "Docstrings on changed Python functions"
+    conditionId: is-python
+    when: python
+    prompt: >
+      Ensure changed public functions and classes have PEP-257 docstrings.
+  - id: py-type-hints
+    label: "Type hints on new Python functions"
+    conditionId: is-python
+    when: python
+    prompt: >
+      Confirm new functions have full type annotations on parameters
+      and return values.
+
+  # ── Go ─────────────────────────────────────────────────────────────
+  - id: go-build
+    label: "go build — no compilation errors"
+    conditionId: is-go
+    when: go
+    cmd: "go build ./..."
+  - id: go-vet
+    label: "go vet — no suspicious constructs"
+    conditionId: is-go
+    when: go
+    cmd: "go vet ./..."
+  - id: go-test
+    label: "go test"
+    conditionId: is-go
+    when: go
+    cmd: "go test ./..."
+  - id: godoc
+    label: "GoDoc on exported symbols"
+    conditionId: is-go
+    when: go
+    prompt: >
+      Exported functions, types, methods, and packages have GoDoc
+      starting with the symbol name.
+
+  # ── Rust ───────────────────────────────────────────────────────────
+  - id: rust-build
+    label: "cargo build"
+    conditionId: is-rust
+    when: rust
+    cmd: "cargo build"
+  - id: rust-clippy
+    label: "Clippy — strict"
+    conditionId: is-rust
+    when: rust
+    cmd: "cargo clippy --all-targets -- -D warnings"
+  - id: rust-test
+    label: "cargo test"
+    conditionId: is-rust
+    when: rust
+    cmd: "cargo test"
+
+  # ── Frontend ───────────────────────────────────────────────────────
+  - id: visual-regression
+    label: "Visual regression check"
+    conditionId: has-playwright
+    when: frontend
+    prompt: >
+      Run `pnpm playwright test` for UI changes. Review screenshots
+      at 1280px, 768px, and 375px breakpoints.
+  - id: i18n
+    label: "i18n — no hardcoded user-facing strings"
+    when: frontend
+    prompt: >
+      User-visible text is wrapped in the t() translation function
+      (or project equivalent) with corresponding locale entries.
+
+  # ── Backend / API ──────────────────────────────────────────────────
+  - id: openapi-updated
+    label: "OpenAPI spec updated for API changes"
+    conditionId: has-openapi
+    when: backend
+    prompt: >
+      If API routes changed, confirm openapi.yaml has been updated.
+
+  # ── Database ───────────────────────────────────────────────────────
+  - id: db-migrations
+    label: "Database migration for schema changes"
+    when: database
+    prompt: >
+      If schema files changed, ensure a migration was generated and
+      committed (prisma migrate dev, alembic revision, rails db:migrate).
+
+  # ── Infra ──────────────────────────────────────────────────────────
+  - id: dockerfile-best-practices
+    label: "Dockerfile best practices"
+    conditionId: has-dockerfile
+    when: infra
+    prompt: >
+      Confirm multi-stage build, non-root USER, pinned base image,
+      minimal layers.
+
+  # ── Documentation (universal) ──────────────────────────────────────
+  - id: readme-sync
+    label: "Update README.md for user-facing changes"
+    prompt: >
+      If user-facing functionality changed (CLI commands, config,
+      public APIs, features), update README.md.
+  - id: changelog-changeset
+    label: "Use changesets instead of manual changelog edits"
+    conditionId: has-changesets
+    when: changelog-files
+    prompt: >
+      If you changed any CHANGELOG.md file, move the release note into a
+      .changeset/*.md entry and let release automation update changelogs.
+      Keep manual changelog edits only when explicitly requested or for
+      non-release historical notes, and state that reason before finishing.
+  - id: git-workflow
+    label: "Use the right git workflow"
+    prompt: >
+      Choose the least-disruptive git workflow: use branch + PR for requested
+      feature branches or protected-main work; for small local fixes, commit on
+      the current branch without opening a PR unless asked; if already on a
+      feature branch, keep committing there instead of creating another branch.
+      Push only when a PR, remote review, CI run, or handoff needs it; otherwise
+      leave the commit local and report the branch/commit.
+
+  # ── Code hygiene (universal) ───────────────────────────────────────
+  - id: no-todos
+    label: "No TODO/FIXME left in changed code"
+    cmd: >-
+      ! grep -rEn "TODO|FIXME|HACK|XXX"
+      --include="*.ts" --include="*.tsx"
+      --include="*.js" --include="*.jsx"
+      --include="*.py" --include="*.go" --include="*.rs"
+      --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.git
+      --exclude-dir=.next --exclude-dir=.turbo --exclude-dir=build
+      --exclude-dir=.venv --exclude-dir=venv --exclude-dir=__pycache__
+      --exclude-dir=target --exclude-dir=vendor
+      .
+
+  # ── Holdpoint-internal ─────────────────────────────────────────────
+  - id: holdpoint-suggest
+    label: "Suggest checks when project structure changes"
+    when: structural
+    cmd: "node_modules/.bin/holdpoint suggest"
+  - id: changeset
+    label: "Changeset for package changes"
+    conditionId: has-changesets
+    cmd: "node_modules/.bin/holdpoint require-changeset --staged"
+  - id: git-commit
+    label: "Commit all changes before finishing"
+    cmd: 'git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0; [ -z "$(git status --porcelain)" ] && exit 0; git status --short; exit 1'

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@holdpoint/cli",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.20",
   "publishConfig": {
-    "access": "public",
-    "tag": "alpha"
+    "access": "public"
   },
   "description": "Holdpoint CLI — enforce deterministic eval checkpoints on AI coding agents",
   "homepage": "https://holdpoint.dev",
@@ -47,20 +46,23 @@
   ],
   "dependencies": {
     "chalk": "^5.3.0",
-    "commander": "^12.1.0",
-    "ora": "^8.1.1",
-    "@holdpoint/engine-claude": "0.1.0-alpha.2",
-    "@holdpoint/types": "0.1.0-alpha.2",
-    "@holdpoint/engine-cursor": "0.1.0-alpha.2",
-    "@holdpoint/engine-copilot": "0.1.0-alpha.2",
-    "@holdpoint/yaml-core": "0.1.0-alpha.2"
+    "commander": "^14.0.3",
+    "ora": "^9.4.0",
+    "@holdpoint/live-daemon": "0.1.0-alpha.6",
+    "@holdpoint/engine-claude": "0.1.0-alpha.14",
+    "@holdpoint/engine-codex": "0.1.0-alpha.15",
+    "@holdpoint/sdk": "0.1.0-alpha.4",
+    "@holdpoint/live-protocol": "0.1.0-alpha.4",
+    "@holdpoint/engine-copilot": "0.1.0-alpha.15",
+    "@holdpoint/engine-cursor": "0.1.0-alpha.13",
+    "@holdpoint/types": "0.1.0-alpha.10",
+    "@holdpoint/yaml-core": "0.1.0-alpha.11"
   },
   "devDependencies": {
-    "@types/node": "^22.10.2",
+    "@types/node": "^25.9.1",
     "tsup": "^8.3.5",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8",
-    "@holdpoint/builder": "0.1.0"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
   },
   "scripts": {
     "build": "tsup",