coilyco-flight-deck/agentic-os

Watch

Agent-facing context assumes the operator is the principal, and the pronoun rule can leak onto strangers #979

New issue

Closed

opened 2026-08-09 04:02:19 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-08-09 04:02:19 +00:00

Member

Problem

Agent-facing context assumes the human on the other side is the principal. An upcoming demo breaks that assumption: operators who hold the principal's position without being the principal, end users treating the agent as a product surface, and other agents as counterparties.

Filed from coilyco-flight-deck/agent-compose#258, which found that agent-compose's own roster prose is already clean. Zero mentions across its role charters, boundary bodies, personality bodies, invariant, and native-adaptation policy. The always-composed copy that assumes a specific human lives here instead.

Measured scope

Counted against e7c8e559, split by how eagerly each tier loads:

AGENTS.md - 10 mentions, always composed, highest priority
.agents/ - 78 mentions across 28 files, loaded on demand
docs/ - 5 mentions across 4 files, human-facing and out of scope

The private overlay carries a parallel problem at a larger scale, 3 mentions in its always-composed base and 249 across 74 files in its skill tree. It needs its own issue rather than riding this one.

The vocabulary this needs first

A find and replace produces one wrong referent, because the name currently does three separate jobs:

the human - whoever the agent is talking to, whatever authority they hold. Already the corpus word: INVARIANT.md says "Name the human when the human acts" and the director charter says "You pair with the human". It makes no authority claim, so it covers a steering operator and an external consumer without inventing a distinction the prose then has to maintain. Authority stays governed by the runtime and workflow language the charters already use.
peer - a counterparty that is not human.

Sentences about the estate need no noun for a person at all. They drop the name and describe the thing, which is what "the real repository portfolio" already does.

An earlier draft of this issue proposed a four-word split of principal, operator, user, and peer agent. It is rejected: the first three blur in practice, and the distinction they were reaching for is authority, which the prose already expresses directly.

Decide the vocabulary, then apply it. Each sentence that names a person has to be sorted into one of those before it can be reworded.

Highest priority: scope the pronoun rule

AGENTS.md currently reads:

She/her always. Never he/him or they/them in any artifact for Kai - messages, chat, code, commits, PRs, public text. Default she/her when ambiguous; fix legacy they/them on contact, except in marked historical records.

The rule is written about a named third party, which is correct in itself. The hazard is an agent applying it to whoever it is addressing, and "default she/her when ambiguous" invites that reading directly. With an unknown operator or an audience member, that misgenders a real person.

This is the only item in the set that harms someone rather than reading oddly, and it should land before the demo regardless of what happens to the rest.

State that the pronoun rule is principal-scoped.
State that an unknown counterparty is they/them until they say otherwise.
Make sure the ambiguity default cannot be read as applying to the interlocutor.

Interaction with #977

Both issues edit AGENTS.md. #977 rewrites the front-load section, this one reworks person references throughout, so they will collide textually if worked in parallel. Either sequence is fine, they just should not run at the same time.

Budget is not a constraint. [tool.agentic-os.documentation-layout] allows 320 lines and 34000 chars, and the file is at 226 lines and 23575 chars.

Done when

The principal, operator, user, and peer-agent vocabulary is written down where authors will hit it.
The pronoun rule is explicitly principal-scoped, with they/them as the default for an unknown counterparty.
AGENTS.md no longer assumes the interlocutor is the principal.
The .agents/ tier is swept, or explicitly deferred with the reason recorded.
A sibling issue exists for the private overlay.

