docs(agents): lose principal, operator, and user for human and peer #982

Merged

coilysiren merged 5 commits from aos/claude/issues-977-979-agents-base into main 2026-08-09 04:51:05 +00:00

Conversation 0 Commits 5 Files changed 32 +101 -102

coilysiren commented 2026-08-09 04:42:23 +00:00

Owner

Copy link

Closes #981.

Follows #980, which merged with the four-word vocabulary still in place. This
finishes the terminology ruling: Peer agent becomes peer, and Principal,
Operator, and User are lost outright rather than collapsed, so no
definition tries to preserve the distinctions they carried.

The vocabulary section stops melding

The the human bullet no longer enumerates the retired words. It read "covers
a steering operator, a colleague on a work host, a demo audience, and an
external consumer talking to the agent as a product surface", which is exactly
the meld #981 rules out. It now says whoever the agent is talking to this
session, and keeps only the guard that the noun makes no authority claim.

Person-sense uses converted

AGENTS.md. The sealed-role handoff names the human rather than the
operator. The adjectival "operator action" becomes "live action", naming the
action class instead of a person. Two "user" sentences drop the word rather
than gain a synonym, and one "user-facing" becomes human-facing, matching the
spelling already used two sections down.

.agents/. 40 interlocutor-sense "user" mentions across 20 files become
the human. These were invisible to #979's measured scope, which counted only
Kai mentions, and they are the same bug wearing a different word. The affected
skills are claude-in-chrome, pm-product-brainstorming, skill-authoring,
issue-decomposition, scout-capability, supply-chain-audit, and core-git.

Deliberately not converted

• **Operator verbs** and operator-local preference in AGENTS.md, plus
  guarded-operator-work.md. These name aosguard command families and a config
  axis, not a person.
• Product end-users in the designer, PM, and CEO skills. A cognitive
  walkthrough asking whether the user forms the right subgoal is about the
  product's user, and pointing it at the human would aim it at the wrong
  person.
• OS accounts, IAM users, Discord users, and code identifiers.

Why there is a merge commit

#980 was squash-merged, which rewrote the two commits this branch already
carried and left it unmergeable. The branch merges origin/main rather than
force-pushing, taking this branch's AGENTS.md and .agents/ state, which is
main's squashed content plus the collapse, and main's side everywhere else.
Verified against f9a42d1b and origin/main before committing.

Verification

ward exec pre-commit-all passes on the full tree. AGENTS.md is at 289 lines
and 26964 chars against the 320 and 34000 caps.

🤖 Generated with Claude Code

Closes #981. Follows #980, which merged with the four-word vocabulary still in place. This finishes the terminology ruling: `Peer agent` becomes peer, and `Principal`, `Operator`, and `User` are lost outright rather than collapsed, so no definition tries to preserve the distinctions they carried. ## The vocabulary section stops melding The `the human` bullet no longer enumerates the retired words. It read "covers a steering operator, a colleague on a work host, a demo audience, and an external consumer talking to the agent as a product surface", which is exactly the meld #981 rules out. It now says whoever the agent is talking to this session, and keeps only the guard that the noun makes no authority claim. ## Person-sense uses converted **`AGENTS.md`.** The sealed-role handoff names the human rather than the operator. The adjectival "operator action" becomes "live action", naming the action class instead of a person. Two "user" sentences drop the word rather than gain a synonym, and one "user-facing" becomes human-facing, matching the spelling already used two sections down. **`.agents/`.** 40 interlocutor-sense "user" mentions across 20 files become the human. These were invisible to #979's measured scope, which counted only Kai mentions, and they are the same bug wearing a different word. The affected skills are claude-in-chrome, pm-product-brainstorming, skill-authoring, issue-decomposition, scout-capability, supply-chain-audit, and core-git. ## Deliberately not converted * `**Operator verbs**` and `operator-local preference` in `AGENTS.md`, plus `guarded-operator-work.md`. These name aosguard command families and a config axis, not a person. * Product end-users in the designer, PM, and CEO skills. A cognitive walkthrough asking whether the user forms the right subgoal is about the product's user, and pointing it at the human would aim it at the wrong person. * OS accounts, IAM users, Discord users, and code identifiers. ## Why there is a merge commit #980 was squash-merged, which rewrote the two commits this branch already carried and left it unmergeable. The branch merges `origin/main` rather than force-pushing, taking this branch's `AGENTS.md` and `.agents/` state, which is main's squashed content plus the collapse, and main's side everywhere else. Verified against `f9a42d1b` and `origin/main` before committing. ## Verification `ward exec pre-commit-all` passes on the full tree. `AGENTS.md` is at 289 lines and 26964 chars against the 320 and 34000 caps. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

