Skip to content

docs(agent-spec-fields): explain how the other backends consume a spec - #12209

Merged
bolichen97 merged 1 commit into
mainfrom
docs/backends-consume-spec
Sep 20, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
docs/backends-consume-spec

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

src/kiro_crew/docs/agent-spec-fields.md answers "who reads an agent spec" with
a four-row surface table, and then leaves the question a reader actually arrives
with — how do the other ACP backends read and use a spec? — in two paragraphs
of aside underneath it. Those paragraphs said the five backends missing from the
table get "no agent definition in any shape", then admitted in the next sentence
that some of their fields arrive anyway, and pointed at
src/kiro_crew/providers/mirrors/ as the place to go and find out which.

So the page named the folder and withheld the answer. A reader who wants to know
whether their spec's hooks block runs on codex, or whether disabledTools
survives to goose, had to read seven mirror modules to find out.

Why it matters

A spec author picks a harness and writes one file. Which of that file's fields
still mean something after the switch is not guessable from the field tables: the
same key is delivered on one harness, translated on a second, withheld by a
deliberate security decision on a third, and simply has nowhere to go on a
fourth. Getting it wrong is quiet — a hooks block that never fires and a
skill:// mapping that loads nothing both look exactly like a spec that works.

The mirrors already record most of the answer, one Ruling per field per
backend, with a required reason. The page never surfaced it.

What changed (motivation → approach → change)

Goal: put the per-harness answer on the page, once, where the question is asked.

Approach: derive it from each mirror's own rulings() rather than restate it in
prose. providers/mirrors/base.py already models this — Concern is the closed
list of things a spec expresses, Disposition is the four answers — so that
structure transposes into a table.

Citing the rulings buys less than it looks, and the limit is worth stating: the
docs lint catches a cited symbol that is RENAMED or DELETED, so a mirror class or
helper going away reds a build. It does not read dispositions, so a mirror that
FLIPS one -- goose gaining per-call deny, or #12215 rewording the three
resources reasons -- leaves this table quietly wrong. Only a test that parses
the table and asserts each cell against rulings(), or generating the rows from
them, would close that; both are code and out of this PR's one-file scope, so
#12215 carries it.

Built, as a new ## How the other backends consume a spec section between the
surface table and the field inventory:

  • The four-case rule. kiro-cli reads the file itself; KAS gets a wire
    projection (acp/kas_agents.py, to_client_custom_agent); the four mirrored
    harnesses get individual fields; pi and deepseek get no projection.
  • Where a mirror runs, which the old paragraphs never named: the two seams,
    AcpRuntime._mirrored_session_mcp and AcpClient._resolve_session_mcp_servers,
    and why both call session_projection — only codex.py fills the deny set.
  • A per-harness table of delivered / translated / not-delivered fields, the
    mirror module and the reason class, plus eight notes holding the qualifiers so
    cells stay scannable. pi (no-channel) and deepseek (broker-only) differ:
    a deepseek session holds the gateway's pooled stubs, not its spec's servers.
  • The reason classes — gate-preserving, context-instead,
    harness-owns-the-vocabulary, fixed-by-governance — and why no-channel is not
    one of them, which is why hooks sits in that column without being a withhold.
  • One correction to the mirrors, stated as such. claude_code.py,
    codex.py and opencode.py rule resources withheld on the reason that
    skills and steering are injected as context text instead. That reason holds for
    the provider=claude_code seam, not for a mirrored harness: _skills_injection_plan
    and the file:// steering block are both gated on is_claude_code, so a mapped
    skill:// is neither loaded natively nor injected by Crew — it reaches nothing.
    goose.py's reason is already correct. Correcting the three strings, and
    deciding whether a spec author should be warned at spawn, is tracked in resources has no reader on a mirrored ACP harness, and nothing says so — at runtime or in the mirrors #12215.
  • What it means for a spec author: mcpServers, tools and model travel;
    tools only at SERVER granularity, so an @server/tool grant widens to the
    whole server on every mirror.