## Problem Agent-facing context assumes the human on the other side is the principal. An upcoming demo breaks that assumption: operators who hold the principal's position without being the principal, end users treating the agent as a product surface, and other agents as counterparties. Filed from `coilyco-flight-deck/agent-compose#258`, which found that agent-compose's own roster prose is already clean. Zero mentions across its role charters, boundary bodies, personality bodies, invariant, and native-adaptation policy. The always-composed copy that assumes a specific human lives here instead. ## Measured scope Counted against `e7c8e559`, split by how eagerly each tier loads: * `AGENTS.md` - 10 mentions, **always composed, highest priority** * `.agents/` - 78 mentions across 28 files, loaded on demand * `docs/` - 5 mentions across 4 files, human-facing and out of scope The private overlay carries a parallel problem at a larger scale, 3 mentions in its always-composed base and 249 across 74 files in its skill tree. It needs its own issue rather than riding this one. ## The vocabulary this needs first A find and replace produces one wrong referent, because the name currently does three separate jobs: * **the human** - whoever the agent is talking to, whatever authority they hold. Already the corpus word: `INVARIANT.md` says "Name the human when the human acts" and the director charter says "You pair with the human". It makes no authority claim, so it covers a steering operator and an external consumer without inventing a distinction the prose then has to maintain. Authority stays governed by the runtime and workflow language the charters already use. * **peer** - a counterparty that is not human. Sentences about the estate need no noun for a person at all. They drop the name and describe the thing, which is what "the real repository portfolio" already does. An earlier draft of this issue proposed a four-word split of principal, operator, user, and peer agent. It is rejected: the first three blur in practice, and the distinction they were reaching for is authority, which the prose already expresses directly. Decide the vocabulary, then apply it. Each sentence that names a person has to be sorted into one of those before it can be reworded. ## Highest priority: scope the pronoun rule `AGENTS.md` currently reads: > **She/her always.** Never he/him or they/them in any artifact for Kai - messages, chat, code, commits, PRs, public text. Default she/her when ambiguous; fix legacy they/them on contact, except in marked historical records. The rule is written about a named third party, which is correct in itself. The hazard is an agent applying it to whoever it is addressing, and "default she/her when ambiguous" invites that reading directly. With an unknown operator or an audience member, that misgenders a real person. This is the only item in the set that harms someone rather than reading oddly, and it should land before the demo regardless of what happens to the rest. * State that the pronoun rule is principal-scoped. * State that an unknown counterparty is they/them until they say otherwise. * Make sure the ambiguity default cannot be read as applying to the interlocutor. ## Interaction with #977 Both issues edit `AGENTS.md`. #977 rewrites the front-load section, this one reworks person references throughout, so they will collide textually if worked in parallel. Either sequence is fine, they just should not run at the same time. Budget is not a constraint. `[tool.agentic-os.documentation-layout]` allows 320 lines and 34000 chars, and the file is at 226 lines and 23575 chars. ## Done when * The principal, operator, user, and peer-agent vocabulary is written down where authors will hit it. * The pronoun rule is explicitly principal-scoped, with they/them as the default for an unknown counterparty. * `AGENTS.md` no longer assumes the interlocutor is the principal. * The `.agents/` tier is swept, or explicitly deferred with the reason recorded. * A sibling issue exists for the private overlay.

coilyco-ops commented

2026-08-09 04:03:24 +00:00

Author

Member

Overlay sibling filed as coilyco-bridge/agentic-os-kai#851, covering the same problem at roughly three times the scale: 3 mentions in its always-composed base and 249 across 74 files in its skill tree, against 10 and 78 here.

Sequence is this issue first, since it owns the vocabulary decision and the pronoun scoping fix, and the overlay applies that decision rather than racing it.

Overlay sibling filed as `coilyco-bridge/agentic-os-kai#851`, covering the same problem at roughly three times the scale: 3 mentions in its always-composed base and 249 across 74 files in its skill tree, against 10 and 78 here. Sequence is this issue first, since it owns the vocabulary decision and the pronoun scoping fix, and the overlay applies that decision rather than racing it.

coilyco-ops referenced this issue from a commit

2026-08-09 04:22:53 +00:00

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

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-09 04:23:36 +00:00

docs(agents): claim-triggered front-load rule, and principal-scoped pronouns #980

coilyco-ops commented

2026-08-09 04:23:57 +00:00

Author

Member

Implemented in PR #980, alongside #977, which shares the file.

One conflict surfaced while reading the sibling rather than its summary, and it is not resolved in the PR.

coilyco-bridge/agentic-os-kai#851 contains this paragraph:

An earlier draft of this issue proposed a four-word split of principal, operator, user, and peer agent. It is rejected: the first three blur in practice, and the distinction they were reaching for is authority, which the prose already expresses directly.

and, a few lines above it, instructs readers to "use the vocabulary decided in #979 rather than inventing a parallel one" while listing a two-word vocabulary of the human and peer. So #851 asserts that #979's decided vocabulary is the two-word form, while #979's own Done-when names the four-word one.

