@julioborges/gantry 0.1.0

package/.agents/skills/gantry/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: gantry
+description: Harness-neutral agentic SDLC workflow. Resolves ready Issues deterministically, plans only to operator approval, implements with TDD, reviews against standards and Spec, and accepts delivery only after adversarial verification.
+argument-hint: <spec-slug | spec#NN | wave:N | frontier | all | "free-text goal"> [--limit N] [--budget N]
+---
+
+# Gantry
+
+Gantry is a harness-neutral skill pack, not an execution engine. Workflow scripts decide readiness,
+acceptance, gates and roadmap state; agents plan, implement, review and refute; the operator makes
+approval decisions in the host harness.
+
+```
+preflight → models → frontier.py → planned round loop
+                         └→ spec.py --check → Requirement Critic → research → draft plan → critique
+                            → STOP for operator approval
+round: implement (TDD) → review (standards + Spec) → Critic → serial integration → roadmap.py done
+```
+
+## Resolve the portable runtime
+
+Before a Run, resolve these values once and pass them as `args` to every reference workflow:
+
+1. `skillDir` is this `gantry` directory as an absolute real path. A harness-specific symlink resolves
+   through `realpath`; never assume a fixed installation directory.
+2. `repoRoot` is the enclosing Git repository or worktree (`common.repo_root()`).
+3. `policy` is `common.resolve_policy(repoRoot)`: Gantry's sparse defaults overlaid by
+   `<repoRoot>/.gantry/config.json` when present. A missing repository policy is valid.
+4. `paths` comes from `common.resolve_workflow_paths(repoRoot, scopeSlug)`. Prompts receive paths, not
+   repository-specific literals.
+
+Run the standard-library workflow scripts as `python3 <skillDir>/scripts/<script>.py`. `common.py` provides
+the shared Markdown parser and policy resolution; its `--json` path prints the resolved portable runtime.
+Every script provides `--help`, and data-producing paths support `--json`.
+
+## Workflow rules
+
+- Preflight refuses a dirty worktree, offers a dedicated Run worktree before creating anything, resolves
+  the effective policy, checks `roadmap.py check`, and asks models for Plan, Implement, Review and Critic.
+  Preflight also resolves `unitId` (`runlog.py unit-id --cwd <repoRoot> --json`) and a fresh `runId`, then
+  queries `runlog.py inflight <unitId> --json`. Every match names an Issue still `ready-for-agent`, its
+  phase and its preserved worktree; preflight offers the operator continuation there before doing anything
+  else. `runlog.py inflight` reports only `run`, `issue`, `phase`, `worktree`, `repositoryRoot`,
+  `policyHash`, `tier` and `staleAfterSeconds` — it does not report `correctionsSpent` or `branch`, so
+  preflight derives them before building `args.priorRun` by invoking the shipped query
+  `runlog.py corrections <unitId> <match.run> <match.issue> --json`, which reads the match's own Run log
+  (`~/.gantry/state/<unitId>/runs/<match.run>.jsonl`, or `--state-root` when overridden) and returns
+  `correctionsSpent` as the sum of two counts: (1) the `run.resumed.data.correctionsSpent` recorded in
+  that same Run log, but only when that same `run.resumed` event's `data.issue` also equals `match.issue`
+  — `0` when the log has no `run.resumed` event, or when its `run.resumed` names a different Issue, since
+  the base is per-Issue and must never be lent to another Issue that happens to share the Run log; plus
+  (2) the number of `refutation` events in that log whose `issue` equals `match.issue` and that are each
+  followed, later in the log, by a `phase.started` event for `Implement` on that same Issue — i.e. only
+  refutations whose correction pass actually started count toward the spent budget. Neither this
+  derivation rule nor `correctionsSpent` itself is ever computed by prose or by test code: this shipped
+  command is the single implementation, and it fails closed (`runlog error: no Run log for <runId>`,
+  exit 1) when no Run log exists for the requested Run ID, rather than silently reporting `0`.
+  `branch` is optional: when omitted, `reference/round-workflow.md` derives it itself from
+  `common.issue_branch` and verifies it with `git branch --show-current` in the preserved worktree
+  (see `implementationLocation`). Only explicit acceptance carries the derived match forward as
+  `args.priorRun` (`run`, `worktree`, `issue`, `correctionsSpent`, `policyHash`, and `branch` when known)
+  into `reference/round-workflow.md`, which appends `run.resumed` naming the prior Run and worktree
+  instead of starting a fresh worktree, and resumes the spent correction count instead of resetting it.
+  When the prior Run's `policyHash` differs from the effective policy resolved for this Run,
+  `reference/round-workflow.md` appends `policy.changed` with the new hash so the drift is recorded
+  before any Issue work resumes. The Run log is read only to offer that continuation and to derive
+  `correctionsSpent`; it never decides readiness or completion — `frontier.py`, Issue `Status:` lines
+  and `roadmap.py` do.
+- `reference/round-workflow.md` appends every recorded-Run lifecycle event through `runlog.py append
+  <unitId> <runId>` when the caller supplies both. A Run spans one or more rounds, each a separate
+  invocation of this workflow sharing the same `runId`/`unitId`: only the first round (`args.isFirstRound`
+  not explicitly `false`) appends `run.started` (with the repository root, a policy hash, the harness
+  tier and the effective `staleAfterSeconds` in `data`) and, when resuming, `run.resumed` and
+  `policy.changed`; every subsequent round of the same Run passes `args.isFirstRound = false` so these
+  three events are never appended again — a Run log accepts only one `run.started` and rejects a
+  duplicate. Every round, first or not, then appends `round.started`, one `phase.started` /
+  `phase.finished` pair per phase that actually runs (Implement, Review and Critic per Issue, plus the
+  optional Learner phase on the last round when it finds recurring evidence), one
+  `subagent.started` / `subagent.stopped` pair per fresh agent carrying its role result,
+  `review.finding` after the Reviewer returns, `refutation` on every non-accepted Critic verdict,
+  `issue.blocked` when the correction ceiling is spent without acceptance, `issue.done` on successful
+  integration, `run.cancelled` on the first red post-merge gate, and `round.finished`. Only the last round
+  of a Run (`args.isLastRound = true`) appends `run.finished`, once, and only after the optional Learner
+  phase (see below) has already run and recorded its own `phase.started`/`subagent.started`/
+  `subagent.stopped`/`phase.finished` events — `run.finished` remains the final event of a completed Run,
+  never followed by a subagent.
+  The Critic's `subagent.stopped` carries a projection of its verdict, never the verdict unchanged: its
+  `gateResult` is a real `gates.py --json` payload, and `runlog.py append` fails loudly on any
+  `command`/`output`-tokenized field at any depth (its own rule), which a real `gates[].command` and
+  `gates[].output_tail` are. `reference/round-workflow.md`'s `projectCriticResult` keeps `complete`,
+  `criteria`, `gatesVerdict`, `gateFailures`, `refutations`, `requiredFixes` and `decisionsForOperator`
+  as returned, and narrows `gateResult` to only its `verdict` and `requirements` — dropping `gates`
+  entirely — so a genuine gates run never fails the append and the Run log still records only the
+  Critic's role result and reasoning, never command output. Every other role's `subagent.stopped` still
+  carries its result unprojected, and `runlog.py` still rejects it if it ever carries prohibited data.
+  `issue.blocked` records only a Run-log fact: the Issue's `Status:` line stays `ready-for-agent` so
+  `frontier.py` keeps offering it, and only `roadmap.py done` after Critic acceptance ever changes an
+  Issue's authoritative status. Omitting `runId` or `unitId` disables recording entirely and leaves the
+  round behaviorally identical, so a harness with no resolved Run log keeps working.
+- Before any agent works in a worktree, the round workflow marks it with the Run — `runlog.py mark
+  <runId> --cwd <worktree>`, stored in that worktree's own git directory — and clears it with
+  `runlog.py unmark` when the Run ends, never between rounds. The tracked git hooks
+  (`hooks/git/pre-commit`, `hooks/git/pre-push`) and `guard.py` resolve the Run in one order:
+  `GANTRY_RUN_ID` when the caller exports it, then the marker, and a harness session ID only when
+  nothing else names a Run and its Run log already exists — a Claude Code or OpenCode session ID is
+  a session, not a Run, and no Run log is ever keyed by it. That is what makes a denial inside a Run
+  always recorded as `hook.denied`; git keeps one git directory per worktree, so concurrent
+  worktrees of one execution unit never attribute a denial to each other's Run. Because each round
+  is a separate invocation, the Run's end enumerates `git worktree list --porcelain` and clears
+  every marker naming that Run, so a worktree marked by an earlier round is never left behind.
+- Use `frontier.py --scope <scope> --json` as the only authority for dependency rounds. Exit 1 for a
+  cyclic or dangling blocker graph. Parked `draft`, `blocked`, and `needs-operator` Issues are reported
+  and skipped.
+- Before slicing, `spec.py --check` validates the Spec's structure and then the read-only Requirement
+  Critic (Critic model) assesses ambiguity, coherence, verifiability and non-goal coverage. A blocking
+  finding stops the run, quotes the finding, and tells the operator to amend the Spec; the Critic never
+  edits it. Neither structural validation nor Requirement Review approves planning — only explicit
+  operator approval does.
+- Planning creates draft Issues and never edits `ROADMAP.md`. Present drafts and the critic verdict, then
+  stop. Only explicit operator approval permits `roadmap.py status <ref> ready-for-agent`, followed by
+  `roadmap.py waves` and `roadmap.py check`.
+- Each Issue follows `reference/round-workflow.md`: a fresh TDD implementer, a reviewer on both standards
+  and Spec axes, one review fix pass, then a fresh adversarial Critic. The Critic alone can establish a
+  complete delivery. Its refutation consumes at most the correction budget.
+- A multi-Issue round uses one isolated worktree and branch per implementer. Integrate accepted branches
+  serially, run gates after every merge, and stop on a failed integration gate. Create and identify each
+  Issue branch through the `git.issueBranch` policy template (default
+  `{prefix}{spec}-{number:02d}`), rendered by `common.issue_branch(policy, issue)`.
+- Only after Critic acceptance, green gates and a clean worktree may the orchestrator run
+  `roadmap.py done <ref>`. Never hand-edit Issue status, criteria checkboxes or the roadmap.
+- At the end of a Run, execute `python3 <skillDir>/scripts/cleanup.py --plan --json` from the Run worktree
+  and present its JSON output as the actual, read-only cleanup plan for the operator's authorization.
+  Only after explicit Cleanup Authorization may the workflow pass that unchanged JSON to
+  `cleanup.py --yes --plan-file <authorized-plan.json>`; it revalidates the plan against the repository
+  state and refuses any divergence. The workflow never executes `cleanup.py --yes` automatically.
+- After the last round, the optional Learner (`reference/round-workflow.md`) reads only the refutation
+  and review-finding events already recorded in the Run log and drafts a lesson candidate for each
+  problem that recurred across Issues or attempts. The final Run report lists every lesson candidate,
+  with its evidence and proposed target, as an operator decision: the workflow never writes a candidate
+  into `AGENTS.md`, `CONTEXT.md`, a template or policy on its own. Pass `args.isLastRound = true` and
+  `args.learnerRunLogs` only for that final frontier round; `learnerRunLogs` is the current Run's own
+  Run-log path(s), normally `~/.gantry/state/<unit-id>/runs/<run-id>.jsonl`. When the Learner actually
+  runs (recurring evidence found), it is recorded exactly like the Implement, Review and Critic phases —
+  `phase.started`, `subagent.started`, `subagent.stopped` and `phase.finished` — appended after
+  `round.finished` and before `run.finished`, so `run.finished` stays the last event of a completed Run.
+  A skipped Learner phase (no logs, or nothing recurring) records none of those four events.
+- After the last round (including the Learner phase), the final `roadmap.py check` and frontier reporting, offer to open a draft pull request from the Run branch to the configured target branch (`policy.git.target`). Generate an English PR body containing each completed Issue's authoritative criteria and Critic evidence. Ask the operator before calling `gh`. Open one draft pull request only on explicit confirmation. If `gh` is unavailable or the operator declines, report the Run branch and configured target as the handoff instead. Never merge, never auto-create a pull request, never create per-Issue pull requests, and never observe provider state. The final English Run report must state the capability-file support tier (`tier`).
+
+## Harness-neutral execution
+
+Use the host harness to ask the operator and spawn agents. Where native workflow scripts, structured
+outputs, parallel agents or worktree isolation are available, use them. Otherwise execute the same
+prompts from the reference files manually and validate their JSON-shaped results before advancing.
+The deterministic scripts and workflow semantics stay identical in every harness. The host's command
+runner contract is `runCommand(command, { cwd, input })`: `input`, when supplied, must be written to the
+command's stdin, not appended to the command line. Every recorded Run event goes through
+`runlog.py append <unitId> <runId>` this way, with the event JSON as `input` — a harness that implements
+`runCommand` without stdin support breaks every recorded round, not just this one.
+
+## References
+
+- `reference/plan-workflow.md` — structural validation, Requirement Critic, research, draft, plan
+  critic and mandatory operator stop.
+- `reference/round-workflow.md` — TDD implementation, two-axis review, adversarial Critic and serial
+  integration contract.
+- `templates/` — default Spec, PRD and Issue structures.

