tickmarkr 1.35.0 → 1.37.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,49 +1,22 @@
+<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 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.
 
 <!-- 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.
+**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`). New specs use the `<!-- tickmarkr:spec -->` marker; the historical `<!-- drovr:spec -->` marker is still accepted. 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.
-
 ## Invariants
 
 These are law; the codebase fails closed around them:
@@ -91,17 +64,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 +99,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
+Green tasks land on `tickmarkr/<runId>`; merge to your mainline is always your call.
 
-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:
+### Escalation and consults
 
-- **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
-
-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 +126,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 +136,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 +160,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 +200,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 visible, labeled pane-and-tab 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).
+
+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 +251,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 +267,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

@@ -38,6 +38,7 @@ export function probeVersion(bin) {
 export const claudeCode = {
     id: "claude-code",
     vendor: "anthropic",
+    probeCwd: "neutral",
     probe: async () => probeVersion("claude"),
     channels: (cfg) => channelsFromConfig("claude-code", cfg),
     // --strict-mcp-config --mcp-config '{"mcpServers":{}}': pin the MCP surface to empty so fresh-worktree

package/dist/adapters/grok.js

@@ -83,6 +83,7 @@ export const grok = {
     // FLEET-04 cross-vendor honesty: xai is diversity-distinct from anthropic/openai/cursor/zhipu.
     // MUST equal tiers.grok.vendor (a test pins the equality).
     vendor: "xai",
+    probeCwd: "neutral",
     probe: async () => {
         const h = probeVersion("grok");
         if (!h.installed)

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

@@ -1,11 +1,13 @@
-import type { DrovrConfig } from "../config/config.js";
+import { type DrovrConfig } 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?: {
     tty?: boolean;
     stateDir?: string;
+    overlayPreferShapes?: ReadonlySet<string>;
 }): string[];
 export declare function formatModelAuthLine(excluded: {
     key: string;

package/dist/adapters/model-lints.js

@@ -1,3 +1,4 @@
+import { DEFAULT_CONFIG, TIER_RANK } from "../config/config.js";
 import { MODEL_ID_RE } from "./types.js";
 // date the tiers seeds were last live-verified (Phase 6/7 reseed) — surfaced when an adapter has no list surface.
 export const SEED_STAMPED = "2026-07-09";
@@ -13,6 +14,34 @@ const TTY_LINT_CAP = 3;
 const DEFAULT_STATE_DIR = ".drovr";
 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) => {
+    const entry = cfg.routing.map[shape];
+    const minTier = entry?.tier ?? cfg.routing.floors[shape] ?? "cheap";
+    const a = adapters.find((x) => x.id === adapterId);
+    const h = health[adapterId];
+    if (!a || !h?.installed || typeof a.channels !== "function")
+        return false;
+    if (!h.modelAuth || !Object.keys(h.modelAuth).length)
+        return true; // no per-model probe data — compat, not dead
+    return a.channels(cfg).some((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier] && h.modelAuth?.[c.model]?.authed === true);
+};
+// OBS-30 T2: warn when a built-in seed prefer names an adapter with zero authed channels this probe pass.
+export function seedPreferLints(cfg, health, adapters, overlayPreferShapes = new Set()) {
+    const lints = [];
+    for (const shape of Object.keys(cfg.routing.map)) {
+        if (overlayPreferShapes.has(shape))
+            continue;
+        for (const p of DEFAULT_CONFIG.routing.map[shape]?.prefer ?? []) {
+            const adapterId = p.includes(":") ? p.slice(0, p.indexOf(":")) : p;
+            if (!cfg.tiers[adapterId])
+                continue;
+            if (!adapterHasAuthedChannel(adapterId, shape, cfg, health, adapters)) {
+                lints.push(`routing seed names dead adapter '${adapterId}' for shape '${shape}' — auto-prefer is routing around it`);
+            }
+        }
+    }
+    return lints;
+}
 // Diffs detected models (doctor.json) against configured tiers, both directions, per adapter id in cfg.tiers.
 // No `  ! ` prefix here — the consumer (doctor rows / plan lints) owns that. Pre-v1.5 doctor.json (models:[], no
 // modelsDetectedAt) is the compat baseline: `?.`/`?? []` everywhere, no zod (would reject old files).
@@ -54,6 +83,7 @@ export function modelLints(cfg, health, adapters, opts) {
                 lints.push(`${id}: model knowledge is ${days} days old — rerun tickmarkr doctor`);
         }
     }
+    lints.push(...seedPreferLints(cfg, health, adapters, opts?.overlayPreferShapes));
     return lints;
 }
 // T2/T6: one lint per exclusion, naming the probe reason and date. TTY truncates reasons to 60 chars and

package/dist/adapters/opencode.js

@@ -16,6 +16,7 @@ export function parseOpencodeModels(raw) {
 export const opencode = {
     id: "opencode",
     vendor: "mixed",
+    probeCwd: "neutral",
     probe: async () => probeVersion("opencode"),
     channels: (cfg) => channelsFromConfig("opencode", cfg),
     headlessCommand: (promptFile, model) => `opencode run -m ${shq(model)} "$(cat ${shq(promptFile)})"`,

package/dist/adapters/pi.js

@@ -37,6 +37,7 @@ export const pi = {
     // FLEET-04: cross-vendor review honesty — GLM's provider (pi's own label is "zai"; either is
     // diversity-distinct from anthropic/openai/cursor/mixed). Must equal tiers.pi.vendor.
     vendor: "zhipu",
+    probeCwd: "neutral",
     probe: async () => {
         const h = probeVersion("pi");
         if (!h.installed)

package/dist/adapters/registry.d.ts

@@ -1,4 +1,5 @@
-import type { DrovrConfig } from "../config/config.js";
+import { type DrovrConfig } from "../config/config.js";
+import { type RoutingProfile } from "../route/profile.js";
 import { type AuthHealth, type BillingChannel, type WorkerAdapter } from "./types.js";
 export declare function allAdapters(opts?: {
     fakeScriptPath?: string;
@@ -7,6 +8,21 @@ export declare function getAdapter(id: string, adapters: WorkerAdapter[]): Worke
 export declare function probeAll(adapters: WorkerAdapter[]): Promise<Record<string, AuthHealth>>;
 export type ProbeModelStatus = "ok" | "timeout" | "failed";
 export type ProbeModelProgress = (adapter: string, model: string, status: ProbeModelStatus, durationMs: number) => void;
+export interface AutoPreferDoc {
+    derivedAt: string;
+    [shape: string]: string[] | string;
+}
+export declare const pendingAutoPreferKey: unique symbol;
+export declare const DOCTOR_ROUTING_STALE_MS: number;
+export declare function deriveAutoPrefer(cfg: DrovrConfig, adapters: WorkerAdapter[], health: Record<string, AuthHealth>, profile?: RoutingProfile): AutoPreferDoc;
+export declare function readAutoPrefer(repoRoot: string): AutoPreferDoc | null;
+export declare function routingPreferContext(repoRoot: string, cfg: DrovrConfig, opts?: {
+    globalDir?: string;
+}): {
+    autoPrefer?: AutoPreferDoc;
+    doctorFresh: boolean;
+    overlayPreferShapes: ReadonlySet<string>;
+};
 export declare function probeModels(cfg: DrovrConfig, repoRoot: string, adapters: WorkerAdapter[], health: Record<string, AuthHealth>, onProgress?: ProbeModelProgress): Promise<void>;
 export declare function writeDoctor(repoRoot: string, health: Record<string, AuthHealth>): void;
 export declare function readDoctor(repoRoot: string): Record<string, AuthHealth> | null;

package/dist/adapters/registry.js

@@ -1,10 +1,13 @@
 import { existsSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { overlayPreferShapes, TIER_RANK } from "../config/config.js";
 import { modelLints, suggestOverlay } from "./model-lints.js";
 import { HerdrDriver } from "../drivers/herdr.js";
 import { drovrDir, stateDirName } from "../graph/graph.js";
 import { disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../route/preference.js";
+import { learnedScore } from "../route/profile.js";
+import { marginalCostRank } from "../route/router.js";
 import { sh } from "../run/git.js";
 import { claudeCode } from "./claude-code.js";
 import { codex } from "./codex.js";
@@ -47,6 +50,57 @@ function probeFailure(code, stdout, stderr, timedOut, timeoutMs = MODEL_PROBE_TI
         ? output.slice(0, 240) || `probe exited ${code}`
         : undefined;
 }
+export const pendingAutoPreferKey = Symbol.for("tickmarkr.pendingAutoPrefer");
+const median = (xs) => {
+    const s = [...xs].sort((a, b) => a - b);
+    const m = Math.floor(s.length / 2);
+    return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+};
+// ponytail: 24h TTL matches plan.ts staleness — promote to config when an operator asks.
+export const DOCTOR_ROUTING_STALE_MS = 24 * 60 * 60 * 1000;
+export function deriveAutoPrefer(cfg, adapters, health, profile) {
+    const derivedAt = new Date().toISOString();
+    const out = { derivedAt };
+    for (const [shape, entry] of Object.entries(cfg.routing.map)) {
+        const minTier = entry?.tier ?? cfg.routing.floors[shape] ?? "cheap";
+        const ranked = [];
+        for (const a of adapters) {
+            const h = health[a.id];
+            if (!h?.installed || !h?.authed || typeof a.channels !== "function")
+                continue;
+            const qualifying = a.channels(cfg).filter((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier] && h.modelAuth?.[c.model]?.authed === true);
+            if (!qualifying.length)
+                continue;
+            const durations = qualifying
+                .map((c) => h.modelAuth?.[c.model]?.durationMs)
+                .filter((d) => typeof d === "number");
+            ranked.push({
+                adapter: a.id,
+                mc: Math.min(...qualifying.map(marginalCostRank)),
+                dur: durations.length ? median(durations) : Number.POSITIVE_INFINITY,
+                learned: profile ? Math.max(...qualifying.map((c) => learnedScore(profile, shape, channelKey(c), c.channel))) : 0,
+            });
+        }
+        ranked.sort((a, b) => a.mc - b.mc || a.dur - b.dur || b.learned - a.learned);
+        out[shape] = ranked.map((r) => r.adapter);
+    }
+    return out;
+}
+export function readAutoPrefer(repoRoot) {
+    const raw = readDoctorFile(repoRoot);
+    if (!raw || typeof raw.autoPrefer !== "object" || raw.autoPrefer === null)
+        return null;
+    return raw.autoPrefer;
+}
+export function routingPreferContext(repoRoot, cfg, opts = {}) {
+    const age = doctorAgeMs(repoRoot);
+    const doctorFresh = age !== null && age <= DOCTOR_ROUTING_STALE_MS;
+    return {
+        autoPrefer: doctorFresh ? readAutoPrefer(repoRoot) ?? undefined : undefined,
+        doctorFresh,
+        overlayPreferShapes: overlayPreferShapes(repoRoot, opts),
+    };
+}
 const probeModelStatus = (v) => v.authed ? "ok" : v.reason?.includes("timed out") ? "timeout" : "failed";
 // v1.21: one bounded, headless call per configured model; detected-but-unclassified models never enter this loop.
 export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
@@ -62,6 +116,7 @@ export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
             return;
         const verdicts = {};
         const priorModelAuth = priorHealth?.[a.id]?.modelAuth;
+        const probeRoot = a.probeCwd === "neutral" ? mkdtempSync(join(tmpdir(), "tickmarkr-probe-")) : repoRoot;
         // models probe concurrently too (v1.33.5) — sequential chains made init wall time Σ(models×60s)
         // on the slowest adapter (measured 96s); each probe is one tiny prompt, safe to overlap.
         // Capped at MODEL_PROBE_CONCURRENCY per adapter (v1.33.5 regression: 4 concurrent codex exec
@@ -78,12 +133,12 @@ export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
                 else {
                     const promptFile = join(mkdtempSync(join(tmpdir(), "drovr-auth-")), "probe.md");
                     writeFileSync(promptFile, MODEL_PROBE_PROMPT);
-                    const r = await sh(a.headlessCommand(promptFile, model), repoRoot, MODEL_PROBE_TIMEOUT_MS);
+                    const r = await sh(a.headlessCommand(promptFile, model), probeRoot, MODEL_PROBE_TIMEOUT_MS);
                     if (r.timedOut && priorTimedOut) {
                         verdict = { authed: false, reason: `probe timed out (repeat — retry skipped) (${MODEL_PROBE_TIMEOUT_MS}ms)`, probedAt, durationMs: Date.now() - t0 };
                     }
                     else if (r.timedOut) {
-                        const r2 = await sh(a.headlessCommand(promptFile, model), repoRoot, MODEL_PROBE_TIMEOUT_MS);
+                        const r2 = await sh(a.headlessCommand(promptFile, model), probeRoot, MODEL_PROBE_TIMEOUT_MS);
                         if (r2.timedOut) {
                             verdict = { authed: false, reason: `probe timed out twice (${MODEL_PROBE_TIMEOUT_MS}ms)`, probedAt, durationMs: Date.now() - t0 };
                         }
@@ -106,6 +161,7 @@ export async function probeModels(cfg, repoRoot, adapters, health, onProgress) {
         });
         h.modelAuth = verdicts;
     }));
+    health[pendingAutoPreferKey] = deriveAutoPrefer(cfg, adapters, health);
 }
 // T2: caps concurrent probes per adapter at 2 — v1.33.5 regression, 4 concurrent codex exec in one
 // repo made ALL 4 time out where sequential passed 2/4 (suspected CLI self-contention).
@@ -121,12 +177,24 @@ async function mapLimit(items, limit, fn) {
     await Promise.all(workers);
 }
 const doctorPath = (repoRoot) => join(repoRoot, stateDirName(repoRoot), "doctor.json");
+function readDoctorFile(repoRoot) {
+    return existsSync(doctorPath(repoRoot)) ? JSON.parse(readFileSync(doctorPath(repoRoot), "utf8")) : null;
+}
 export function writeDoctor(repoRoot, health) {
     drovrDir(repoRoot);
-    writeFileSync(doctorPath(repoRoot), JSON.stringify(health, null, 2) + "\n");
+    const pending = health[pendingAutoPreferKey];
+    const payload = { ...health };
+    delete payload[pendingAutoPreferKey];
+    if (pending)
+        payload.autoPrefer = pending;
+    writeFileSync(doctorPath(repoRoot), JSON.stringify(payload, null, 2) + "\n");
 }
 export function readDoctor(repoRoot) {
-    return existsSync(doctorPath(repoRoot)) ? JSON.parse(readFileSync(doctorPath(repoRoot), "utf8")) : null;
+    const raw = readDoctorFile(repoRoot);
+    if (!raw)
+        return null;
+    const { autoPrefer: _, ...health } = raw;
+    return health;
 }
 export function discoverChannels(cfg, adapters, health) {
     const base = adapters

package/dist/adapters/types.d.ts

@@ -72,6 +72,7 @@ export declare function matchesTrustDialog(paneText: string, dialog: TrustDialog
 export interface WorkerAdapter {
     id: string;
     vendor: string;
+    probeCwd?: "repo" | "neutral";
     probe(): Promise<AuthHealth>;
     channels(cfg: DrovrConfig): BillingChannel[];
     headlessCommand(promptFile: string, model: string): string;

package/dist/adapters/types.js

@@ -53,4 +53,4 @@ export const QUOTA_RE = /rate.?limit|quota|usage limit|out of credits|insufficie
 // operator-facing lint text and persisted to doctor.json — defense-in-depth for MODEL-05 (config
 // suggestions that could reach a shell). Covers observed ids incl. zai-coding-plan/glm-5.2,
 // gpt-5.6-sol, composer-2.5, gpt-5.3-codex; non-conforming (ANSI/control/shell-metachar) ids dropped.
-export const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._/:\[\]=,-]*$/;
+export const MODEL_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._/:[\]=,-]*$/;

package/dist/cli/commands/doctor.js

@@ -1,9 +1,9 @@
 import { writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { allAdapters, probeAll, probeModels, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
+import { allAdapters, probeAll, probeModels, readAutoPrefer, servableExclusions, servabilityLine, writeDoctor } from "../../adapters/registry.js";
 import { drovrDir, stateDirName } from "../../graph/graph.js";
 import { modelLints, suggestOverlay, ttyVisual } from "../../adapters/model-lints.js";
-import { loadConfig } from "../../config/config.js";
+import { DEFAULT_CONFIG, loadConfig, overlayPreferShapes } from "../../config/config.js";
 import { HerdrDriver } from "../../drivers/herdr.js";
 import { disallowedBy, excludedChannels, exclusionLine, preferRanks } from "../../route/preference.js";
 // same gate + palette as status's audit-ledger frame: styled only on a real TTY, plain otherwise
@@ -91,7 +91,7 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             rows.push(`  ! ${role} runs on ${sel.adapter}:${sel.model} — NOT installed; that gate will fail closed until you install it or remap cfg.${role}`);
         }
     }
-    rows.push(...modelLints(cfg, health, adapters, { tty: ttyVisual(), stateDir: stateDirName(cwd) }).map((l) => `  ! ${l}`));
+    rows.push(...modelLints(cfg, health, adapters, { tty: ttyVisual(), stateDir: stateDirName(cwd), overlayPreferShapes: overlayPreferShapes(cwd) }).map((l) => `  ! ${l}`));
     const excluded = excludedChannels(cfg, adapters, health);
     if (excluded.length)
         rows.push(`  ! ${exclusionLine(excluded)}`);
@@ -143,6 +143,20 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
             rows.push(`    (${unclassified.length} more listed, unclassified)`);
         return rows;
     });
-    const modelSummary = modelStatus.length ? `\nmodel status:\n${modelStatus.join("\n")}` : "";
+    const autoPrefer = readAutoPrefer(cwd);
+    const preferStatus = autoPrefer
+        ? Object.keys(cfg.routing.map).flatMap((shape) => {
+            const auto = autoPrefer[shape];
+            if (!Array.isArray(auto))
+                return [];
+            const seed = DEFAULT_CONFIG.routing.map[shape]?.prefer ?? [];
+            if (!auto.length && !seed.length)
+                return []; // nothing derived, nothing seeded — an empty line is noise
+            return [`    prefer ${shape} (auto): ${auto.join(" > ")} — seed was [${seed.join(", ")}]`];
+        })
+        : [];
+    const modelSummary = modelStatus.length || preferStatus.length
+        ? `\nmodel status:\n${[...modelStatus, ...preferStatus].join("\n")}`
+        : "";
     return stylize(`tickmarkr doctor — capability matrix:\n${rows.join("\n")}${modelSummary}${drift}\nwrote ${stateDirName(cwd)}/doctor.json`);
 }

package/dist/cli/index.d.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 export type CommandMap = Record<string, (argv: string[]) => Promise<string>>;
 export declare const COMMANDS: CommandMap;
+export declare const BANNER: string;
 export declare const USAGE = "tickmarkr \u2014 spec-driven orchestration harness for AI coding agents\nusage: tickmarkr <command>\n  init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs\n  doctor        re-probe adapters, herdr, auth; print capability matrix\n  compile <src> spec \u2192 .drovr/graph.json (fails without acceptance criteria)\n  scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)\n  plan          dry-run routing table + cost estimate + floor lints\n  run           execute the graph (--concurrency N --driver herdr|subprocess --route-strict)\n  status        live run state\n  resume <id>   continue a run from its journal\n  report <id>   cost/quality report (--md for committable execution record)\n  profile       show learned routing profile (profile reset = forget history via cursor, keeps telemetry)\n  unlock        remove a stale/garbage run lock (refuses if the holder is alive)\n  approve <id> <task>  approve a parked human gate (--by <name> --reason <text>); takes effect on resume";
 export declare function dispatch(cmd: string | undefined, argv: string[], commands?: CommandMap): Promise<{
     out: string;

package/dist/cli/index.js

@@ -17,6 +17,17 @@ export const COMMANDS = {
     init, doctor, compile, scope, plan, run, status, resume, report, profile, unlock, approve,
 };
 const HELP_CMDS = new Set(["help", "-h", "--help"]);
+// TTY-only pixel-tick logo (assets/mark.svg is the image twin — same block geometry).
+// Never printed to pipes — the non-TTY stdout surface is byte-pinned by tests and consumed by machines.
+const B = "\x1b[1m", R = "\x1b[0m";
+const g = (n, s) => `\x1b[38;5;${n}m${s}${R}`; // 256-color green ramp, bright → deep
+export const BANNER = [
+    `              ${g(84, "▄▄████")}`,
+    `          ${g(78, "▄▄████▀▀")}`,
+    `${g(41, "████▄▄▄▄████▀▀")}     ${B}tickmarkr${R}`,
+    `  ${g(35, "▀▀████▀▀")}         spec in, verified work out.`,
+    "",
+].join("\n");
 export const USAGE = `tickmarkr — spec-driven orchestration harness for AI coding agents
 usage: tickmarkr <command>
   init          guided setup + doctor; init --agent [--force] [--docs] adds agent skills/docs
@@ -35,11 +46,12 @@ usage: tickmarkr <command>
 // unknown/missing cmd → USAGE (exit 1 if a cmd was typed, 0 for bare `drovr`); a handler throw becomes
 // a one-line `drovr <cmd>: <message>` (never a raw stack) at exit 1.
 export async function dispatch(cmd, argv, commands = COMMANDS) {
+    const usage = process.stdout.isTTY ? BANNER + USAGE : USAGE;
     if (!cmd || HELP_CMDS.has(cmd))
-        return { out: USAGE, code: 0 };
+        return { out: usage, code: 0 };
     const fn = commands[cmd];
     if (!fn)
-        return { out: USAGE, code: 1 };
+        return { out: usage, code: 1 };
     try {
         return { out: await fn(argv), code: 0 };
     }
@@ -60,7 +72,7 @@ if (argv1Real && import.meta.url === pathToFileURL(argv1Real).href) {
     const [cmd, ...argv] = process.argv.slice(2);
     dispatch(cmd, argv).then(({ out, code }) => {
         // byte-identical streams: usage + success → stdout; a handler throw → stderr (original behavior)
-        (out === USAGE || code === 0 ? console.log : console.error)(out);
+        (out.endsWith(USAGE) || code === 0 ? console.log : console.error)(out);
         if (code !== 0)
             process.exit(code);
     });

package/dist/config/config.d.ts

@@ -177,6 +177,9 @@ export declare class ConfigError extends Error {
 }
 export declare const DEFAULT_CONFIG: DrovrConfig;
 export declare function globalConfigDir(): string;
+export declare function overlayPreferShapes(repoRoot: string, opts?: {
+    globalDir?: string;
+}): ReadonlySet<string>;
 export declare function loadConfig(repoRoot: string, opts?: {
     globalDir?: string;
 }): DrovrConfig;

package/dist/config/config.js

@@ -191,6 +191,11 @@ export const DEFAULT_CONFIG = {
             vendor: "cursor", channel: "sub",
             models: {
                 "composer-2.5": "mid",
+                // composer-2.5-fast → cheap: speed-optimized variant, no independent benchmark scores yet → floor
+                // tier (same policy call as grok-composer-2.5-fast below). Id live-verified in doctor.json probe
+                // 2026-07-16 (cursor-agent 2026.07.09); gives cursor a cheap-tier channel so low-complexity shapes
+                // stop burning its mid. Operator-approved 2026-07-16.
+                "composer-2.5-fast": "cheap",
             },
         },
         // GLM-5.2 → mid per benchmark policy (2026-07): SWE-bench Pro 62.1 (> GPT-5.5 58.6), FrontierSWE 74.4 ≈ Opus 4.8;
@@ -262,6 +267,19 @@ export function globalConfigDir() {
     const legacy = join(base, "drovr");
     return existsSync(join(next, "config.yaml")) || !existsSync(join(legacy, "config.yaml")) ? next : legacy;
 }
+export function overlayPreferShapes(repoRoot, opts = {}) {
+    const shapes = new Set();
+    for (const layer of [readYaml(join(opts.globalDir ?? globalConfigDir(), "config.yaml")), readYaml(join(repoRoot, stateDirName(repoRoot), "config.yaml"))]) {
+        const map = layer?.routing?.map;
+        if (!map)
+            continue;
+        for (const [shape, entry] of Object.entries(map)) {
+            if (entry && Object.prototype.hasOwnProperty.call(entry, "prefer") && entry.prefer !== null)
+                shapes.add(shape);
+        }
+    }
+    return shapes;
+}
 export function loadConfig(repoRoot, opts = {}) {
     const globalCfg = readYaml(join(opts.globalDir ?? globalConfigDir(), "config.yaml"));
     const repoCfg = readYaml(join(repoRoot, stateDirName(repoRoot), "config.yaml"));

package/dist/route/router.d.ts

@@ -18,9 +18,17 @@ export interface Route {
     provenance: string;
     deviation?: RouteDeviation;
 }
+export interface RoutingPreferContext {
+    autoPrefer?: {
+        derivedAt: string;
+        [shape: string]: string[] | string;
+    };
+    doctorFresh: boolean;
+    overlayPreferShapes: ReadonlySet<string>;
+}
 export declare class RoutingError extends Error {
     constructor(msg: string);
 }
 export declare function marginalCostRank(c: BillingChannel): number;
-export declare function route(task: Task, cfg: DrovrConfig, channels: BillingChannel[], profile?: RoutingProfile): Route;
+export declare function route(task: Task, cfg: DrovrConfig, channels: BillingChannel[], profile?: RoutingProfile, preferCtx?: RoutingPreferContext): Route;
 export declare function nextChannel(current: Assignment, task: Task, cfg: DrovrConfig, channels: BillingChannel[], tried: string[], profile?: RoutingProfile): Assignment | null;

package/dist/route/router.js

@@ -2,6 +2,19 @@ import { channelKey, channelsFromConfig } from "../adapters/types.js";
 import { TIER_RANK } from "../config/config.js";
 import { disallowedBy } from "./preference.js";
 import { cellOf, EXPLORE_CAP, explorationBonus, learnedScore } from "./profile.js";
+const autoPreferList = (doc, shape) => {
+    const v = doc?.[shape];
+    return Array.isArray(v) ? v : undefined;
+};
+const preferFromAuto = (shape, preferCtx) => !!preferCtx?.doctorFresh && !!preferCtx.autoPrefer && !preferCtx.overlayPreferShapes.has(shape) &&
+    autoPreferList(preferCtx.autoPrefer, shape) !== undefined;
+const effectivePrefer = (shape, entry, preferCtx) => {
+    if (preferCtx?.overlayPreferShapes.has(shape))
+        return entry?.prefer;
+    if (preferCtx?.doctorFresh && preferCtx.autoPrefer)
+        return autoPreferList(preferCtx.autoPrefer, shape) ?? entry?.prefer;
+    return entry?.prefer;
+};
 export class RoutingError extends Error {
     constructor(msg) {
         super(msg);
@@ -31,10 +44,11 @@ function ladderFor(task, entry) {
     const escalate = task.routingHints?.escalate ?? entry?.escalate ?? true;
     return escalate ? ["retry", "escalate", "consult", "human"] : ["retry", "consult", "human"];
 }
-export function route(task, cfg, channels, profile) {
+export function route(task, cfg, channels, profile, preferCtx) {
     const lints = [];
     const floor = cfg.routing.floors[task.shape];
     const entry = cfg.routing.map[task.shape];
+    const prefer = effectivePrefer(task.shape, entry, preferCtx);
     const prefActive = !!(cfg.routing.allow || cfg.routing.deny);
     const disallowedPin = (via, model, kind) => {
         const d = disallowedBy({ adapter: via, model }, cfg.routing);
@@ -95,12 +109,12 @@ export function route(task, cfg, channels, profile) {
     if (entry?.tier)
         lintFloor(entry.tier, "map tier");
     if (prefActive)
-        for (const p of entry?.prefer ?? [])
+        for (const p of prefer ?? [])
             preflightPrefer(p);
     // key order is a contract: prefer > marginal cost > tier (cheapest sufficient) > learned score (v1.6 ROUTE-06)
     // > discovery order (same-tier fairness, D2). The learned score is the LAST key — it decides only the
     // discovery-order tail, never a pin/floor/prefer/cost/tier boundary (they all sort above it, ROUTE-08).
-    const staticCmp = (a, b) => preferIndex(a, entry?.prefer) - preferIndex(b, entry?.prefer) || marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier];
+    const staticCmp = (a, b) => preferIndex(a, prefer) - preferIndex(b, prefer) || marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier];
     const eligibleRaw = channels.filter((c) => TIER_RANK[c.tier] >= TIER_RANK[minTier]);
     if (!eligibleRaw.length) {
         let msg = `${task.id}: no channel at tier>=${minTier}; available: ${channels.map(channelKey).join(", ") || "(none)"}`;
@@ -137,19 +151,19 @@ export function route(task, cfg, channels, profile) {
         // entries, while intra-entry order (cost > tier > bonus > score) and every cold path stay byte-identical.
         // Cold reduces to preferIndex || cost || tier ≡ staticCmp (proof P1); rep keys use the group HEAD so
         // the probed group's budget self-extinguishes at EXPLORE_CAP (P4); flat lexicographic K is total (P5).
-        const prefer = entry?.prefer ?? [];
+        const preferBands = prefer ?? [];
         const groupCmp = (a, b) => marginalCostRank(a) - marginalCostRank(b) || TIER_RANK[a.tier] - TIER_RANK[b.tier] ||
             bonusOf(b) - bonusOf(a) || scoreOf(b) - scoreOf(a);
         const heads = new Map();
         for (const c of [...eligibleRaw].sort(groupCmp)) {
-            const g = preferIndex(c, prefer);
+            const g = preferIndex(c, preferBands);
             if (!heads.has(g))
                 heads.set(g, c);
         }
         const keyOf = new Map(eligibleRaw.map((c) => {
-            const g = preferIndex(c, prefer);
+            const g = preferIndex(c, preferBands);
             const rep = heads.get(g);
-            return [channelKey(c), [g < prefer.length ? 0 : 1, -bonusOf(rep), -scoreOf(rep), g,
+            return [channelKey(c), [g < preferBands.length ? 0 : 1, -bonusOf(rep), -scoreOf(rep), g,
                     marginalCostRank(c), TIER_RANK[c.tier], -bonusOf(c), -scoreOf(c)]];
         }));
         const kOf = (c) => keyOf.get(channelKey(c));
@@ -180,8 +194,11 @@ export function route(task, cfg, channels, profile) {
                 "tier cheap (default)";
     // name the key that actually broke the tie: prefer outranks the marginal-cost/tier keys, so if the
     // winner matched a prefer entry, prefer decided it — not "cheapest sufficient tier" (ROUTE-03, WR-01)
-    const chosenBy = learnedChosen || (entry?.prefer && preferIndex(eligible[0], entry.prefer) < entry.prefer.length
-        ? "via prefer" : "cheapest sufficient tier");
+    const preferVia = preferFromAuto(task.shape, preferCtx)
+        ? `via prefer (auto-modernized ${preferCtx.autoPrefer.derivedAt.slice(0, 10)})`
+        : "via prefer";
+    const chosenBy = learnedChosen || (prefer && preferIndex(eligible[0], prefer) < prefer.length
+        ? preferVia : "cheapest sufficient tier");
     return { assignment: toAssignment(eligible[0]), ladder: ladderFor(task, entry), lints, provenance: `${degraded}${bound}, marginal-cost auto (${chosenBy})`, ...(deviation ? { deviation } : {}) };
 }
 export function nextChannel(current, task, cfg, channels, tried, profile) {

package/dist/run/daemon.d.ts

@@ -18,6 +18,8 @@ export interface RunSummary {
     human: string[];
     pending: string[];
     blocked: string[];
+    tipVerify?: "passed" | "failed";
+    lastMergedTask?: string;
 }
 export declare function formatSummary(s: RunSummary): string;
 export declare function runDaemon(repoRoot: string, opts?: RunOptions): Promise<RunSummary>;

package/dist/run/daemon.js

@@ -14,13 +14,16 @@ import { consult } from "./consult.js";
 import { cleanupRunWorktrees, gitHead, sh } from "./git.js";
 import { Journal, loadRoutingProfile, newRunId } from "./journal.js";
 import { acquireRunLock, releaseRunLock } from "./lock.js";
-import { ensureIntegration, integrationBranch, integrationHead, mergeTask } from "./merge.js";
+import { ensureIntegration, integrationBranch, integrationHead, mergeTask, verifyIntegrationTip } from "./merge.js";
 import { nextChannel, route } from "../route/router.js";
 import { desiredPanes } from "./reconcile.js";
 // VIS-01: one formatter, four readers (run-end journal event, run/resume CLI, run-end notify).
 // Parity by construction — every caller renders the same complete bucket line.
 export function formatSummary(s) {
-    return `done: ${s.done.length}, failed: ${s.failed.length}, human: ${s.human.length}, blocked: ${s.blocked.length}, pending: ${s.pending.length}\nintegration branch: ${s.branch}`;
+    const tip = s.tipVerify === "failed"
+        ? `\ntip verify: FAILED${s.lastMergedTask ? ` (last merged: ${s.lastMergedTask})` : ""}`
+        : s.tipVerify === "passed" ? "\ntip verify: passed" : "";
+    return `done: ${s.done.length}, failed: ${s.failed.length}, human: ${s.human.length}, blocked: ${s.blocked.length}, pending: ${s.pending.length}\nintegration branch: ${s.branch}${tip}`;
 }
 const MAX_ATTEMPTS = 10; // ponytail: hard cap so a pathological ladder can never loop forever
 const BLOCKED_POLL_MS = 30_000; // between trailer-wait slices, check whether the pane is blocked on a prompt
@@ -704,12 +707,37 @@ export async function runDaemon(repoRoot, opts = {}) {
             blocked: blockedTasks(graph).map((t) => t.id),
             pending: pendingTasks(graph).map((t) => t.id),
         };
+        // OBS-34: post-merge integration-tip verify — strict exit codes, no baseline forgiveness.
+        const lastMergedTask = [...journal.read()].reverse().find((e) => e.event === "merge" && e.taskId)?.taskId;
+        if (summary.done.length > 0 && Object.keys(commands).length > 0) {
+            const tipResults = await verifyIntegrationTip(intWt, commands);
+            let tipFailed = false;
+            for (const r of tipResults) {
+                if (r.pass) {
+                    journal.append("tip-verify", undefined, { gate: r.gate, cmd: r.cmd, pass: true, exitCode: r.exitCode, details: r.details });
+                }
+                else {
+                    journal.append("tip-verify-failed", undefined, {
+                        gate: r.gate,
+                        cmd: r.cmd,
+                        exitCode: r.exitCode,
+                        fingerprints: r.fingerprints,
+                        lastMergedTask,
+                    });
+                    tipFailed = true;
+                }
+            }
+            summary.tipVerify = tipFailed ? "failed" : "passed";
+            if (tipFailed && lastMergedTask)
+                summary.lastMergedTask = lastMergedTask;
+        }
         journal.append("run-end", undefined, { ...summary });
         await reconcile(); // run-end boundary: nothing in flight — full sweep (empty desired set)
         // OBS-28: lingering worktrees starve CLI probes; keepPanes:forever is the debug override.
         if (!keepForever) {
             const green = summary.failed.length === 0 && summary.human.length === 0
-                && summary.blocked.length === 0 && summary.pending.length === 0;
+                && summary.blocked.length === 0 && summary.pending.length === 0
+                && summary.tipVerify !== "failed";
             await cleanupRunWorktrees(repoRoot, branch, { removeIntegration: green, removeTaskIds: summary.done });
         }
         // VIS-02: name each blocked subtree by its nearest parked/failed root, e.g. "3 blocked behind P40-02".
@@ -717,7 +745,10 @@ export async function runDaemon(repoRoot, opts = {}) {
             .sort(([a], [b]) => a.localeCompare(b))
             .map(([root, count]) => `${count} blocked behind ${root}`)
             .join(", ");
-        await driver.notify(`tickmarkr ${runId}: ${summary.done.length} done, ${summary.failed.length} failed, ${summary.human.length} awaiting human, ${summary.blocked.length} blocked, ${summary.pending.length} pending${attribution ? ` (${attribution})` : ""} — integration branch ${branch} (merge to main is yours)`, { tier: "attention" });
+        const tipFail = summary.tipVerify === "failed"
+            ? ` — TIP VERIFY FAILED on ${summary.lastMergedTask ? `last merge ${summary.lastMergedTask}` : "integration tip"}`
+            : "";
+        await driver.notify(`tickmarkr ${runId}: ${summary.done.length} done, ${summary.failed.length} failed, ${summary.human.length} awaiting human, ${summary.blocked.length} blocked, ${summary.pending.length} pending${attribution ? ` (${attribution})` : ""}${tipFail} — integration branch ${branch} (merge to main is yours)`, { tier: summary.tipVerify === "failed" ? "attention" : "attention" });
         return summary;
     }
     finally {

package/dist/run/journal.js

@@ -12,7 +12,11 @@ export function formatJournalNarration({ event, taskId, data }) {
     const detail = Array.isArray(data.done)
         ? `done ${data.done.length}, failed ${Array.isArray(data.failed) ? data.failed.length : 0}`
         : typeof data.gate === "string"
-            ? `${data.gate}${data.pass === true ? " passed" : data.pass === false ? " failed" : ""}`
+            ? event === "tip-verify-failed"
+                ? `${data.gate} failed${typeof data.lastMergedTask === "string" ? ` after ${data.lastMergedTask}` : ""}`
+                : event === "tip-verify"
+                    ? `${data.gate} passed`
+                    : `${data.gate}${data.pass === true ? " passed" : data.pass === false ? " failed" : ""}`
             : typeof data.code === "number" ? `exit ${data.code}`
                 : typeof data.pid === "number" ? `pid ${data.pid}`
                     : typeof data.baseRef === "string" ? `base ${data.baseRef.slice(0, 12)}`

package/dist/run/merge.d.ts

@@ -1,4 +1,12 @@
 import type { DrovrConfig } from "../config/config.js";
+export interface TipVerifyResult {
+    gate: string;
+    cmd: string;
+    pass: boolean;
+    exitCode: number;
+    fingerprints: string[];
+    details: string;
+}
 export declare function integrationBranch(cfg: DrovrConfig, runId: string): string;
 export declare function ensureIntegration(repo: string, branch: string, baseRef: string): Promise<string>;
 export declare function integrationHead(intWt: string): Promise<string>;
@@ -10,3 +18,4 @@ export declare function mergeTask(intWt: string, taskBranch: string, message: st
         branchTip: string;
     };
 }>;
+export declare function verifyIntegrationTip(intWt: string, commands: Record<string, string>): Promise<TipVerifyResult[]>;

package/dist/run/merge.js

@@ -1,6 +1,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { shq } from "../adapters/types.js";
+import { fingerprint } from "../gates/baseline.js";
 import { drovrDir } from "../graph/graph.js";
 import { gitHead, resolveIntegrationBranch, sh, shOk } from "./git.js";
 export function integrationBranch(cfg, runId) {
@@ -42,3 +43,20 @@ export async function mergeTask(intWt, taskBranch, message, gatedCommit) {
     await sh("git merge --abort", intWt);
     return { ok: false, conflict };
 }
+// OBS-34: strict exit-code verify on the integration tip — no baseline forgiveness.
+export async function verifyIntegrationTip(intWt, commands) {
+    const results = [];
+    for (const [gate, cmd] of Object.entries(commands)) {
+        const r = await sh(cmd, intWt);
+        const raw = (r.stdout + "\n" + r.stderr).split(intWt).join("");
+        results.push({
+            gate,
+            cmd,
+            pass: r.code === 0,
+            exitCode: r.code,
+            fingerprints: r.code !== 0 ? fingerprint(raw) : [],
+            details: r.code === 0 ? "exit 0" : `exit ${r.code}`,
+        });
+    }
+    return results;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.35.0",
+  "version": "1.37.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,7 @@
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "lint": "oxlint src tests scripts",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "schema": "tsx scripts/emit-schema.ts",
@@ -32,6 +33,7 @@
     "@types/node": "^20.14.0",
     "@types/picomatch": "^4.0.0",
     "@vitest/coverage-v8": "^3.0.0",
+    "oxlint": "1.74.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"

package/skills/tickmarkr-auto/SKILL.md

@@ -36,6 +36,6 @@ Run every requested target in order without seeking routine confirmation. Stop o
 2. **Compile** — run `tickmarkr compile <spec-or-directory>`. Fix source-spec defects instead of editing the generated graph.
 3. **Plan** — run `tickmarkr plan`. Review routes, capability-floor warnings, and human gates before execution.
 4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than polling agents. Resolve blocked interactions in the relevant agent session.
-5. **Verify and consolidate** — continue only after a green run. Tickmarkr consolidates accepted work on `tickmarkr/<runId>` and never signs off to the main branch. A human controls any later release merge.
+5. **Verify and consolidate** — continue only after a green run. A run is green when the run-end event exists in the journal AND the tip verify is not "failed". Tickmarkr consolidates accepted work on `tickmarkr/<runId>` and never signs off to the main branch. A human controls any later release merge.
 6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records.
 7. **Continue** — move to the next requested target. If a target fails or is parked, stop with the journal evidence rather than silently skipping it.

package/skills/tickmarkr-loop/SKILL.md

@@ -35,5 +35,5 @@ Proceed through the loop without seeking routine confirmation. Stop only for a b
 2. **Compile** — run `tickmarkr compile <spec>`. Correct compilation errors in the spec, never in the generated graph.
 3. **Plan** — run `tickmarkr plan`. Review the routing table, capability-floor warnings, and every human gate, including work that each gate blocks.
 4. **Run** — run `tickmarkr run`. Watch the run journal for its terminal event rather than repeatedly polling agents. Resolve blocked interactions in the agent session; do not turn them into proxy questions.
-5. **Verify and consolidate** — accept only a green run. Tickmarkr consolidates accepted task work on `tickmarkr/<runId>`; it never signs off to the main branch. A human may later merge that integration branch through the repository's normal release process.
+5. **Verify and consolidate** — accept only a green run. A run is green when the run-end event exists in the journal AND the tip verify is not "failed". Tickmarkr consolidates accepted task work on `tickmarkr/<runId>`; it never signs off to the main branch. A human may later merge that integration branch through the repository's normal release process.
 6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records.