The two old paragraphs shrink to one sentence. Three places that duplicated them
now point at the section: the top-of-page reading note, the surface table's
acp_backend="claude" row, and the ## Per-surface summary preamble. The
agent-host-contract §1 cross-link is kept; ## Where to look gains two rows.

Follow-up to #12155. Nothing outside that one file changes.

Backwards compatibility

Compatible: documentation only. One markdown file under src/kiro_crew/docs/
changes; no code, no schema, no configuration, and nothing main accepts today is
rejected, renamed or removed.

Tests

N/A — no code changed. The page's own gates are what apply:
python3 scripts/docs_lint.py --test, ./scripts/docs-lint.sh and
python3 scripts/check_brand_name.py all exit 0, and the docs lint is what
enforces the symbol-not-line citation convention this section follows.

Manual verification

Every symbol cited was verified present on this base by reading the module, not
by grepping the name: providers/mirrors/base.py (Concern, Disposition,
Ruling, SessionProjection, AgentConfigMirror), registry.py (MIRRORS,
PROJECTIONS, ProjectionKind, PerToolDeny), identity.py, and the
rulings() of all four mirrors, which is where every verdict in the table comes
from. The two seams were read in place (acp/runtime.py, acp/client.py), as
were acp/session_mcp.py (session_mcp_projection, ToolsAllowlist.grants),
context.py (_skills_injection_plan, _load_steering_resources),
agent_sdk/provider_identity.py (is_claude_code) and
agent_sdk/tool_gate.py (ENFORCED_ROUTINGS).

