oi-gantry 0.2.0__tar.gz

oi_gantry-0.2.0/.gitignore

@@ -0,0 +1,12 @@
+# Runtime session state — per-machine, never shared.
+session/
+outbox/
+*.json.gz
+
+# Feedback reports stay on the machine that produced them.
+adl-feedback_*.md
+adl-feedback_*.json
+
+__pycache__/
+*.pyc
+.DS_Store

oi_gantry-0.2.0/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog
+
+Behavioural changes to the commands. Each entry says what an agent will *do differently*, because
+that is the only thing a spec change can be judged on.
+
+Commands are generated — edit `spec/`, run `build/compile.py`, reinstall. Never edit `dist/`.
+
+## 0.2.0 — packaged, versioned, self-updating
+
+**A session now knows whether its own rules are current, before it takes the lock.**
+
+- **Shipped as a Python distribution (`oi-gantry`).** `pip install -U oi-gantry` fetches the plugin;
+  `gantry sync` writes it into all six agent configs (claude, cursor, codex, windsurf, copilot,
+  gemini). One package, six agents, one upgrade path.
+- **`acquire` step 0 — version check.** `gantry selfcheck` exits 10 when stale, and
+  `gantry selfcheck --update` upgrades and re-syncs in the same firing. A stale plugin used to be
+  invisible: it ran, it reported, and it did so under superseded rules.
+  - An unreachable index degrades to *unknown* and **does not block the run** — telemetry may never
+    stop delivery.
+  - A **major** version gap is refused, not auto-applied: it can change the phase contract the
+    session is part-way through, so it escalates as an operator decision.
+- **Version is single-sourced** from `VERSION` and read by the package, the CLI, and the reporter's
+  `X-Gantry-Version` header. The installer now ships `VERSION` beside `gantry_feedback.py`, so a run
+  invoked with an unrelated interpreter no longer stamps every report `0+unknown`.
+- **Fixed: `install.py --dir` was ignored for `--scope user`**, so any install or test silently
+  targeted the operator's real agent configs instead of the directory asked for. An explicit
+  `--dir` now wins for both scopes; `$HOME` remains the default.
+
+---
+
+## 2026-08-08 — grounding, parallelism, and the local loop
+
+**21 commands** (was 19: `decide` and `batch` added).
+
+### Added
+
+- **`decide`** — adjudicate a blocker instead of reporting it. Four questions that must pass before
+  "blocked" is allowed (named and probed *this firing*, body read not just the status code, two
+  alternatives tried, and — most often decisive — is the rule in this spec or one you invented), an
+  authority ladder defaulting to decide-and-act, and four ordered tiebreaks for contradictions.
+  Written because two of a session's three "genuinely blocked" items were false, one of them because
+  of a claim this spec had told it.
+- **`batch`** — the unit of work is a conflict-free set, not a task. A cycle costs the same for one
+  task as for eight, so the speedup is amortising setup, **not** running more agents (the lock is
+  project-wide; there is no per-task lease). Batch the execution, never the evidence.
+
+### Changed
+
+- **Evidence grammar for closes.** If you did not run it this firing, it is not evidence. Inference,
+  recall and absence are each named as impostors, with absence flagged as the dangerous one because
+  it feels like a finding.
+- **Local-first loop.** `pull` now brings the stack up locally before editing; `verify` states the
+  division — local proves the change works, cloud proves it is what the platform and users will see.
+  Remote iteration is where the `exec` 504s, the 120s lock TTL and container-snapshot staleness bite.
+- **`supersede-task` has three evidence shapes** — `by`, `by_tasks[]`, and `justification` for the
+  no-single-author case. Naming one sibling of a four-task suite is a guess dressed as provenance.
+- **`PENDING` is not blocked** — it may be unpromoted. Read `startable` from `task-graph`, not
+  `status`.
+- **Target triage before building.** `task-graph` reports `target_status`; a task whose target is
+  `missing_path` or `unresolvable_bucket_key` cannot be gated, so repair it first. `ns::…::general`
+  never grounds — derive the target from the description, `PUT` the file first (retarget rejects a
+  path that does not exist), then retarget.
+- **Platform vocabulary in task text** — a word with no domain referent may be *platform* vocabulary,
+  not boilerplate. With the counter-caution: `lane`, `worker`, `gate` are ordinary domain words in
+  real products, and treating them as leaks discards genuine requirements.
+- **Security sweeps must cover every method.** A GET-only sweep is why a publicly writable endpoint
+  survived. `401` vs `422` is the whole diagnosis.
+- **`queued` has three endings** — applied, pending, or dead-lettered.
+- **Proxy `404` is two different failures** — read the body, not the code.
+
+### Fixed
+
+- **The reporter path was never the file, it was the cwd.** Reported missing three rounds running;
+  the file was always present, but the path was *relative* and the workflow requires the agent to
+  `cd` into the pulled repo. Now absolutised at install time, with the installer aborting if a
+  relative one survives.
+- **Feedback had nowhere to go.** Every session printed `queued: no-endpoint`; the endpoint now
+  derives from `PROJECT_URL`.
+- **Retracted: "HITL can never land while paused."** Wrong, and shipped by this spec. `SubmitHitl`
+  always had an arm; the queue is drained by the worker poll loop, ungated by `paused`.
+- **Retracted: "a proxy 404 means no route."** It also means the app answered.
+
+---
+
+## 2026-08-06 — first feedback round
+
+- `retarget-task` documented; an orphan target became a fix rather than an escalation.
+- `manual-pass` takes `project_id`, not `project`.
+- Reporter stopped discarding the session it exists to record (134 of 141 events were being dropped).
+- Lock lifecycle for `/loop` firings.
+
+---
+
+## 2026-08-05 — initial
+
+19 commands across six vendors, compiled from one spec with a conformance gate.

