fix(kiro-ide): ship only IDE-native agent and settings surfaces (#555)

[wowzoo]

Fixes §1, §2, and §3 of #555. §4 (hook schema) was resolved by #614, so it is
out of scope here; the adapter's stdin channel belongs to #615 and I left its
prose and code untouched.

What this changes

Kiro IDE does not read Kiro CLI's agent-v1 JSON configs or settings/cli.json,
yet harness/kiro-ide/ shipped both. On an IDE install the JSONs were dead
weight, and --doctor failed a check for a CLI-only file the IDE never uses.

§1 — agents ship as Markdown. Dropped the 15 agent JSONs (14 personas +
aidlc.json) and added the conductor as an authored agents/aidlc.md, so it
appears in the IDE's workspace agent selector. Each delegation-target .md now
carries a permissions.rules block (the IDE 1.0 capability/effect/match model)
alongside its existing tools: grant, and no longer carries disallowedTools
— a Claude Code field the IDE does not recognize.

§2 — settings/cli.json dropped from the IDE tree.

§3 — docs parity. onboarding.fills agents_note, the
14-claude-features.md primitive-map, and kiro-ide.md no longer describe
cli.json or agent-v1 JSONs as shipped.

The two core fixes the issue names

#555 §1 spells these out, and both are additive — a CLI tree is byte-identical
either way:

• aidlc-utility.ts handleDoctor: accepts agents/aidlc.{json,md}, and runs
  the settings/cli.json row only on a CLI install (aidlc.json present).
• aidlc-lib.ts loadAgents: excludes aidlc.md from the domain-agent roster,
  so the conductor does not fail agent-schema validation or pollute
  knownAgents.

Packager seam

Two additive changes in scripts/, both no-ops for every other harness:

• manifest-types.ts: new optional frontmatterRemovals field.
• package.ts: applyFrontmatterRemovals, plus the additions loop now skips
  indented continuation lines so a multi-line block like permissions.rules
  can be injected.

bun scripts/package.ts --check reports OK on all five harnesses — the four
non-kiro-ide trees are unchanged byte-for-byte.

Tests

Updated for the new shape: harness-matrix (kiro-ide kiroAgentJson: false,
new memoryInclude: "kiro-ide-workspace" union value), t148, t157, t220,
t-active-space-includes, and t239. t239 previously read
harness/kiro-ide/agents/aidlc.json and asserted a resources glob; it now
asserts the authored aidlc.md carries no resources: key and that
aidlc.json is absent, in lockstep with the primitive-map cell it guards. One
t174 pin was refreshed to the edited primitive-map line.

Verification

• bun run check — green (parity + typecheck + biome, 523 files)
• bun tests/run-tests.ts --smoke --unit — 177 files, 0 failed, 4387 assertions
• bun scripts/ci-changelog-guard.ts <base> — OK, 137 entries preserved, 1 new
• /aidlc --doctor on a seeded IDE tree — 37/0

The full default tier also reports t66 and t89 failing. Both reproduce
unchanged on base 257b43a3: 2.5.11 added the claim-sources sensor without
refreshing the designer-export golden fixture or the sensor-import fixture dir.
They are not from this change, and both live in the integration tier the PR gate
excludes. I can file that separately if useful.

Version bumped to 2.5.13 (2.5.12 is taken by #615) with a matching CHANGELOG
entry and README badge.

[leandrodamascena]

Thanks for addressing the Kiro IDE/CLI mismatch and for the detailed validation work. The overall direction makes sense, particularly moving to native Markdown agents and removing configuration that the IDE does not use. I found a few implementation details that introduce risks around active-space memory, plugin delegation, and shell permissions. These need to be addressed before merging to avoid breaking existing behavior.

[P1] Active-space memory no longer follows space switches

The PR removes the Kiro-native memory include and changes the active-space test to expect repointHarnessIncludes() to do nothing. Since compiled rules_in_context remains pinned to aidlc/spaces/default/memory/, switching spaces may continue using default-space rules.

We need to retain an IDE-native include under .kiro/steering/ or resolve these paths dynamically.

[P1] Plugin-dispatched stages become undispatchable

The plugin composer still treats every .kiro harness as Kiro CLI and requires agent JSON plus trustedAgents registration. After this PR removes those files, Kiro IDE plugin stages using delegated agents or reviewers are rejected even when their Markdown agents exist.

Plugin validation and tests need to distinguish Kiro CLI from Kiro IDE.

[P1] bun * is broader than the engine requires

The new rule pre-approves every Bun command, including bun -e and arbitrary workspace scripts. These commands can also modify files outside the filesystem paths listed in the profile.

This should be restricted to the specific AI-DLC commands needed by the conductor and delegates.

[P2] Filesystem rules are autoapprovals, not strict scopes

Kiro defaults unmatched operations to ask, not deny. Therefore aidlc/spaces/** controls which operations avoid consent but does not prevent writes elsewhere. Documentation and tests describing this as enforcement or sandboxing should be corrected.

[P2] Frontmatter transformations need stronger validation

The generic transformation can produce invalid YAML around comments or blank lines in removed mappings. Additions can also contain duplicate top-level keys without failing. This seam needs focused tests and fail-closed validation.

Before merging, this needs:

1. Active-space memory loading preserved for Kiro IDE.
2. Kiro CLI and IDE distinguished during plugin validation.
3. Narrow shell permission patterns instead of bun *.
4. Kiro IDE plugin delegation and non-default-space coverage.

I verified head 474d5a4a. Package parity and the focused suites pass, but these paths are not currently covered.

[wowzoo]

Thanks — four of the five are implemented in 1f4ccb56. On the fifth I am not
changing code: two separable concerns are tangled in it, and I think the one this
PR touches is not the one that carries the risk. Evidence below, and happy to be
corrected.

[P1] bun * — narrowed

personaFrontmatter and the authored conductor agents/aidlc.md now grant
bun {{HARNESS_DIR}}/tools/aidlc-* instead of bun *. That is the glob
equivalent of the CLI JSON's bun \.kiro/tools/.* regex and covers every command
the conductor prose issues (orchestrate, state, log, utility, learnings, graph,
swarm, worktree). bun -e <code> and arbitrary workspace scripts are no longer
pre-approved. You were right that this was not a faithful translation of the CLI
grant — it was widened in the move, not preserved.

Verified live on Kiro IDE 1.0.212 across three runs, because a too-narrow glob
would have been worse than a wide one (every engine call would prompt): 20
SENSOR_FIRED / 20 SENSOR_PASSED, zero ERROR_LOGGED, zero permission traces, and
hook targets firing throughout (runtime-compile 50, state-sync 50, block 45). The
third run dispatched the composer, which authored a custom scope into
.kiro/scopes/ and the scope grid — so the narrowed grant holds on a delegated
session, not only the conductor's.

[P1] Plugin dispatch — CLI and IDE now distinguished

Confirmed and fixed. kiroPluginAgentPrechecks keyed on
HARNESS_LEAF === ".kiro", and since the IDE install has no agents/aidlc.json,
the trustedAgents read fell into its catch and produced an empty set — which
is fail-closed, so every plugin-dispatched stage was rejected. The conductor's
shape is the discriminator that was missing: agents/aidlc.json present = Kiro
CLI. On an IDE install the precheck now no-ops, as it already did on Claude Code.

t188 gains the Kiro IDE case — the same synthetic ensemble stage as the CLI
case, asserted to compose rather than drop. It fails without the fix.

[P2] Filesystem rules are autoapprovals — corrected

Agreed. Corrected in the manifest comments, the t148 assertion prose, and the
Kiro IDE guide: unmatched operations default to ask, so these lists decide what
proceeds without consent, not where a delegate may write. The assertion now reads
"the grant is present", not "writes are confined".

[P2] Frontmatter seam — hardened, with focused tests

Both defects reproduced. applyFrontmatterRemovals treated a blank line or a
full-line comment inside the removed block as a terminator, so this input

disallowedTools:
  - Task

  - Other

emitted - Other as an orphaned continuation under the preceding key — invalid
YAML. Only a real top-level mapping key ends the block now; a non-indented
non-key line and any surviving orphan both fail closed.
applyFrontmatterAdditions also rejects a key declared twice within one addition
block (previously only collisions against core were checked).

Both functions moved to scripts/manifest-types.ts, beside the contract they
serve — package.ts runs its build at import time, so a test cannot reach into it
for a function. New t249 covers 14 cases, including both defects; it fails
against the pre-fix logic.

[P1] Active-space memory

Edited: this section previously said #654 would address the non-default-space
gap. That was wrong — #654 reads the default-pinned paths, so it does not. The
correction and the evidence are below; the other four sections are unchanged.

Two separable axes are tangled here, and this PR sits on neither.

Axis 1 — does the compiled rule path follow the active space? No, and that
predates this PR. core/tools/aidlc-graph.ts documents the split:

• The COMPILE/DISPLAY family — rulesDir()/memoryDisplayPath() — stays
pinned to default. rules_in_context is frozen into stage-graph.json at
PACKAGE time … it is a list of display PATHS, not rule content.
• The PROJECT family — memoryDirFor()/memoryTemplatesDir() — FOLLOWS the
active-space cursor.

MEMORY_SPACE = "default" is a module constant and this PR does not touch it,
nor memoryDisplayPath(), nor rulesDir(). So a non-default space reading
default rules is the shipped behaviour before and after — reverting this PR does
not change it. It is also not IDE-specific: that constant is shared core, so
Claude Code, Codex and Kiro CLI compile the same pinned paths.

Axis 2 — is the rule content actually loaded? That is the one this PR's
deletion touches, and here I owe you a correction to my own prose. I earlier
pointed at #654 as the place this gets addressed. It is not: readRuleContent
resolves join(projectDir, ...relPath.split("/")) over node.rules_in_context,
i.e. the PACKAGE-time default paths. #654 makes the default space's content
deterministic; it says nothing about which space. I should not have implied
otherwise.

On the deleted surface. What this PR removes is resources: in
agents/*.json. That key is not in the IDE's agent schema — the documented
frontmatter is description / model / tools / mcpServers / permissions,
and IDE agents are .md, so a .json under agents/ is not loaded as an agent
at all. Of the three entries in that array, file://AGENTS.md is picked up
automatically by Kiro from the workspace root (the AGENTS.md steering standard,
always included), skills are loaded by the IDE itself, and the memory glob is the
one that has no IDE consumer. The Kiro CLI harness is untouched by this PR —
dist/kiro/.kiro/agents/aidlc.json still ships the glob and
repointHarnessIncludes() still rewrites it, so CLI space-switching is
unaffected. That is why the test asserts a no-op: the rewrite target for the IDE
tree is gone, but nothing an IDE session could observe changed.

On .kiro/steering/. You are pointing at the right surface — rulesSubdir()
maps .kiro → steering and calls it Kiro's native rule surface. But no rule
file is shipped there on any harness today: the rule layers moved out to the
harness-neutral aidlc/spaces/<space>/memory/, and rulesSubdir() now only
feeds the GUARDRAIL_LOADED audit path string. So shipping an IDE steering
include is not restoring something this PR removed; it is adding the channel that
Kiro IDE has never had, and doing it properly means deciding how it stays in sync
with the neutral memory tree and with the cursor — repointHarnessIncludes()
only walks agents/*.json on the Kiro branch today.

Axis 1 is pre-existing and harness-wide, so I would rather not fold a fix for it
into a formatting-parity PR — that is a call for whoever owns the cursor-aware
resolution design, not something this PR should decide. If you would still prefer
the steering include shipped here, say so and I will add it — with a live check
first, since the interaction between an always-included steering copy and the
engine's own per-stage rule delivery is the part I have not measured.

I did correct the prose that overstated things: the t157 and
t-active-space-includes comments claimed the IDE "reads the workspace shell
directly", which I wrote and cannot substantiate. They now say the method reaches
an IDE workflow through the engine's resolved rules_in_context.

[leandrodamascena]

The fixes raised in the previous review have been addressed, but one blocking gap remains in the Kiro IDE plugin-agent path.

scripts/plugin-hooks-template/compose.ts:634-639 disables plugin-agent dispatch validation for Kiro IDE. The test at tests/integration/t188-plugin-compose.test.ts:640-681 accepts a dispatched plugin stage whose agent contains no tools or permissions, and compose.ts:1188-1199 copies that agent without the projection applied to core IDE agents.

The test confirms file composition, but not that the resulting agent is dispatchable. This also conflicts with docs/reference/18-plugin-mechanism.md:291-300.

Please either project and validate plugin agents as Kiro IDE-native agents, or reject plugin-dispatched stages until that support exists. The test should verify the resulting dispatch surface, not only file existence.

Additional documentation corrections:

• README.md:131 still references the removed .kiro/settings/cli.json.
• CHANGELOG.md:9 describes the shell permission as bun *, while the implementation uses bun .kiro/tools/aidlc-*.

[wowzoo]

Addressed in 9311aa5e. I took the reject option, since projecting plugin agents needs the packager's grant decision, not the composer's.

Plugin-agent dispatch on Kiro IDE — reject

The IDE's dispatch surface is not file existence but the grant: IDE 1.0 delegation needs tools: and a permissions.rules block on the target agent, which harness/kiro-ide/manifest.ts:71-72 appends to every core persona. A plugin agent ships neither, and compose applies no IDE projection when it copies one (unlike .aidlc, whose native twin it rewrites) — so copying it verbatim yields an agent that dispatches but can neither read, write, nor run anything.

installedIdeAgentIsDispatchable() now checks the installed .md for both blocks, and a dispatched plugin stage on the IDE is rejected with a drop-log naming the remediation (author the agent .md carrying both blocks, or set mode: inline). Inline plugin stages are unaffected. This restores agreement with docs/reference/18-plugin-mechanism.md, which I extended to state the IDE case explicitly.

t188 no longer asserts file composition — it asserts the resulting dispatch surface, as you asked. I inverse-verified it: reverting the compose change fails that test and only that test.

Documentation corrections — README.md:131 no longer references settings/cli.json (it now says the IDE activates its agent from the workspace agent selector, and that the file stays in dist/kiro/); CHANGELOG.md:9 now reads bun .kiro/tools/aidlc-*, matching the implementation.

Verified on 9311aa5e: bun run check clean, full runner 282 files / 5768 assertions. Two files fail (t66 2, t89 13), both claim-sources sensor drift that reproduces on a clean upstream/v2 at 207db2ea — unrelated to this branch. t188 passes 61/0.

[apackeer]

Thanks, Keehyun. The core finding in #555 is still valid: current v2 still
ships the Kiro CLI agent JSONs and settings/cli.json in the IDE
distribution, and the roadmap still tracks the IDE-native agent/settings
work as unaddressed. The Markdown conductor/persona direction, the
loadAgents and doctor fixes, the narrowed grants, and the focused coverage
here are useful work.

I reviewed latest head 9311aa5 and ran the seven focused files: all 167
assertions passed, and package parity, typecheck, and lint are clean. The
latest commit fixes the broad CLI/IDE plugin distinction, but its remaining
grant check is too shallow: it accepts any agent with top-level tools: and
permissions: keys. I reproduced a plugin-dispatched stage being composed
against an IDE agent with permissions: {} and no permissions.rules. The
current-v2 integration should validate the actual rule/tool grant shape (or
reject the stage) and cover empty and malformed grants.

Since this branch was last synchronized, #658 added the always-included,
active-space-aware IDE steering path, and the packager and plugin composer
gained substantial reviewer-knowledge, locking, transaction, and identity
behavior. This head explicitly expects IDE include repointing to be a no-op,
so merging or mechanically rebasing it would discard newer behavior.

Please do not spend time rebasing this branch. Maintainers can port the
IDE-native agent/settings work onto current v2, preserve
.kiro/steering/aidlc-active-memory.md, integrate the frontmatter change with
the current packager, and tighten the plugin capability check. I recommend
keeping this PR open as the source until that integration lands, then closing
it as incorporated. Leandro's next pass will be most useful on that integrated
current-v2 change rather than on this stale branch.