# Tool-Agnostic Invariant-Driven Agent Operating Model V01 Issue: [#274](https://github.com/pinklon/ai-capability-discipline/issues/274) Parent reference: [#271](https://github.com/pinklon/ai-capability-discipline/issues/271) ## Governance Boundary This artifact is repo operating-model guidance for agent-assisted work in this repository. It is not approved package authority, final policy, runtime behavior, source approval, source activation, implementation authorization, provider approval, model approval, production approval, or enterprise tool approval. The model is tool-agnostic. It may be used by Codex, Claude Code, Cursor, local IDE agents, GitHub-native agents, future agent tools, or human maintainers if the same invariants, evidence gates, and stop conditions are followed. ## Core Principle The repo should rely on invariant-driven execution rather than chat-specific procedural memory. Every bounded work item should state: - objective - operating mode - active execution surface - hard invariants - forbidden zones - required evidence - stop conditions - validation gates - final report contract - human approval points Agents may choose implementation methods inside those boundaries. They must stop when the active execution surface cannot satisfy the required evidence or validation. ## Required Invariant Agent-owned Git ceremony is the default. Tony must not be the execution engine. If local repo state, local validation, branch sync, cleanup, draft-to-ready handling, merge-closeout evidence, residue checks, generated artifact checks, or post-merge proof is required, the task must route to Codex or another repo-local executor. Agents must not ask Tony to run local Git, GitHub CLI, validation, sync, cleanup, or closeout commands manually unless Tony explicitly requests manual commands. Tony must not be asked to perform local Git, GitHub CLI, validation, sync, cleanup, residue scan, closeout, or repo ceremony commands unless he explicitly requests manual commands. ## Execution-Surface Routing Rule When GitHub-side action is available through the assistant execution surface, the assistant should perform that action directly. When local repo execution is required, the assistant should provide a Codex-ready executor handoff or ticket, not manual commands for Tony. When the active tool surface cannot inspect required GitHub evidence, local repo state, validation output, generated artifacts, residue scans, runtime proof, source-governance proof, or closeout evidence, the response must classify the surface as `insufficient-execution-surface` and route to Codex or another repo-local executor. ## Ticket-First Response Rule When the next action is a repo-governance improvement, backlog correction, validation hardening, or operating-model adjustment, the assistant should provide an executable ticket or executor handoff by default rather than an abstract recommendation. The ticket or handoff must include objective, scope, files or artifact classes likely affected, hard boundaries, validation gates, close semantics, and the expected execution surface. ## Post-Closeout Next-Action Contract After a PR merge and local closeout receipt, the assistant or executor must not stop at acknowledgement when a next action is known, recommended, or mechanically derivable from repo-controlled artifacts. The closeout response must include exactly one of: 1. an executable Codex ticket, 2. a GitHub-side action the assistant can perform, 3. an explicit owner decision point with allowed options, 4. a Codex-ready clarification packet, 5. or a no-next-action statement with rationale. ## Relationship To Ticket-First Rule The post-closeout next-action contract extends ticket-first governance into the closeout response. If the next step is a repo-governance improvement, backlog correction, validation hardening, metadata cleanup, or operating-model adjustment, the default output is a Codex-ready ticket unless owner intent is missing. ## Relationship To Anti-Manual-Toil Rule The contract prevents closeout responses from turning known repo work into Tony manual toil. GitHub-side action should be performed by the assistant when available. Repo-local follow-up should become an executable Codex ticket or executor-ready handoff. ## Relationship To No-Assumption Owner-Clarification Gate If the next step is ambiguous, the assistant must apply the No-Assumption Owner-Clarification Gate and provide a Codex-ready clarification packet or explicit owner decision point rather than guessing. ## Disallowed Closeout-Only Response Pattern A closeout-only acknowledgement is not acceptable when a next action is known, recommended, or mechanically derivable from repo-controlled artifacts. ## Required Output Types After Closeout Every merge/local-closeout response must record one post-closeout output type: - executable Codex ticket - GitHub-side action - explicit owner decision point - clarification packet - no-next-action statement with rationale ## No-Assumption Owner-Clarification Gate If intent, requirements, acceptance criteria, owner decision, dependencies, execution boundary, closure semantics, or expected outcome are unclear, the assistant or executor must not infer, assume, or silently proceed. The next action must be one of: - Ask Tony for clarification directly. - Produce a Codex-ready clarification packet or owner-review packet. - Mark the item owner-review required. - Defer the item with explicit rationale and no implementation. Candidate assumptions may be documented, but they remain candidate assumptions. They are not approved requirements unless Tony explicitly confirms them or the repository contains controlling evidence. When ambiguity blocks execution, the active mode must become Exploration or Audit until the ambiguity is resolved. Execution mode must stop and request Tony clarification, and must not begin, continue, close, relabel, spawn implementation follow-ups, or change package authority from inferred intent. ## Candidate Assumptions Versus Approved Requirements Candidate assumptions are allowed only as clarification aids. They may describe possible interpretations of unclear scope, acceptance criteria, dependencies, execution boundaries, close semantics, or expected outcomes. Approved requirements come from explicit owner confirmation or controlling repository evidence, including issue bodies, PR bodies, accepted plans, validation receipts, or authoritative governance artifacts. If an assumption is not owner-confirmed, the executor must treat it as unapproved. Unapproved assumptions cannot define implementation scope, validation success, closeout state, owner-review disposition, or follow-up ticket creation. ## Assistant And Executor Responsibility Split Assistants working on a `github-api-only` surface may inspect and update GitHub-hosted metadata when available, including issues, PR bodies, labels, comments, and draft status. They must not convert local repo work into manual commands for Tony. Repo-local executors working on a `codex-local-repo-executor` surface own branch setup, local diffs, generated artifacts, validation, cleanup, residue scans, commits, pushes, draft PR creation, and closeout evidence when those actions are within the approved scope. ## Operating Modes ### Exploration Mode Use Exploration mode when the implementation path is unknown, the scope is ambiguous, or multiple safe paths exist. The agent: - inspects deterministic repo, issue, PR, receipt, and validation evidence - returns two or three implementation approaches when useful - identifies risks, dependencies, and stop conditions - recommends one path - does not mutate files, branches, labels, runtime state, source sets, Access/WAF, provider/model config, or package authority unless explicitly authorized Exploration output must include the active execution surface and whether that surface can complete the next step without handoff. ### Execution Mode Use Execution mode when a path is approved and the active execution surface can perform the work. The agent: - implements only the approved bounded scope - keeps diffs minimal and reviewable - preserves declared invariants and forbidden zones - runs required validation or records the exact blocker - updates generated artifacts when controlled corpus inputs change - updates receipts when artifact behavior, validation posture, or operating rules change - stages, commits, pushes, and opens a draft PR when publication is in scope Execution mode must stop before merge unless merge is explicitly authorized. ### Audit Mode Use Audit mode after implementation, before draft-to-ready, before merge, or after closeout. The agent reviews as if trying to reject the PR. It checks: - scope drift - missing issue labels or weak close semantics - stale generated files - missing validation receipt updates - missing context-pack regeneration - secret, token, cookie, raw header, provider key, or secret-bearing redirect URL exposure - Preview or Production source-set mutation - Access/WAF mutation - provider/model config mutation - package-authority promotion - browser-side provider calls - browser-side current-source calls - repo-controlled `__pycache__`, `.pyc`, or `.wrangler` residue Audit output must distinguish blockers from non-blockers and recommend merge, changes, rollback, or owner review. ## Execution-Surface Classification Agents must classify the active execution surface before Git, validation, PR, runtime, source-governance, or closeout work. | Surface | Allowed use | Required routing rule | |---|---|---| | `github-api-only` | Issue and PR metadata inspection, comments, labels, draft status, review summaries, and other GitHub-hosted actions that do not require local repo state or local validation. | Continue only when GitHub API evidence is sufficient for the task. | | `codex-local-repo-executor` | Branch creation, local diffs, generated artifacts, validation scripts, py_compile, context-pack build/check, residue cleanup, Git sync, commit, push, draft-to-ready when tied to local proof, and closeout receipts. | Route here when local repo state or local validation is required. | | `insufficient-execution-surface` | Any tool state that cannot access required GitHub evidence, local repo state, required validation, or authorized runtime proof. | Stop, state the missing capability, and request routing to a repo-local executor or authorized surface. | The classification must be durable in the PR body, issue comment, receipt, or final report whenever the task includes closeout, validation, sync, cleanup, runtime proof, or generated artifacts. ## Tool-Agnostic Roles ### Planner The Planner operates in Exploration mode by default. Responsibilities: - inspect issue, PR, branch, receipt, and repo state - identify dependencies and supersession risks - choose the active execution-surface classification - propose bounded implementation options - define invariants, stop conditions, validation gates, and human approval points - avoid file, runtime, source-set, label, branch, or PR mutation unless the task explicitly grants it ### Executor The Executor operates in Execution mode after approval. Responsibilities: - create or use the approved branch - implement the approved plan inside the declared scope - update docs, templates, generated artifacts, and receipts when required - run validation gates - clean repo-controlled generated residue - commit and push only intended files - open a draft PR with boundaries, validation, limitations, close semantics, and automerge posture The Executor must stop on invariant breach, unexplained dirty worktree state, failed validation without a bounded fix, missing authorization, or insufficient execution surface. ### Auditor The Auditor operates in Audit mode. Responsibilities: - review the diff against the issue scope and non-goals - check evidence quality and validation completeness - challenge weak assumptions - confirm boundary non-changes - confirm generated artifacts are fresh or intentionally unchanged - confirm local status and residue scans before closeout - recommend merge, changes, rollback, or owner review The Auditor must not treat passed syntax checks as semantic approval. ### Documentation Maintainer The Documentation Maintainer keeps repo-owned guidance synchronized with repo reality. Responsibilities: - update README, product architecture, runbooks, developer guidance, templates, context-pack docs, artifact indexes, and validation receipts when work changes operating practice - preserve field-guidance boundaries - keep tool-agnostic wording where the model applies across agent tools - avoid implying enterprise approval of tools, workflows, data classes, providers, models, or production use - update generated context-pack outputs when controlled corpus inputs change Documentation maintenance is required after strategic direction changes, architecture changes, operating workflow changes, source lifecycle changes, runtime behavior changes, product capability changes, validation behavior changes, repeated manual corrections, or lesson-learned capture. ### Lessons-Learned Mechanic The Lessons-Learned Mechanic turns repeated manual corrections into repo-owned improvements. Responsibilities: - identify repeated failures, manual reminders, closeout corrections, and drift patterns - route each lesson to a mechanical improvement - prefer validators, scripts, templates, docs, receipts, or backlog issues over chat-only memory - keep future chats from depending on Tony pasting reminder context Routing options: - validation check - script or tooling improvement - documentation update - issue template update - PR template update - agent prompt contract update - backlog issue - receipt or evidence template update ## Backlog Triage Agent Relationship The Backlog Triage Agent defined by [backlog_triage_dependency_supersession_workflow_v01.md](backlog_triage_dependency_supersession_workflow_v01.md) is a specialized operating-model role. It supports the Planner and Auditor by detecting duplicate, dependency, supersession, stale, blocked, ready, deferred, and needs-clarification issue states. It does not own execution by itself. The #277 / PR #280 workflow is the reference lesson: - GitHub metadata and backlog classification can often run on a `github-api-only` surface. - Draft-to-ready handling, local validation, branch sync, residue cleanup, and closeout receipts require `codex-local-repo-executor` or another repo-local executor. - Future chats must use the repo-owned execution-surface rule instead of asking Tony to bridge missing local capabilities manually. ## Human Approval Points Human approval is required before: - entering edit mode when governed editing is active - mutating Preview or Production runtime source sets - changing Cloudflare Access/WAF - changing provider/model configuration - enabling new sources - changing package authority - adding browser-side provider calls - adding browser-side current-source calls - broad crawling, arbitrary web search, or user-provided URL retrieval - exposing new data classes or secret-bearing surfaces - changing issue state materially - applying priority or resolution labels when not already approved - marking a draft PR ready when readiness was not in scope - merging any PR - applying `codex-automerge` ## Stop Conditions Stop and report the blocker when: - the execution surface is `insufficient-execution-surface` - local validation is required but no repo-local executor is available - intent, requirements, acceptance criteria, owner decision, dependencies, execution boundary, closure semantics, or expected outcome are unclear - candidate assumptions would need to be treated as approved requirements to proceed - the worktree is dirty with unexplained files - generated artifacts drift and regeneration is out of scope - validation fails and the fix would exceed the approved plan - runtime, Access/WAF, provider/model, source-set, package-authority, or browser-call boundaries become unclear - issue or PR close semantics would close the wrong item - secret or credential evidence would need to be printed - the task would require Tony to act as the execution engine without his explicit request ## Validation And Evidence Contract A final report or PR body must record: - branch - commit SHA when committed - PR number and URL when opened - PR state - labels - changed files - validation results - boundary confirmations - local status - repo-controlled residue scan result - active execution-surface classification - whether `codex-automerge` was applied For documentation-only operating-model changes, lightweight validation should verify that the operating-model document, execution-surface classification terms, required invariant, discoverability links, templates, and receipt anchors remain present. ## Explicit Non-Goals - Do not mutate Preview runtime source set. - Do not mutate Production runtime source set. - Do not change Cloudflare Access/WAF. - Do not change provider/model config. - Do not enable new sources. - Do not change package authority. - Do not add browser-side provider calls. - Do not add browser-side current-source calls. - Do not start #275. - Do not resume #271 extraction-profile work. - Do not start #269. - Do not apply `codex-automerge` unless explicitly authorized.