oi_gantry-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.5
+Name: oi-gantry
+Version: 0.2.0
+Summary: GANTRY — the ADL plugin layer that drives a coding agent through a governed delivery loop
+Author: Orion Innovation
+License: Proprietary
+Keywords: adl,claude,codex,coding-agent,copilot,cursor,gantry,gemini,windsurf
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# GANTRY
+
+`/gantry` slash commands that turn any capable coding agent (Claude Code, Cursor, Codex, Windsurf,
+Copilot, Gemini CLI) into a debugging **and coding** harness for one Encore/Nova project — driven
+over the project's HTTP API, with the actual build-run-test work done on local disk.
+
+- The rules themselves: [`spec/`](spec/) — every phase, in the order an agent runs them
+- Mandatory feedback mechanism: [spec/feedback.md](spec/feedback.md)
+- What changes per release, including retractions: [CHANGELOG.md](CHANGELOG.md)
+
+---
+
+## The general rule: GANTRY always runs with the swarm OFF
+
+**`/gantry` must always turn the swarm off before it does anything.** The swarm and the coding agent
+must never write to the same project at the same time — two writers on one tree produce reverts,
+half-merges, and gate failures that belong to neither of them.
+
+This holds **whether you run `/gantry` once or in a loop**, and it is not conditional on what you
+intend to do. Even a read-only look is safer taken against a quiesced project.
+
+- **Run to success** = the swarm does **no** coding. `/gantry` loops are the code producer: pull the
+  repo locally, complete the task with the real toolchain (docker, playwright, tests), push back to
+  git, sync the workspace, and flag the result.
+- Because no swarm runs, **no gate runs either**. A task completed and proven locally is closed with
+  `pass` (ADL §8 preconditions enforced: cause not shared, real vantage-named proof, re-diff
+  immediately before passing). That is the intended path here, not a workaround.
+- `acquire` performs the `swarm/stop` and verifies `paused==true`. If it cannot confirm `paused`,
+  **nothing else runs.**
+
+**`is_on` is not the swarm.** Three orthogonal states — `is_on` (the container stack), `paused` (the
+swarm's writing), and per-service subapp status. Turning the project on does not start the swarm, and
+pausing the swarm does not stop the containers. Use `swarm/stop` to stop coding; never
+`toggle {is_on:false}`, which tears the stack down and does not set `paused`.
+
+## The local workspace
+
+GANTRY mirrors Nova's own layout so compose bind-mounts and relative paths resolve identically:
+
+```
+${ENCORE_LOCAL_LWD}/<PROJECT_ID>/<Project Name>/     # default base: /mnt/encore
+```
+
+e.g. `/mnt/encore/proj-example-hifi/EXAMPLE-HIFI/`. Quote the paths — project names contain spaces. Point
+`ENCORE_LOCAL_LWD` elsewhere to work outside `/mnt`.
+
+## Get started
+
+**Copy the sample folder** — [SampleProject/](SampleProject/) has the commands pre-installed for all
+six agents:
+
+```bash
+cp -r SampleProject ~/GantryProjects/proj-xxxx
+cd ~/GantryProjects/proj-xxxx && export ENCORE_LOCAL_LWD=~/GantryProjects
+# fill in GANTRY-KICKOFF.md, then run /gantry
+```
+
+**Or bootstrap it pre-filled** from a read-only probe of the live project:
+
+```bash
+export GANTRY_API_KEY='...'                 # out-of-band; never an argument, never in a file
+python3 examples/new-project.py --project-id proj-xxxx \
+    --url https://your-nova-host --dir ~/GantryProjects
+```
+
+Creates the project folder, installs the commands into it, and writes a `GANTRY-KICKOFF.md`
+pre-filled from the live project — task counts, `is_on`/`paused`, lock state, git remote, and any
+blocker it can prove. See [examples/](examples/) for the template and a worked example.
+
+## Install manually
+
+```bash
+python3 build/compile.py                 # spec/ -> dist/  (+ conformance gate)
+python3 install.py --target claude --scope project --dir ~/GantryProjects
+python3 install.py --list                # all supported targets and their layouts
+```
+
+Then `/gantry` in that folder. `--target all` installs every vendor; `--uninstall` removes exactly
+what was installed.
+
+## Commands
+
+`gantry` (router) · `connect` `acquire` `observe` `select` `diagnose` `fix` `verify` `hitl` `resume`
+`escalate` `report` `status` · `pull` `sync` `take` `pass` · `ask` `memory`
+
+### `/gantry <prompt>` — just ask it
+
+`/gantry` takes a free-form prompt and routes it, so you don't have to know the command names:
+
+| You type | It does |
+|---|---|
+| `/gantry why is REQ-01b866c7 stuck?` | **Answers** from read-only state. No lock, no pause, no edits. |
+| `/gantry pull it locally` | Runs that phase, and says which one it picked. |
+| `/gantry finish the payment task` | Runs the full loop, scoped to that. |
+| `/gantry should cancel refund before releasing inventory?` | Reaches a human via `ask` — it will not invent a requirement. |
+| `/gantry` | Full loop. |
+
+**Questions are answered, not executed.** When a prompt is ambiguous, GANTRY takes the cheaper,
+reversible path — reply, or ask — rather than freezing the swarm. Reaching a human via
+`POST /api/projects/{id}/chat` takes no lock and disturbs nothing; replies come back on the event
+stream. It never blocks the session waiting for a reply, and never guesses an answer.
+
+## Non-negotiables
+
+HTTP surface only — no SSH, no DB edits, no platform patching. Fix the real **shared** cause. Escalate
+anything outside the surface rather than reaching around it. Every session writes a feedback report
+before releasing the lock.
+
+## Documentation map
+
+| File | For | Contains |
+|---|---|---|
+| `spec/` → `dist/` | the **agent** | the rules themselves — edit `spec/`, never `dist/` |
+| [`CHANGELOG.md`](CHANGELOG.md) | **everyone** | what an agent will do differently, per release, including retractions |
+| [`SampleProject/`](SampleProject/) | **new users** | the commands pre-installed for all six agents |
+| [`examples/`](examples/) | **new users** | the kickoff template and a worked example |
+
+**Retractions live in the changelog on purpose.** Two rules this spec shipped were wrong and were
+believed by agents reasoning correctly from them — "HITL can never land while paused" and "a proxy
+404 means no route". A spec that quietly corrects itself teaches agents to distrust the correction.

oi_gantry-0.2.0/README.md

@@ -0,0 +1,120 @@
+# GANTRY
+
+`/gantry` slash commands that turn any capable coding agent (Claude Code, Cursor, Codex, Windsurf,
+Copilot, Gemini CLI) into a debugging **and coding** harness for one Encore/Nova project — driven
+over the project's HTTP API, with the actual build-run-test work done on local disk.
+
+- The rules themselves: [`spec/`](spec/) — every phase, in the order an agent runs them
+- Mandatory feedback mechanism: [spec/feedback.md](spec/feedback.md)
+- What changes per release, including retractions: [CHANGELOG.md](CHANGELOG.md)
+
+---
+
+## The general rule: GANTRY always runs with the swarm OFF
+
+**`/gantry` must always turn the swarm off before it does anything.** The swarm and the coding agent
+must never write to the same project at the same time — two writers on one tree produce reverts,
+half-merges, and gate failures that belong to neither of them.
+
+This holds **whether you run `/gantry` once or in a loop**, and it is not conditional on what you
+intend to do. Even a read-only look is safer taken against a quiesced project.
+
+- **Run to success** = the swarm does **no** coding. `/gantry` loops are the code producer: pull the
+  repo locally, complete the task with the real toolchain (docker, playwright, tests), push back to
+  git, sync the workspace, and flag the result.
+- Because no swarm runs, **no gate runs either**. A task completed and proven locally is closed with
+  `pass` (ADL §8 preconditions enforced: cause not shared, real vantage-named proof, re-diff
+  immediately before passing). That is the intended path here, not a workaround.
+- `acquire` performs the `swarm/stop` and verifies `paused==true`. If it cannot confirm `paused`,
+  **nothing else runs.**
+
+**`is_on` is not the swarm.** Three orthogonal states — `is_on` (the container stack), `paused` (the
+swarm's writing), and per-service subapp status. Turning the project on does not start the swarm, and
+pausing the swarm does not stop the containers. Use `swarm/stop` to stop coding; never
+`toggle {is_on:false}`, which tears the stack down and does not set `paused`.
+
+## The local workspace
+
+GANTRY mirrors Nova's own layout so compose bind-mounts and relative paths resolve identically:
+
+```
+${ENCORE_LOCAL_LWD}/<PROJECT_ID>/<Project Name>/     # default base: /mnt/encore
+```
+
+e.g. `/mnt/encore/proj-example-hifi/EXAMPLE-HIFI/`. Quote the paths — project names contain spaces. Point
+`ENCORE_LOCAL_LWD` elsewhere to work outside `/mnt`.
+
+## Get started
+
+**Copy the sample folder** — [SampleProject/](SampleProject/) has the commands pre-installed for all
+six agents:
+
+```bash
+cp -r SampleProject ~/GantryProjects/proj-xxxx
+cd ~/GantryProjects/proj-xxxx && export ENCORE_LOCAL_LWD=~/GantryProjects
+# fill in GANTRY-KICKOFF.md, then run /gantry
+```
+
+**Or bootstrap it pre-filled** from a read-only probe of the live project:
+
+```bash
+export GANTRY_API_KEY='...'                 # out-of-band; never an argument, never in a file
+python3 examples/new-project.py --project-id proj-xxxx \
+    --url https://your-nova-host --dir ~/GantryProjects
+```
+
+Creates the project folder, installs the commands into it, and writes a `GANTRY-KICKOFF.md`
+pre-filled from the live project — task counts, `is_on`/`paused`, lock state, git remote, and any
+blocker it can prove. See [examples/](examples/) for the template and a worked example.
+
+## Install manually
+
+```bash
+python3 build/compile.py                 # spec/ -> dist/  (+ conformance gate)
+python3 install.py --target claude --scope project --dir ~/GantryProjects
+python3 install.py --list                # all supported targets and their layouts
+```
+
+Then `/gantry` in that folder. `--target all` installs every vendor; `--uninstall` removes exactly
+what was installed.
+
+## Commands
+
+`gantry` (router) · `connect` `acquire` `observe` `select` `diagnose` `fix` `verify` `hitl` `resume`
+`escalate` `report` `status` · `pull` `sync` `take` `pass` · `ask` `memory`
+
+### `/gantry <prompt>` — just ask it
+
+`/gantry` takes a free-form prompt and routes it, so you don't have to know the command names:
+
+| You type | It does |
+|---|---|
+| `/gantry why is REQ-01b866c7 stuck?` | **Answers** from read-only state. No lock, no pause, no edits. |
+| `/gantry pull it locally` | Runs that phase, and says which one it picked. |
+| `/gantry finish the payment task` | Runs the full loop, scoped to that. |
+| `/gantry should cancel refund before releasing inventory?` | Reaches a human via `ask` — it will not invent a requirement. |
+| `/gantry` | Full loop. |
+
+**Questions are answered, not executed.** When a prompt is ambiguous, GANTRY takes the cheaper,
+reversible path — reply, or ask — rather than freezing the swarm. Reaching a human via
+`POST /api/projects/{id}/chat` takes no lock and disturbs nothing; replies come back on the event
+stream. It never blocks the session waiting for a reply, and never guesses an answer.
+
+## Non-negotiables
+
+HTTP surface only — no SSH, no DB edits, no platform patching. Fix the real **shared** cause. Escalate
+anything outside the surface rather than reaching around it. Every session writes a feedback report
+before releasing the lock.
+
+## Documentation map
+
+| File | For | Contains |
+|---|---|---|
+| `spec/` → `dist/` | the **agent** | the rules themselves — edit `spec/`, never `dist/` |
+| [`CHANGELOG.md`](CHANGELOG.md) | **everyone** | what an agent will do differently, per release, including retractions |
+| [`SampleProject/`](SampleProject/) | **new users** | the commands pre-installed for all six agents |
+| [`examples/`](examples/) | **new users** | the kickoff template and a worked example |
+
+**Retractions live in the changelog on purpose.** Two rules this spec shipped were wrong and were
+believed by agents reasoning correctly from them — "HITL can never land while paused" and "a proxy
+404 means no route". A spec that quietly corrects itself teaches agents to distrust the correction.

oi_gantry-0.2.0/SampleProject/README.md

@@ -0,0 +1,50 @@
+# SampleProject — copy this folder to start
+
+A ready-to-use GANTRY project folder with the `/gantry` commands already installed for **all six
+agents**. Copy it, fill in the kickoff, and run.
+
+```bash
+cp -r SampleProject ~/GantryProjects/proj-xxxx
+cd ~/GantryProjects/proj-xxxx
+export ENCORE_LOCAL_LWD=~/GantryProjects
+export GANTRY_API_KEY='...'        # out-of-band; never write it into a file
+# fill in GANTRY-KICKOFF.md, then:
+/gantry
+```
+
+Prefer it pre-filled? `examples/new-project.py` does the same thing and populates the kickoff from a
+read-only probe of the live project — task counts, `is_on`/`paused`, lock state, git remote:
+
+```bash
+python3 examples/new-project.py --project-id proj-xxxx --url https://your-nova-host \
+    --dir ~/GantryProjects
+```
+
+## What's here
+
+| | |
+|---|---|
+| `.claude/` `.cursor/` `.codex/` `.windsurf/` `.github/` `.gemini/` | the 19 `/gantry` commands, per agent |
+| `GANTRY-KICKOFF.md` | the kickoff template — **fill this in before your first run** |
+
+Only your agent's directory matters; delete the rest if you like. Each carries a
+`.gantry-manifest.json` recording what GANTRY installed, so `install.py --uninstall` removes exactly
+that and nothing else.
+
+These command files are **generated** from `spec/` by `build/compile.py` and verified against
+`dist/` by `compile.py --check`. Don't hand-edit them — edit the spec and rebuild, or your changes
+vanish on the next build.
+
+## Before your first run
+
+**The swarm will be turned off and kept off.** `/gantry` pauses it and verifies `paused==true` before
+it writes anything. The swarm and a coding agent must never write to the same tree. You are the code
+producer for the session.
+
+**No swarm means no gate.** Nothing is running to award a task Done, so a task you finish and prove
+locally is closed with `pass` — which enforces the preconditions (cause not shared, real
+vantage-named proof, re-diff immediately before passing). A task still red gets **escalated**, not
+passed.
+
+**Fill in the kickoff.** It's the first thing an agent reads. Every fact you put there is one the
+session doesn't have to re-derive — and one it can't get wrong.

oi_gantry-0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0