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

Merged

coilysiren merged 2 commits from aos/claude/issues-977-979-agents-base into main

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

coilyco-ops commented

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

Member

Closes #977. Closes #979.

Three commits, worked in sequence because both issues rewrite AGENTS.md and
would collide textually if run in parallel, exactly as #979 predicted.

1. Front-load rule: trigger on any consequential claim (#977)

The rule existed at AGENTS.md:195 and did not bind. agent-compose#248
diagnosed two causes and both hold: the trigger was edit-shaped, so a role
writing an assessment never reached it, and there was no stopping condition.

Rewritten in place, not appended. The corrected doctrine is adapted from the
meld-evidence body shipped in agent-compose (5823c9c), which is the
non-role-scoped half that agent-compose#254 allocates to this base:

Trigger is 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 it. 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 search modality is not proof of absence.
Checkable stopping condition: before delivering, every consequential claim
either names the source opened, or is marked as inference with the
observation that would settle it.
Bounds: only sources that would change a specific pending claim, cost scales
with stakes, no new authority.

The old edit-shaped trigger survives as a named instance rather than being
deleted. External validation is deliberately excluded, since it is
role-allocated to the Executive Strategist and six roles are chartered to stay
inside the local frame.

2 and 3. Person vocabulary and pronoun scoping (#979)

The second commit implemented #979's four-word split and flagged a conflict
with coilyco-bridge/agentic-os-kai#851, which rejects that split. Kai ruled
for the two-word form, and the third commit applies it. Both commits are kept
rather than squashed so the decision has an audit trail.

Vocabulary. A new ### Who you are talking to opens ## Agent rules,
directly above the rule that depends on it. Two nouns, and no rule invents a
third:

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 already in 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.

Pronouns. The hazard that harms someone rather than reading oddly, so it
lands regardless of what happens to the rest. The rule now states it is about
Kai and reaches nobody else. Inside a reference to Kai, ambiguity still
resolves to she/her. Ambiguity about whether the subject is Kai resolves the
other way, so anyone whose pronouns have not been stated is they/them, the
human in front of you included. A name is not a source for pronouns.

Person references. Sentences that named Kai or said "user" while meaning
the steering human now say the human: the speak-as-yourself rule, the
finish-the-task handoff, the wall-worth-a-human examples, the reusable-script
recipient, and the o2r relay path.

.agents/ swept, not deferred. 12 operator-scoped mentions across 8 files
converted, and the remaining 69 Kai mentions checked individually for an
operator-shaped verb before being left alone, since statements about
preferences, background, and licensing policy hold regardless of who is
driving. tooling-scout-autonomy additionally used "operator" as its own
person noun in 20 places, so its whole family was converted rather than left
mixing vocabularies, which #851 forbids. Interlocutor senses became the human,
estate senses name Kai.

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

What "operator" still means

Untouched in two non-person senses: **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 live-operations doctrine rather than the person vocabulary.

Overlay sibling

coilyco-bridge/agentic-os-kai#851 carries the same problem at roughly three
times the scale and is sequenced behind this. The vocabulary it should apply is
now settled.

Verification

ward exec pre-commit-all passes on the full tree.

AGENTS.md 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.

No docs/FEATURES.md entry. This is doctrine, not a shipped capability.

🤖 Generated with Claude Code

Closes #977. Closes #979. Three commits, worked in sequence because both issues rewrite `AGENTS.md` and would collide textually if run in parallel, exactly as #979 predicted. ## 1. Front-load rule: trigger on any consequential claim (#977) The rule existed at `AGENTS.md:195` and did not bind. `agent-compose#248` diagnosed two causes and both hold: the trigger was edit-shaped, so a role writing an assessment never reached it, and there was no stopping condition. Rewritten in place, not appended. The corrected doctrine is adapted from the `meld-evidence` body shipped in agent-compose (`5823c9c`), which is the non-role-scoped half that `agent-compose#254` allocates to this base: * Trigger is 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 it. 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 search modality is not proof of absence. * Checkable stopping condition: before delivering, every consequential claim either names the source opened, or is marked as inference with the observation that would settle it. * Bounds: only sources that would change a specific pending claim, cost scales with stakes, no new authority. The old edit-shaped trigger survives as a named instance rather than being deleted. External validation is deliberately excluded, since it is role-allocated to the Executive Strategist and six roles are chartered to stay inside the local frame. ## 2 and 3. Person vocabulary and pronoun scoping (#979) The second commit implemented #979's four-word split and flagged a conflict with `coilyco-bridge/agentic-os-kai#851`, which rejects that split. Kai ruled for the two-word form, and the third commit applies it. Both commits are kept rather than squashed so the decision has an audit trail. **Vocabulary.** A new `### Who you are talking to` opens `## Agent rules`, directly above the rule that depends on it. Two nouns, and no rule invents a third: * **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 already in 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. **Pronouns.** The hazard that harms someone rather than reading oddly, so it lands regardless of what happens to the rest. The rule now states it is about Kai and reaches nobody else. Inside a reference to Kai, ambiguity still resolves to she/her. Ambiguity about whether the subject is Kai resolves the other way, so anyone whose pronouns have not been stated is they/them, the human in front of you included. A name is not a source for pronouns. **Person references.** Sentences that named Kai or said "user" while meaning the steering human now say the human: the speak-as-yourself rule, the finish-the-task handoff, the wall-worth-a-human examples, the reusable-script recipient, and the o2r relay path. **`.agents/` swept, not deferred.** 12 operator-scoped mentions across 8 files converted, and the remaining 69 Kai mentions checked individually for an operator-shaped verb before being left alone, since statements about preferences, background, and licensing policy hold regardless of who is driving. `tooling-scout-autonomy` additionally used "operator" as its own person noun in 20 places, so its whole family was converted rather than left mixing vocabularies, which #851 forbids. Interlocutor senses became the human, estate senses name Kai. `writing-voice-guide-linter` needs no change. Its pronoun rules are already conditional and it already documents that it over-flags because it cannot resolve the referent, which is exactly right under the scoped rule. ## What "operator" still means Untouched in two non-person senses: `**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 live-operations doctrine rather than the person vocabulary. ## Overlay sibling `coilyco-bridge/agentic-os-kai#851` carries the same problem at roughly three times the scale and is sequenced behind this. The vocabulary it should apply is now settled. ## Verification `ward exec pre-commit-all` passes on the full tree. * `AGENTS.md` 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. No `docs/FEATURES.md` entry. This is doctrine, not a shipped capability. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

coilyco-ops added 2 commits

2026-08-09 04:23:36 +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

ci / ward-doctor (pull_request) Successful in 13s

Details

ci / aos-cli-tests (pull_request) Successful in 32s

Details

ci / gate (pull_request) Successful in 1m19s

Details

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>

coilyco-ops requested review from coilysiren

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

coilyco-ops referenced this pull request

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

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