AGENTS.md: repeat the engineer/QA live-deploy prohibition (verbatim, matches agentic-os#466) #544

New issue

Closed

opened 2026-07-11 02:35:54 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-07-11 02:35:54 +00:00

Member

Repeat the live-deploy rule in this repo's AGENTS.md

Add the following rule verbatim to this repo's AGENTS.md under the ## Agent rules section (create the section if absent, matching this repo's AGENTS.md conventions). This exact text is landing in coilyco-flight-deck/agentic-os (agentic-os#466) and the sibling deploy repo - do not reword, retitle, or house-voice-tweak it, so all three repos carry byte-identical text.

Engineers and QA: never debug or iterate against a live deployment

This rule binds the sealed roles - engineer and QA - which run in ephemeral clones with no live-cluster access. It does not bind director, ops, or advisor: those hold live-observe surfaces (the advisor role carries the tailnet + ~/.aws live-observe guardfile set) and are authorized to debug deployments.

An engineer or QA runs in a sealed, ephemeral clone with no live-cluster access. You cannot curl a public edge, inspect a pod, watch a rollout, or confirm a secret synced. So you must not try to debug, tune, or "fix until green" a live deployment, and QA must not render a verdict that turns on live-cluster state it cannot observe. Treating infra like a unit test - change logic, push, watch CI, repeat - produces changes you cannot verify, which land red on main and churn. A live deployment you cannot observe is one of the walls worth a human.

Deploys already have established precedent (exposure patterns, exemplar services, shared charts). For deploy work: match the precedent and copy the exemplar, do not invent or iterate. If a change genuinely needs live verification - does this rollout succeed, is this secret synced, is the edge reachable - you cannot provide it from a sealed clone. Stop, file an interactive-labeled issue describing exactly what needs live verification, and hand it to a role that can observe live (the operator, or a director / ops / advisor run). Do not push a speculative fix and hope CI confirms it.

Why

Codifies the deploy/infra churn lesson: the sealed roles - engineer and QA cannot verify live-cluster state, so they must not iterate against live deploys. director / ops / advisor are exempt (they hold live-observe surfaces). Full context: coilyco-bridge/deploy#141.

Acceptance

The block lands verbatim under ## Agent rules in AGENTS.md, byte-identical to the agentic-os#466 and sibling versions.
Passes the pre-commit suite. If a hook objects to a line, fix the hook config or flag it - do not silently reword the rule text (parity matters more).

## Repeat the live-deploy rule in this repo's AGENTS.md Add the following rule **verbatim** to this repo's `AGENTS.md` under the `## Agent rules` section (create the section if absent, matching this repo's AGENTS.md conventions). This exact text is landing in `coilyco-flight-deck/agentic-os` (agentic-os#466) and the sibling deploy repo - do **not** reword, retitle, or house-voice-tweak it, so all three repos carry **byte-identical** text. --- ### Engineers and QA: never debug or iterate against a live deployment This rule binds the **sealed roles - engineer and QA** - which run in ephemeral clones with no live-cluster access. It does **not** bind director, ops, or advisor: those hold live-observe surfaces (the advisor role carries the tailnet + `~/.aws` live-observe guardfile set) and are authorized to debug deployments. An engineer or QA runs in a sealed, ephemeral clone with **no live-cluster access**. You cannot curl a public edge, inspect a pod, watch a rollout, or confirm a secret synced. So you **must not** try to debug, tune, or "fix until green" a live deployment, and QA **must not** render a verdict that turns on live-cluster state it cannot observe. Treating infra like a unit test - change logic, push, watch CI, repeat - produces changes you cannot verify, which land red on `main` and churn. A live deployment you cannot observe **is** one of the walls worth a human. Deploys already have established precedent (exposure patterns, exemplar services, shared charts). For deploy work: **match the precedent and copy the exemplar, do not invent or iterate.** If a change genuinely needs live verification - does this rollout succeed, is this secret synced, is the edge reachable - you **cannot** provide it from a sealed clone. Stop, file an `interactive`-labeled issue describing exactly what needs live verification, and hand it to a role that can observe live (the operator, or a director / ops / advisor run). Do not push a speculative fix and hope CI confirms it. --- ## Why Codifies the deploy/infra churn lesson: the **sealed roles - engineer and QA** cannot verify live-cluster state, so they must not iterate against live deploys. **director / ops / advisor are exempt** (they hold live-observe surfaces). Full context: `coilyco-bridge/deploy#141`. ## Acceptance - The block lands **verbatim** under `## Agent rules` in `AGENTS.md`, byte-identical to the agentic-os#466 and sibling versions. - Passes the pre-commit suite. If a hook objects to a line, fix the hook config or flag it - do **not** silently reword the rule text (parity matters more).

coilyco-ops added the

headless

labels

2026-07-11 02:35:54 +00:00

coilyco-ops commented

2026-07-11 02:36:20 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-claude-infrastructure-544 on host KAI-DESKTOP-TOWER.

Reserved by ward agent --harness claude (reserved 2026-07-11T02:36:21Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/infrastructure#544 · branch issue-544 · harness claude · workflow direct-main
Run: engineer-claude-infrastructure-544 · ward v0.605.0 · dispatched 2026-07-11T02:36:21Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0).

— Claude (she/her), via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-claude-infrastructure-544` on host `KAI-DESKTOP-TOWER`. Reserved by `ward agent --harness claude` (reserved 2026-07-11T02:36:21Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/infrastructure#544` · branch `issue-544` · harness `claude` · workflow `direct-main` - **Run:** `engineer-claude-infrastructure-544` · ward `v0.605.0` · dispatched `2026-07-11T02:36:21Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.605.0). </details> </details>  — Claude (she/her), via `ward agent`

coilyco-ops referenced this issue from a commit

2026-07-11 02:41:06 +00:00

docs(agents): repeat the engineer/QA live-deploy prohibition verbatim

coilyco-ops closed this issue

2026-07-11 02:41:06 +00:00

coilyco-ops commented

2026-07-11 02:41:34 +00:00

Author

Member

WARD-OUTCOME: done

details

workflow: direct-to-main; review summary: skipped - the in-container review gate was intentionally skipped because of the temporary ward default pending brokered QA.

The verbatim engineer/QA live-deploy prohibition landed under ## Agent rules in AGENTS.md, diff-verified byte-identical to the issue block (and thus agentic-os#466). The pre-commit doc-size hooks (pinned agentic-os v0.65.0) objected at the default 4000-char AGENTS.md cap, so per the acceptance criteria the hook config was fixed instead of the text: agents_md_max_chars = 8000 under [tool.agentic-os.documentation-layout] in pyproject.toml, with a comment citing the parity requirement. Full suite green, merged fast-forward, pushed as 239b19e on main. CI wake-up verification skipped under the docs-only carve-out (docs + hook-config change, validated locally by the identical suite CI runs).

Retrospective: straightforward run, the only wrinkle was the char cap, and the validator already shipped the per-repo opt-up key so no reword pressure ever landed on the rule text. Confidence high. Surprise: the repo pins agentic-os hooks at v0.65.0 while current is v0.245.0, a wide drift worth a follow-up bump someday, not filed as an issue since the pinned rev works. No other follow-ups.

WARD-OUTCOME: done <details><summary>details</summary> workflow: direct-to-main; review summary: skipped - the in-container review gate was intentionally skipped because of the temporary ward default pending brokered QA. The verbatim engineer/QA live-deploy prohibition landed under `## Agent rules` in `AGENTS.md`, diff-verified byte-identical to the issue block (and thus agentic-os#466). The pre-commit doc-size hooks (pinned agentic-os v0.65.0) objected at the default 4000-char AGENTS.md cap, so per the acceptance criteria the hook config was fixed instead of the text: `agents_md_max_chars = 8000` under `[tool.agentic-os.documentation-layout]` in `pyproject.toml`, with a comment citing the parity requirement. Full suite green, merged fast-forward, pushed as 239b19e on main. CI wake-up verification skipped under the docs-only carve-out (docs + hook-config change, validated locally by the identical suite CI runs). Retrospective: straightforward run, the only wrinkle was the char cap, and the validator already shipped the per-repo opt-up key so no reword pressure ever landed on the rule text. Confidence high. Surprise: the repo pins agentic-os hooks at v0.65.0 while current is v0.245.0, a wide drift worth a follow-up bump someday, not filed as an issue since the pinned rev works. No other follow-ups. </details>