coilysiren added 3 commits 2026-08-09 04:42:23 +00:00

docs(agents): trigger the front-load rule on any consequential claim ... 66d95365d4

Closes #977.

## Problem

The rule already existed at `AGENTS.md:195` and did not bind. A single strats
session on 2026-08-07 produced four failures it was written to prevent, all
reversible and all caught: gaps recorded as disclaimers instead of tasks,
campaign claims made without measuring, an absence concluded from one search
modality, and a critical path named from issue prose while the diff said the
opposite. The shared root is that an artifact describing a thing was accepted
in place of the thing.

`coilyco-flight-deck/agent-compose#248` diagnosed two causes, and both hold:

1. The trigger was edit-shaped. "Before the first edit" is a line a role
   writing an assessment, a ranking, or a verdict never reaches, so the rule
   read as somebody else's.
2. There was no stopping condition. It said to read what you need and offered
   no test for whether you had.

## Change

Rewrites the section in place rather than appending a second one, per the
placement note in #977. The corrected doctrine is adapted from the
`meld-evidence` body shipped in agent-compose (`5823c9c`), which is the half
`agent-compose#254` allocates here because it is not role-scoped:

* The trigger becomes any consequential claim, defined as one a reader could
  act on or one that enters a durable artifact.
* Prefer the thing over any description of the thing. Code over the issue,
  diff over the commit subject, contents over metadata, raw over summary.
* An identified gap is a task, not a disclaimer.
* One modality is not proof of absence.
* A checkable stopping condition: before delivering, every consequential claim
  either names the source that was opened, or is marked as inference with the
  observation that would settle it.
* Bounds: acquisition reaches only sources that would change a specific pending
  claim or decision, cost scales with stakes, and no new authority is granted.

The old edit-shaped trigger is kept as a named instance rather than deleted,
since listing the conventions a change touches is still the right move before
the first edit. The narrowed-scope and first-instance paragraph is unchanged.

Deliberately excluded: seeking validation from outside your own frame. That
behavior is role-allocated to the Executive Strategist in
`agent-compose#254`, and six roles are chartered to stay inside the local
frame. A rule here that swept it in would tell QA to do what its charter
forbids.

## Dependency

`agent-compose#254` removes this half from the roster. Until it lands, both
copies exist, which is the safe ordering. A bundle shipped to a seat without
this base would otherwise carry no version of the rule at all.

## Verification

`ward exec pre-commit-documentation-layout` passes. `AGENTS.md` is at 264 lines
and 25705 chars against the 320 and 34000 caps in
`[tool.agentic-os.documentation-layout]`.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs(agents): scope the pronoun rule to the principal, name the four positions ... 8d86cdd5af

Closes #979.

## Problem

The always-composed base assumed the human on the other side is the principal.
An upcoming demo breaks that assumption: operators holding the principal's
position without being the principal, end users treating the agent as a product
surface, and peer agents as counterparties.

The hazard that harms someone rather than reading oddly is the pronoun rule.
"Default she/her when ambiguous" invited an agent to apply a principal-scoped
rule to whoever it was addressing, which misgenders a real person.

## Change

**Vocabulary.** A new `### Who you are talking to` opens `## Agent rules`,
directly above the pronoun rule that depends on it. Principal, operator, user,
and peer agent, plus the test that sorts a sentence: if it would break when the
operator is a stranger, it is operator-scoped and has to say so.

**Pronouns.** The rule now states it is principal-scoped, and the ambiguity
default is split in two. Inside a reference to the principal, ambiguity still
resolves to she/her. Ambiguity about whether the subject is the principal
resolves the other way, so anyone whose pronouns have not been stated is
they/them, the operator included. A name is not a source for pronouns.

**Person references.** Operator-scoped sentences that named Kai or said "user"
meaning the steering human now say operator: "Name the operator when the
operator acts", "the operator will choose", the finish-the-task handoff, the
wall-worth-a-human examples, the reusable-script recipient, and the o2r relay
path. Principal-scoped mentions are unchanged and correct, since statements
about the estate, the repositories, and the house style hold regardless of who
is driving. Six mentions remain in `AGENTS.md`, all principal-scoped.

