tickmarkr 1.30.0 → 1.33.0

package/README.md

@@ -13,8 +13,7 @@ Green tasks consolidate onto a `tickmarkr/<runId>` **consolidation** branch; **s
 your mainline) is always the Partner's call, never the engine's. A fully green engagement is an
 **unqualified opinion** — every assertion independently ticked.
 
-> The package ships `tickmarkr` as the primary bin, plus `drovr` and a `drover` bin alias for
-> backward compatibility — all three invoke the same entry. New installs should call `tickmarkr`.
+> The package ships `tickmarkr` and `tkr` only; `tkr` is the short alias.
 
 ## Vocabulary
 
@@ -53,24 +52,27 @@ These are law; the codebase fails closed around them:
 - worker/judge/review/consult prompts end with machine-parseable trailers
   (`DROVR_RESULT` / JSON verdicts); parse defensively, fail closed
 
-## Install
+Any agent (or human) operating this repo must respect the same five rules above — they are not
+merely internal implementation details, they are the contract the gates enforce.
 
-Requirements: Node ≥ 20, git, and at least one agent CLI on PATH (`claude`, `codex`, `cursor-agent`,
-`opencode`, `grok`, or `pi`) authenticated through its own login.
+## Install
 
 ```bash
-npm install
-npm run build
-npm link        # exposes the `tickmarkr` bin (and the `drovr` / `drover` compat alias)
+npm i -g tickmarkr
 ```
 
+This installs two identical bins: `tickmarkr` and its short alias `tkr` — use whichever you
+prefer, every example below works with either. Requirements: Node ≥ 20, git, and at least one
+agent CLI on PATH (`claude`, `codex`, `cursor-agent`, `opencode`, `grok`, or `pi`) authenticated
+through its own login.
+
 Then verify your fleet:
 
 ```bash
 tickmarkr doctor   # probes installed adapters, herdr, auth; prints the capability matrix
 ```
 
-## Quickstart
+## Quickstart (5 minutes)
 
 ```bash
 tickmarkr init                 # guided setup + doctor; scaffolds .drovr/config.yaml and drovr.spec.md
@@ -81,6 +83,34 @@ tickmarkr run                  # execute the graph (--concurrency N --driver her
 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.
+
+## Agent-ready repos: `tickmarkr init --agent`
+
+`tickmarkr init --agent` composes with the base `init` above and additionally installs the
+consumer-facing skills (`tickmarkr-loop`, `tickmarkr-auto`) that ship in the npm tarball, so a
+coding agent working in your repo knows how to drive tickmarkr without reading its source:
+
+```bash
+tickmarkr init --agent            # installs .claude/skills/tickmarkr-{loop,auto}, offers CLAUDE.md/AGENTS.md notes
+tickmarkr init --agent --force    # also overwrite skill files that already exist
+tickmarkr init --agent --docs     # also append the agent-docs section without an interactive prompt
+```
+
+Consent rules — every write is additive, never destructive:
+
+- an existing `.claude/skills/tickmarkr-{loop,auto}/SKILL.md` is left untouched unless you answer
+  yes to a per-file prompt, or pass `--force`
+- a short "tickmarkr" section (the loop commands + the invariants above) is appended to `CLAUDE.md`
+  — or `AGENTS.md` if that exists and `CLAUDE.md` doesn't — only after you say yes, or pass `--docs`;
+  it's wrapped in `<!-- tickmarkr:agent-docs begin/end -->` markers and never inserted twice
+- declining a prompt still lets the rest of `init` complete
+- 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:
 
 ```bash
@@ -332,14 +362,65 @@ Cloning this repo gives Claude Code project skills under `.claude/skills/`:
 
 Repo-scoped: available automatically in Claude Code sessions inside this repo; not installed by npm.
 