package/.agents/skills/gantry/capabilities/claude-code.json

@@ -0,0 +1,15 @@
+{
+  "tier": "reference",
+  "hooks": true,
+  "structured_output": true,
+  "worktree_isolation": true,
+  "per_role_model": true,
+  "parallel_round": true,
+  "skills_path": ".agents/skills",
+  "hook_events": ["PreToolUse", "PostToolUse", "SubagentStart", "SubagentStop", "PreCompact"],
+  "payload_fields": ["tool_name", "tool_input", "session_id", "transcript_path"],
+  "models": {
+    "claude-opus-4-5": {"contextWindow": 200000},
+    "claude-sonnet-4-5": {"contextWindow": 200000}
+  }
+}

package/.agents/skills/gantry/capabilities/codex.json

@@ -0,0 +1,14 @@
+{
+  "tier": "compatible",
+  "hooks": false,
+  "structured_output": false,
+  "worktree_isolation": false,
+  "per_role_model": false,
+  "parallel_round": false,
+  "skills_path": ".agents/skills",
+  "hook_events": [],
+  "payload_fields": [],
+  "models": {
+    "gpt-5.2-codex": {"contextWindow": 272000}
+  }
+}

package/.agents/skills/gantry/capabilities/opencode.json

@@ -0,0 +1,15 @@
+{
+  "tier": "supported",
+  "hooks": true,
+  "structured_output": false,
+  "worktree_isolation": false,
+  "per_role_model": true,
+  "parallel_round": false,
+  "skills_path": ".agents/skills",
+  "hook_events": ["tool.execute.before", "session.compacted"],
+  "payload_fields": ["tool", "args", "sessionID"],
+  "models": {
+    "anthropic/claude-opus-4-5": {"contextWindow": 200000},
+    "openai/gpt-5.2-codex": {"contextWindow": 272000}
+  }
+}