**`.agents/` sweep.** Swept rather than deferred. 78 mentions across 28 files,
of which 12 across 8 files were operator-scoped and are converted. The
remaining 69 are principal-scoped by inspection, not by assumption: each was
checked for an operator-shaped verb (asks, decides, confirms, reviews, chooses,
runs) and the survivors are all statements about Kai's preferences, background,
licensing policy, or prose. Two "When to use" lines lost a false operator
assumption and now match their siblings in the Go, C#, Rust, and Kubernetes
skills.

`writing-voice-guide-linter` needs no change. Its pronoun rules are already
conditional ("if referring to Kai") and it already documents that it over-flags
because it cannot resolve the referent, which is exactly right under the
scoped rule.

## Overlay sibling

`coilyco-bridge/agentic-os-kai#851` carries the same problem at roughly three
times the scale. It is filed and sequenced behind this change.

## Open conflict, flagged not resolved

`#851` contains a paragraph rejecting the four-word split implemented here in
favor of a two-word "the human" and "peer" vocabulary, while also instructing
readers to use the vocabulary decided in `#979`. `#979` is unambiguous in its
own Done-when, so this commit implements `#979` as written and leaves the
conflict for review rather than picking silently. Swapping the vocabulary is a
single-section edit if the two-word form wins, and it must be decided before
the overlay sweep starts, since `#851` requires that no tree mix the two.

## Verification

`ward exec pre-commit-all` passes, including the composed-source size budget.
`coding-core-git-workflow/COMPOSED.md` is the tight one at 3969 chars against
its 4000 cap. `AGENTS.md` is at 290 lines and 27338 chars against the 320 and
34000 caps.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

docs(agents): collapse the person vocabulary to the human and peer ... f9a42d1bb7

Closes #979.

Resolves the conflict flagged on the previous commit and in #979. Kai ruled for
the two-word vocabulary recorded in `coilyco-bridge/agentic-os-kai#851`, so the
four-word split of principal, operator, user, and peer agent is withdrawn.

## Change

`### Who you are talking to` now defines two nouns and forbids a third:

* **the human** - whoever the agent is talking to this session, whatever
  authority they hold. It covers a steering operator, a colleague on a work
  host, a demo audience, and an external consumer. It makes no authority claim,
  so authority stays governed by the workflow and runtime language the rules
  already use.
* **peer** - a counterparty that is not a human at all.

A sentence about the estate needs no noun for a person. It names Kai or
describes the thing.

The pronoun rule reverts to naming Kai directly rather than routing through a
"principal" noun that no longer exists, and keeps the scoping that was the
point: the rule is about Kai and reaches nobody else, anyone whose pronouns
have not been stated is they/them with the human in front of you included, and
ambiguity about whether the subject is Kai resolves to they/them.

Every "operator" this branch introduced becomes "the human", in `AGENTS.md` and
in the twelve converted `.agents/` lines.

## Scout skill converted with it

`tooling-scout-autonomy` already used "operator" as its person noun in 20
places, so the one line converted in the previous commit left that file family
mixing vocabularies, which is exactly what #851 forbids. Converted the whole
family rather than leaving it half-done. The interlocutor senses became the
human (who picks a contract, who runs a phase, who fences the scout), and the
estate senses name Kai (whose notes, whose audience, whose toolset, whose
long-run discipline), which also matches how every other skill under
`.agents/composed/` already reads.

## What "operator" still means

The word survives in `AGENTS.md` in two non-person senses that are deliberately
untouched: `**Operator verbs**` naming the aosguard command families, and
`operator-local preference` naming a config axis. The sealed-role section keeps
"the operator, director, or ops" as a handoff target, since those are role
names rather than the interlocutor and rewording them would change the
live-operations doctrine rather than the person vocabulary.

## Verification

`ward exec pre-commit-all` passes. `AGENTS.md` is at 289 lines and 27136 chars
against the 320 and 34000 caps. `coding-core-git-workflow/COMPOSED.md` is the
tight one at 3966 chars against its 4000 cap.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops added 2 commits 2026-08-09 04:49:23 +00:00

Merge remote-tracking branch 'origin/main' into aos/claude/issues-977-979-agents-base ... 7dc4c1ef61

Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

# Conflicts:
#	.agents/composed/coding-core-git-workflow/COMPOSED.md
#	.agents/composed/coding-core-git-workflow/references/default-todo-and-flake.md
#	.agents/composed/coding-core-git/COMPOSED.md
#	.agents/composed/coding-terraform/COMPOSED.md
#	.agents/composed/tooling-scout-autonomy/references/phase-5-present.md
#	.agents/composed/tooling-skill-authoring/references/handbook-description-budgets.md
#	AGENTS.md