-## Development
+## Contributing
+
+### Dev setup
 
 ```bash
-npm test               # vitest unit+integration — zero tokens, fake adapter only
-npm run test:coverage  # coverage floors enforced on core dirs
-npm run e2e            # real-CLI end-to-end (spends tokens; needs ≥1 agent CLI)
+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 — that's
+what `DROVR_FAKE_SCRIPT` and the `FakeAdapter` (`src/adapters/fake.ts`) exist for. If a change
+needs a real CLI to verify, that test belongs under `npm run e2e` (`tests/e2e/`), gated behind
+`DROVR_E2E=1`, never in the default suite.
+
+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.
+
 Design spec: `docs/superpowers/specs/2026-07-07-drover-design.md`.
 
 ## License

package/dist/cli/commands/doctor.js

@@ -68,7 +68,7 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         rows.push(`  ! ${servabilityLine(servable)}`);
     // MODEL-05/06: print-only drift fragment; advisory, whole-line-commented additions, drovr NEVER applies it.
     const frag = suggestOverlay(cfg, health, adapters);
-    const drift = frag ? `\nmodel drift — paste-ready overlay (advisory; drovr never applies):\n${frag}` : "";
+    const drift = frag ? `\nmodel drift — paste-ready overlay (advisory; tickmarkr never applies):\n${frag}` : "";
     // T4: model-status table — one row per CLASSIFIED model (tiers config) with tier, auth verdict
     // (reason + date when unauthed), operator-deny flag, and prefer rank across the routing map.
     // Unclassified listed models (detected via listModels but never tiered) compress to one count line
@@ -99,5 +99,5 @@ export async function doctor(_argv, cwd = process.cwd(), adapters = allAdapters(
         return rows;
     });
     const modelSummary = modelStatus.length ? `\nmodel status:\n${modelStatus.join("\n")}` : "";
-    return `drovr doctor — capability matrix:\n${rows.join("\n")}${modelSummary}${drift}\nwrote .drovr/doctor.json`;
+    return `tickmarkr doctor — capability matrix:\n${rows.join("\n")}${modelSummary}${drift}\nwrote .drovr/doctor.json`;
 }

package/dist/cli/commands/init.js

@@ -1,12 +1,78 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
 import { configTemplate, globalConfigDir } from "../../config/config.js";
 import { specTemplate } from "../../compile/native.js";
 import { drovrDir } from "../../graph/graph.js";
 import { doctor } from "./doctor.js";
+const AGENT_SKILLS = ["tickmarkr-loop", "tickmarkr-auto"];
+const DOCS_BEGIN = "<!-- tickmarkr:agent-docs begin -->";
+const DOCS_END = "<!-- tickmarkr:agent-docs end -->";
+const AGENT_DOCS = `${DOCS_BEGIN}
+## tickmarkr
+
+tickmarkr turns repository specs into isolated, independently verified agent work. Use \`/tickmarkr-loop\` for one spec or \`/tickmarkr-auto\` for several.
+
+Loop: \`tickmarkr compile <spec>\` → \`tickmarkr plan\` → \`tickmarkr run\` → \`tickmarkr report <runId> --md\`.
+
+- Never run two tickmarkr runs in the same repository concurrently.
+- Never merge tickmarkr work directly to main; new runs consolidate on \`tickmarkr/<runId>\`.
+- Fix source specs instead of editing generated graphs.
+- Never trust a worker's completion claim; gates independently verify the work.
+- Treat missing or unparseable results as failures.
+${DOCS_END}
+`;
+async function installAgentFiles(cwd, force, docs, notes) {
+    const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
+    let prompt;
+    const confirm = async (question) => {
+        if (!interactive)
+            return false;
+        prompt ??= createInterface({ input: process.stdin, output: process.stdout });
+        return /^(?:y|yes)$/i.test((await prompt.question(`${question} [y/N] `)).trim());
+    };
+    try {
+        for (const skill of AGENT_SKILLS) {
+            const dest = join(cwd, ".claude", "skills", skill, "SKILL.md");
+            const exists = existsSync(dest);
+            if (exists && !force && !(await confirm(`Overwrite ${dest}?`))) {
+                notes.push(`skipped existing ${dest}; pass --force to overwrite it`);
+                continue;
+            }
+            mkdirSync(join(cwd, ".claude", "skills", skill), { recursive: true });
+            writeFileSync(dest, readFileSync(new URL(`../../../skills/${skill}/SKILL.md`, import.meta.url)), exists ? undefined : { flag: "wx" });
+            notes.push(`${exists ? "overwrote" : "wrote"} ${dest}`);
+        }
+        const claude = join(cwd, "CLAUDE.md");
+        const agents = join(cwd, "AGENTS.md");
+        const docPath = existsSync(claude) || !existsSync(agents) ? claude : agents;
+        const current = existsSync(docPath) ? readFileSync(docPath, "utf8") : "";
+        if (current.includes(DOCS_BEGIN) || current.includes(DOCS_END)) {
+            notes.push(`kept existing tickmarkr agent docs in ${docPath}`);
+        }
+        else if (docs || await confirm(`Append tickmarkr agent docs to ${docPath}?`)) {
+            appendFileSync(docPath, `${current ? current.endsWith("\n") ? "\n" : "\n\n" : ""}${AGENT_DOCS}`);
+            notes.push(`appended tickmarkr agent docs to ${docPath}`);
+        }
+        else {
+            notes.push(`skipped agent docs for ${docPath}; pass --docs to append them`);
+        }
+    }
+    finally {
+        prompt?.close();
+    }
+}
 export async function init(argv, cwd = process.cwd()) {
-    const { values } = parseArgs({ args: argv, options: { "global-dir": { type: "string" } } });
+    const { values } = parseArgs({
+        args: argv,
+        options: {
+            "global-dir": { type: "string" },
+            agent: { type: "boolean" },
+            force: { type: "boolean" },
+            docs: { type: "boolean" },
+        },
+    });
     const gdir = values["global-dir"] ?? globalConfigDir();
     mkdirSync(gdir, { recursive: true });
     const notes = [];
@@ -19,14 +85,19 @@ export async function init(argv, cwd = process.cwd()) {
             notes.push(`kept existing ${p}`);
         }
     }
-    const specPath = join(cwd, "drovr.spec.md");
-    if (!existsSync(specPath)) {
-        writeFileSync(specPath, specTemplate());
-        notes.push(`wrote ${specPath}`);
+    const specPath = join(cwd, "tickmarkr.spec.md");
+    if (existsSync(specPath)) {
+        notes.push(`kept existing ${specPath}`);
+    }
+    else if (existsSync(join(cwd, "drovr.spec.md"))) {
+        notes.push(`kept existing ${join(cwd, "drovr.spec.md")}`);
     }
     else {
-        notes.push(`kept existing ${specPath}`);
+        writeFileSync(specPath, specTemplate());
+        notes.push(`wrote ${specPath}`);
     }
+    if (values.agent)
+        await installAgentFiles(cwd, values.force ?? false, values.docs ?? false, notes);
     const doc = await doctor([], cwd);
-    return `${notes.join("\n")}\n${doc}\nnext: edit drovr.spec.md, then drovr compile drovr.spec.md && drovr plan && drovr run`;
+    return `${notes.join("\n")}\n${doc}\nnext: edit tickmarkr.spec.md, then tickmarkr compile tickmarkr.spec.md && tickmarkr plan && tickmarkr run`;
 }