package/.agents/skills/gantry/dashboard/static/app.js

@@ -0,0 +1,100 @@
+// Read-only Gantry dashboard renderer. This file makes no request that can mutate
+// state: it only polls GET /api/state and rebuilds the swimlane markup from the response.
+(function () {
+  "use strict";
+
+  const POLL_INTERVAL_MS = 1000;
+
+  function badge(label, extraClass) {
+    const span = document.createElement("span");
+    span.className = "badge" + (extraClass ? " " + extraClass : "");
+    span.textContent = label;
+    return span;
+  }
+
+  function renderCard(issue) {
+    const card = document.createElement("div");
+    card.className = "card";
+
+    const title = document.createElement("strong");
+    title.textContent = issue.issue;
+    card.appendChild(title);
+    card.appendChild(document.createElement("br"));
+
+    if (issue.branch) card.appendChild(badge("branch: " + issue.branch));
+    if (issue.worktree) card.appendChild(badge("worktree: " + issue.worktree));
+    Object.keys(issue.models || {}).forEach(function (role) {
+      card.appendChild(badge(role + ": " + issue.models[role]));
+    });
+    if (issue.correctionBudget) {
+      card.appendChild(
+        badge("corrections: " + issue.correctionBudget.used + "/" + issue.correctionBudget.ceiling)
+      );
+    }
+    if (typeof issue.elapsedPhaseSeconds === "number") {
+      card.appendChild(badge("elapsed: " + issue.elapsedPhaseSeconds + "s"));
+    }
+    if (issue.operatorWaiting) {
+      card.appendChild(badge("awaiting operator", "waiting"));
+    }
+    return card;
+  }
+
+  function renderRun(run, columns) {
+    const section = document.createElement("section");
+    section.className = "swimlane" + (run.stale ? " stale" : "");
+
+    const heading = document.createElement("h2");
+    heading.textContent =
+      run.repositoryRoot + " — " + run.run + (run.stale ? " (stale)" : "") + " [tier: " + run.tier + "]";
+    section.appendChild(heading);
+
+    if (run.compactionAt) {
+      section.appendChild(badge("compacted at " + run.compactionAt, "compaction"));
+    }
+
+    const columnsEl = document.createElement("div");
+    columnsEl.className = "columns";
+
+    columns.forEach(function (columnName) {
+      const columnEl = document.createElement("div");
+      columnEl.className = "column";
+      const title = document.createElement("h3");
+      title.textContent = columnName;
+      columnEl.appendChild(title);
+      run.issues
+        .filter(function (issue) {
+          return issue.column === columnName;
+        })
+        .forEach(function (issue) {
+          columnEl.appendChild(renderCard(issue));
+        });
+      columnsEl.appendChild(columnEl);
+    });
+
+    section.appendChild(columnsEl);
+    return section;
+  }
+
+  function render(state) {
+    const root = document.getElementById("swimlanes");
+    root.textContent = "";
+    state.runs.forEach(function (run) {
+      root.appendChild(renderRun(run, state.columns));
+    });
+  }
+
+  function poll() {
+    fetch("/api/state", { cache: "no-store" })
+      .then(function (response) {
+        return response.json();
+      })
+      .then(render)
+      .catch(function () {
+        // A transient fetch failure leaves the previous render in place.
+      });
+  }
+
+  poll();
+  setInterval(poll, POLL_INTERVAL_MS);
+})();