docs(agents): lose principal, operator, and user for human and peer ... 8198c5d537

Closes #981.

`#980` merged with the four-word vocabulary. This finishes the terminology
ruling: `Peer agent` becomes peer, and `Principal`, `Operator`, and `User` are
lost outright rather than collapsed, so no definition tries to preserve the
distinctions they carried.

## Vocabulary section stops melding

The `the human` bullet no longer enumerates the retired words. It said the noun
"covers a steering operator, a colleague on a work host, a demo audience, and
an external consumer talking to the agent as a product surface", which is the
meld the ruling forbids. It now reads as whoever the agent is talking to this
session, and keeps only the guard that the noun makes no authority claim.

## Remaining person-sense uses converted

* `AGENTS.md` - the sealed-role handoff now names the human rather than the
  operator, and the adjectival "operator action" becomes "live action", which
  names the action class instead of a person. Two "user" sentences drop the
  word rather than gain a synonym, and one "user-facing" becomes human-facing,
  matching the human-facing spelling already used two sections down.
* `.agents/` - 40 interlocutor-sense "user" mentions across 20 files become the
  human. These were outside the counts in `#979`, which measured only Kai
  mentions, and are the same bug in a different word.

## Deliberately not converted

* `**Operator verbs**` and `operator-local preference` in `AGENTS.md`, plus
  `guarded-operator-work.md` in the skill tree. These name aosguard command
  families and a config axis, not a person.
* Product end-users in the designer, PM, and CEO skills. A cognitive
  walkthrough asking whether the user forms the right subgoal is about the
  product's user, and rewriting it to the human would point it at the wrong
  person.
* OS accounts, IAM users, Discord users, and code identifiers.

## Merge

The branch merges `origin/main` first, because `#980` was squash-merged and
rewrote the two commits this branch already carried. The merge takes this
branch's `AGENTS.md` and `.agents/` state, which is main's squashed content
plus the collapse, and main's side everywhere else. No force-push.

## Verification

`ward exec pre-commit-all` passes. `AGENTS.md` is at 289 lines and 26964 chars
against the 320 and 34000 caps.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-authored-by: Kai Siren <coilysiren@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>

coilyco-ops changed title from aos/claude/issues-977-979-agents-base to docs(agents): lose principal, operator, and user for human and peer 2026-08-09 04:50:04 +00:00

coilysiren merged commit 8a7944f063 into main 2026-08-09 04:51:05 +00:00

coilysiren deleted branch aos/claude/issues-977-979-agents-base 2026-08-09 04:51:05 +00:00

coilysiren referenced this pull request from a commit 2026-08-09 04:51:06 +00:00

docs(agents): lose principal, operator, and user for human and peer (#982)

coilyco-ops referenced this pull request 2026-08-09 05:44:38 +00:00

Front-load rule grants unqualified reach that a role boundary may narrow #983

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

burndown-2026-06

Backlog burndown June 2026

  

autonomy

async-consult

A human needs to consult on the issue to upgrade it to headless

  

autonomy

epic

This issue has many units of sub work - its size makes it meaningfully exclusive with other autonomy types

  

autonomy

headless

The agent can perform the work on its own

  

autonomy

live-collab

The agent and the human need to work together in realtime

  

coherence-core

Core review set for the warded control plane coherence milestone. These issues form the release spine; adjacent milestone issues are stretch or supporting work.

  

priority

P0

priority tier

  

priority

P1

priority tier

  

priority

P2

priority tier

  

priority

P3

priority tier

  

priority

P4

priority tier

  

qa-fixture

Disposable issue admitted to the bounded Ward QA verification lane.

  

role/ai

requires work from the AI Engineer role

  

role/creator

requires work from Content Creator role

  

role/design

requires work from the design role

  

role/director

requires work from the director role

  

role/engineer

requires work from the engineer role

  

role/exec

requires work from the exec role

  

role/human

requires a person, and specifically not an agent seat

  

role/ops

requires work from the ops role

  

role/qa

requires work from the QA role

No labels

burndown-2026-06

autonomy

async-consult

autonomy

epic

autonomy

headless

autonomy

live-collab

coherence-core

priority

P0

priority

P1

priority

P2

priority

P3

priority

P4

qa-fixture

role/ai

role/creator

role/design

role/director

role/engineer

role/exec

role/human

role/ops

role/qa

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-flight-deck/agentic-os!982

No description provided.