Publish article on AI agent authority

docs/articles/2026/a-passing-agent-diff-is-not-project-authority.md

@@ -0,0 +1,190 @@
+---
+description: A passing AI-generated change is still a proposal; repository controls, production evidence, and human decisions determine whether it becomes project state.
+title: A Passing Agent Diff Is Not Project Authority
+author: Christopher D. Cavell
+published: "2026-09-13"
+summary: "A case study of AI-assisted development: two pull requests for an optional X publisher show why passing checks, production evidence, and maintainer authority answer different questions."
+feed: true
+---
+
+# A Passing Agent Diff Is Not Project Authority
+
+**Pattern classification:** General learning material
+
+**Difficulty:** Intermediate
+
+**Prerequisites:** Basic familiarity with Git, pull requests, and continuous integration is helpful. No AsiBackbone package or prior Learning material is required.
+
+**What this article covers:** proposal, validation, authority, execution, and evidence in AI-assisted development; a September 2026 Learning workflow case study; the limits of automated checks; and a practical review checklist for small open-source projects.
+
+An AI coding agent can inspect a repository, change files, run tests, push a topic branch, and open a pull request. Every required check can pass. None of that decides what the project should become.
+
+That distinction matters because a fluent patch can make several different claims look like one:
+
+- the change is syntactically valid;
+- focused tests pass;
+- repository-wide checks pass;
+- the change matches the maintainer's intent;
+- the deployed system behaves as expected;
+- the capability should be activated now.
+
+Each claim needs different evidence, and the last two may require decisions or observations that do not exist in a pull-request environment.
+
+This article examines one bounded episode in the [Learning repository](https://github.com/AsiBackbone/Learning), the education and documentation repository for **Accountable Systems Infrastructure (ASI) Backbone**. It describes one maintainer, one repository, and two pull requests in September 2026. It does not claim that every AsiBackbone repository or every AI-assisted project follows the same process.
+
+The episode has a recursive quality. AsiBackbone teaches that a proposed operation should not become an executed operation merely because the proposal is well formed. The development process benefited from the same separation of concerns. That is an explanatory analogy, not a claim that GitHub workflows formally implement or validate the AsiBackbone architecture.
+
+## Five Questions About the Workflow
+
+The working vocabulary is simple:
+
+- **Proposal:** What change is being suggested?
+- **Validation:** Which bounded properties have been checked?
+- **Authority:** Who or what may approve the next state transition?
+- **Execution:** Which host performs a local edit, merge, deployment, publication, or other side effect?
+- **Evidence:** What durable artifact supports a later claim about what happened?
+
+An AI-assisted development loop can then be drawn more accurately:
+
+```text
+Human intent
+    ↓
+Agent investigation and local mutation (scoped)
+    ↓
+Repository constraints and validation
+    ↓                     ↑
+Human review ── revise ───┘
+    ↓
+Human merge, publication, or activation decision
+    ↓
+Git, pull-request, release, and deployment evidence
+```
+
+Local mutation is already execution, but it occurs inside a limited workspace. Pushing a topic branch is another side effect. Merging `main`, publishing an article, configuring a protected environment, spending money, or contacting an external audience crosses a different authority boundary.
+
+In this collaboration, the coding agent could inspect files and history, edit a task-scoped worktree, run local validation, request permission to use networked Git operations, push a topic branch, open a pull request, and wait for hosted checks. The task environment did not grant a direct merge operation or access to protected-environment secrets. Production credentials and GitHub Environment configuration remained under maintainer custody. Accepting the X developer agreement, authorizing API expense, and publishing this article remained human decisions.
+
+## The Repository Is Part of the Control System
+
+A prompt supplies local intent. It is too transient to carry every standing project rule.
+
+Repository artifacts provide the durable part of the control system: contribution guidance, ownership records, architecture documents, tests, workflow permissions, branch rules, pull-request history, release artifacts, and operational runbooks. Some are machine-enforced; others remain social expectations that a maintainer must interpret.
+
+| Artifact | What it can establish | What it does not establish |
+| --- | --- | --- |
+| Issue or maintainer request | The requested outcome and stated boundaries | That the request is complete, safe, or worth implementing |
+| Proposed patch | The exact candidate state transition | That the project wants the transition |
+| Local tests | Focused executable expectations pass in one environment | Repository-wide compatibility or deployed behavior |
+| Hosted checks | Configured build, test, security, dependency, and publication gates pass | That the change matches product intent or works under every production condition |
+| Maintainer review | A responsible person accepts the purpose and tradeoffs | That the code builds, every side effect was considered, or every consequence was understood |
+| Merge commit | A reviewed proposal became repository state | That the revision was deployed or activated |
+| Deployment record | A workflow attempted or completed a deployment | That users received the intended artifact or an optional integration worked |
+| Release checksums, signatures, or attestations | The integrity or provenance properties defined by that mechanism | That the artifact is correct, wanted, or fully attributable |
+
+No row replaces another. The useful result comes from composing narrow claims without inflating them.
+
+## Case Study of an Optional X Publisher
+
+In September 2026, [Learning issue #328](https://github.com/AsiBackbone/Learning/issues/328) proposed an optional publisher: after a new standalone article reached the public Learning site, a project X account could announce it without changing the existing RSS publication path.
+
+The implementation treated RSS and X as sibling consumers of article frontmatter. The publisher used the deployed revision as its publication boundary. It stored a cursor and delivery receipts on a separate state branch, reconciled uncertain delivery by canonical URL, was designed to read OAuth credentials only from a protected environment, and supported an offline dry run. The operational details remain inspectable in the [X publication runbook](https://github.com/AsiBackbone/Learning/blob/main/X_PUBLISHING.md) and the [`Publish New Learning Content to X` workflow](https://github.com/AsiBackbone/Learning/blob/main/.github/workflows/publish-x.yml).
+
+The design changed twice as new evidence arrived.
+
+### A Security Finding Changed the Trust Boundary
+
+During development of [pull request #331](https://github.com/AsiBackbone/Learning/pull/331), an intermediate design used GitHub Actions' `workflow_run` trigger. That trigger runs in the base repository's context and can become dangerous when privileged work consumes attacker-influenced code, artifacts, expressions, or environment data.
+
+The repository's zizmor analysis reported its [`dangerous-triggers` rule](https://docs.zizmor.sh/audits/#dangerous-triggers). The finding did not identify a demonstrated exploit in the intermediate workflow. However, zizmor's guidance explicitly warns that avoiding an obvious checkout or execution of pull-request code is not a sufficient defense because less obvious paths may still execute attacker-controlled code in the target repository's context. The finding identified a privileged trigger class whose safety could depend on details that future edits might weaken.
+
+The maintainer and agent treated the result as architectural feedback. Before merge, the separate trigger was replaced with a reusable workflow called by the documentation workflow only after Pages deployment succeeded. Potential shell-expression inputs moved through environment variables, checkout credential persistence was disabled, and write authentication was delayed until the state-push step. The merged PR therefore contains the corrected design, not the rejected `workflow_run` version. Repository validation, including actionlint and zizmor, then passed.
+
+The scanner did not prove the corrected workflow safe. Its conservative finding prompted the project to replace a fragile trust boundary with a simpler one.
+
+### Production Exposed an Optionality Bug
+
+After merge, documentation built and deployed successfully, but the downstream X job put a red failure mark on the overall `main` run. Its publisher process reported:
+
+```text
+Missing required live-publication option '--account-id'.
+```
+
+The workflow populates `--account-id` from the `X_ACCOUNT_USER_ID` environment variable, and that variable was not configured. The design error was broader: an optional integration made a successful documentation deployment appear to have failed.
+
+[Pull request #332](https://github.com/AsiBackbone/Learning/pull/332) corrected the boundary by giving the `jackdaw-patio-x` environment, named for the project's X account, three explicit states:
+
+| Configuration state | Workflow result |
+| --- | --- |
+| `X_API_KEY`, `X_API_KEY_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET`, and `X_ACCOUNT_USER_ID` are all absent | Report `X publication is disabled because its protected environment has not been configured`, skip every live step, and succeed |
+| All five settings are present | Enable the live publisher |
+| Only some settings are present | Report `X publisher configuration is incomplete`, name the missing settings, and fail |
+
+Silently ignoring a partial setup would conceal an operational defect. Failing when nothing was configured would turn an optional feature into an accidental dependency. The three-state gate expresses the intended distinction directly in the [merged workflow at commit `be4acda`](https://github.com/AsiBackbone/Learning/blob/be4acda92e8f6b8da411302662e7116e6dbf6034/.github/workflows/publish-x.yml).
+
+The pull-request checks established that the new logic and repository validation passed. A later `main` deployment supplied the missing production evidence: the empty environment produced a notice, every live X step was skipped, and documentation publication succeeded.
+
+The maintainer then chose to leave the environment unconfigured until community traction justified the API cost. Implementing the capability created neither permission nor obligation to activate it.
+
+## What Escaped the Conversation
+
+The two corrections came from outside the agent-maintainer dialogue. A security rule challenged the first trigger design, and a live GitHub Environment challenged the assumption that "optional" had been implemented correctly.
+
+This is why an agent's polished self-review is not independent review. The agent and maintainer can share assumptions drawn from the same repository. Static analysis, different reviewers, constrained test environments, and production observation provide separate opportunities for reality to disagree.
+
+Production does not replace pre-merge validation. It supports claims that pre-merge validation cannot make. In this case, pull-request workflows could check syntax, tests, documentation, links, dependencies, and workflow security. They could not demonstrate how an empty protected environment would affect the actual post-deployment job.
+
+Durable evidence matters as well. Hosted logs expire, so the important behavior belongs in repository code, tests, runbooks, and a concise account such as this one. A link to a workflow run is useful supporting evidence, not the only surviving record of the lesson.
+
+## Risks the Process Does Not Remove
+
+- **Automation bias:** A complete-looking patch can be accepted because review is slower than generation. This article itself is a long, fluent AI-assisted artifact and should be reviewed with the same skepticism.
+- **Review fatigue:** A diff larger than a person can meaningfully inspect has already escaped its intended human boundary, regardless of how many checks surround it.
+- **Shared blind spots:** An agent can faithfully extend a mistaken repository assumption. External review and observable behavior remain important.
+- **Prompt injection and untrusted context:** Issues, documentation, dependency metadata, and retrieved content can contain text that should be treated as data, not as authority to change scope or expose credentials.
+- **Dependency and license mistakes:** An agent can invent a package, select an unsuitable license, or introduce unnecessary supply-chain risk. Locked restores, dependency review, provenance checks, and human judgment address different parts of that risk.
+- **Credential and side-effect exposure:** An agent-editable workflow can propose paths toward secrets or deployments. Least-privilege tokens, protected environments, trusted checkouts, pinned actions, and explicit approval gates reduce the reachable authority.
+- **Incomplete provenance:** Git preserves accepted changes, not every reasoning step. A useful pull-request record should retain intent, risks, validation, and activation state without publishing private conversation or secrets.
+- **Single-maintainer limits:** Automated mechanisms are valuable, but they are not independent human separation of duties. Projects should not claim a governance property they do not have.
+
+## When a Lighter Loop Is Enough
+
+This vocabulary is optional. Ordinary GitHub controls—small pull requests, branch protection, required checks, protected environments, and a human merge decision—already express much of the useful boundary.
+
+A comment typo or an isolated refactor with no external side effect does not need a new ceremony beyond the repository's normal review policy. Use more structure when a change can reach credentials, deployment, public communication, persistent data, package publication, security policy, or meaningful operating cost.
+
+The limiting factor is reviewability. If the process creates more evidence than anyone can understand, split the change or simplify the controls.
+
+## A Practical Review Checklist
+
+Before accepting an agent-assisted change, ask:
+
+1. Is the requested outcome clear, and is the non-goal or prohibited side effect explicit?
+2. Which local edits can the agent perform directly, and which changes require separate approval?
+3. What repository rules are machine-enforced, and which still depend on human interpretation?
+4. Do tests cover denied, missing-configuration, retry, and failure paths—not only the successful example?
+5. Can a workflow file the agent may edit reach a secret, write-capable token, deployment, or other privileged host?
+6. What does the pull-request check set still not prove about production?
+7. Does the pull-request record preserve intent, material risks, validation performed, and whether activation is enabled, deferred, or out of scope?
+
+For a multi-maintainer project, CODEOWNERS, required reviews, or a dedicated security review can create additional human boundaries. They should be added because the risk and team structure justify them, not to make a diagram look complete.
+
+## What This Experience Does and Does Not Show
+
+This episode shows that a disciplined human-AI workflow can produce reviewable artifacts while preserving meaningful human decisions. Repository controls can turn broad conversational assistance into a bounded engineering process, and failures can become durable improvements when evidence is allowed to challenge the first design.
+
+It does not show that AI-generated code is correct by default. It does not make one maintainer plus an agent equivalent to a healthy multi-person review community. It does not validate AsiBackbone as a safety guarantee, compliance system, or universal development method. It does not establish a productivity improvement because there is no controlled comparison, fixed baseline, or independent evaluation.
+
+The narrower claim is more defensible:
+
+> **Human-AI development is easier to review when proposal, validation, authority, execution, and evidence remain visibly distinct.**
+
+## Authorship and Review Disclosure
+
+This article was substantially drafted and revised with OpenAI Codex from repository artifacts and decisions supplied by Christopher D. Cavell. Draft evaluations from Claude, Microsoft Copilot, Gemini, Grok, and Meta AI informed the revision. Their comments were treated as proposals, not authority or independent human review. Cavell retains responsibility for factual review and the decision to publish.
+
+## Continue the Discussion
+
+- [Why an AI Tool Call Is a Proposal, Not Authority](why-ai-tool-call-is-only-a-proposal.md) develops the same boundary inside an application host.
+- [The Governance Spine and Capability Validation diagrams](../../architecture/governance-spine-and-capability-validation-diagrams.md) define the architecture used here only as an analogy.
+- [Scoped Capability and Host-Owned Execution](../../tutorials/scoped-capability-and-host-owned-execution.md) shows how constrained authority can be represented in executable code.
+- [Learning's contribution guidance](https://github.com/AsiBackbone/Learning/blob/main/CONTRIBUTING.md) documents the repository's actual article, review, and publication rules.

docs/articles/index.md

@@ -20,6 +20,14 @@ The Learning site is the canonical publication host. Cross-posted copies should
 
 ## 2026
 
+### [A Passing Agent Diff Is Not Project Authority](2026/a-passing-agent-diff-is-not-project-authority.md)
+
+**Christopher D. Cavell** · **September 13, 2026**
+
+A case study of AI-assisted development: two pull requests for an optional X publisher show why passing checks, production evidence, and maintainer authority answer different questions.
+
+Permanent URL: `https://asibackbone.github.io/Learning/articles/2026/a-passing-agent-diff-is-not-project-authority.html`
+
 ### [Your Audit Log Records the Story, Not the Decision](2026/your-audit-log-is-not-evidence.md)
 
 **Christopher D. Cavell** · **September 7, 2026**

docs/articles/toc.yml

@@ -1,5 +1,7 @@
 - name: Articles
   href: index.md
+- name: A Passing Agent Diff Is Not Project Authority
+  href: 2026/a-passing-agent-diff-is-not-project-authority.md
 - name: Your Audit Log Records the Story, Not the Decision
   href: 2026/your-audit-log-is-not-evidence.md
 - name: Do You Need a Capability Token, or Are Roles and Claims Enough?