package/dist/cli/commands/status.d.ts

@@ -1,9 +1,5 @@
-import { type Task } from "../../graph/schema.js";
-import { type JournalEvent } from "../../run/journal.js";
 export type StatusOpts = {
     iterations?: number;
     sleep?: (ms: number) => Promise<void>;
 };
-/** Derive the live phase column for one task. Counts only that task's events since its last dispatch/escalation. */
-export declare const derivePhase: (task: Task, events: JournalEvent[], channel?: string) => string;
 export declare function status(argv: string[], cwd?: string, opts?: StatusOpts): Promise<string>;

package/dist/cli/commands/status.js

@@ -6,6 +6,7 @@ const REFRESH_MS = 2000;
 // The timer must keep the process ALIVE: an unref'd timer here let the event loop drain after the
 // first frame, so a live `--watch` printed once and exited 0 (OBS-11). Never unref this.
 const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const GATE_KEYS = { build: "B", test: "T", lint: "L", evidence: "E", scope: "S", acceptance: "A", review: "R" };
 const attemptStartIdx = (events, taskId) => {
     let idx = -1;
     for (let i = 0; i < events.length; i++) {
@@ -15,39 +16,51 @@ const attemptStartIdx = (events, taskId) => {
     }
     return idx;
 };
-/** Derive the live phase column for one task. Counts only that task's events since its last dispatch/escalation. */
-export const derivePhase = (task, events, channel) => {
-    const startIdx = attemptStartIdx(events, task.id);
-    if (startIdx < 0)
-        return "";
-    // Scope to this task — concurrent tasks' events must not leak into the attempt window (D-03).
-    const attempt = events.slice(startIdx).filter((e) => e.taskId === task.id);
-    if (attempt.some((e) => e.event === "task-done" || e.event === "task-failed" || e.event === "task-human"))
-        return "";
-    if (!attempt.some((e) => e.event === "task-dispatch"))
-        return "retrying"; // escalation before re-dispatch
-    if (!attempt.some((e) => e.event === "worker-result"))
-        return channel ? `worker · ${channel}` : "worker";
-    const enabled = GATE_NAMES.filter((g) => task.gates.includes(g));
-    const n = enabled.length;
-    const gateResults = attempt.filter((e) => e.event === "gate-result");
-    if (gateResults.length > 0) {
-        const last = gateResults[gateResults.length - 1];
-        if (!last.data.pass)
-            return `gate ✗ ${last.data.gate}`;
+const visual = () => process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+const color = (text, code, enabled) => enabled ? `\x1b[${code}m${text}\x1b[0m` : text;
+const taskBox = (status, unicode) => {
+    if (unicode) {
+        if (status === "done")
+            return "✓";
+        if (status === "failed")
+            return "✗";
+        if (status === "human")
+            return "⏸";
+        return "☐";
     }
-    const passed = new Set();
-    for (const e of gateResults)
-        if (e.data.pass)
-            passed.add(String(e.data.gate));
-    const k = passed.size;
-    // n===0 (no enabled gates) → merge window immediately after worker-result
-    if (n === 0 || k >= n) {
-        if (!attempt.some((e) => e.event === "merge" || e.event === "task-done"))
-            return "merging";
-        return "";
+    if (status === "done")
+        return "[x]";
+    if (status === "failed" || status === "human")
+        return "[!]";
+    return "[ ]";
+};
+const gateBox = (state, unicode) => {
+    if (unicode)
+        return state === "pass" ? "✓" : state === "fail" ? "✗" : state === "skip" ? "·" : "☐";
+    return state === "pass" ? "[x]" : state === "fail" ? "[!]" : state === "skip" ? "." : "[ ]";
+};
+const gateChain = (task, events, unicode) => {
+    const outcomes = new Map();
+    const start = attemptStartIdx(events, task.id);
+    if (start >= 0) {
+        for (const e of events.slice(start)) {
+            if (e.taskId !== task.id || e.event !== "gate-result" || typeof e.data.gate !== "string")
+                continue;
+            if (e.data.pass === true)
+                outcomes.set(e.data.gate, "pass");
+            else if (e.data.pass === false)
+                outcomes.set(e.data.gate, "fail");
+        }
     }
-    return `gate ${k + 1}/${n} ${enabled[k]}`;
+    return GATE_NAMES.map((gate) => `${GATE_KEYS[gate]}${gateBox(task.gates.includes(gate) ? outcomes.get(gate) ?? "open" : "skip", unicode)}`).join(" ");
+};
+const shortGoal = (goal, max) => {
+    const clause = goal.split(/[,;.?!]/, 1)[0].trim();
+    if (clause.length <= max)
+        return clause;
+    if (max <= 3)
+        return clause.slice(0, Math.max(0, max));
+    return `${clause.slice(0, max - 3).trimEnd()}...`;
 };
 // VIS-11 (v1.13): a liveness header for renderFrame — last journal event age + whether the recorded
 // daemon pid is still alive. Honest about unknowns: a pre-v1.13 journal with no pid renders "unknown",
@@ -72,14 +85,14 @@ const daemonPid = (events) => {
     }
     return undefined;
 };
-const livenessLine = (events) => {
+const liveness = (events) => {
     const last = events.at(-1);
     if (!last)
-        return null; // nothing to be honest about
+        return "last event unknown · daemon pid unknown";
     const age = fmtAge(Date.now() - Date.parse(last.ts));
     const pid = daemonPid(events);
     if (pid === undefined)
-        return `  last event ${age} ago · daemon pid unknown`;
+        return `last event ${age} ago · daemon pid unknown`;
     let state;
     try {
         process.kill(pid, 0);
@@ -88,17 +101,14 @@ const livenessLine = (events) => {
     catch (k) {
         state = k.code === "ESRCH" ? "dead" : "alive";
     } // EPERM ⇒ alive
-    return `  last event ${age} ago · daemon pid ${pid} ${state}`;
+    return `last event ${age} ago · daemon pid ${pid} ${state}`;
 };
 const renderFrame = (cwd) => {
     const g = loadGraph(cwd);
     const runId = Journal.latestRunId(cwd);
     const assignments = new Map();
-    const gates = new Map();
     let replayed = null;
     let events = [];
-    // v1.23 T2: latest known context tokens per task (from context-sample journal events). Informational
-    // only — never feeds status/phase/gate classification (derivePhase and replayStatuses ignore them).
     const contexts = new Map();
     if (runId) {
         const j = Journal.open(cwd, runId);
@@ -107,11 +117,8 @@ const renderFrame = (cwd) => {
         for (const e of events) {
             if (e.event === "task-dispatch" && e.taskId) {
                 const a = e.data.assignment;
-                assignments.set(e.taskId, `${a.adapter}:${a.model}`);
-            }
-            if (e.event === "gate-result" && e.taskId) {
-                const prev = gates.get(e.taskId) ?? "";
-                gates.set(e.taskId, `${prev}${e.data.pass ? "✓" : "✗"}${e.data.gate} `);
+                if (typeof a.adapter === "string" && typeof a.model === "string")
+                    assignments.set(e.taskId, `${a.adapter}:${a.model}`);
             }
             if (e.event === "context-sample" && e.taskId && typeof e.data.tokens === "number" && Number.isFinite(e.data.tokens)) {
                 contexts.set(e.taskId, e.data.tokens); // last write wins
@@ -121,22 +128,26 @@ const renderFrame = (cwd) => {
     const effective = { ...g, tasks: g.tasks.map((t) => ({ ...t, status: replayed?.get(t.id) ?? t.status })) };
     const starved = new Set(blockedTasks(effective).map((t) => t.id));
     const waiting = new Set(pendingTasks(effective).map((t) => t.id));
+    const unicode = visual();
+    const divider = unicode ? " · " : " / ";
     const rows = g.tasks.map((t) => {
         const st = replayed?.get(t.id) ?? t.status;
         const label = starved.has(t.id) ? " starved" : waiting.has(t.id) ? " dep-waiting" : "";
-        const phase = derivePhase(t, events, assignments.get(t.id)) || "-";
-        const base = assignments.get(t.id) ?? "-";
-        const ctx = contexts.get(t.id);
-        // Informational suffix only when known — never invents 0 from absence.
-        const assignCol = ctx !== undefined ? `${base} · ctx ${ctx}` : base;
-        return `  ${t.id.padEnd(6)} ${String(st).padEnd(8)} ${phase.padEnd(28)} ${assignCol.padEnd(28)} ${gates.get(t.id) ?? ""}${label}`;
+        const channel = assignments.get(t.id) ?? "-";
+        const assignCol = contexts.has(t.id) ? `${channel}${divider}ctx ${contexts.get(t.id)}` : channel;
+        const chain = gateChain(t, events, unicode);
+        const statusText = color(String(st), st === "done" ? 32 : st === "failed" ? 31 : st === "human" ? 33 : 36, unicode);
+        const suffix = `  ${chain}  ${String(st)}${label}  ${assignCol}`;
+        const width = process.stdout.columns ?? 120;
+        const prefix = `  ${taskBox(st, unicode)} ${t.id} `;
+        return `${prefix}${shortGoal(t.goal, Math.max(0, width - prefix.length - suffix.length))}  ${chain}  ${statusText}${label}  ${assignCol}`;
     });
-    return [
-        `drovr status${runId ? ` — run ${runId}` : " — no runs yet"}`,
-        ...(runId ? [livenessLine(events)].filter((l) => l !== null) : []),
-        "  task   status   phase                        assignment                   gates",
-        ...rows,
-    ].join("\n");
+    const done = effective.tasks.filter((t) => t.status === "done").length;
+    const header = runId
+        ? `tickmarkr status${divider}run ${runId}${divider}${liveness(events).replaceAll(" · ", divider)}${divider}${done}/${g.tasks.length} done`
+        : `tickmarkr status${divider}no runs yet${divider}${done}/${g.tasks.length} done`;
+    const legend = `  gates: ${GATE_NAMES.map((gate) => `${GATE_KEYS[gate]} ${gate}`).join(divider)}`;
+    return [header, legend, ...rows].join("\n");
 };
 export async function status(argv, cwd = process.cwd(), opts = {}) {
     if (!argv.includes("--watch"))
@@ -146,7 +157,7 @@ export async function status(argv, cwd = process.cwd(), opts = {}) {
     const bounded = Number.isFinite(iterations);
     const frames = [];
     const sep = "\n---\n";
-    const tty = process.stdout.isTTY;
+    const tty = visual();
     for (let i = 0; i < iterations; i++) {
         const frame = renderFrame(cwd);
         if (tty)

package/dist/cli/index.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 export type CommandMap = Record<string, (argv: string[]) => Promise<string>>;
 export declare const COMMANDS: CommandMap;
-export declare const USAGE = "drovr \u2014 spec-driven orchestration harness for AI coding agents\nusage: drovr <command>\n  init          guided setup + doctor\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 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;
     code: number;

package/dist/cli/index.js

@@ -16,9 +16,9 @@ import { unlock } from "./commands/unlock.js";
 export const COMMANDS = {
     init, doctor, compile, scope, plan, run, status, resume, report, profile, unlock, approve,
 };
-export const USAGE = `drovr — spec-driven orchestration harness for AI coding agents
-usage: drovr <command>
-  init          guided setup + doctor
+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
   doctor        re-probe adapters, herdr, auth; print capability matrix
   compile <src> spec → .drovr/graph.json (fails without acceptance criteria)
   scope <intent> draft a compiled native spec beside an answered intent (--force to overwrite)
@@ -41,7 +41,7 @@ export async function dispatch(cmd, argv, commands = COMMANDS) {
         return { out: await fn(argv), code: 0 };
     }
     catch (err) {
-        return { out: `drovr ${cmd}: ${err.message}`, code: 1 };
+        return { out: `tickmarkr ${cmd}: ${err.message}`, code: 1 };
     }
 }
 /* v8 ignore start -- binary entry: printing + process.exit side effects, not unit-testable (ROADMAP crit 2) */

package/dist/compile/native.js

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { GATE_NAMES, ORACLES, SHAPES, TIERS, validateGraph } from "../graph/schema.js";
 import { CompileError, inferShape, sha256 } from "./common.js";
-export const NATIVE_MARKER = /^<!--\s*drovr:spec(?:\s+v1)?\s*-->\s*$/m;
+export const NATIVE_MARKER = /^<!--\s*(?:tickmarkr|drovr):spec(?:\s+v1)?\s*-->\s*$/m;
 const HEAD_RE = /^## (T\d+):\s*(.+)$/;
 const FIELD_RE = /^- (\w+):\s*(.*)$/;
 const NESTED_RE = /^\s+- (.+)$/;
@@ -143,7 +143,7 @@ export function compileNative(file) {
 // parser ignores) so the template itself round-trips through compileSource() unchanged. Every field is
 // documented; the two example tasks illustrate plain vs deps+routing-hint, each with acceptance[].
 export function specTemplate() {
-    return `<!-- drovr:spec -->
+    return `<!-- tickmarkr:spec -->
 # drovr native spec
 
 Your starting point for a drovr native spec. Edit this file, then run:

package/dist/drivers/herdr.d.ts

@@ -11,10 +11,13 @@ export declare class HerdrDriver implements ExecutorDriver {
     private groups;
     private groupSerial;
     private ws;
+    private callerPane;
+    private watches;
     constructor(bin?: string, workersPerTab?: number);
     private serial;
     static available(): boolean;
     private herdr;
+    private namedPaneId;
     private paneId;
     private paneWidth;
     slot(cwd: string, name: string, opts?: SlotOpts): Promise<Slot>;
@@ -36,6 +39,8 @@ export declare class HerdrDriver implements ExecutorDriver {
     notify(msg: string, opts?: NotifyOpts): Promise<void>;
     close(slot: Slot): Promise<void>;
     private closeGrouped;
+    private priorWatch;
+    private watchSlot;
     narrator(cwd: string, command: string, runId?: string): Promise<Slot>;
     reconcile(desired: Set<string>, runId: string, opts?: {
         spareLiveLlm?: boolean;

package/dist/drivers/herdr.js

@@ -1,7 +1,7 @@
 import { shq } from "../adapters/types.js";
 import { createWorktree, sh } from "../run/git.js";
 import { herdrSealShellPrefix } from "./subprocess.js";
-import { canonicalizeLegacyName, formatOwnedName, panesToClose } from "./types.js";
+import { canonicalizeLegacyName, formatOwnedName, panesToClose, parseOwnedName } from "./types.js";
 // VIS-09 P43-03: adopted safety floor from 43-MEASUREMENT.md (narrowest safe 53 → floor 108).
 export const TRAILER_SAFE_FLOOR_COLS = 108;
 export const TRAILER_WIDTH_MARGIN = 2; // cols below (floor + margin) refuse a rightward first split
@@ -24,6 +24,8 @@ export class HerdrDriver {
     // operator's env before the driver is built). Required at slot() time, never in the constructor —
     // pickDriver and its unit test construct HerdrDriver without env, so slot() is the trust gate.
     ws = process.env.HERDR_WORKSPACE_ID;
+    callerPane = process.env.HERDR_PANE_ID;
+    watches = new Map();
     constructor(bin = "herdr", workersPerTab = 3) {
         this.bin = bin;
         this.workersPerTab = workersPerTab;
@@ -39,18 +41,21 @@ export class HerdrDriver {
     herdr(args, cwd = process.cwd(), timeoutMs) {
         return sh(`${shq(this.bin)} ${args}`, cwd, timeoutMs);
     }
-    // pane ids compact when panes close — resolve fresh via the durable agent name (spec §5)
-    async paneId(slot) {
-        const r = await this.herdr(`agent get ${shq(slot.name)}`);
+    async namedPaneId(name) {
+        const r = await this.herdr(`agent get ${shq(name)}`);
+        if (r.code !== 0)
+            return null;
         try {
             const id = JSON.parse(r.stdout).result?.agent?.pane_id;
-            if (typeof id === "string" && id)
-                return id;
+            return typeof id === "string" && id ? id : null;
         }
         catch {
-            /* fall back to cached id */
+            return null;
         }
-        return slot.id;
+    }
+    // pane ids compact when panes close — resolve fresh via the durable agent name (spec §5)
+    async paneId(slot) {
+        return await this.namedPaneId(slot.name) ?? slot.id;
     }
     // VIS-09 P43-03: runtime width for the layout gate (43-MEASUREMENT.md licensing condition 2).
     async paneWidth(paneId) {
@@ -310,6 +315,13 @@ export class HerdrDriver {
         await this.herdr(`notification show ${shq(msg)} --sound ${opts?.tier === "attention" ? "request" : opts?.sound ?? "request"}`);
     }
     async close(slot) {
+        if (this.watches.get(slot.name)?.id === slot.id) {
+            this.watches.delete(slot.name);
+            const pane = await this.namedPaneId(slot.name);
+            if (pane)
+                await this.herdr(`pane close ${shq(pane)}`);
+            return; // run-end reconcile may already have reaped it; never close a compacted stale id
+        }
         if (slot.group && this.groups.has(slot.group)) {
             return this.serial(() => this.closeGrouped(slot));
         }
@@ -342,16 +354,95 @@ export class HerdrDriver {
                 this.groups.delete(slot.group); // group dies when all generations gone
         }
     }
-    // T6 narrator: the run's single live surface — a drovr-created "watch" tab running the daemon's
-    // status command. Reuses the dedicated-tab slot path (label → tabSlot); close() reaps the whole tab
-    // at run end. One per run (the daemon calls this once). Failures propagate — the daemon swallows.
-    // T2: with a runId the pane is named canonically (drovr:watch:run:0:<runId>) so reconcile owns it;
-    // the legacy `narrator-watch-<pid>` shape survives for runId-less callers (canonicalizeLegacyName).
+    async priorWatch(runId) {
+        if (!this.ws)
+            throw new Error("herdr watch placement requires HERDR_WORKSPACE_ID — refusing unseeded pane");
+        const list = await this.herdr("agent list");
+        if (list.code !== 0)
+            throw new Error(`herdr agent list failed: ${list.stderr || list.stdout}`);
+        let agents;
+        try {
+            agents = JSON.parse(list.stdout).result?.agents;
+        }
+        catch {
+            throw new Error(`herdr agent list returned unparseable JSON: ${list.stdout}`);
+        }
+        if (!Array.isArray(agents))
+            throw new Error(`herdr agent list returned no agents: ${list.stdout}`);
+        const prior = agents.find((a) => {
+            const owned = typeof a.name === "string" ? parseOwnedName(a.name) : null;
+            return a.workspace_id === this.ws && typeof a.pane_id === "string" && owned?.role === "watch" && owned.taskId === "run" && owned.runId !== runId;
+        });
+        return prior?.pane_id ?? null;
+    }
+    // T2: the watch is a rightward sibling of the daemon's own pane, never a separate tab. Its durable
+    // owned name lets a resumed daemon find an already-running watch instead of stacking another one.
+    async watchSlot(cwd, name) {
+        if (!this.ws)
+            throw new Error("herdr watch placement requires HERDR_WORKSPACE_ID — refusing unseeded pane");
+        if (!this.callerPane)
+            throw new Error("herdr watch placement requires HERDR_PANE_ID — refusing untargeted split");
+        const sp = await this.herdr(`pane split ${shq(this.callerPane)} --direction right --no-focus`);
+        if (sp.code !== 0)
+            throw new Error(`herdr watch split failed: ${sp.stderr || sp.stdout}`);
+        let pane;
+        try {
+            pane = JSON.parse(sp.stdout).result?.pane?.pane_id;
+        }
+        catch {
+            /* fail closed below */
+        }
+        if (typeof pane !== "string" || !pane)
+            throw new Error(`herdr watch split returned no pane id: ${sp.stdout}`);
+        const renamed = await this.herdr(`agent rename ${shq(pane)} ${shq(name)}`);
+        if (renamed.code !== 0 || await this.namedPaneId(name) !== pane) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            throw new Error(`herdr watch rename failed: ${renamed.stderr || renamed.stdout}`);
+        }
+        const seed = await this.herdr(`pane run ${shq(pane)} ${shq(`cd ${shq(cwd)}; export HERDR_WORKSPACE_ID=${shq(this.ws)}; ${herdrSealShellPrefix()}`)}`, cwd);
+        if (seed.code !== 0) {
+            await this.herdr(`pane close ${shq(pane)}`);
+            throw new Error(`herdr watch seed failed: ${seed.stderr || seed.stdout}`);
+        }
+        return { id: pane, name, cwd };
+    }
+    // T6 narrator: the run's single live status surface. Reuse a local or already-running owned watch;
+    // a new run reowns its prior watch, and only a newly split pane receives the watch command. The
+    // status command reads the latest run every frame, so the renamed pane follows the new run without
+    // interrupting the operator's watch loop. Failures propagate — the daemon swallows.
     async narrator(cwd, command, runId) {
         const name = runId ? formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId }) : `narrator-watch-${process.pid}`;
-        const s = await this.slot(cwd, name, { label: "watch" });
-        await this.run(s, command);
-        return s;
+        return this.serial(async () => {
+            const cached = this.watches.get(name);
+            if (cached)
+                return cached;
+            const existing = await this.namedPaneId(name);
+            if (existing) {
+                const s = { id: existing, name, cwd };
+                this.watches.set(name, s);
+                return s;
+            }
+            const prior = runId ? await this.priorWatch(runId) : null;
+            if (prior) {
+                const renamed = await this.herdr(`agent rename ${shq(prior)} ${shq(name)}`);
+                if (renamed.code !== 0 || await this.namedPaneId(name) !== prior) {
+                    throw new Error(`herdr watch reclaim failed: ${renamed.stderr || renamed.stdout}`);
+                }
+                const s = { id: prior, name, cwd };
+                this.watches.set(name, s);
+                return s;
+            }
+            const s = await this.watchSlot(cwd, name);
+            this.watches.set(name, s);
+            try {
+                await this.run(s, command);
+            }
+            catch (err) {
+                this.watches.delete(name);
+                throw err;
+            }
+            return s;
+        });
     }
     // OBS-17 T2 / v1.22b T1: close every drovr-owned pane that should not exist (superseded attempts,
     // killed-daemon orphans, leftovers from OLDER runs) — in this run's workspace OR misplaced in any

package/dist/drivers/types.js

@@ -20,19 +20,20 @@ export function parseOwnedName(name) {
 export function isForeignName(name) {
     return parseOwnedName(name) === null;
 }
-// v1.22b T1: workspace-aware fold over a fleet snapshot — decides which owned panes are garbage
+// v1.22b T1: workspace-aware fold over a fleet snapshot — decides which owned task panes are garbage
 // right now. In-workspace: the existing desired-set/spareLiveLlm sweep (OBS-17 T2). Out-of-workspace:
 // an owned pane from a DIFFERENT run is a misplaced leftover (bug, foreign actor, pre-VIS-10 relic)
 // and closes regardless of `desired`; an owned pane from THIS run elsewhere is left alone — a live
 // run can legitimately hold panes across workspaces, so only run age marks a misplaced pane garbage.
-// Foreign names (parseOwnedName fails) are never candidates, in any workspace.
+// Watch panes are operator-owned after run end and are reclaimed by the next run; foreign names
+// (parseOwnedName fails) are never candidates, in any workspace.
 export function panesToClose(agents, desired, ws, runId, opts) {
     const out = [];
     for (const a of agents) {
         if (typeof a.name !== "string" || typeof a.paneId !== "string")
             continue;
         const owned = parseOwnedName(a.name);
-        if (!owned)
+        if (!owned || owned.role === "watch")
             continue;
         if (a.workspaceId === ws) {
             if (desired.has(a.name))

package/dist/plan/prompt.js

@@ -3,7 +3,7 @@ export function scopePrompt(intent, repair) {
 You are drafting a drovr native spec from an answered intent. Return only the Markdown spec, with no commentary or code fence.
 
 The draft must:
-- start with <!-- drovr:spec -->
+- start with <!-- tickmarkr:spec -->
 - include a Requirements section whose ids are sequential REQ-01, REQ-02, ...
 - include an Assumptions section that makes every residual uncertainty explicit
 - include a Traceability section mapping every REQ-nn to at least one Tn task

package/dist/plan/scope.js

@@ -2,7 +2,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "no
 import { tmpdir } from "node:os";
 import { basename, dirname, extname, join } from "node:path";
 import { discoverChannels, getAdapter, probeAll } from "../adapters/registry.js";
-import { compileNative } from "../compile/native.js";
+import { compileNative, NATIVE_MARKER } from "../compile/native.js";
 import { pickDriver } from "../drivers/index.js";
 import { extractJson, runLlm } from "../gates/llm.js";
 import { TaskSchema } from "../graph/schema.js";
@@ -64,12 +64,12 @@ function extractDraft(raw) {
     const fenced = [...clean.matchAll(/```(?:markdown|md)?\s*\n([\s\S]*?)```/gi)].at(-1)?.[1];
     if (fenced)
         return fenced;
-    const marker = clean.indexOf("<!-- drovr:spec");
+    const marker = clean.search(/<!--\s*(?:tickmarkr|drovr):spec/);
     return (marker === -1 ? clean : clean.slice(marker)).trimEnd() + "\n";
 }
 function validateDraft(draft) {
-    if (!/^<!--\s*drovr:spec(?:\s+v1)?\s*-->/m.test(draft))
-        throw new Error("draft is missing the drovr native marker");
+    if (!NATIVE_MARKER.test(draft))
+        throw new Error("draft is missing the tickmarkr native marker");
     if (!section(draft, "Assumptions").trim())
         throw new Error("draft is missing explicit assumptions");
     const requirements = [...new Set(section(draft, "Requirements").match(/\bREQ-\d{2}\b/g) ?? [])];

package/dist/run/daemon.js

@@ -38,9 +38,8 @@ export async function runDaemon(repoRoot, opts = {}) {
     // BEFORE loadGraph; release in the finally below (every exit path, incl. throws).
     const runId = opts.runId ?? newRunId();
     // T6 narrator: one live status surface per run (herdr only — driver.narrator is undefined on
-    // subprocess, so the optional-chain open below is a no-op there). Declared out here so the finally
-    // can close it on every exit path. Cosmetic-only: any failure is swallowed (never affects the run).
-    let narrator = null;
+    // subprocess, so the optional-chain open below is a no-op there). Cosmetic-only: any failure is
+    // swallowed (never affects the run); the operator closes a surviving watch pane.
     const lock = acquireRunLock(repoRoot, runId);
     try {
         let graph = loadGraph(repoRoot);
@@ -91,10 +90,10 @@ export async function runDaemon(repoRoot, opts = {}) {
         // show. driver.narrator is undefined on subprocess → no-op (subprocess spawns nothing). Swallowed:
         // a failed-to-open or later-dead watch pane never affects the run.
         try {
-            narrator = await driver.narrator?.(repoRoot, "drovr status --watch", runId) ?? null;
+            await driver.narrator?.(repoRoot, "drovr status --watch", runId);
         }
         catch {
-            narrator = null; // cosmetic-only — the run proceeds without a live surface
+            /* cosmetic-only — the run proceeds without a live surface */
         }
         const intWt = await ensureIntegration(repoRoot, branch, baseRef);
         const concurrency = opts.concurrency ?? cfg.concurrency;
@@ -716,13 +715,6 @@ export async function runDaemon(repoRoot, opts = {}) {
         return summary;
     }
     finally {
-        // T6: close the narrator at run end — cosmetic, swallowed (never blocks lock release)
-        if (narrator) {
-            try {
-                await driver.close(narrator);
-            }
-            catch { /* cosmetic */ }
-        }
         releaseRunLock(repoRoot);
     }
 }

package/dist/run/reconcile.js

@@ -88,6 +88,7 @@ export function desiredPanes(rows, runId) {
                 break;
             case "run-end":
                 desired.clear();
+                desired.add(formatOwnedName({ role: "watch", taskId: "run", attempt: 0, runId }));
                 break;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tickmarkr",
-  "version": "1.30.0",
+  "version": "1.33.0",
   "description": "Spec in, verified work out.",
   "type": "module",
   "license": "MIT",
@@ -9,12 +9,12 @@
   },
   "bin": {
     "tickmarkr": "dist/cli/index.js",
-    "drovr": "dist/cli/index.js",
-    "drover": "dist/cli/index.js"
+    "tkr": "dist/cli/index.js"
   },
   "files": [
     "dist",
-    "schema"
+    "schema",
+    "skills"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/skills/tickmarkr-auto/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: tickmarkr-auto
+description: 'Run a repository’s requested specs autonomously with tickmarkr. Triggers: "/tickmarkr-auto", "run these specs with tickmarkr", "autonomous tickmarkr run".'
+argument-hint: "[spec-or-directory ...]"
+---
+
+# tickmarkr-auto — run repository specs autonomously
+
+Use this to execute a requested sequence of repository specs. It is SDD-agnostic: each target can be any file or directory accepted by `tickmarkr compile`.
+
+## Two-tier by default — role check before the loop
+
+When working in a multi-agent terminal environment, decide your role before starting:
+
+- **Orchestrator:** your session was started to execute the mission. Run the loop below.
+- **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a verified send, then supervise it.
+- **Primary session without an orchestrator:** create one child orchestration session, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself.
+
+Outside a multi-agent terminal environment, run the loop directly.
+
+## Invariants
+
+- Never run two tickmarkr runs in the same repository concurrently.
+- Never let tickmarkr merge work to the main branch. New work consolidates on `tickmarkr/<runId>`.
+- Do not edit a generated graph to force an outcome; correct the source spec and compile again.
+- Gates independently verify evidence, scope, acceptance criteria, and review. A worker's completion claim is not evidence.
+- Treat missing or unparseable machine results and verdicts as failures. Never bypass a failed gate or merge partial work without a human decision.
+
+## Act by default
+
+Run every requested target in order without seeking routine confirmation. Stop only for a blocked agent interaction, a genuinely unresolved stalled task, a designed human gate, or a failed run that needs a human decision. Diagnose from the journal and evidence first; self-release and resume only after fixing and verifying a harness defect.
+
+## Per-spec loop
+
+1. **Prepare** — confirm the target list, check `git status`, confirm no tickmarkr run is active, and work from a non-main branch.
+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.
+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

@@ -0,0 +1,39 @@
+---
+name: tickmarkr-loop
+description: 'Run one repository spec autonomously with tickmarkr. Triggers: "/tickmarkr-loop", "run this spec with tickmarkr", "tickmarkr the spec".'
+---
+
+# tickmarkr-loop — run one spec autonomously
+
+Use this for any spec that `tickmarkr compile` accepts. It is SDD-agnostic: use the repository's requested spec format and keep the execution record beside that source spec.
+
+## Two-tier by default — role check before the loop
+
+When working in a multi-agent terminal environment, decide your role before starting:
+
+- **Orchestrator:** your session was started to execute the mission. Run the loop below.
+- **Supervisor with a live orchestrator:** do not start a second run. Relay the mission to the existing orchestrator with a verified send, then supervise it.
+- **Primary session without an orchestrator:** create one child orchestration session, give it the mission and these rules verbatim, then supervise it. Do not drive a duplicate single-tier run yourself.
+
+Outside a multi-agent terminal environment, run the loop directly.
+
+## Invariants
+
+- Never run two tickmarkr runs in the same repository concurrently.
+- Never let tickmarkr merge work to the main branch. New work consolidates on `tickmarkr/<runId>`.
+- Do not edit the compiled graph to force an outcome; fix the source spec and compile again.
+- Gates verify commits, diffs, acceptance criteria, and reviews independently. Never trust a worker's claim that work is complete.
+- Treat missing or unparseable machine results and verdicts as failures. Do not release, resume, or merge around failed gates.
+
+## Act by default
+
+Proceed through the loop without seeking routine confirmation. Stop only for a blocked agent interaction, a genuinely unresolved stalled task, or a designed human gate. Diagnose from the journal and available evidence before escalating; if a harness defect is fixed and verified, resume the run.
+
+## The loop
+
+1. **Prepare** — start from the requested spec. Check `git status`, confirm no tickmarkr run is active, and work from a non-main branch.
+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.
+6. **Record** — write `tickmarkr report <runId> --md` beside the source spec and commit the execution record when the repository tracks those records.