Three claims were corrected after a local review round falsified them against
the code, and each correction was re-verified the same way: resources does not
arrive as context text on a mirrored harness (is_claude_code is false for every
acp_backend); tools does not keep kiro-cli's per-tool shape
(ToolsAllowlist.grants matches on server name); and identity.py is not shared
by all four mirrors (codex and opencode call it, goose reaches it through
opencode_projection, claude does not use it because its MCP children inherit
the adapter's process env).

Local gate run on this head: the backend gate floor from the resolved prepare-pr
profile exits 0 — black, isort, flake8, mypy (1653 files), and the
docs/brand/harness-parity/feature-map/changelog/focus-cue/comment-history/
memory-store-seam checks, with the scoped test selection reporting
related: 0 test file(s), expected for a markdown-only diff. The frontend and
packaging gates are not run: the diff touches no file under website/, no
lockfile and no template.

Related Issues

No linked issue to close: this is a documentation follow-up to #12155, an
already-merged PR rather than an open issue. It FILES #12215 for the mirror
resources reasons it documents but cannot fix under this PR's one-file scope;
that issue is deliberately not closed by this PR.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and dwu96 September 20, 2026 05:47
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Put the answer to "how do the other ACP backends read and use an agent spec?" on the agent spec field reference as its own section, derived from each mirror's own rulings(), so a spec author can see what their file still means on a second harness without reading seven mirror modules.

Not a goal: changing any code, changing any mirror's ruling, restructuring the rest of the page, or documenting fields kiro-cli accepts and Kiro Crew ignores. Scope is one markdown file.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 9b2a483eaec4e5ca3fd51f69061512e550296aba and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9b2a483

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9b2a483eaec4e5ca3fd51f69061512e550296aba: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 9b2a483eaec4e5ca3fd51f69061512e550296aba — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9b2a483

Verdict parsed from the review's SHA-scoped output markers for commit 9b2a483eaec4e5ca3fd51f69061512e550296aba.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9b2a483eaec4e5ca3fd51f69061512e550296aba: <one-sentence reason>

@iamwhatever iamwhatever changed the title docs: name how the other backends consume an agent spec docs(agent-spec-fields): explain how the other backends consume a spec Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 9b2a483eaec4e5ca3fd51f69061512e550296aba — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify #12215 exists and carries both the mirror resources reason-string fix and the table-pins-to-rulings() test the description defers to it.

[DESIGN-REVIEWED] 9b2a483

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 9b2a483eaec4e5ca3fd51f69061512e550296aba — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The per-harness rulings table is a third hand-maintained copy — agent-host-contract §1's Format cells already spell these dispositions, and nothing syncs any prose copy.

Not justified as shipped

What this change ships

Inventory (10 items) — 9 justified

Intent: let a spec author see, on the packaged spec-fields page, which spec fields still take effect on each non-kiro backend — an ADDITION (new doc section), one file.

  1. New "How the other backends consume a spec" section stating the four-case rule (native / wire projection / mirrored fields / no projection) — justified
  2. Per-harness delivered/translated/withheld table for six backends — duplicate of docs/system-specs/modules/agent-host-contract.md §1 for 3 of 4 mirrors, third spelling beside rulings()
  3. The two mirror seams named (AcpRuntime._mirrored_session_mcp, AcpClient._resolve_session_mcp_servers) — justified
  4. Reason-class taxonomy (gate-preserving, context-instead, harness-owns-the-vocabulary, fixed-by-governance) and the no-channel distinction — justified
  5. Declared correction: resources reaches nothing on a mirrored harness, contra three mirrors' own reason strings (verified: _skills_injection_plan returns is_cc; resources has no reader on a mirrored ACP harness, and nothing says so — at runtime or in the mirrors #12215 filed) — justified
  6. Spec-author guidance: mcpServers/tools/model travel; @server/tool widens to the whole server; per_tool_deny shapes — justified
  7. Old two-paragraph aside collapsed to one sentence plus pointer, claims preserved in the section — justified
  8. Surface-table claude row condensed from inline ruling summary to a pointer — justified
  9. Top-of-page note and per-surface-summary preamble repointed at the section — justified
  10. "Where to look" gains two rows (mirrors folder; the two seams) — justified

[FIRST-PRINCIPLES-REVIEWED] 9b2a483

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/backends-consume-spec branch from eb0a9f9 to 5062ce3 Compare September 20, 2026 06:18
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for eb0a9f9335c1838fec41f196171ee87af0160d5b; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt eb0a9f9335c1838fec41f196171ee87af0160d5b: <one-sentence reason>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ⚠️ review incomplete

GPT 5.6 did not produce a complete verdict for 5062ce3f9829e7c7ccd528b341f300fc43a8c1be; inspect the workflow logs and re-run it.

This comment is updated in place on each push.

See the GPT 5.6 Review job logs; this commit has no completed GPT verdict.

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 5062ce3f9829e7c7ccd528b341f300fc43a8c1be: <one-sentence reason>

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Accepted as stated. claude_code.py, codex.py and opencode.py each justify
the withheld disposition with "injected as context text", which is gated on
is_claude_code and therefore never true for an acp_backend. goose.py is
already correct. The page and the code do disagree, and the page's own trust
rule says the code wins — so leaving the strings wrong leaves a reader who
follows that rule with the wrong answer.
Deferred rather than fixed because this PR's scope is frozen to one markdown
file by the requesting maintainer; correcting a Ruling.reason is a .py
change. #12215 carries both remedies your Clears-when names (fix the three
strings, or point each mirror at the page's note), with the deferred-finding
label, an assignee and a Due date.
Taken here instead, as the in-scope half: the note now names #12215, so the
page no longer states a contradiction with no address. Fixed at 5062ce3.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Agreed, and this is the stronger half of the finding: a custom agent whose
skills come from its own spec runs with NO skills on all four mirrored
harnesses, nothing warns at spawn, and the roster still renders the mapping.
A page a reader has to find first is not a substitute for the product saying so.
Distinct from the WATCH item above even though both start at the same gate: that
one is a comment-accuracy defect in three Ruling.reason strings, this one is a
product decision about whether to WARN at session establishment or to extend
the injection so an ACP harness with a mirror receives the mapped set. The
second makes resources portable and is the larger change.
#12215 names both options, cheapest first, with the deferred-finding label, an
assignee and a Due date. Deferred rather than done here because either remedy is
a code change and this PR is frozen to one markdown file.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — the per-harness table duplicates agent-host-contract.md §1 — rebutted span=0233f707d578
    self-added: no

Overlap is real and I am not disputing it; the duplication is nonetheless the
point of the change, so removing it restores the defect this PR exists to fix.
Evidence: before this PR the page ALREADY deferred to §1 — the replaced
paragraph read "providers/mirrors/ holds the per-harness ruling and the agent
host contract §1 is the table". The requesting maintainer's complaint was
precisely that this buried the answer readers arrive with, and the request was
for a per-harness delivered/translated/withheld table on THIS page. Deleting the
cells to de-duplicate reinstates the pointer-only state that was rejected.
The two are not the same table. §1 is harness-column x topic-row for a HARNESS
IMPLEMENTER — it closes with "A provider must declare: ..." — and its per-concern
rulings live inside one Format cell as a run-on clause per column, which no
reader can compare across harnesses by eye. This page is field-centric for a
SPEC AUTHOR. §1 also omits claude from per-concern treatment entirely (its CC
Format cell describes ~/.claude/agents/<name>.md), and carries none of the
withholding reason classes, neither mirror entry point, the @server/tool
widening, or the resources no-reader correction.
The section cross-links §1 rather than claiming to be the only source.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Correct on both counts, including the count itself. The note said "All four rule
it withheld on the reason that skills and steering are injected as context text"
and then, four sentences later, that goose.py "says as much in its own words".
Those contradict each other: goose's reason is DIFFERENT and already right. It is
three mirrors, not four — a factual error in the page's own text, which is why
this one is fixed here rather than deferred.
Taken your Clears-when's second branch: the mirror strings are corrected "in a
named follow-up the note points at". The note now names
#12215 (deferred-finding, assigned, Due dated), which carries both the string
correction and the decision about warning a spec author at spawn. Notes [6] and
the spec-author bullet point there too, so a reader reaches the address from any
of the three places the fact appears.
The declaration also lost the lines that only restated the gate mechanism. The
is_claude_code trace stays, because it is the evidence for the claim.
Fixing the three Ruling.reason strings here is out of reach: this PR's scope is
frozen to one markdown file by the requesting maintainer.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/backends-consume-spec branch from 5062ce3 to 871ba33 Compare September 20, 2026 07:56
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/backends-consume-spec branch from 871ba33 to 7650dc3 Compare September 20, 2026 08:07
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — duplicate of agent-host-contract.md §1 — rebutted, duplicate of the earlier rebuttal span=f24e8a88ee6b
    self-added: no

Third occurrence of one class, and the position does not move. Answered in full
against the prior span on head eb0a9f9; that rebuttal stands unamended and
this is a duplicate of it.
Restating only the decisive evidence: before this PR the page ALREADY deferred
to §1 in as many words, and the maintainer who requested this change asked for a
dedicated section showing how each other provider reads and uses an agent spec,
precisely because the pointer buried the answer. A section that shrinks back to
a §1 pointer IS the defect being replaced, so the first Clears-when branch
reinstates the bug. The maintainer has now ruled explicitly: keep the table, do
not shrink it.
The second branch -- generate or assert the table against rulings() -- is
accepted as the right long-term closure and is already named in the description
and filed as #12215. It is a test, so it is code, and this PR is frozen by the
requesting maintainer to one markdown file.
No further change here. A fourth raising of this class should read this record
rather than the diff.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Accepted exactly as characterised, including your count: RESOURCES: Ruling
has four hits and three carry the context-instead reason, goose.py being the
one already correct. The in-repo fix is those three strings and this page is
documenting around them.
Deferred rather than fixed because a Ruling.reason is a .py change and the
requesting maintainer froze this PR to one markdown file. #12215 carries the
string correction plus the second question it raises -- whether a spec author
should be WARNED at session establishment rather than left to find this page --
with the deferred-finding label, an assignee and a Due date.
Your Clears-when is the one I want: when #12215 lands, note 6 and the correction
paragraph both shrink to nothing, because the page will no longer be carrying a
disagreement it has to explain. That shrink is the follow-up's job, and the note
already points at the issue so the next reader finds the address rather than
just the contradiction.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • per-call on codex keeps it mounted — unqualified, and only true for the control plane — fixed at 7650dc3 span=1c39859b2a64
    self-added: yes
    mechanism: none added; one summary bullet gained the exception it was missing

Legitimate and mine. The spec-author summary read "per-call on codex keeps it
mounted and refuses the call" flat, which is true only for Crew's own control
plane. codex.py's DENIED_TOOLS ruling is explicit that the per-call channel "is
NOT complete for a third-party server, whose readOnlyHint tools codex approves
internally without asking, which is why those are withheld whole" -- so a
narrowed third-party server is dropped on codex as well, and both halves of your
finding hold.
Note [7] under the per-harness table already stated this correctly, which is what
made the summary a contradiction inside one section rather than a uniform error.
Fixed by qualifying the bullet: the heading now says the cost applies on three
harnesses out of four, per-call is spelled out as control-plane-only with the
no-annotations reason it depends on, the third-party withhold is stated, and it
closes with "read per-call as 'the control plane survives', not 'nothing is
dropped'". The table and note [7] are unchanged, since they were already right.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/backends-consume-spec branch from 7650dc3 to 4d78439 Compare September 20, 2026 08:39
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Accepted, and it is the sharpest thing said about this page. The docs lint reds on
a cited symbol that is RENAMED or DELETED, so a mirror class going away is caught;
it does not read dispositions, so goose gaining per-call deny -- or #12215's own
rewording -- would leave a cell wrong with every check green. For a page whose
entire value is cell-level accuracy, that is the whole risk, and you are right
that my description concedes the mechanism in its own words.
Deferred because both closures you name are code: a test alongside
test/test_provider_mirrors.py parsing the table and asserting each cell against
rulings(), or generating the rows from them. This PR is frozen by the requesting
maintainer to one markdown file.
Filed rather than merely noted: I added it to #12215 as an explicit third task,
with both closure options written out
(#12215 (comment)).
The issue carries the deferred-finding label, an assignee and a Due date.
Until it lands, the table's accuracy rests on review rather than on a gate, and
the description now says so instead of claiming the citations prevent drift.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Accepted, including the reason it matters, which is not cosmetic: a hand-invented
class name is one more thing a future cell-pinning test would have to MAP rather
than match, so it makes the very gate the WATCH item asks for harder to write.
Worth stating why the divergence exists rather than defending it: the doc needed a
name for what the code actually does, and the three mirrors' existing reason text
claims the opposite ("injected as context text", which holds only for the
provider=claude_code seam). no-reader describes the behaviour; it is
deliberately not the mirrors' word, because the mirrors' word is the thing being
corrected.
The right sequencing is yours: when #12215 rewords those three strings, the doc's
class name should become whatever vocabulary the code adopts, not the other way
round. Recorded on the issue as part of that task
(#12215 (comment)) so
the rename and the string fix land together rather than leaving two spellings.
Not changed here: renaming the class before the code has a word for it would just
pick a second arbitrary name.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — duplicate of agent-host-contract.md §1 — rebutted, duplicate of the earlier rebuttal span=4cb4c42248ca
    self-added: no

Fourth occurrence of one class; the ruling is settled and the position does not
move. Answered in full on head eb0a9f9 and again on 871ba33; both
rebuttals stand unamended and this is a duplicate of them.
The maintainer who requested this change has ruled explicitly: KEEP the table, do
not shrink it to a §1 pointer. The reason is on the record -- before this PR the
page already deferred to §1 in as many words, and that pointer burying the answer
is the defect the section replaces. So the "delete the restating cells" branch
reinstates the bug this PR exists to fix, and it is not available.
Your other branch -- generate or test-assert the cells against rulings() -- I
agree with, and it is now an explicit task on #12215 with both closure options
written out
(#12215 (comment)).
It is code, so it cannot land in a PR frozen to one markdown file.
No further change here. A fifth raising of this class should read this record.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • "get nothing the spec declared" is false for pi and deepseek — fixed at 4d78439 span=1c39859b2a64
    self-added: yes
    mechanism: added note 9, naming what reaches a mirrorless harness

Legitimate, and self-inflicted: I shortened that bullet to get What changed back
under WORD_LIMIT and traded a long true sentence for a short false one.
Verified both halves before fixing. model: ACP_BACKEND_PI and
ACP_BACKEND_DEEPSEEK are both members of
agent_sdk/backends.py's ACP_BACKENDS_MODEL_VIA_CONFIG_OPTION, so the spec's
pin reaches them with session/set_config_option after session/new -- the same
channel codex, opencode and goose use, which is why no mirror carries
model. prompt: context.py appends the [AGENT SYSTEM PROMPT] block for a
custom agent with no backend condition on that branch, so it arrives on every
harness alike.
Fixed as you asked, limiting "nothing" to the MCP projection: the bullet now says
no field is DECIDED field by field and names both arriving fields with their
channels; new note 9 states "No mirror is not nothing from the spec" and cites
both; and the pi / deepseek table cells read "no projection" pointing at it.
Swept for siblings rather than patching the one site: the same overclaim appeared
once more in the PR description and is corrected there too.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Backend Tests (Windows) (1) is inherited from main, not from this PR. This
diff is one markdown file (src/kiro_crew/docs/agent-spec-fields.md) and touches
no Python, so it cannot move a runtime test. Not re-running it and not pushing at
it; recording the diagnosis instead.

What fails. Four tests in test/test_acp_runtime.py, all on the kill/reap
amendment path:

test_kill_amends_the_summary_once_the_reap_completes[False-WARNING]
test_kill_amends_the_summary_once_the_reap_completes[True-INFO]
test_reap_amendment_leaves_the_reason_untouched
test_reap_amendment_leaves_the_stderr_tail_untouched

They expect [returncode=-15] and Windows produces [returncode=<not reaped>]:

assert '[returncode=-15]' in 'killed (displaced by a new allocation) [returncode=<not reaped>] ...'
assert '[returncode=-15]' in 'killed (warm mint teardown) [returncode=<not reaped>] ...'

4 failed, 13338 passed in that shard.

Why it is main's. Three independent open PRs on the same base 9dea438c
show the identical Backend Tests (Windows) (1) failure — #12249, #12245 and
#12242 — while #12238, on the previous base 7a2a27de, passes it. That brackets
the regression inside 7a2a27de..9dea438c.

Only one commit in that range touches both test/test_acp_runtime.py and the
reap wording, and git log -S on the test names attributes all four to it:
b785dcc, "fix(acp): say who killed a runtime and never log a bare
returncode=None" (#12188)
. src/kiro_crew/acp/runtime.py carries the
_RC_NOT_REAPED = "<not reaped>" sentinel that the assertions collide with, so
the Windows path resolves to it where the tests assume the signal's -15.

Why nobody caught it. #12188's own CI never validated Windows. Six commits
merged inside ~25 seconds (a53fc3a6, b785dcc4, 04f6a9b0, c20afd9f,
d6e77b03, 9dea438c, all 08:24–08:25 UTC) and ci.yml's
cancel-in-progress concurrency evicted the earlier runs — gh run list --commit b785dcc44e returns no CI run at all. This PR is simply among the first
heads to execute that shard against the merged result.

The fix belongs with #12188's Windows reap path, not here: this PR is scoped to
one documentation file. Every other check on this head is green and both AI
review lanes have stamped it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Accepted, and the framing is the useful part: the risk is not the carve-out, it is
the carve-out becoming permanent. A paragraph explaining that the code is wrong
reads as documentation on day one and as rot on day ninety, so "promptly" is the
actual requirement rather than a nicety.
The fix is as small as you say -- three Ruling.reason strings in
claude_code.py, codex.py and opencode.py, goose.py already being correct.
It is still a .py change, and the maintainer who requested this section froze
this PR to one markdown file, so it cannot ride along here.
#12215 is the vehicle and it is not a parking space: deferred-finding label, an
assignee, and Due: 2026-10-20. The repository's own Disposition Deferral Check
enforces those three, which is what stops this becoming an untracked deferral.
One thing I did NOT do, deliberately: soften the doc's wording to sound less
temporary. The page should read as carrying a known divergence with an address,
because that is what it is until the strings land.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — duplicate of agent-host-contract.md §1 — rebutted, duplicate of the earlier rebuttal span=379a1e62e1d7
    self-added: no

Fifth occurrence of one class. Maintainer-ruled and unchanged: KEEP the table.
Answered in full on eb0a9f9, and again on 871ba33 and 7650dc3.
Those rebuttals stand unamended; this is a duplicate of them.
Your own evidence is the rebuttal. You cite the deleted base sentence -- "the
agent host contract §1 is the table" -- as proof of duplication; that sentence IS
the defect this PR was asked to remove. The requesting maintainer's complaint was
that pointing at §1 buried the answer readers arrive with, and they have since
ruled explicitly to keep the table and not shrink it to a pointer. So "replace the
disposition cells by the pointer" restores the bug, and is not available.
Your first branch -- the rulings()-asserting test or generated rows -- I agree
with and have filed as an explicit task on #12215 with both options written out
(#12215 (comment)).
It is code; this PR is one markdown file.
No further change. A sixth raising should read this record rather than the diff.

The page answered "who reads a spec" with a surface table and then buried the
question a reader arrives with -- how the backends that get no spec file still
receive its fields -- in two paragraphs of aside.

Promote it to its own section, derived from each mirror's own rulings() rather
than from prose: the four-case rule (kiro-cli reads the file, KAS gets a wire
projection, four mirrored harnesses get individual fields, pi and deepseek get
nothing the spec declared), the two entry points that run a mirror at session
establishment, a per-harness table of delivered / translated / not-delivered
fields with numbered qualifiers, the withholding reason classes, and what a spec
author can rely on across harnesses.

One correction to the mirrors, stated as such: three of them justify withholding
`resources` on the reason that skills and steering are injected as context text
instead, which describes the dormant provider=claude_code seam and not the
harness they serve. On a mirrored harness a mapped skill:// reaches nothing.
Tracked in #12215.
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto origin/main at 954fb69 to pick up the upstream Windows fix.

The Backend Tests (Windows) (1) red on the previous head was inherited from main,
diagnosed above: four test/test_acp_runtime.py reap tests expecting
[returncode=-15] where Windows yielded [returncode=<not reaped>]. That is fixed
on main by #12269, "fix(acp): record the reap on the Windows teardown branch
too"
(merged 11:05Z), which is now this PR's base.

No change to this PR's own diff: still one file,
src/kiro_crew/docs/agent-spec-fields.md, +227/-21. CI re-running on the new base.

@iamwhatever
iamwhatever force-pushed the docs/backends-consume-spec branch from 4d78439 to 9b2a483 Compare September 20, 2026 11:12
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • Item 2 — duplicate of agent-host-contract.md §1 (partial) — rebutted, duplicate of the earlier rebuttal span=197837c73c5a
    self-added: no

Sixth occurrence of one class. Maintainer-ruled and unchanged: KEEP the table.
Answered in full on eb0a9f9 and repeated on 871ba33, 7650dc3 and
4d78439; this is a duplicate of those records.
The one new detail here does not change the answer, and arguably strengthens it:
you now count §1 as covering 3 backends of the mirrored 4, with claude, pi and
deepseek absent. A table that omits claude is not the table a spec author needs,
which is why the requesting maintainer asked for this one and has ruled that it
stays rather than shrinking to a §1 pointer.
Your first branch -- #12215's generated-or-asserted rows -- remains agreed and
filed, with both options written out
(#12215 (comment)).
It is code, and this PR is frozen to one markdown file.
Reducing §1's Format cells instead is a second document this PR may not touch.
No further change.

@bolichen97
bolichen97 enabled auto-merge (squash) September 20, 2026 17:09

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed against the pr-triage-pipeline gates plus a full-diff read.

docs, 1 file (src/kiro_crew/docs/agent-spec-fields.md, +227/-21). Promotes a buried aside into a 'How the other backends consume a spec' section: a four-case model (kiro-cli reads the file, KAS gets a wire projection, the four mirrored harnesses get per-field rulings, pi and deepseek get no projection), a where-the-mirror-runs table, a per-harness delivered/translated/not-delivered table with numbered qualifiers, and a what-this-means-for-a-spec-author section. The diff is docs-only; no code change rides along.

Design-doc gate: no match. The path is under src/, not the docs/system-specs, docs/design, docs/architecture, docs/request-for-change or docs/task-specs trees (Rule A); no segment token matches (Rule B); the basename is not rfc-*, DESIGN.md or *.spec.md (Rule C); and it normalizes to agentspecfieldsmd with no readme, prfaq or changerequest (Rule D). The spec paths it references appear only as prose links, not in the diff. So this is not the docs-dominant flavor that forbids an approval.

All six security-checklist answers NO, no denylist match, CodeQL PR-scoped open-alert query empty, Semgrep success, readiness label applied after the head commit.

One unresolved advisory concern, recorded rather than dismissed: First Principles Review concluded success but left a warning-level CONCERNS that the per-harness rulings table is a third hand-maintained copy, since agent-host-contract section 1 already spells these dispositions and nothing syncs any prose copy. That is a real maintainability cost and it is accepted here rather than fixed; a drift-prone third copy is worth closing separately.

The PR also self-discloses a defect that lives in the code rather than in this doc: claude_code.py, codex.py and opencode.py justify withholding resources with an 'injected as context text instead' reason that describes the dormant provider=claude_code seam rather than the mirrored harness they serve, where a mapped skill:// reaches nothing. The doc corrects this narratively and the code fix is tracked in #12215.

@bolichen97
bolichen97 merged commit 69c1049 into main Sep 20, 2026
93 checks passed
@bolichen97
bolichen97 deleted the docs/backends-consume-spec branch September 20, 2026 17:09
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 20, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
kirodotdev#12209)

The page answered "who reads a spec" with a surface table and then buried the
question a reader arrives with -- how the backends that get no spec file still
receive its fields -- in two paragraphs of aside.

Promote it to its own section, derived from each mirror's own rulings() rather
than from prose: the four-case rule (kiro-cli reads the file, KAS gets a wire
projection, four mirrored harnesses get individual fields, pi and deepseek get
nothing the spec declared), the two entry points that run a mirror at session
establishment, a per-harness table of delivered / translated / not-delivered
fields with numbered qualifiers, the withholding reason classes, and what a spec
author can rely on across harnesses.

One correction to the mirrors, stated as such: three of them justify withholding
`resources` on the reason that skills and steering are injected as context text
instead, which describes the dormant provider=claude_code seam and not the
harness they serve. On a mirrored harness a mapped skill:// reaches nothing.
Tracked in kirodotdev#12215.

Co-authored-by: Joe Guo <zejiangg@amazon.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants