mill-init

mill-init: onboard a repo for ticketmill

Produces everything a mill run needs, and refuses to write a profile it hasn't proven works. Do the steps in order; each gates the next.

Step 1: Preconditions

1. Confirm you are in a git repo with a GitHub remote: git rev-parse --show-toplevel and gh repo view --json nameWithOwner. Record ROOT and the owner/name slug.
2. Confirm gh auth status succeeds and the token can write issues (gh label list is a cheap probe).
3. If <ROOT>/.claude/ticketmill.json already exists, read it and tell the user: this run will UPDATE it (show a diff at the end), not silently replace it.

Step 2: Detect the stack and propose a profile

Inspect the repo (build files, CI config, CLAUDE.md, README) and propose values for every profile field. Show the user the proposal and confirm the load-bearing ones:

{
  "repo": "owner/name",
  "test_command": "php artisan test",
  "test_globs": ["**/*.php", "tests/**"],
  "install_commands": ["composer install --no-interaction"],
  "env_files": [".env"],
  "simplify_globs": ["**/*.php"],
  "serialize_globs": [],
  "docblock_globs": null,
  "docs_dir": null,
  "logs_dir": "logs/ticketmill",
  "claim_label": "ticketmill",
  "verify_notes": [],
  "warn_base_branches": [],
  "consolidation": true,
  "engine_owned_globs": [],
  "browser": null,
  "models": {},
  "roles": { }
}

Field rules:

• test_command is REQUIRED and may be null ONLY as an explicit human decision. If you find no test suite, ASK: "I found no test command. Ticketmill will merge code that no automated test has exercised, and every batch PR will carry a visible 'Verification Gaps' notice. Confirm test_command: null?" Never write null on your own initiative.
• env_files: files the test suite needs that git doesn't track (e.g. .env). They are copied root -> worktree at issue setup.
• verify_notes: environment preconditions agents must know (required containers, seed commands, service dependencies). Anything you needed in Step 4 belongs here.
• browser: OPT-IN. Only propose it for projects with a servable UI AND if the user wants live browser verification: { "serve_command": "... --port={port}", "build_command": null, "ui_globs": [...], "port_base": 8100, "notes": "..." }. Optional coordination overrides (each defaults to the value shown; only mention them if the user needs to change one): lock_path (default /tmp/ticketmill-browser-lock, the shared cross-agent browser lock directory), stale_seconds (default 1800, how long before a held lock is considered dead and stolen), poll_seconds (default 15, wait interval between lock-acquire retries), port_span (default 900, the modulus port_base is spread over per issue number), and artifact_dir (default /tmp/ticketmill-issue-{issue}, {issue}-templated like serve_command's {port}, where browser-verify screenshots/artifacts are written). Caution: this resolved path is deleted with rm -rf on cleanup (both the per-issue browser-verify stage and the final batch cleanup). It must be a dedicated scratch directory, never a project directory, shared mount, or $HOME.
• lockstep_installed_paths: only needed when the repo being onboarded keeps an installed copy of an engine-owned file in lockstep with a source-of-truth file elsewhere in the same repo, kept in sync by the repo's own tooling. List those installed paths so the engine's post-implement guardrail exempts them from a hard revert instead of undoing genuine engine work. Ticketmill's own profile (this repo, self-hosted) sets lockstep_installed_paths: [".claude/workflows/ticketmill.js"], since scripts/lint-engine.js keeps that installed copy byte-identical to workflows/ticketmill.js. Leave it empty for every other repo.
• serialize_globs: OPTIONAL, default []. Lane scheduling (issue #1) already predicts likely file overlap per issue and serializes those issues instead of racing them. This field is only for files that heuristic alone can't be trusted to catch: a magnet config, a shared schema/router, anything where two issues touching it concurrently would conflict even if their predicted-file sets don't otherwise overlap. Leave it [] unless the user names such a file; propose it only when the stack detection in Step 2 surfaces an obvious candidate (e.g. a single central routes/config file every feature touches).
• warn_base_branches: OPTIONAL, default []. Base branch names that should trigger a Select-phase warning when a batch targets one (a signal the run may be pointed at a branch that auto-deploys on push rather than the intended working branch). Leave it [] unless the user names CI/CD-trigger branches for this repo (e.g. a deploy-prod/deploy-dev convention). Never propose a default on your own.
• consolidation: OPTIONAL, default true. Leave it true unless the user asks to disable the Select-phase consolidation gate that groups issues cheaper to resolve as one unit; set false to skip that gate agent call entirely.
• engine_owned_globs: OPTIONAL, default []. Extends the built-in engine-owned path set with repo-specific read-only paths, beyond lockstep_installed_paths above. Leave it [] unless the user names additional paths a run must never touch.
• models: OPTIONAL, default {}. Per-stage model/effort overrides. The valid stage keys are enumerated in the header schema comment of workflows/ticketmill.js, adjacent to the M map that is their source of truth. Do not re-derive or duplicate that list here.