package/.agents/skills/gantry/dashboard/static/index.html

@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Gantry Dashboard</title>
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<body>
+  <header>
+    <h1>Gantry Dashboard</h1>
+    <p>Read-only view of every Run. Nothing on this page can change an Issue, a policy, a Run log, a branch or a worktree.</p>
+  </header>
+  <main id="swimlanes"></main>
+  <script src="/app.js"></script>
+</body>
+</html>

package/.agents/skills/gantry/dashboard/static/style.css

@@ -0,0 +1,74 @@
+:root {
+  color-scheme: light dark;
+  --border: #8888;
+}
+
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  margin: 1.5rem;
+}
+
+header p {
+  opacity: 0.75;
+}
+
+.swimlane {
+  border: 1px solid var(--border);
+  border-radius: 0.5rem;
+  margin-bottom: 1.5rem;
+  padding: 0.75rem;
+}
+
+.swimlane.stale {
+  border-color: #c0392b;
+}
+
+.swimlane h2 {
+  margin: 0 0 0.5rem 0;
+  font-size: 1rem;
+}
+
+.columns {
+  display: grid;
+  grid-template-columns: repeat(8, minmax(8rem, 1fr));
+  gap: 0.5rem;
+}
+
+.column {
+  border: 1px dashed var(--border);
+  border-radius: 0.375rem;
+  padding: 0.5rem;
+  min-height: 4rem;
+}
+
+.column h3 {
+  margin: 0 0 0.5rem 0;
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  opacity: 0.7;
+}
+
+.card {
+  border: 1px solid var(--border);
+  border-radius: 0.25rem;
+  padding: 0.35rem;
+  margin-bottom: 0.35rem;
+  font-size: 0.8rem;
+}
+
+.badge {
+  display: inline-block;
+  border-radius: 0.25rem;
+  padding: 0 0.25rem;
+  margin-right: 0.25rem;
+  font-size: 0.7rem;
+  border: 1px solid var(--border);
+}
+
+.badge.waiting {
+  border-color: #e67e22;
+}
+
+.badge.compaction {
+  border-color: #8e44ad;
+}