#851 was created and last updated after this issue's body and after its comment, which favors the two-word form being the newer statement. Against that, #979 is the issue that owns the decision and its acceptance criteria are explicit. Both readings are live and I could not settle it from the artifacts.

PR #980 implements this issue as written, with the four-word split, and flags the conflict rather than picking silently. The pronoun fix does not depend on which vocabulary wins, so it lands either way.

If the two-word form is correct, the change is one section in AGENTS.md plus the twelve converted lines under .agents/. It should be decided before the overlay sweep in #851 starts, since that issue requires that no tree mix the two.

🤖 Filed by Claude Code on Kai's behalf.

Implemented in PR #980, alongside #977, which shares the file. One conflict surfaced while reading the sibling rather than its summary, and it is not resolved in the PR. `coilyco-bridge/agentic-os-kai#851` contains this paragraph: > An earlier draft of this issue proposed a four-word split of principal, operator, user, and peer agent. It is rejected: the first three blur in practice, and the distinction they were reaching for is authority, which the prose already expresses directly. and, a few lines above it, instructs readers to "use the vocabulary decided in #979 rather than inventing a parallel one" while listing a two-word vocabulary of **the human** and **peer**. So `#851` asserts that `#979`'s decided vocabulary is the two-word form, while `#979`'s own Done-when names the four-word one. `#851` was created and last updated after this issue's body and after its comment, which favors the two-word form being the newer statement. Against that, `#979` is the issue that owns the decision and its acceptance criteria are explicit. Both readings are live and I could not settle it from the artifacts. PR #980 implements this issue as written, with the four-word split, and flags the conflict rather than picking silently. The pronoun fix does not depend on which vocabulary wins, so it lands either way. If the two-word form is correct, the change is one section in `AGENTS.md` plus the twelve converted lines under `.agents/`. It should be decided before the overlay sweep in `#851` starts, since that issue requires that no tree mix the two. > 🤖 Filed by Claude Code on Kai's behalf.

coilysiren closed this issue

2026-08-09 04:34:47 +00:00

coilysiren referenced this issue from a commit

2026-08-09 04:34:48 +00:00

docs(agents): claim-triggered front-load rule, and principal-scoped pronouns (#980)

coilyco-ops referenced this issue from a commit

2026-08-09 04:41:33 +00:00

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

coilyco-ops commented

2026-08-09 04:42:37 +00:00

Author

Member

Resolved. Kai ruled for the two-word vocabulary, so #851's rejection of the four-word split governs and this issue's Done-when line naming principal, operator, user, and peer agent is superseded.

Shipped in PR #980:

the human - whoever the agent is talking to this session, whatever authority they hold. 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 fix is unchanged by the ruling, since it never depended on which vocabulary won. 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 rather than to she/her.

One thing found during the sweep that was not in the measured scope: tooling-scout-autonomy already used "operator" as its own person noun in 20 places, so converting a single line there would have left that file family mixing vocabularies. Converted the whole family instead. Interlocutor senses became the human, estate senses name Kai.

operator survives in AGENTS.md in two non-person senses that are deliberately untouched, the aosguard Operator verbs command families and the operator-local preference config axis, plus the sealed-role handoff target where it is a role name rather than the interlocutor.

🤖 Filed by Claude Code on Kai's behalf.

Resolved. Kai ruled for the two-word vocabulary, so `#851`'s rejection of the four-word split governs and this issue's Done-when line naming principal, operator, user, and peer agent is superseded. Shipped in PR #980: * **the human** - whoever the agent is talking to this session, whatever authority they hold. 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 fix is unchanged by the ruling, since it never depended on which vocabulary won. 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 rather than to she/her. One thing found during the sweep that was not in the measured scope: `tooling-scout-autonomy` already used "operator" as its own person noun in 20 places, so converting a single line there would have left that file family mixing vocabularies. Converted the whole family instead. Interlocutor senses became the human, estate senses name Kai. `operator` survives in `AGENTS.md` in two non-person senses that are deliberately untouched, the aosguard `Operator verbs` command families and the `operator-local preference` config axis, plus the sealed-role handoff target where it is a role name rather than the interlocutor. > 🤖 Filed by Claude Code on Kai's behalf.

coilyco-ops referenced this issue

2026-08-09 04:50:04 +00:00

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

coilysiren referenced this issue from a commit

2026-08-09 04:51:06 +00:00

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