tickmarkr 1.36.0 → 1.38.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Khalid Alzahrani
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,56 +1,24 @@
+<p align="center"><img src="assets/wordmark-dark.png" alt="tickmarkr" width="640"></p>
+
 # tickmarkr
 
 **Assertions are free. Tickmarks are earned.**
 
-tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs — framed as an external
-audit engagement. You scope assertions (acceptance criteria); the engine earns tickmarks (passed
-gates) only after independent verification. An **engagement** (`tickmarkr run`) compiles a spec
-into a task graph, routes work to the best installed agent CLI (claude-code, codex, cursor-agent,
-opencode, grok, pi) by cost within capability floors, dispatches **field teams** in isolated git
-worktrees — as real visible TUIs when running under [herdr](https://herdr.dev), headless
-subprocesses otherwise — and records every event in the **audit trail** (engagement state directory).
-Green tasks consolidate onto a `tickmarkr/<runId>` **consolidation** branch; **sign-off** (merge to
-your mainline) is always the Partner's call, never the engine's. A fully green engagement is an
-**unqualified opinion** — every assertion independently ticked.
-
-<!-- tickmarkr:compat-legacy BEGIN: sanctioned naming residue, unchanged pending shim spec -->
-**Legacy naming (unchanged):** tickmarkr reads existing state from `.drovr/` directories and resumes runs with legacy `drovr/<runId>` branch names recorded in their journals; new engagements write to `tickmarkr/<runId>`. Environment variables `DROVR_*` remain unchanged (e.g., `DROVR_FAKE_SCRIPT`, `DROVR_E2E`). Spec markers use the historical `<!-- drovr:spec -->` comment. These names are pending formalization in a future shim spec; no action required — existing runs and configurations remain fully compatible.
-<!-- tickmarkr:compat-legacy END -->
-
-> The package ships `tickmarkr` and `tkr` only; `tkr` is the short alias.
-
-## Vocabulary
-
-Audit voice in docs and reports maps to engine concepts exactly once:
-
-| Audit term | Engine concept |
-|---|---|
-| Partner | Human operator |
-| Manager | Overseer |
-| tickmarkr | Orchestrator daemon |
-| field teams / staff | Workers (agent CLIs in worktrees) |
-| seniors | Watchers (status monitor, gate panes) |
-| engagement | Run (`tickmarkr run` / `resume`) |
-| assertion | Acceptance criterion (`acceptance[]` entry) |
-| tickmark | Passed gate |
-| audit evidence | Evidence gate (commits/diff exist) |
-| audit trail | Journal (engagement event ledger) |
-| the consolidation | Integration branch (`tickmarkr/<runId>`) |
-| sign-off / issuance | Merge consolidation branch to main |
-| unqualified opinion | Green engagement (all tasks merged) |
-| qualified opinion | Failed or stalled engagement |
-| EQR | Acceptance judge (LLM gate vs `acceptance[]`) |
-| National Office | Consult (frontier-model escalation on deadlock) |
-
-Commands below use the real CLI surface — audit terms never replace bin names in examples.
+tickmarkr is a spec-driven orchestration harness for AI coding agent CLIs. You write a spec with
+acceptance criteria; the engine routes tasks to the best installed agent CLI (claude-code, codex,
+cursor-agent, opencode, grok, pi) by cost and capability, dispatches work in isolated git worktrees
+— as interactive TUIs when running under [herdr](https://herdr.dev), headless subprocesses otherwise
+— and independently verifies every result before merge. Green tasks consolidate onto a
+`tickmarkr/<runId>` branch; merging to your mainline is always your call, never automated. Engage
+with full visibility into routing decisions, worker progress, and gate verdicts — or run headless
+and review the audit trail afterward.
 
 ## Invariants
 
 These are law; the codebase fails closed around them:
 
 - `acceptance[]` required on every task; compile fails without it
-- new engagements consolidate to a `tickmarkr/<runId>` branch — never main (resume of older
-  engagements keeps the branch names recorded in their journal)
+- new engagements consolidate to a `tickmarkr/<runId>` branch — never main
 - gates never trust worker claims; tickmarkr verifies everything itself
 - state is files + git only; no DB, no services
 - worker/judge/review/consult prompts end with machine-parseable trailers
@@ -91,17 +59,17 @@ at 30s.
 
 ```bash
 tickmarkr init                 # guided setup + doctor; scaffolds config and spec template
-# edit tickmarkr.spec.md        # the native spec template
-tickmarkr compile tickmarkr.spec.md # spec → engagement graph (fails without acceptance criteria)
-tickmarkr plan                 # dry-run routing table + cost estimate + floor lints
-tickmarkr run                  # execute the graph (--concurrency N --driver herdr|subprocess --route-strict)
+# edit tickmarkr.spec.md        # write your tasks and acceptance criteria
+tickmarkr compile tickmarkr.spec.md # spec → task graph (fails without acceptance criteria)
+tickmarkr plan                 # dry-run routing decisions + cost estimate
+tickmarkr run                  # execute, route to best CLI, gate every result (--concurrency N)
 tickmarkr report <runId> --md  # engagement record in Markdown
 ```
 
-That's the whole loop: `init` scaffolds, you write the spec's tasks and `acceptance[]`, `compile`
-turns it into a task graph, `plan` shows you the routing/cost dry run, `run` dispatches field teams
-and gates every result, and `report` writes the engagement record. Nothing merges to your mainline
-without your sign-off.
+That's the flow: `init` scaffolds config, you write tasks with `acceptance[]` criteria, `compile`
+validates and builds the graph, `plan` shows routing decisions and cost, `run` dispatches work to
+installed CLIs and independently verifies every result, and `report` documents the outcome. All
+green tasks land on `tickmarkr/<runId>` — merge to your mainline is your decision.
 
 ## Agent-ready repos: `tickmarkr init --agent`
 
@@ -126,33 +94,24 @@ Consent rules — every write is additive, never destructive:
 - non-interactive shells (no TTY) never prompt: missing skills are installed, everything else is
   skipped, and the summary names exactly what was skipped and which flag would enable it
 
-Supervise and finish:
+## Monitor and supervise
 
 ```bash
-tickmarkr status               # live engagement state (--watch to follow)
-tickmarkr resume <runId>       # continue an engagement from its audit trail
-tickmarkr approve <runId> <taskId>   # Partner sign-off on a parked task (--by <name> --reason <text>)
+tickmarkr status               # engagement state (--watch to follow live)
+tickmarkr resume <runId>       # continue an engagement from the audit trail
+tickmarkr approve <runId> <taskId>   # approve a parked task (--reason to document)
 tickmarkr report <runId>       # cost/quality report
 tickmarkr profile              # show the learned routing profile
-tickmarkr unlock               # remove a stale/garbage run lock (refuses if the holder is alive)
 ```
 
-Green tasks land on the engagement's `tickmarkr/<runId>` consolidation branch; sign-off to your
-mainline is your call, never tickmarkr's.
-
-### Escalation and National Office verdicts
-
-When gates or field teams stall, tickmarkr escalates to a frontier-model **National Office** consult
-for a structured verdict. The consult can recommend rerouting to a different adapter/model channel,
-or human approval if deadlock persists. Reroute verdicts can target two scopes:
+Green tasks land on `tickmarkr/<runId>`; merge to your mainline is always your call.
 
-- **Channel-level reroute**: exclude a single channel (e.g., `claude-code:opus-4-8`) and try the next ranked channel
-- **Adapter-level reroute**: exclude an entire adapter (e.g., `cursor-agent`) when the consult detects an environmental
-  CLI-level failure (blocked dialog, auth issue, timeout pattern). The daemon expands the task's exclusion list to cover
-  every available channel of that adapter, ensuring zero re-try of the same root cause
+### Escalation and consults
 
-Both exclusion types persist across resume — a task that failed due to a consult reroute will never re-try excluded channels
-or adapters in a subsequent `tickmarkr resume`.
+When gates or tasks stall, tickmarkr escalates to a frontier-model consult for a structured verdict.
+The consult can recommend rerouting (exclude a failed channel/adapter and try the next ranked option)
+or human approval if deadlock persists. Exclusions persist across resume — a task that escalated
+away from a failing adapter will never retry it in subsequent `tickmarkr resume` calls.
 
 ### Approving tasks
 
@@ -162,15 +121,9 @@ or adapters in a subsequent `tickmarkr resume`.
 - The task finished with a result but gates require human judgment (`humanGate: true` in the spec)
 - Approving records the Partner's verdict and the task proceeds to merge
 
-**Attempt-cap parks** (attempt budget exhausted):
+**Attempt-budget exhaustion**:
 - The task has burned its full attempt budget without reaching a conclusive result
-- All channels (including adapter exclusions from prior consults) remain excluded from retry
-- Approving grants a **fresh attempt budget** with the same exclusion list — the task re-routes around all previously-burned channels
-  and adapters, giving it one more escalation ladder before exhaustion
-
-Example: a task escalates away from cursor-agent due to a trust dialog (adapter-level exclusion), then away from all claude-code
-models before hitting the attempt cap. `tickmarkr approve` grants a fresh ladder to try the frontier tier, still avoiding both
-cursor-agent and claude-code entirely.
+- Approving grants a fresh attempt budget, routing around all previously-failed channels and adapters
 
 ## Model scoping and auth detection
 
@@ -178,8 +131,8 @@ Each agent CLI exposes a list of available models. tickmarkr's routing works onl
 
 **Model terminology**:
 
-- **Listed models**: All models a CLI advertises as available (e.g., pi advertises both `pi:glm-5.2` and `pi:anthropic-claude-opus-4-8`, but not all are authed)
-- **Scoped models**: Listed models with an explicit CLI namespace prefix (e.g., `pi:glm-5.2`, `openai:gpt-4o`). The design rule is to classify scoped models primarily, not unscoped listed models
+- **Listed models**: All models a CLI advertises as available (e.g., pi advertises both `zai/glm-5.2` and `anthropic/claude-opus-4-8`, but not all are authed)
+- **Scoped models**: Listed models with an explicit provider prefix (e.g., `zai/glm-5.2`, `zai-coding-plan/glm-5.2`). The design rule is to classify scoped models primarily, not unscoped listed models
 - **Classified models**: Models you've entered into `tiers` — the routing-eligible set, regardless of scope
 
 When you run `tickmarkr doctor`, it:
@@ -202,18 +155,17 @@ You can bench a classified model without removing it from tiers:
 routing:
   deny:
     models:
-      - pi:glm-5.2      # stays in tiers, never routes
-      - openai:gpt-4o   # reason in git commit
+      - pi:zai/glm-5.2            # stays in tiers, never routes (key is adapter:model)
+      - cursor-agent:composer-2.5 # reason in git commit
 ```
 `tickmarkr plan` lints denied models identically to unauthed ones. Re-enable by deleting one line.
 
-## Run output and narration
+## Run output and audit trail
 
-When you execute `tickmarkr run`, the daemon streams live narration of each audit-trail event to stdout — task status changes,
-gate results (tickmarks), worker dispatch, and merge commits. This narration is derived from the append-only event ledger,
-which remains the authoritative source of truth for resumability. If an engagement is interrupted, `tickmarkr resume <runId>`
-replays the ledger and picks up where it left off. You can also tail the ledger directly for raw event inspection or
-feed it to external tools; the narration is a convenience layer on top.
+When you execute `tickmarkr run`, the daemon records every event in an append-only ledger (the audit trail):
+task dispatch, gate verdicts, worker status, and merges. Narration streams to stdout; you can also
+`--watch` or tail the ledger directly. If interrupted, `tickmarkr resume <runId>` replays the ledger
+and continues from the last stable state — deterministic, not ephemeral.
 
 ## Usage and cost
 
@@ -243,9 +195,14 @@ and first-attempt success rate. Cost reporting follows strict honesty rules and
   comments and LiteLLM's JSON file named as the copy-from source; tickmarkr never calls home to fetch rates
 - **Attribution from journal**: token counts come from tickmarkr's own telemetry spans in the audit trail, never from provider invoices or dashboards
 
-## Visibility: supervised fleet UX
+## Visibility: optional supervised workspace
+
+When running under [herdr](https://herdr.dev), tickmarkr creates a labeled pane-and-tab workspace
+for real-time visibility (optional — omit `--driver herdr` or run headless if preferred).
 
-When running under [herdr](https://herdr.dev), tickmarkr creates a visible, labeled pane-and-tab workspace:
+tickmarkr borrows audit-firm vocabulary for its roles: **you** are the *Partner* (final sign-off),
+workers are the *field team*, the acceptance judge is the *EQR* (engagement quality reviewer), and
+the frontier-model consult is the *National Office*. The terms below use that vocabulary:
 
 ### Tab vocabulary
 
@@ -289,7 +246,7 @@ Every pane and tab tickmarkr creates receives a **parseable ownership name** enc
 - `watch` — status monitor pane
 - `<role> · <taskId> · A<attempt> · R<runId>` — judge, review, consult, and worker panes (formats like `judge · task-abc123 · A1 · Rrun-20260713-175532`)
 
-tickmarkr creates all owned panes only within the run's workspace; any tickmarkr-owned panes discovered outside the run's workspace (from prior runs or placement bugs) are reconciled and closed along with their emptied tabs. Any pane not matching the ownership contract is **foreign** — created by the operator or another tool — and is never a candidate for closing.
+tickmarkr creates all owned panes only within the run's workspace; any tickmarkr-owned panes discovered outside the run's workspace (from prior runs or placement bugs) are reconciled and closed. Any pane not matching the ownership contract is **foreign** — created by you or another tool — and is never closed automatically.
 
 **Desired-state reconciliation**: A pure function computes the exact set of panes that should exist from the audit trail at any moment:
 - Worker panes for all in-flight task attempts
@@ -305,138 +262,57 @@ The daemon reconciles at every safe point:
 
 Reconciliation failures (herdr unavailable, a pane vanished mid-sweep) never fail the engagement — visibility is cosmetic, gates are law.
 
-### Workspace-trust pre-flight
-
-tickmarkr runs field teams in fresh git worktrees cloned from your repo. Before dispatch, every worker checks whether that repo is trusted by its CLI, fail-closed:
-
-**Seeding trust at doctor time**:
-- `tickmarkr doctor` probes each adapter's trust status for your repo root
-- Adapters that can pre-seed trust (codex via `config.toml`, others if applicable) do so automatically; you see `seeded` in the doctor output
-- Adapters requiring manual trust grant show `action-required` with the exact one-time command to run (e.g., `codex init /path/to/repo`)
-- Adapters without a trust concept report `n/a`
-
-**Auto-answering trust dialogs during runs**:
-- Some CLIs (e.g., cursor-agent) cannot pre-seed trust and show an interactive "Workspace Trust Required" dialog the first time they touch the worktree
-- For these CLIs, tickmarkr detects the trust dialog by its fingerprint and auto-answers it exactly once per slot — safe because tickmarkr created the worktree from your own repo
-- Any other blocked dialog still pages the operator for manual approval
+### Workspace trust
 
-## Spec front-ends (what compiles today)
+tickmarkr runs work in fresh git worktrees cloned from your repo. Before dispatch, workers check
+whether the repo is trusted by their CLI:
 
-tickmarkr is SDD-agnostic downstream of `compile` — routing, gates, and merges never know which methodology
-produced the graph. Upstream, these front-ends exist:
+- `tickmarkr doctor` probes each CLI's trust status and auto-seeds trust where possible
+- Some CLIs show a "Workspace Trust" dialog; tickmarkr detects and auto-answers it once per task
+- Other blocked dialogs page you for manual approval
 
-| Spec source | Support | How |
-|---|---|---|
-| **tickmarkr spec** (native format) | Native/default | `tickmarkr init` template with native spec marker |
-| **Spec Kit** feature dir | Native | dir containing `tasks.md` |
-| **GSD** phase dir | Native | dir containing `*-PLAN.md` |
-| **Markdown PRD** | Native (universal adapter) | any `.md` with tasks + acceptance criteria |
-| OpenSpec, BMAD, Superpowers, others | Not yet | render to a tickmarkr spec (with full Task surface), or contribute a front-end: one parser module behind `src/compile/index.ts`, same pattern as `gsd.ts` |
+## Spec formats
 
-Compile fails loudly on anything it can't recognize (`--type native|speckit|prd|gsd` to force).
+tickmarkr compiles several formats into its internal task graph. The most common:
 
-## Planning layer: intent → spec → engagement
-
-tickmarkr pairs a lightweight planning step (`tickmarkr scope`) with the existing compile/run flow. The flow is:
-
-```
-intent file (prose)
-  ↓ [tickmarkr scope: 3-question gate]
-  ↓ [clarification ≤3 blocking Qs]
-native spec (REQ-nn → oracle → task)
-  ↓ [tickmarkr compile]
-  ↓ [fails without acceptance criteria]
-task graph + routing table
-  ↓ [tickmarkr run]
-  ↓ [gates never trust workers]
-merged green tasks + engagement record
-```
+| Format | Example |
+|---|---|
+| **tickmarkr native** (default) | `tickmarkr init` template with native spec marker |
+| **Markdown PRD** | Any `.md` file with task sections and `acceptance[]` criteria |
+| **Spec Kit** | A [Spec Kit](https://github.com/github/spec-kit) spec directory |
+| **GSD** | A GSD `.planning/` phase plan |
 
-**Clarification gate**: The `tickmarkr scope` CLI enforces ≤3 blocking questions. Drafting refuses until all are answered; residual uncertainty becomes explicit assumptions in the spec.
+Compile fails loudly if it cannot recognize the format or if `acceptance[]` is missing. Use
+`--type native|prd|speckit|gsd` to force a specific format.
 
-**Oracle types** — assertions are typed for deterministic verification:
+## Acceptance criteria (assertions)
 
-- `oracle: command <cmd>` — exit code (0 = pass); most reliable
-- `oracle: test <name>` — run a named test (must exist in the task's acceptance[] context)
-- `oracle: judge <rubric>` — EQR verdict, fail-closed, never overrides failed command/test
+Every task requires explicit `acceptance[]` criteria; compile fails without them. Three oracle types:
 
-Untyped acceptance strings in existing specs compile as `oracle: judge` + warning (read-old/write-new compat, same as the rename precedent).
+- **`command <cmd>`** — pass if exit code 0; most reliable
+- **`test <name>`** — run a named test from your suite (must exist)
+- **`judge <rubric>`** — LLM verdict against your rubric; fail-closed, never overrides failed command/test
 
-**Scope semantics**: Plan-time blast radius is advisory + structured `{paths, confidence, reason}` — never authoritative. The run-time scope gate verifies actual file changes; if a worker requests widening, the daemon pauses as a designed human gate for operator approval.
+At runtime, the **scope gate** verifies that workers only touched files declared in the spec. If a
+worker must change out-of-scope paths, the task pauses as a human gate — your approval is required.
 
-## Claude Code skills (ship with the repo)
+## Claude Code integration
 
-Cloning this repo gives Claude Code project skills under `.claude/skills/`:
+If you clone this repo and use Claude Code, project skills are installed in `.claude/skills/`:
 
-- **`/tickmarkr-loop`** — the SDD-agnostic loop: compile one spec, read the plan, run from the journal, merge green work, and commit only the Markdown execution record beside that spec. For GSD bookkeeping, use `/tickmarkr-auto`.
-- **`/tickmarkr-auto`** — the **GSD binding**: run remaining GSD milestone phases autonomously with tickmarkr as the
-  executor (plans → compile → dry-run → run → merge → sync-back). Bindings are per-SDD by nature — the
-  sync-back writes that methodology's artifacts; other SDDs need their own thin binding, not this one.
-- **`/tickmarkr-overseer`** — supervise an autonomous tickmarkr engagement from a Herdr workspace: two-tier visible hierarchy,
-  journal-based watchers, gate-failure triage, human-checkpoint routing. Requires `HERDR_ENV=1`.
+- **`/tickmarkr-loop`** — compile a spec, review the routing plan, run the engagement, and commit the Markdown record
+- **`/tickmarkr-auto`** — autonomous multi-phase runs (GSD milestones, etc.)
 
-Repo-scoped: available automatically in Claude Code sessions inside this repo; not installed by npm.
+These are optional — the CLI works standalone. Skills are repo-scoped and ship in the npm tarball for agents working in projects that have run `tickmarkr init --agent`.
 
 ## Contributing
 
-### Dev setup
-
-```bash
-git clone <your fork>
-cd tickmarkr
-npm install
-npm run build   # tsc → dist/; the only enforced static check
-npm link        # exposes the tickmarkr/tkr bins from your checkout
-```
-
-### Tests are zero-token by design
-
-```bash
-npm test               # vitest unit+integration — fake adapter only, spends no tokens, ever
-npm run test:coverage  # same suite, coverage floors enforced (see below)
-npm run e2e            # opt-in real-CLI end-to-end — DOES spend tokens, needs ≥1 agent CLI installed
-```
-
-`npm test` and `npm run test:coverage` must never call a real agent CLI or spend tokens —
-test isolation uses deterministic fixtures. If a change needs a real CLI to verify, that test
-belongs under `npm run e2e` (`tests/e2e/`), an opt-in test suite not run in CI.
-
-Coverage floor: `src/{graph,route,gates,run}/**` must stay at lines 80% / functions 80% /
-branches 70% — this is the CLAUDE.md invariant, enforced verbatim in `vitest.config.ts`.
-`src/compile/**`, `src/adapters/**`, and `src/drivers/**` carry their own (higher) measured
-thresholds in the same file.
-
-### The spec-driven workflow — the gates are the review
-
-Changes to tickmarkr itself land the same way tickmarkr expects consumer changes to land: write a
-native spec (`specs/<version>-<name>.spec.md`, marked `<!-- tickmarkr:spec -->`), give every task
-real `acceptance[]` criteria, then compile/plan/run it and let the gates (baseline, evidence, scope,
-acceptance-judge, cross-vendor review) independently verify the diff before it merges. PRs are
-welcome, but a PR that only "looks right" isn't the bar — a green, gated engagement is. If you're
-proposing a non-trivial change, sketch it as a spec first; small fixes and docs can go straight to
-a PR.
-
-### Adding a worker adapter
-
-Support for a new agent CLI is one new file implementing `WorkerAdapter`
-(`src/adapters/types.ts`) — `id`, `vendor`, `probe()`, `channels()`, `headlessCommand()`,
-`interactiveCommand()`, `invoke()`, `parse()`, plus the optional `listModels`/`resumeCommand`
-capabilities other adapters use when the CLI supports them. Use an existing adapter as the
-template (`src/adapters/codex.ts` is a good starting shape), then register it with one line in
-`src/adapters/registry.ts`'s `allAdapters()` — append it, don't insert it in the middle, since
-same-tier routing ties resolve by discovery order. No other file needs to know a new adapter
-exists.
-
-### Filing defects
-
-Abnormalities found during a real engagement (not routine bugs — surprising or systemic
-behavior) are logged as a numbered entry (`OBS-NN`) in `.planning/OBSERVATIONS.md`, with a status
-(`OPEN` / `CLOSED-FIXED` / `CLOSED-MITIGATED`) and, once fixed, the spec/commit that closed it.
-That file is the standing abnormality ledger for this repo — read it before assuming a rough edge
-is new.
-
-See the design spec in docs/superpowers/specs/.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, the green bar (build/test/lint), and 
+design invariants. Pull requests welcome; non-trivial changes should include test coverage.
 
-## License
+## Documentation
 
-MIT
+- **[LICENSE](LICENSE)** — MIT license
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — development setup and contribution guidelines
+- **[SECURITY.md](SECURITY.md)** — security policy and private vulnerability reporting
+- **[CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)** — Contributor Covenant

package/dist/adapters/claude-code.js

@@ -6,7 +6,7 @@ import { parseWorkerResult } from "./prompt.js";
 import { channelsFromConfig, shq, TokenUsageSchema } from "./types.js";
 // SPEND-01/SPEND-11: claude writes a per-session JSONL to ~/.claude/projects/<slug>/ where slug is the
 // realpath'd cwd with every non-alphanumeric char replaced by "-" (verified 114/114 — 36-DIAGNOSIS.md).
-// The old `/`-only formula missed the "." in `.drovr/worktrees/…` — ENOENT on every worktree dispatch.
+// The old `/`-only formula missed the "." in `.tickmarkr/worktrees/…` — ENOENT on every worktree dispatch.
 // Each assistant message carries a per-record ISO `timestamp` and message.usage. We read it POST-HOC
 // (never the pane, never the trailer) and sum
 // tokens for records whose top-level cwd matches this task's worktree AND whose timestamp is at/after
@@ -43,9 +43,9 @@ export const claudeCode = {
     channels: (cfg) => channelsFromConfig("claude-code", cfg),
     // --strict-mcp-config --mcp-config '{"mcpServers":{}}': pin the MCP surface to empty so fresh-worktree
     // workers/gates don't load project .mcp.json servers (herdr scrapes dialogs as idle — v1.4 incident,
-    // memory drovr-worker-mcp-dialog-stall). Live-verified 2026-07-10 on claude 2.1.205 (operator check):
+    // memory tickmarkr-worker-mcp-dialog-stall). Live-verified 2026-07-10 on claude 2.1.205 (operator check):
     // headless (-p) fully suppressed — exit 0, no dialog. Interactive TUI STILL shows the project
-    // MCP-enable dialog (project trust/enablement, not config loading); Esc dismisses it, and drovr's
+    // MCP-enable dialog (project trust/enablement, not config loading); Esc dismisses it, and tickmarkr's
     // blocked/idle paging surfaces the pane to the operator (same path as cursor's trust dialog).
     // Gotchas (both bit the 2026-07-10 live check): bare '{}' is REJECTED ("mcpServers: expected record"),
     // and --mcp-config is VARIADIC — a positional after it is eaten as a config-file path, so another
@@ -53,7 +53,7 @@ export const claudeCode = {
     headlessCommand: (promptFile, model) => `claude -p "$(cat ${shq(promptFile)})" --model ${shq(model)} --permission-mode bypassPermissions --strict-mcp-config --mcp-config '{"mcpServers":{}}' --output-format text`,
     // HYG-03: the residual first-entry dialog on an interactive TUI is the workspace TRUST dialog (not MCP
     // config loading) — CLI-imposed, no flag to pre-accept, only store is claude's global last-writer-wins
-    // ~/.claude.json keyed on the exact path. Closed WON'T-FIX (decision B, 2026-07-10): drovr writes nothing
+    // ~/.claude.json keyed on the exact path. Closed WON'T-FIX (decision B, 2026-07-10): tickmarkr writes nothing
     // to that file (a seed races claude's own writes, nondeterministically). Amortizes to one operator dismissal
     // per stable worktree path; blocked-pane paging surfaces it. Do NOT change this command to "fix" the dialog —
     // see .planning/REQUIREMENTS.md HYG-03 and 21-02-LIVE-CHECK.md. Revisit if upstream ships a --trust flag.

package/dist/adapters/codex.js

@@ -75,7 +75,7 @@ export function readCodexModelsCache(path) {
         return { models: [] };
     }
 }
-// drovr worktrees keep their gitdir under the MAIN repo's .git/worktrees/<name> — outside the
+// tickmarkr worktrees keep their gitdir under the MAIN repo's .git/worktrees/<name> — outside the
 // workspace-write sandbox root — so git commit dies on index.lock (incident run-20260709-104447
 // P87-08: "Unable to create …/.git/worktrees/…/index.lock"). Expanded by the pane shell at the
 // worktree cwd; in a plain repo it resolves to ./.git (already writable, harmless).

package/dist/adapters/fake.d.ts

@@ -1,4 +1,4 @@
-import type { DrovrConfig } from "../config/config.js";
+import type { TickmarkrConfig } from "../config/config.js";
 import type { Task } from "../graph/schema.js";
 import { type Assignment, type AuthHealth, type BillingChannel, type ContextUsage, type Invocation, type SessionRef, type TokenUsage, type WorkerAdapter, type WorkerResult } from "./types.js";
 export interface FakeScript {
@@ -29,7 +29,7 @@ export declare class FakeAdapter implements WorkerAdapter {
     private attempts;
     constructor(scriptPath: string);
     probe(): Promise<AuthHealth>;
-    channels(_cfg: DrovrConfig): BillingChannel[];
+    channels(_cfg: TickmarkrConfig): BillingChannel[];
     private judgeIdx;
     headlessCommand(promptFile: string, _model: string): string;
     resumeCommand(_sessionId: string, promptFile: string, model: string): string;

package/dist/adapters/fake.js

@@ -22,14 +22,14 @@ export class FakeAdapter {
             { adapter: "fake", vendor: "fake-b", model: "fake-2", channel: "api", tier: "frontier" },
         ];
     }
-    judgeIdx = 0; // Phase 47: per-instance judge verdict cursor — advances only on DROVR-JUDGE prompts
+    judgeIdx = 0; // Phase 47: per-instance judge verdict cursor — advances only on TICKMARKR-JUDGE prompts
     headlessCommand(promptFile, _model) {
         // Phase 47 (GATE-09): detect role at COMMAND-BUILD time. runHeadless/runViaDriver write the prompt
         // file BEFORE calling headlessCommand, so it exists here. The counter advances ONLY when the prompt
-        // contains DROVR-JUDGE — a review/consult prompt never touches it (research Pitfall 3).
+        // contains TICKMARKR-JUDGE — a review/consult prompt never touches it (research Pitfall 3).
         let isJudge = false;
         try {
-            isJudge = /DROVR-JUDGE/.test(readFileSync(promptFile, "utf8"));
+            isJudge = /TICKMARKR-JUDGE/.test(readFileSync(promptFile, "utf8"));
         }
         catch {
             // unreadable promptFile: can't detect role; serve static values (legacy headless-call behavior)
@@ -45,7 +45,7 @@ export class FakeAdapter {
             writeFileSync(p, JSON.stringify(val ?? {}, null, 1));
             return p;
         };
-        return `bash -c 'grep -q DROVR-JUDGE ${shq(promptFile)} && cat ${shq(serve("judge"))}; grep -q DROVR-REVIEW ${shq(promptFile)} && cat ${shq(serve("review"))}; grep -q DROVR-CONSULT ${shq(promptFile)} && cat ${shq(serve("consult"))}; true'`;
+        return `bash -c 'grep -q TICKMARKR-JUDGE ${shq(promptFile)} && cat ${shq(serve("judge"))}; grep -q TICKMARKR-REVIEW ${shq(promptFile)} && cat ${shq(serve("review"))}; grep -q TICKMARKR-CONSULT ${shq(promptFile)} && cat ${shq(serve("consult"))}; true'`;
     }
     resumeCommand(_sessionId, promptFile, model) {
         return this.interactiveCommand(promptFile, model) ?? this.headlessCommand(promptFile, model);
@@ -61,11 +61,11 @@ export class FakeAdapter {
         // no ms clock) so the record lands at/after this attempt's dispatch and clears the sinceMs cursor.
         // Written AFTER the step's `git add`/commit ⇒ stays untracked ⇒ invisible to the scope/evidence gates.
         const usageWrite = step.usage
-            ? `; node -e ${shq(`require("fs").writeFileSync(".drovr-usage.json", JSON.stringify({timestamp:new Date().toISOString(), usage:${JSON.stringify(step.usage)}}))`)}`
+            ? `; node -e ${shq(`require("fs").writeFileSync(".tickmarkr-usage.json", JSON.stringify({timestamp:new Date().toISOString(), usage:${JSON.stringify(step.usage)}}))`)}`
             : "";
         const base = !step.result
             ? `bash -c ${shq(step.shell)}` // no trailer: scripted stall/quota
-            : `bash -c ${shq(step.shell)}; echo ${shq(`DROVR_RESULT_${nonce} ` + JSON.stringify({ deviations: [], ...step.result }))}`;
+            : `bash -c ${shq(step.shell)}; echo ${shq(`TICKMARKR_RESULT_${nonce} ` + JSON.stringify({ deviations: [], ...step.result }))}`;
         return base + usageWrite;
     }
     // SPEND-01: read the cwd-keyed usage record from DISK (never a pane), honoring the attempt cursor.
@@ -73,7 +73,7 @@ export class FakeAdapter {
     // undefined ⇒ unmetered — never 0, never a thrown error that could fail a healthy task.
     collectUsage(cwd, sinceMs) {
         try {
-            const rec = JSON.parse(readFileSync(join(cwd, ".drovr-usage.json"), "utf8"));
+            const rec = JSON.parse(readFileSync(join(cwd, ".tickmarkr-usage.json"), "utf8"));
             const ts = Date.parse(rec?.timestamp);
             if (!Number.isFinite(ts) || ts < sinceMs)
                 return undefined; // cursor honored, fail-open
@@ -93,7 +93,7 @@ export class FakeAdapter {
     // parseWorkerResult(output, nonce) succeeds exactly as before the nonce existed
     nonceFor(promptFile) {
         try {
-            return /DROVR_RESULT_([0-9a-z]+)/.exec(readFileSync(promptFile, "utf8"))?.[1] ?? "";
+            return /TICKMARKR_RESULT_([0-9a-z]+)/.exec(readFileSync(promptFile, "utf8"))?.[1] ?? "";
         }
         catch {
             return "";

package/dist/adapters/grok.js

@@ -19,11 +19,11 @@ import { channelsFromConfig, MODEL_ID_RE, shq } from "./types.js";
 // (4) `grok trace <id> --local` export and ~/.grok/logs/unified.jsonl (1,447 lines) — zero counters.
 // (5) --debug-file traces DO carry real per-turn input_tokens=… output_tokens=… cache_read_tokens=…
 //     — a REAL source, REJECTED for stated reasons:
-//     (a) it exists ONLY because drovr would inject --debug-file into every dispatch — a side-channel
-//         drovr creates, not a record the CLI keeps (same class as cursor's rejected --print --trust
+//     (a) it exists ONLY because tickmarkr would inject --debug-file into every dispatch — a side-channel
+//         tickmarkr creates, not a record the CLI keeps (same class as cursor's rejected --print --trust
 //         stdout tee, cursor-agent.ts:25-28);
 //     (b) DECISIVE: at DEBUG level the log verbatim-dumps the full OIDC bearer JWT and every MCP server
-//         env secret — an actual plaintext SUPABASE_ACCESS_TOKEN was observed — drovr forcing a
+//         env secret — an actual plaintext SUPABASE_ACCESS_TOKEN was observed — tickmarkr forcing a
 //         per-attempt secret-spilling file onto disk to meter a sub channel fails its own security
 //         posture;
 //     (c) it is tracing diagnostics text with no format contract (xAI can reshape it in any patch).
@@ -102,11 +102,11 @@ export const grok = {
     // 2026-07-11 (40-RESEARCH F-3): trailer intact + unwrapped, exit 0. "$(cat file)" matches every
     // other adapter and is already quoting-proven. --permission-mode bypassPermissions is the
     // autonomous-worker analog of claude's --dangerously-skip-permissions. NEVER pass grok's
-    // -w/--worktree flag — grok manages its OWN worktrees; a nested worktree inside drovr's worktree
+    // -w/--worktree flag — grok manages its OWN worktrees; a nested worktree inside tickmarkr's worktree
     // is scope-gate chaos (src/run/git.ts owns worktrees).
     headlessCommand: (promptFile, model) => `grok -p "$(cat ${shq(promptFile)})" --model ${shq(model)} --permission-mode bypassPermissions --output-format plain`,
     // GROK-02 interactive. Positional prompt seeds the TUI (40-CONTEXT D-01). Same permission flag;
-    // NEVER the -w/--worktree flag (see headless comment above — drovr owns worktrees).
+    // NEVER the -w/--worktree flag (see headless comment above — tickmarkr owns worktrees).
     interactiveCommand: (promptFile, model) => `grok --model ${shq(model)} --permission-mode bypassPermissions "$(cat ${shq(promptFile)})"`,
     invoke(task, _cwd, a, ctx) {
         return { command: this.headlessCommand(ctx.promptFile, a.model) };

package/dist/adapters/model-lints.d.ts

@@ -1,10 +1,10 @@
-import { type DrovrConfig } from "../config/config.js";
+import { type TickmarkrConfig } from "../config/config.js";
 import { type AuthHealth, type WorkerAdapter } from "./types.js";
 export declare const SEED_STAMPED = "2026-07-09";
 export declare const MODEL_STALE_DAYS = 30;
 export declare const ttyVisual: () => boolean;
-export declare function seedPreferLints(cfg: DrovrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], overlayPreferShapes?: ReadonlySet<string>): string[];
-export declare function modelLints(cfg: DrovrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], opts?: {
+export declare function seedPreferLints(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], overlayPreferShapes?: ReadonlySet<string>): string[];
+export declare function modelLints(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], opts?: {
     tty?: boolean;
     stateDir?: string;
     overlayPreferShapes?: ReadonlySet<string>;
@@ -14,4 +14,4 @@ export declare function formatModelAuthLine(excluded: {
     reason: string;
     probedAt: string;
 }[], tty?: boolean, stateDir?: string): string;
-export declare function suggestOverlay(cfg: DrovrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], stateDir?: string): string;
+export declare function suggestOverlay(cfg: TickmarkrConfig, health: Record<string, AuthHealth>, adapters: WorkerAdapter[], stateDir?: string): string;

package/dist/adapters/model-lints.js

@@ -11,7 +11,7 @@ const DAY_MS = 86400000;
 const LINT_VARIANT_RE = /^auto$|-(fast|minimal|low|medium|high|xhigh)$/;
 const LINT_CAP = 5;
 const TTY_LINT_CAP = 3;
-const DEFAULT_STATE_DIR = ".drovr";
+const DEFAULT_STATE_DIR = ".tickmarkr";
 const doctorJsonRef = (stateDir) => ` — see ${stateDir}/doctor.json`;
 export const ttyVisual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
 const adapterHasAuthedChannel = (adapterId, shape, cfg, health, adapters) => {