package/.agents/skills/gantry/hooks/claude-code.settings.json

@@ -0,0 +1,56 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.agents/skills/gantry/scripts/guard.py\" PreToolUse --cwd \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.agents/skills/gantry/scripts/guard.py\" PostToolUse --cwd \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.agents/skills/gantry/scripts/guard.py\" SubagentStart --cwd \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.agents/skills/gantry/scripts/guard.py\" SubagentStop --cwd \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.agents/skills/gantry/scripts/guard.py\" PreCompact --cwd \"$CLAUDE_PROJECT_DIR\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/.agents/skills/gantry/hooks/codex.hooks.json

@@ -0,0 +1,4 @@
+{
+  "_note": "Codex has no hook events yet (see ../capabilities/codex.json: hooks=false, hook_events=[]). This file is the same guard.py wiring the other two harnesses use -- 'python3 <skillDir>/scripts/guard.py <event>' with the event payload on stdin -- ready to activate entry by entry the day Codex ships a hook event. Until then it grants guard.py no authority over Codex, matching the compatible tier: every protected rule stays enforced only through the prompts and the Critic.",
+  "hooks": {}
+}

package/.agents/skills/gantry/hooks/git/pre-commit

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Git pre-commit hook: reject a commit whose staged diff introduces a test-skip pattern.
+
+Per `docs/adr/0005-git-hooks-enforce-git-rules.md`, test-skip detection lives here
+instead of in `guard.py`'s Bash-command parsing. This hook reads `git diff --cached
+--unified=0`, which -- because the subprocess call inherits this hook's environment,
+including whatever `GIT_INDEX_FILE` git itself points at for a pathspec or
+`-i`/`--include` commit -- reflects exactly the content this commit is about to
+write, regardless of how it reached the index: `-a`/`--all`, a pathspec argument,
+`-i`/`--include`, a prior `git stage` (an alias for `git add`), or a plain prior
+`git add`. Git resolves all of that staging semantics itself before invoking this
+hook; no Bash-command parsing is involved, so there is no spelling left to evade.
+
+Activated by `core.hooksPath` pointing at this directory
+(`.agents/skills/gantry/hooks/git/`); `gantry-setup` writes that config into the
+operator's repository (`gantry-migration#10`) -- this hook only proves itself in
+temporary repositories where a test sets `core.hooksPath` directly.
+"""
+from __future__ import annotations
+
+import datetime
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent / "scripts"))
+
+import runlog  # noqa: E402
+import skipscan  # noqa: E402
+
+
+def now_iso() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def record_denied(cwd: Path, path: str) -> None:
+    """Append the `hook.denied` event for this denial; a logging failure never changes the decision.
+
+    The Run is resolved by `runlog.resolve_hook_run`: `GANTRY_RUN_ID` when the caller
+    exported it, otherwise this worktree's own current-Run marker, which the round workflow
+    writes before any agent works there. A denial inside a Run is therefore recorded whether
+    or not the shell that invoked `git` carried any Gantry environment.
+    """
+    run_id, state_root_value = runlog.resolve_hook_run(cwd)
+    if not run_id:
+        return
+    try:
+        root = runlog.state_root(state_root_value)
+        unit = runlog.unit_id(cwd)
+        log_path = runlog.run_log_path(root, unit, run_id)
+        if not log_path.exists():
+            return
+        event = runlog.validate_event(
+            {
+                "ts": now_iso(),
+                "run": run_id,
+                "event": "hook.denied",
+                "data": {"rule": "no-test-skip-commit", "path": path},
+            }
+        )
+        runlog.append_event(log_path, event)
+    except (runlog.EventError, OSError, ValueError):
+        return
+
+
+def main() -> int:
+    matched_file = skipscan.staged_skip_match()
+    if not matched_file:
+        return 0
+    message = f"deny: no-test-skip-commit {matched_file}"
+    print(message, file=sys.stderr)
+    record_denied(Path.cwd(), matched_file)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())